SmartThings virtual devices using CLI

Devices & Integrations
#1

Now it’s possible to make virtual devices using CLI

Following commands are added to CLI

smartthings virtualdevices [ID]
smartthings virtualdevices:create
smartthings virtualdevices:create-standard
smartthings virtualdevices:delete [ID]
smartthings virtualdevices:events [ID] [NAME] [VALUE] [UNIT]
smartthings virtualdevices:update [ID]

More information from
GitHub - SmartThingsCommunity/smartthings-cli: Command Line Interface for the SmartThings APIs.

I made one using command

$ smartthings virtualdevices:create-standard # interactive mode

Virtual switch in IDE

vSwitchStd
vSwitchStd885×426 15.3 KB

3 Likes
#2

Interesting!

@TAustin @ygerlovin

1 Like
#3

Typical, I’ve been avidly watching and waiting for these to go live, and then as soon as I finally get hit by the dreaded lurgy out they pop.

1 Like
#4

smartthings virtualdevices:create-standard

You can create a device from one of the standard prototypes

Select a device prototype. 3
────────────────────────────────────────────────────

Name Id

────────────────────────────────────────────────────
1 Switch VIRTUAL_SWITCH
2 Dimmer Switch VIRTUAL_DIMMER_SWITCH
3 Button VIRTUAL_BUTTON
4 Camera VIRTUAL_CAMERA
5 Color Bulb VIRTUAL_COLOR_BULB
────────────────────────────────────────────────────
6 Contact Sensor VIRTUAL_CONTACT_SENSOR
7 Dimmer (no switch) VIRTUAL_DIMMER
8 Garage Door Opener VIRTUAL_GARAGE_DOOR_OPENER
9 Lock VIRTUAL_LOCK
10 Metered Switch VIRTUAL_METERED_SWITCH
────────────────────────────────────────────────────
11 Motion Sensor VIRTUAL_MOTION_SENSOR
12 Multi-Sensor VIRTUAL_MULTI_SENSOR
13 Presence Sensor VIRTUAL_PRESENCE_SENSOR
14 Refrigerator VIRTUAL_REFRIGERATOR
15 RGBW Bulb VIRTUAL_RGBW_BULB
────────────────────────────────────────────────────
16 Siren VIRTUAL_SIREN
17 Thermostat VIRTUAL_THERMOSTAT
────────────────────────────────────────────────────

#5

Hmm, this is indeed interesting. I think I can see where they are going but I am not totally sure.

I would describe the virtual devices as being like a wrapper for capabilities. Something like the standard virtual switch has the switch and refresh capabilities with the usual switch attribute and on and off commands so works rather like we are used to. However the standard virtual presence only has the presenceSensor and refresh capabilities so there aren’t any commands to set the presence attribute. The only way to do that seems to be to use the API to send the events (and I found that I had to be the Location owner for those to work). So that isn’t what we are used to, but why should it be?

I haven’t looked to see if the commands implemented are limited to enum and setter commands, which obviously have a direct correspondence with certain attributes. I guess there could be more fancy command mapping to come. Similarly I’d imagine there will the a cloud v local option in future.

#6

On iOS, I can get this with these virtual devices: when I create one, it may show up right away in the mobile and you can tap on it to go into device Controls, but I may get nothing but a blank page - not even a way to navigate back out. The only option is to shut down the app and restart. I repeated this procedure several time last evening then gave up. Today, the device is properly displaying and functional. :face_with_diagonal_mouth:

#7

Here’s a bit of an anomoly: if you create a refrigerator virtual device, it uses the thermostatCoolingSetpoint capability in both the main and freezer components. However that capability only allows you to set it to a low of freezing (32 degrees F / 0 degrees C). Not very useful for a freezer thermostat where you typically have it a few degrees BELOW freezing.

@nayelyz FYI.

1 Like
#8

Have you checked if changing the range in the device-config helps? The capability definition allows a range of -460 - 10000 but I know this and heatingSetpoint are a little tricky, specially related to the unit used in the location and the events.

#9

How would I do this? I see the range in the device presentation and I don’t know how to change that short of creating a custom capability and presentation.

#10

What are you referring to here? An option would be to create a custom capability but remember those are not supported in some third-party integrations like Alexa.

To change the range of a capability (this affects only the presentation, not the definition), you need to do something like this in the device-config to create a custom presentation:

{
    "component": "main",
    "capability": "thermostatCoolingSetpoint",
    "version": 1,
    "values": [
      {
        "key": "coolingSetpoint.value",
        "range": [
          -4,
          80
        ],
        "step": 1
      }
    ]
}

Note: The value in step depends on the “jumps” you want to allow for the - and + symbols. This way, the value will increase/decrease in that amount. For example,if it’s 0.5, the value will change between 12.0 to 12.5

#11

You showed me something new! I did not know you could do that. Thank you!

3 Likes
#12

Hi @nayelyz

Since you mention it, I think there are other thing that must have been broken with the app updates.

The temperature steps work by clicking on the “+” or “-”, but if you want to enter a value directly with the keyboard it does not work well.

In steps of 0.1° is empty and impossible enter a value.
In 0.5° steps you can enter them, but it doesn’t show the current value, it’s empty too

Screenshot_20220714-210353
Screenshot_20220714-2103531023×2048 167 KB

Screenshot_20220714-215006
Screenshot_20220714-2150061595×2048 219 KB

Screenshot_20220714-215130
Screenshot_20220714-2151301597×2048 234 KB

#13

I see that Isabelle has created a pull request for a Virtual Switch driver (covers switch, dimmer and dimmer-switch). Looks stateless to match the DTH. Interesting.

#14

Could you give me an example of how to create a virtualDevice using the API.

I can list the virtual devices using the following in Postman.
https://api.smartthings.com/virtualdevices
but I am at a loss what the URL & body would look like for a POST request to create a virtual device.
I can find nothing in the online API documentation.

#15

I have made virtual devices only using CLI.
I don’t have any experience about SmartThings API and Postman.

#16

Sure, but I should add the disclaimer that there has been no obvious attempt to launch these devices yet and they may not even be ready for us to play with. As the devices are based on capabilities, unless there is a setter or enum command defined in said capabilities there is as yet no way to use them in Routines, Scenes and Rules. Instead you use an API command to specify events, rather like you would with a SmartApp based device. It is clear that the virtual devices will support either local or cloud at some stage, and it is possible that this might involve Edge drivers for the local ones. I simply don’t know. The custom virtual devices seem to have some kind of command mapping feature to come. I don’t know what that is. That said, if you want to create a cloud based virtual switch , this is what the CLI does (tarted up a bit for readability):

URL:  https://api.smartthings.com/virtualdevices/prototypes
Body: { "name": "{{Label for the device}}",
        "roomId": "{{Room ID}}",
        "prototype": "VIRTUAL_SWITCH",
        "owner": {
          "ownerType": "LOCATION",
          "ownerId": "{{Location ID}}"
        }
      }

As it is a switch it has on and off commands that do the obvious thing. However just to show how it works for other virtual devices, this is how the switch could be turned off:

URL:  https://api.smartthings.com/virtualdevices/{{Device ID}}/events
Body: { "deviceEvents: [
          { "component": "main",
            "capability":"switch",
            "attribute": "switch",
            "value": "off"
          }
        ]
      }

I don’t know what the deal is with the ‘state change’ value on these devices. I think it may default to on, at least for the switch. I don’t know if there is a way to turn it off.

I am not recommending to anyone to do any of the above. I am just a reporter. I didn’t uncork the bottle.

2 Likes
#17

As usual @orangebucket comes across with the api information need.

1 Like
#18

Yes @orangebucket API information is very useful.

#19

Thanks to this thread I was able the ability to create VR devices to my Tasker tasks.