Smartthings CLI - Create Virtual Device

Developer Programs
16

Let’s start with https://github.com/SmartThingsCommunity/smartthings-core-sdk/blob/main/src/endpoint/virtualdevices.ts as we know that we are interested in virtual devices. So we already know the endpoint we are interested in is likely to be https://api.smartthings.com/virtualdevices otherwise they’d have called the file something else.

So let’s look for something in the file about creating events. It is on lines 82-89. I can’t read TypeScript/JavaScript that brilliantly but line 89 suggests to me we are doing a POST to https://api.smartthings.com/virtualdevices/{{deviceId}}/events and the body is, in TypeScript/JavaScript terms, { deviceEvents }. We also know from the previous line that deviceEvents is an array of whatever DeviceEvent is.

So effectively it is { deviceEvents: [ DeviceEvent ] } and now we have to find DeviceEvent.

Line 3 shows that DeviceEvent is actually found in https://github.com/SmartThingsCommunity/smartthings-core-sdk/blob/main/src/endpoint/devices.ts. If we go to lines 511-522 we find:

export interface DeviceEvent {
	value: unknown
	component: string
	capability: string
	attribute: string
	unit?: string
	data?: { [name: string]: object }
}

export interface DeviceEventList {
	deviceEvents: DeviceEvent[]
}

So there we have the definition of deviceEvents as a list of DeviceEvent and above it is the definition of DeviceEvent. So let’s glue them together.

{
  deviceEvents: [
    {
      value: unknown
	  component: string
	  capability: string
	  attribute: string
	  unit?: string
	  data?: { [name: string]: object }
    }
  ]
}

That is now starting to resemble an event. We have the component, capability and attribute, a value, an optional unit and some optional extra data (where they used to stick buttonNumber and things like that). So let’s fill in some real data. In the same order I just gave (having moved value) we have main, presenceSensor, presence, present and we don’t need the other stuff. So we have:

{
  deviceEvents: [
    { 
      component: "main",
      capability: "presenceSensor",
      attribute: "presence",
      value: "present"
    }
  ]
}

Unsurprisingly JSON, the JavaScript Object Notation, is pretty similar to that. It just needs the quotes around the keys too.

{
  "deviceEvents": [
    {
      "component": "main",
      "capability": "presenceSensor",
      "attribute": "presence",
      "value": "present"
    }
  ]
}

As I say though, if you know the CLI command you can get places quicker.

> set SMARTTHINGS_DEBUG=true
> smartthings virtualdevices:events {{deviceId}} presenceSensor:presence present

That first fetched the capability so it can check you are asking something sensible and it will then pop up:

[2022-10-13T19:44:55.552] [DEBUG] rest-client - making axios request: {"url":"https://api.smartthings.com/virtualdevices/{{deviceId}}/events","method":"post","headers":{"Content-Type":"application/json;charset=utf-8","Accept":"application/json","User-Agent":"@smartthings/cli/1.0.0-beta.20 win32-x64 node-v16.16.0","Accept-Language":"en-GB","Authorization":"Bearer {{Personal Access Token}"},"data":{"deviceEvents":[{"component":"main","capability":"presenceSensor","attribute":"presence","value":"present"}]}}