Smart Home LockUnlock Trait Schema

action.devices.traits.LockUnlock - This trait belongs to any devices that support locking and unlocking, and/or reporting a locked state.

Device ATTRIBUTES

None.

Sample SYNC Request and Response

Request

{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "inputs": [{
      "intent": "action.devices.SYNC"
    }]
}

Node.js

'use strict';

const {smarthome} = require('actions-on-google');
const functions = require('firebase-functions');

const app = smarthome();

app.onSync((body, headers) => {
  return {
    requestId: body.requestId,
    payload: {
      agentUserId: '1836.15267389',
      devices: [{
        id: '123',
        type: 'action.devices.types.LOCK',
        traits: [
          'action.devices.traits.LockUnlock'
        ],
        name: {
          defaultNames: ['Sirius Cybernetics Corporation 33321'],
          name: 'Lock',
          nicknames: ['front door']
        },
        willReportState: true,
        deviceInfo: {
          manufacturer: 'Sirius Cybernetics Corporation',
          model: '492135',
          hwVersion: '3.2',
          swVersion: '11.4'
        },
        customData: {
          fooValue: 74,
          barValue: true,
          bazValue: 'lambtwirl'
        }
      }]
    }
  };
});

// ...

exports.smarthome = functions.https.onRequest(app);

Java

@NotNull
@Override
public SyncResponse onSync(@NotNull SyncRequest syncRequest, @Nullable Map<?, ?> headers) {
  Payload payload = new Payload();
  payload.setAgentUserId("1836.15267389");
  payload.setDevices(
      new Device[] {
        new Device.Builder()
            .setId("123")
            .setType("action.devices.types.LOCK")
            .addTrait("action.devices.traits.LockUnlock")
            .setName(
                Collections.singletonList("Sirius Cybernetics Corporation 33321"),
                "front door lock",
                Collections.singletonList("front door"))
            .setWillReportState(true)
            .setDeviceInfo("Sirius", "492134", "3.2", "11.4")
            .setCustomData(
                new JSONObject()
                    .put("fooValue", 74)
                    .put("barValue", true)
                    .put("bazValue", "lambtwirl")
                    .toString())
            .build()
      });
  return new SyncResponse(syncRequest.getRequestId(), payload);
}

JSON

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "agentUserId": "1836.15267389",
    "devices": [
      {
        "id": "123",
        "type": "action.devices.types.LOCK",
        "traits": [
          "action.devices.traits.LockUnlock"
        ],
        "name": {
          "defaultNames": [
            "Sirius Cybernetics Corporation 33321"
          ],
          "name": "Lock",
          "nicknames": [
            "front door"
          ]
        },
        "willReportState": true,
        "deviceInfo": {
          "manufacturer": "Sirius Cybernetics Corporation",
          "model": "492135",
          "hwVersion": "3.2",
          "swVersion": "11.4"
        },
        "customData": {
          "fooValue": 74,
          "barValue": true,
          "bazValue": "lambtwirl"
        }
      }
    ]
  }
}

Validator

Device STATES

State	Definition
`isLocked`	Boolean. Indicates whether the device is currently locked.
`isJammed`	Boolean. Indicates whether the device is currently jammed and therefore its locked state cannot be determined.

Sample QUERY Request and Response

User	Is the front door unlocked?
Google Assistant	Front door is locked.

Request

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
      "intent": "action.devices.QUERY",
      "payload": {
        "devices": [{
          "id": "123"
        }, {
          "id": "456"
        }]
     }
  }]
}

Node.js

'use strict';

const {smarthome} = require('actions-on-google');
const functions = require('firebase-functions');

const app = smarthome();

app.onQuery((body, headers) => {
  return {
    requestId: body.requestId,
    payload: {
      devices: {
        123: {
          on: true,
          online: true,
          status: 'SUCCESS'
        },
        456: {
          online: true,
          isLocked: true,
          isJammed: false,
          status: 'SUCCESS'
        }
      }
    }
  };
});

// ...

exports.smarthome = functions.https.onRequest(app);

Java

@NotNull
@Override
public QueryResponse onQuery(@NotNull QueryRequest queryRequest, @Nullable Map<?, ?> map) {
  QueryResponse.Payload payload = new QueryResponse.Payload();
  payload.setDevices(
      new HashMap<String, Map<String, Object>>() {
        {
          put(
              "123",
              new HashMap<String, Object>() {
                {
                  put("on", true);
                  put("online", true);
                  put("status", "SUCCESS");
                }
              });
          put(
              "456",
              new HashMap<String, Object>() {
                {
                  put("on", false);
                  put("isLocked", true);
                  put("isJammed", false);
                  put("status", "SUCCESS");
                }
              });
        }
      });

  return new QueryResponse(queryRequest.getRequestId(), payload);
}

JSON

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "devices": {
      "123": {
        "on": true,
        "online": true,
        "status": "SUCCESS"
      },
      "456": {
        "online": true,
        "isLocked": true,
        "isJammed": false,
        "status": "SUCCESS"
      }
    }
  }
}

Device COMMANDS

Command	Parameters/Definition
`action.devices.commands.LockUnlock`	`lock` Boolean. True when command is to lock, false to unlock.

Sample EXECUTE Request and Response

User	Lock the front door.
Google Assistant	Ok, locking front door.

Request

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123",
          "customData": {
            "fooValue": 74,
            "barValue": true,
            "bazValue": "lambtwirl"
           }
         }],
        "execution": [{
          "command": "action.devices.commands.LockUnlock",
          "params": {
            "lock": true
          }
        }]
      }]
    }
  }]
}

Node.js

'use strict';

const {smarthome} = require('actions-on-google');
const functions = require('firebase-functions');

const app = smarthome();

app.onExecute((body, headers) => {
  return {
    requestId: body.requestId,
    payload: {
      commands: [{
        ids: ['123'],
        status: 'SUCCESS',
        states: {
          isLocked: true,
          isJammed: false
        }
      }]
    }
  };
});

// ...

exports.smarthome = functions.https.onRequest(app);

Java

@NotNull
@Override
public ExecuteResponse onExecute(
    @NotNull ExecuteRequest executeRequest, @Nullable Map<?, ?> map) {
  ExecuteResponse.Payload payload = new ExecuteResponse.Payload();

  payload.setCommands(
      new Commands[] {
        new Commands(
            new String[] {"123"},
            "SUCCESS",
            new HashMap<String, Object>() {
              {
                put("isLocked", true);
                put("isJammed", false);
              }
            },
            null,
            null)
      });
  return new ExecuteResponse(executeRequest.getRequestId(), payload);
}

JSON

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "isLocked": true,
          "isJammed": false
        }
      }
    ]
  }
}

Device ERRORS

These are some error codes that can be returned with your responses:

remoteSetDisabled If two-factor authentication (2FA) is not yet supported, indicates that the user tried to unlock. This results in a response of "That action is currently disabled" instead of an actual error.

deviceJammingDetected Indicates that the device cannot be locked or unlocked because it is jammed.

notSupported Indicates that the device supports querying locked state but not locking and unlocking.

See the full list of errors and exceptions.