Skip to main content
Version: 1.0

ShellyX

Powered by Shelly Devices​

Powered by Shelly devices are products manufactured by third-party vendors that embed ShellyX modules to connect seamlessly with the Shelly ecosystem, transforming them into smart devices.

There are two main categories of such devices:

  1. Shelly-developed firmware devices

    • The device firmware is fully developed by Shelly and integrated directly into Shelly OS, hereafter referred to as the Application.

  2. ShellyX devices

    • These devices are split into two subgroups: XMOD and XT.

    • Both rely on specialized Application software (XMOD or XT) which contains no device-specific functionality by default.

XMOD Devices — No-Code Solution​

XMOD devices use predefined Application Components to implement device-specific functionality. A special configuration defines which Components to use, how they should be set up, and how the Shelly module interacts with the device’s MCU using inputs/outputs. This approach enables a no-code solution: third-party manufacturers can configure ShellyX modules entirely through the ShellyX Developer Portal, without writing custom software.

XT Devices — Low-Code Solution​

XT devices are designed for cases where Application Components are not sufficient. Manufacturers can extend functionality by writing a custom JavaScript module that runs on the ShellyX module. This module is called a Service.

A Service is similar to a Component, but it is bound to the specific device it manages. Each Service acts as a bridge between the device's unique functionality and the XT module, and it encapsulates its own Virtual Components. These Virtual Components function the same way as standard Virtual Components, but they can't be managed through Virtual API.

Additionally, XT modules require a configuration to instruct Application on which Service to run and how to configure inputs/outputs.

Configuration Data for ShellyX Modules (JWS)​

Configuration for ShellyX modules is provided in the form of a JSON Web Token (JWT), referred to as JWS (JWT Signed). A JWS defines key information about the device, including:

  • Assigned inputs and outputs
  • Product name and manufacturer name
  • Product URL

To obtain a JWS token, the manufacturer must create the configuration through the ShellyX Developer Portal.

Methods​

Shelly.GetDeviceInfo​

Request​

Parameters

Response​

For XT1 devices, the response includes additional attributes:

PropertyTypeDescription

jti

string

Unique identifier of the JWS configuration.

jwt

object

Decoded JWS payload containing detailed configuration data.

PropertyTypeDescription

aud

string

Target Application type for which this JWS is applicable.

iat

number

"Issued At" timestamp indicating when the JWS was created.

v

string

JWS version.

p

string

"Prefix" - Device identifier used in the AP SSID, hostname, MQTT Client ID, and other system identifiers.

n

string

Product name.

m

string

Manufacturer name. Optional.

url

string

Product information URL.

f

number

Finalization flag. If set to 1, no new JWS configuration can be applied.

Example​

Shelly.GetDeviceInfo example​

http://192.168.33.1/rpc/Shelly.GetDeviceInfo

Response

{
  "name": null,
  "id": "watervalve-84fce6368be0",
  "mac": "84FCE6368BE0",
  "slot": 0,
  "model": "S3XT-0S",
  "gen": 3,
  "fw_id": "20251009-012418/gee47857",
  "ver": "1.8.99-dev141821+1-dev141902",
  "app": "XT1+simple-water-valve-controller",
  "auth_en": false,
  "auth_domain": null,
  "jti": "0000C1000003",
  "jwt": {
    "aud": "XT1",
    "iat": 1000000000,
    "jti": "000000000000",
    "v": 1,
    "p": "WaterValve",
    "n": "Water Valve",
    "m": "",
    "url": "",
    "f": 0,
    "xt1": {
      "svc0": {
        "type": "simple-water-valve-controller"
      }
    }
  },
  "svc0": {
    "type": "simple-water-valve-controller",
    "ver": "1-dev141902",
    "build_id": "20251009-103105/6997087"
  }
}