Virtual Components

caution

Available as preview since 1.1.0-beta3. The API is subject to change.

note

Available only for Gen3 and Gen2 Pro* devices.

Virtual components are a subset of dynamic components that allow the user to interact with scripts.

Creation and deletion of components is done through 2 methods from the Virtual namespace.

• Virtual.Add to create new virtual component
• Virtual.Delete to remove existing virtual component

There is a limit of 10 instances per device.

A list with all virtual components can be fetched only by Shelly.GetComponents method.

Available virtual components:

• Boolean
• Number
• Text
• Enum
• Group
• Button

Interaction with virtual components

Virtual components are used to store/transfer data between scripts or runs, but they provide the possibility for the user to interact with them from the device's local home page. Each virtual group is added to the home page and is made up of cards. Each component has its own card with different inputs inside, based on the component's configuration.

Methods

Virtual.Add

Request

Properties:

Property	Type	Description
type	string	The type of virtual component to be created. Range of values: boolean, text, number, enum, group, button. Required
config	object	Configuration to be used for the new component. Optional
id	number	ID for the new component. Accepted range: [200..299]. Optional. If omitted, the first free ID will be used. If the desired ID is not available, an error will be returned.

Response

The result from calling this method is a JSON object, with an id on success, otherwise it will return an error.

Received attributes:

Property	Type	Description
id	number	ID of the newly created component.

Virtual.Delete

Request

Properties:

Property	Type	Description
key	string	Component key (in format <type>:<cid>, for example boolean:200). Required

Response

The result from calling this method is null on success, otherwise it will return an error.

Examples

Virtual.Add example

Virtual.Add HTTP GET Request

http://192.168.33.1/rpc/Virtual.Add?type="boolean"

Virtual.Add Curl Request

curl -X POST -d '{"id":1,"method":"Virtual.Add","params":{"type":"boolean"}}' http://${SHELLY}/rpc

Virtual.Add Mos Request

mos --port ${PORT} call Virtual.Add '{"type":"boolean"}'

Response

Virtual.Add HTTP GET Response

{
  "id": 200
}

Virtual.Add Curl Response

{
  "id": 1,
  "src": "shelly1pmminig3-84fce63fe000",
  "params": {
    "id": 200
  }
}

Virtual.Add Mos Response

{
  "id": 200
}

Virtual.Delete example

Virtual.Delete HTTP GET Request

http://192.168.33.1/rpc/Virtual.Delete?key="boolean:200"

Virtual.Delete Curl Request

curl -X POST -d '{"id":1,"method":"Virtual.Delete","params":{"key":"boolean:200"}}' http://${SHELLY}/rpc

Virtual.Delete Mos Request

mos --port ${PORT} call Virtual.Delete '{"key":"boolean:200"}'

Response

Virtual.Delete HTTP GET Response

null

Virtual.Delete Curl Response

{
  "id": 1,
  "src": "shelly1pmminig3-84fce63fe000",
  "params": null
}

Virtual.Delete Mos Response

null