Shelly Power Dongle Application Packages

This repository hosts application packages and integrations for the Shelly Power Dongle (SPD), targeting CAN and RS485 devices.

Requirements

Every package developed for a MODBUS device in this repository must follow these requirements:

1. Dynamic Modbus ID Virtual Component. The device's Modbus slave/unit ID must never be hardcoded into the script logic — it must be exposed as a number Virtual Component so it can be reconfigured from the Shelly app without redeploying code, following the pattern established in pkgs/marstek/venus_e/revision/app.shelly.js:
   • Component config: min: 1, max: 247 (the valid Modbus unit-ID range), persisted: true (survives reboot), meta.ui.view: "field" — a precise numeric text-entry input, not "slider", since being off by even one value breaks communication with the device entirely.
   • A getSlaveId()-style helper reads the component's live value on every request (not just once at script init), clamps/rounds it into the valid range, and syncs the clamped value back to the component if it was out of range — mirroring how getControlPower() handles the Control Power component in the same script.
   • Every MODBUS frame-building function (both read and write) must call this helper for the unit-ID byte, instead of referencing a static config constant.
   • This component's mapping.json entry must carry the modbus_id role (see Roles below).

This set of requirements is not closed — more will be added as new packages establish new conventions.

Roles

Each Virtual Component entry in a package's mapping.json carries a role field — a standardized tag describing what the component semantically represents (independent of its device-specific key/name). This lets tooling reason about components generically across different vendor integrations (e.g. any component tagged battery_level means the same thing regardless of which package defines it).

The currently defined roles are:

Role	Data type	Description	Example use case
auto_balancing	boolean	Whether automatic (e.g. cell/load) balancing is enabled	Battery pack auto cell-balancing toggle
auto_start	boolean	Whether the device automatically starts/resumes operation	Generator or pump auto-start enable
average_temperature	number	An averaged temperature reading across multiple sensors	Average of several battery cell temperatures
backlight_enable	boolean	Toggle for a display's backlight	Thermostat screen backlight on/off
battery_consumption	number	Power/energy drawn from the battery	Instantaneous discharge power
battery_level	number	Battery state of charge	SOC, in %
battery_power	number	Instantaneous battery power, bidirectional (positive = discharge, negative = charge)	Marstek Pbat-style live power reading
battery_state	text	The battery's current operating state	charging / discharging / idle / fault
brightness	number	A numeric brightness/dimming level	Display or light brightness, in %
charge_command	enum	A command that triggers a charge/discharge/stop action (not a passive mode readback)	Marstek ChgCmd-style dropdown: Stop / Force Charge / Discharge
charged	boolean	Boolean flag: battery/device is fully charged	—
charging_power	number	The power setpoint applied on the next charge or discharge command (bidirectional use, despite the name)	Marstek ChgPowerSet-style control power field
close	button	Command to close an actuator	Close a valve, cover, or gate
curr_temperature	number	Deprecated — legacy alias of current_temperature; use that instead	—
current	number	Electrical current reading	Amps
current_humidity	number	The current/live relative humidity reading	—
current_limit	number	A configured maximum current limit	Charge current cap
current_temperature	number	The current/live temperature reading (preferred over curr_temperature)	—
enable	boolean	Generic on/off enable toggle for a feature/function	—
energy_charge	number	Energy delivered during a charge session	kWh charged this session
fan_mode	enum	The fan's operating mode	auto / manual / sleep
fan_speed	number	The fan's speed setting	Numeric or step level
flow_rate	number	Liquid/water flow rate	L/min
grid_consumption	number	Power/energy drawn from the utility grid	—
heater_relay_status	boolean	On/off status of a heater's relay/output	—
house_consumption	number	Total household/site power consumption	—
humidity	number	Legacy alias of current_humidity, kept for backward compatibility	Prefer current_humidity in new integrations
last_precipitation	number	Most recent recorded precipitation reading/timestamp	Weather-station rain gauge
max_charge	number	Configured maximum charge limit	Max SOC % or max charge power
modbus_id	number	The Modbus slave/unit ID address used to reach this device on the RS485 bus	Dynamic Modbus ID field required by every MODBUS package (see Requirements)
open	button	Command to open an actuator	Open a valve, cover, or gate
position	number	A numeric position value	Valve or cover position, in %
power	number	Generic instantaneous power reading	Watts
ppm	number	A parts-per-million concentration reading	CO2 / air-quality sensor
pv_consumption	number	Power/energy consumed that is sourced from a PV (solar) system	—
start_charging	button	Command to begin a charging session	—
status	text	General device status/health information	Not tied to device-specific business logic
stop	button	Generic stop command	—
switch	boolean	A generic on/off switch component	—
target_humidity	number	The desired/setpoint humidity level	—
target_temperature	number	The desired/setpoint temperature level	—
thermostat_mode	enum	The thermostat's operating mode	heat / cool / auto / off
time_charge	TBD	Meaning not yet finalized — needs a definition before use	—
total_active_energy	number	Cumulative active energy (standard electrical metering term)	kWh
total_charge	number	Cumulative (lifetime) energy charged into the battery	—
total_current	number	Total/aggregated current reading	e.g. summed across phases
total_power	number	Total/aggregated power reading	e.g. summed across phases or sources
water_consumption	number	Cumulative water usage	—
water_pressure	number	Water pressure reading	—
water_temperature	number	Water temperature reading	—
work_state	text	The device's operational state, tied to its core business logic	idle / heating / cooling / charging / discharging
working_mode	enum	The mode the device is currently operating in, usually user- or schedule-selected	manual / auto / eco / boost

status, work_state, and working_mode are related but distinct: status is general device health/info, work_state reflects the device's business-logic-driven operational state, and working_mode reflects how the device is configured to behave.

This set is not closed — new roles can be added as new integrations require them.

Contributing

Contributions are welcome — see CONTRIBUTING.md for contribution terms and guidelines.

License

Licensed under the Apache License 2.0.