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
        },
        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, Object>() {{      put("123", new HashMap<String, Object>() {{          put("on", true);
          put("online", true);
      }});
      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
      },
      "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
      )
  });
  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.