Repository navigation
Plugin shelly cloud integrator
Loads and caches configured Shelly device states from the Shelly Cloud API for OSPy and other plug-ins.
| Item | Value |
|---|---|
| Version | 1.0.8 |
| Category | Energy and building control |
| Author | Martin Pihrt |
| License | GPL-3.0 |
| OSPy |
3.0.211 or newer |
| Python |
3.8 or newer |
| Permissions | network |
| Hardware | No dedicated hardware requirement declared |
| Dependencies | None |
| Python/OS packages |
requests (required) |
| Interfaces | Mobile API v1 |
| Source | Open the plug-in directory |
Loads and caches configured Shelly device states from the Shelly Cloud API for OSPy and other plug-ins.
Tested in Python 3+
The plug-in includes a plugin.json manifest and reports its worker, Shelly server, configured, loaded and online devices, retry state, latest request and errors through the OSPy system health interface. The cloud authorization key is not included in diagnostics or the settings JSON endpoint.
How to get the latest device status via Shelly Cloud API and curl. Path: https://server_uri/device/status. Supported methods: GET and POST. Parameters are supplied via query or request body Required data to send the request: Target device ID: key = "id" account authentication key: key = "auth_key" The result is a JSON object with the device status. The server URL where all the devices and client accounts are located. This can be obtained from Shelly > User Settings > Cloud Authorization Key.
The settings page manages devices individually instead of asking for a sensor count. Add new Shelly opens a new-device editor, Edit changes only the selected configuration and Delete removes only that configuration after confirmation without deleting the physical Shelly device or its cloud account. Existing parallel-list settings remain the persisted compatibility format, and migration adds stable internal identifiers while preserving device order, enabled state, labels, Shelly IDs, types, generation, reading source, local addresses and add-on labels.
The device overview can be displayed as a compact list or responsive cards. The selected view is saved in the plug-in settings and does not alter measurements, cached data or integrations that identify devices by Shelly ID.
The internal Shelly device service exposes snapshots of both cached readings and configured device identities. Dependent plug-ins can therefore distinguish a missing or disabled device from an enabled device that is still waiting for its first reading. Reading the service before the worker starts safely returns an empty cache.
Shelly 2.5 reports its shared voltage consistently in roller and switch modes over both cloud and local connections. Status output uses that value directly and no longer references a channel-specific variable that is not provided by Shelly 2.5. Local switch mode reads its IP address and RSSI from the standard wifi object. Shelly 2PM Add-on and Shelly 1PM Add-on status lines display both the actual RSSI and update timestamp in their correct fields.
The add and edit form, compact list and responsive cards show a local preview image for every supported device type. Selecting a different device type or generation updates the editor preview immediately, and selecting an image opens the matching official Shelly Knowledge Base page in a new tab. Preview files are stored locally with the plug-in, so the settings page does not depend on loading images from an external server.
-
Server uri: The server URL where all the devices and client accounts are located. This can be obtained from Shelly > User Settings > Cloud Authorization Key.
-
Auth key: This can be obtained from Shelly > User Settings > Cloud Authorization Key.
-
Request interval: Shelly cloud data download recovery interval.
-
Use sensor: If you do not want to use the sensor but do not want to delete it in the list, uncheck the box.
-
Label for Shelly sensor: Your Shelly designation (Shelly will be available in the OSPy system under this designation).
-
Shelly sensor ID: Unique ID number to identify Shelly devices. It can be found in the Shelly device settings or on the Shelly manufacturer's cloud site: https://control.shelly.cloud after logging in, click on the desired device and the "device information" section.
-
Shelly sensor type: Shelly Plus HT, Shelly Plus Plug S, Shelly Pro 2PM, Shelly Pro 3EM and Shelly 3EM-63T Gen3. The three-phase meters expose power, reverse power, voltage, current, power factor and accumulated energy for every phase, including total power and total energy for use by other OSPy plug-ins.
-
Status: Status window from the plugin.
Shelly API:
The following notes are generated from the help page shipped with this plug-in. Field names are also explained directly in the OSPy settings page.
This extension adds integration of Shelly devices into the OSPy ecosystem. After setting up this extension and adding devices, these devices will appear in OSPy sensors and you will be able to work with them further.
How to get the latest device status via Shelly Cloud API and curl.
Path: https:// <***server_uri > /device/status.
Supported methods: GET and POST.
Parameters are supplied via *query or **request body
Required data to send the request:
Target device ID: key = "id"
**** account authentication key: key = "auth_key"
The result is a JSON object with the device status.
The server URL where all the devices and client accounts are located. This can be obtained from Shelly > User Settings > Cloud Authorization Key.
Shelly API
Reading data over the local network
From devices that are permanently connected to the local network (Wi-Fi or LAN), data can be read directly outside the Shelly cloud. The advantage is that data can be read regardless of the cloud provider, i.e. Shelly cloud API. This method cannot be used for devices that sleep and wake up (for example shelly H&T, etc.) and are not permanently connected to the network.
In the device settings (for devices that support it) there is an option to select reading: cloud or locally.
Example of reading data over the local network for a gen1 device. http://IP/status
Example of reading data over the local network for a gen2+ device. http://IP/rpc/Shelly.GetStatus
If you do not want to use the cloud, but only the local network, fill in at least 5 arbitrary characters. Some devices are not available on the local network (e.g. Wi-FI H&T).
Managing Shelly devices
The settings page manages every Shelly device individually. Add new Shelly opens an empty editor, Edit changes only the selected device and Delete removes only the selected configuration after confirmation. The physical Shelly device and its Shelly Cloud account are never deleted.
Existing installations are migrated automatically from the previous sensor-count configuration. Device order, enabled state, labels, Shelly IDs, types, generation, reading source, local address and add-on labels are preserved, while an internal stable identifier is added for safe editing and deletion.
Choose List for a compact table or Cards for a responsive device overview. The selected display mode is saved and does not affect measurement, cached readings or integrations with other OSPy plug-ins.
Dependent plug-ins can identify configured Shelly devices before their first reading is cached. This lets them wait and retry without incorrectly reporting that an enabled device is missing.
Shelly 2.5 is supported in roller and switch modes through cloud or local reading. Its shared voltage, local network address and RSSI are read from the corresponding device response.
A local device preview is shown in the add and edit form, list and cards. Changing the selected device type or generation updates the preview immediately. Select the image to open the matching official Shelly Knowledge Base page in a new tab.
Check OSPy → Diagnostics first and remove passwords, tokens, private addresses and other secrets before sharing logs. Report reproducible plug-in problems in the OSPy-plugins issue tracker.
Start
Reference
Catalog sections