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

Ownership and access

Since version 2.0.0

Virtual components can be owned by a service or a script. Ownership metadata is not part of the component's configuration (<Type>.GetConfig), it is reported in the attrs object returned by Shelly.GetComponents:

Property	Type	Description
owner	string	Key of the owner, for example service:0 or script:1. Present only if the component has an owner.
access	string	Access permissions for everyone except the owner. Present if the component has an owner or if access is restricted. A combination of: * — Full access (all operations). C — Full config access (GetConfig and SetConfig). c — Read-only config access (GetConfig only). w — Write access (also implies read) — allows modifying the component's value. r — Read-only access — allows reading the component's value. m — Manage access — allows deleting the component with Virtual.Delete.
role	string	Role of the component within its owner. Present only if set.

Methods

Virtual.Add

Request

Parameters:

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

Parameters:

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