Correct Z-Wave Lock API Command

Developer Programs Support
, ,
1

Hi all,

I am moving from Vera to Smartthings. On Vera I have a a Siri shortcut that goes through my Airbnb booking and grabs the last 4 digits of the guest’s phone number and then programs my Yale pushbutton lock (through vera REST API) with this code.

On Smartthings, I can’t seem to figure out the correct REST command to do the same thing. Devices that are simple on/off are easy:

curl --request POST
–url https://api.smartthings.com/v1/devices/ef8bbc69-dcc7-49b8-afad-da15bc4***/commands
–header 'authorization: Bearer *****
–header ‘content-type: application/json’
–data ‘{
“commands”: [
{
“component”: “main”,
“capability”: “switch”,
“command”: “off”
}
]
}’

For a z-wave lock? Does anyone have an example for SET, GET codes??? Also, looks like scheduling code expiration is not possible in the provided DTH, is that right?

2

If you have access to RBoy apps check out this app which provides a comprehensive REST API for remote lock user programming and actions with a variety of options and also verifies that programming was successful.

2 Likes
3

Thanks, but I don’t need all that. The Smartthings api does what I need, I just need to figure out the right syntax :frowning:

1 Like
4

@fdanna, did you ever figure this out? I can help you with the GET, but you should know that you can only get the name and ID of a code, but not the code itself (and rightfully so).

There are two ways that I can see,

Get Lock Codes

  1. uri: devices/{deviceId}/status
  • once you have the response, you should see the codes in the following json path:
    components/{componentId}/{capabilityId}
  1. uri: devices/{deviceId}/components/{componentId}/capabilities/{capabilityId}/status

I am using Schlage so I know that capabilityId in my case is lockCodes, but it should be specific to your device.

Get Device Capabilities
You can find your device’s capabilities by api endpoint: devices/{deviceId}
Then you will see them in the json path components/capabilities

Set Lock Codes
I’ve been trying to do this myself and can’t seem to find a way yet. One thing we know for certain is that it is possible since we know @RBoy figured it out. If you figure this one out, I’d be interested to see how you did it. More importantly I’d like to know how you found out, since I have a lot more I would like to do with my devices.

1 Like
5

Hi Sam, never figured it out. I did figure out that since my account was registered in the wrong region I didn’t see the smart lock guest access app. Samsung told me I should be able to use the api to configure the locks through the api with the smart lock app. It doesn’t seem apparent to me how that is supposed to go :frowning:

6

I got you bro (I think). It looks like even if a command is not exposed publicly on the API you can still call it if the device has it. This means that for a Schlage Connect lock:

devices/{deviceId}/commands
with this body:

{
  "commands": [
    {
      "component": "main",
      "capability": "lockCodes",
      "command": "setCode",
      "arguments": [
        3,"1235","Test Code"
      ]
    }
  ]
}

will properly set a new code, while:
devices/{deviceId}/commands
with this body:

{
  "commands": [
    {
      "component": "main",
      "capability": "lockCodes",
      "command": "deleteCode",
      "arguments": [
        3
      ]
    }
  ]
}

will effectively delete the code you created.

I REALLY wish there was a way to see which commands were available for a given capability. I cannot believe it is not supported yet.

If you (or anyone else) find out any more info on how to do this, I would really appreciate posting the answer here.

1 Like
7

As of Sept 14, here is the response from SmartThings regarding the lockCodes capability:

Unfortunately, the Lock Codes capability still being under proposed status, therefore it may not work as expected at the Connected platform .

For this and more details about the Lock Codes capability run the following cURL script into your computer’s terminal ( notice that you’ll need a personal access token to authenticate yourself to the API ).

 curl -X GET "http://api.smartthings.com/v1/capabilities/lockCodes/1" \
 -H "Authorization: Bearer <personal_access_token>"

Please, let me know if is there anything else I can help you with.

If you look at that URL, you get the following:

{
    "id": "lockCodes",
    "version": 1,
    "status": "proposed",
    "name": "Lock Codes",
    "attributes": {
        "codeLength": {
            "schema": {
                "type": "object",
                "properties": {
                    "value": {
                        "title": "PositiveInteger",
                        "type": "integer",
                        "minimum": 0
                    }
                },
                "additionalProperties": false,
                "required": []
            },
            "setter": "setCodeLength",
            "enumCommands": []
        },
        "maxCodes": {
            "schema": {
                "type": "object",
                "properties": {
                    "value": {
                        "title": "PositiveInteger",
                        "type": "integer",
                        "minimum": 0
                    }
                },
                "additionalProperties": false,
                "required": []
            },
            "enumCommands": []
        },
        "maxCodeLength": {
            "schema": {
                "type": "object",
                "properties": {
                    "value": {
                        "title": "PositiveInteger",
                        "type": "integer",
                        "minimum": 0
                    }
                },
                "additionalProperties": false,
                "required": []
            },
            "enumCommands": []
        },
        "codeChanged": {
            "schema": {
                "type": "object",
                "properties": {
                    "value": {
                        "title": "String",
                        "type": "string",
                        "maxLength": 255
                    }
                },
                "additionalProperties": false,
                "required": []
            },
            "enumCommands": []
        },
        "lock": {
            "schema": {
                "type": "object",
                "properties": {
                    "value": {
                        "title": "LockState",
                        "type": "string",
                        "enum": [
                            "locked",
                            "unknown",
                            "unlocked",
                            "unlocked with timeout"
                        ]
                    }
                },
                "additionalProperties": false,
                "required": []
            },
            "enumCommands": [
                {
                    "command": "lock",
                    "value": "locked"
                },
                {
                    "command": "unlock",
                    "value": "unlocked"
                },
                {
                    "command": "unlockWithTimeout",
                    "value": "unlocked with timeout"
                }
            ]
        },
        "minCodeLength": {
            "schema": {
                "type": "object",
                "properties": {
                    "value": {
                        "title": "PositiveInteger",
                        "type": "integer",
                        "minimum": 0
                    }
                },
                "additionalProperties": false,
                "required": []
            },
            "enumCommands": []
        },
        "codeReport": {
            "schema": {
                "type": "object",
                "properties": {
                    "value": {
                        "title": "JsonObject",
                        "type": "object"
                    }
                },
                "additionalProperties": false,
                "required": [
                    "value"
                ]
            },
            "enumCommands": []
        },
        "scanCodes": {
            "schema": {
                "type": "object",
                "properties": {
                    "value": {
                        "title": "String",
                        "type": "string",
                        "maxLength": 255
                    }
                },
                "additionalProperties": false,
                "required": []
            },
            "enumCommands": []
        },
        "lockCodes": {
            "schema": {
                "type": "object",
                "properties": {
                    "value": {
                        "title": "String",
                        "type": "string",
                        "maxLength": 255
                    }
                },
                "additionalProperties": false,
                "required": []
            },
            "enumCommands": []
        }
    },
    "commands": {
        "setCodeLength": {
            "arguments": [
                {
                    "name": "length",
                    "optional": false,
                    "schema": {
                        "title": "PositiveInteger",
                        "type": "integer",
                        "minimum": 0
                    }
                }
            ]
        },
        "reloadAllCodes": {
            "arguments": []
        },
        "unlock": {
            "arguments": []
        },
        "unlockWithTimeout": {
            "arguments": []
        },
        "setCode": {
            "arguments": [
                {
                    "name": "codeSlot",
                    "optional": false,
                    "schema": {
                        "title": "PositiveInteger",
                        "type": "integer",
                        "minimum": 0
                    }
                },
                {
                    "name": "codePIN",
                    "optional": false,
                    "schema": {
                        "title": "String",
                        "type": "string",
                        "maxLength": 255
                    }
                },
                {
                    "name": "codeName",
                    "optional": false,
                    "schema": {
                        "title": "String",
                        "type": "string",
                        "maxLength": 255
                    }
                }
            ]
        },
        "updateCodes": {
            "arguments": [
                {
                    "name": "codes",
                    "optional": false,
                    "schema": {
                        "title": "JsonObject",
                        "type": "object"
                    }
                }
            ]
        },
        "lock": {
            "arguments": []
        },
        "requestCode": {
            "arguments": [
                {
                    "name": "codeSlot",
                    "optional": false,
                    "schema": {
                        "title": "PositiveInteger",
                        "type": "integer",
                        "minimum": 0
                    }
                }
            ]
        },
        "deleteCode": {
            "arguments": [
                {
                    "name": "codeSlot",
                    "optional": false,
                    "schema": {
                        "title": "PositiveInteger",
                        "type": "integer",
                        "minimum": 0
                    }
                }
            ]
        },
        "nameSlot": {
            "arguments": [
                {
                    "name": "codeSlot",
                    "optional": false,
                    "schema": {
                        "title": "PositiveInteger",
                        "type": "integer",
                        "minimum": 0
                    }
                },
                {
                    "name": "codeName",
                    "optional": false,
                    "schema": {
                        "title": "String",
                        "type": "string",
                        "maxLength": 255
                    }
                }
            ]
        }
    }
}

It would seem the answer is: just wait.

Meanwhile, the groovy smartapp stuff does NOT have an EOL date yet and works fine. Even though they’re shutting down the old mobile app soon, I suspect the groovy backend will be much harder to sunset.

8

@awesam @fdanna just wondering if either of you discovered a way to edit the code name?

9

Nope. I create a code via api and no matter what I send along as the code name, SmartThings names the code “Code 1” based on whatever slot the code is. Then I have to manually go into the app and edit it…

The reverse is not true. If you create a code from the app, and get it from the API, the name is as it should be. Seems like SmartThings has 2 fields for name and they are not mapping properly.

So:

------------------------------------------------------------
| Action                       | API Get     | App         |
------------------------------------------------------------
| Api setcode "Test Code"      | "Test Code" | "Code 1"    |
| App Invite Guest "Test Code" | "Test Code" | "Test Code" |
------------------------------------------------------------
1 Like
10

Interesting, I noticed that myself. I wonder if @nayelyz can help with this.

11

Hi, @Jake_Mohl!
Can you bring me up to speed, please? Why is it important to change the code’s name?

Also, remember that, when you send a command from the API, it calls directly the capability handler from the DTH which I assume your device is still using, right?

Have you seen the DTH’s code for that device? maybe we’re sending the wrong parameters…If you can share the device’s brand and Model, I can look it up to see what I can find.

12

Here’s the cliff notes version.

Lock Model.
Schlage Connect Zwave Model# BE469ZP
I don’t know what exact model number @awesam has.

The main reason is to be notified of who has used the lock

If you add a code using this code it adds the code but it doesn’t use the name supplied it defaults to “code x”. You can rename them in the Smart Lock Guest Access, so it would make since you should be able to do it through the API.

{
  "commands": [
    {
      "component": "main",
      "capability": "lockCodes",
      "command": "setCode",
      "arguments": [
        3,"1235","Test Code"
      ]
    }
  ]
}

So it would be nice to rename a existing code and have the name supplied be retained.

13

@nayelyz sorry to ping you about this but it has been 22 days. Can you at least verify the argument structure for setting a lock code is correct? Currently using this the name of the code defaults to “code 3” and not “Test Code”

{
  "commands": [
    {
      "component": "main",
      "capability": "lockCodes",
      "command": "setCode",
      "arguments": [
        3,"1235","Test Code"
      ]
    }
  ]
}
14

Hi, @Jake_Mohl!
Can you specify which device type is selected for this device, please? I’d like to see its configuration if possible.
I believe this is because of how the event is handled and saved in the API but I want to confirm.

15

This is for the Stock Zwave Lock Edge driver. In the past it would have been this DTH Zwave Lock

16

Hi, @Jake_Mohl. Sorry for the delay, I made some tests with the DTH and I confirmed the command is using the parameters correctly, I don’t know exactly where the codeName is lost.
Here’s the function that gets the command from the API:

def setCode(codeID, code, codeName = null) {
   //I printed the values received using the command you shared:
   log.trace("codeID ${codeID}, code ${code}, codeName ${codeName}")
   //This is the output:
   //codeID 3, code 1235, codeName Test Code
}

It is hard to troubleshoot its behavior because the functionality depends on the messages exchange and I don’t have the device. Have you seen if this happens also with the Edge driver for the device?

17

I have tested this on two different locks both the same model but one is DTH and the other is Edge, both do not except codeName. It defaults to “Code x” - x being the current slot.

18

can you get the logs from the device controlled by the driver and send them to build@smartthings.com, please? I’d like to see the messages sent and received.

19

How do I do that?

20

oh, sorry about that.
You need to set up the SmartThings CLI in a PC, the instructions are in this doc.

Once you finish, you should be able to execute this command:

smartthings edge:drivers:logcat --hub-address=x.x.x.x

You need to replace x.x.x.x with the Hub’s IP address that you can find in the IDE (my hubs > Hub’s details.

To copy them into a file, you need to:

  1. Select the text in the console, right-click and select “copy”.
  2. Then, in a text file right-click and tap on “paste”

Note: In Windows, it might be hard to copy the text if the command is still running, this is because the console itself tries to scroll down automatically to the last line in the log.
To stop the command, you just need to use ctrl + C.

2 Likes