Manifest Reference

The manifest (manifest.svc.json) is a JSON file that declares your device's controls and properties (the device's behavior). It tells the Shelly system what your firmware extension exposes and how to present it to users.

Basic Structure

{
  "handlers": [],
  "vc": { ... },
  "meta": { ... }
}

Virtual Components (vc)

Virtual components are software-defined variables that don't represent physical hardware - they're logical abstractions you create to control or monitor a specific function. Each key is a control name (called a "role"):

"vc": {
  "state": { ... },
  "brightness": { ... }
}

Component Types

Boolean (On/Off Toggle)

"state": {
  "type": "boolean",
  "access": "crw",
  "config": {
    "name": "Power",
    "default_value": false,
    "meta": {
      "ui": {
        "view": "toggle",
        "titles": ["Off", "On"]
      }
    }
  }
}

Number (Slider)

"brightness": {
  "type": "number",
  "access": "crw",
  "config": {
    "name": "Brightness",
    "default_value": 50,
    "min": 0,
    "max": 100,
    "meta": {
      "ui": {
        "view": "slider",
        "step": 1,
        "unit": "%"
      }
    }
  }
}

Enum (Dropdown)

"mode": {
  "type": "enum",
  "access": "crw",
  "config": {
    "name": "Mode",
    "default_value": "off",
    "options": [
      { "value": "off", "display": "Off" },
      { "value": "heat", "display": "Heat" },
      { "value": "cool", "display": "Cool" }
    ],
    "meta": {
      "ui": { "view": "dropdown" }
    }
  }
}

Read-Only Sensor

"temperature": {
  "type": "number",
  "access": "cr",
  "config": {
    "name": "Temperature",
    "default_value": 20,
    "meta": {
      "ui": {
        "view": "label",
        "unit": "°C"
      }
    }
  }
}

Access Levels

See XT1 → Virtual Components for the full list of access permission characters and their meanings.

UI Views

• toggle — On/off button (for booleans)
• slider — Range control (for numbers)
• dropdown — Select list (for enums)
• label — Read-only text display
• text_input — Text box (for strings)
• button — Action button (for momentary actions)

Metadata (meta)

Organize your device and enable integrations:

"meta": {
  "groups": [
    { "type": "switch" },
    { "type": "light" }
  ],
  "integrations": {
    "aa": [{ "class": "light:bulb" }],
    "st": [{ "class": "light:bulb" }],
    "gh": [{ "class": "light:bulb" }]
  }
}

groups — Device categories (switch, light, thermostat, cover, sensor)

integrations — Smart home platforms:

• aa — Amazon Alexa
• st — Samsung SmartThings
• gh — Google Home

Common Integration Classes

• switch — On/off device
• light:bulb — Light bulb
• light:color — Color-changing light
• thermostat — Temperature control
• cover:blind — Motorized blind/shade
• sensor — Sensor readings
• evse — EV charger

Quick Example

A simple light with brightness:

{
  "handlers": [],
  "vc": {
    "state": {
      "type": "boolean",
      "access": "crw",
      "config": {
        "name": "Power",
        "default_value": false,
        "meta": { "ui": { "view": "toggle", "titles": ["Off", "On"] } }
      }
    },
    "brightness": {
      "type": "number",
      "access": "crw",
      "config": {
        "name": "Brightness",
        "default_value": 100,
        "min": 0,
        "max": 100,
        "meta": { "ui": { "view": "slider", "step": 1, "unit": "%" } }
      }
    }
  },
  "meta": {
    "groups": [{ "type": "switch" }, { "type": "light" }],
    "integrations": {
      "aa": [{ "class": "light:bulb" }],
      "st": [{ "class": "light:bulb" }],
      "gh": [{ "class": "light:bulb" }]
    }
  }
}

Next: Script Development