Skip to content

Spello Consulting Smart Device Libary

The SCSmartDevice package is designed to make it easy to integrate with Shelly and Tasmota smart switches. Specifically this library supports switches and energy meter as allows you to:

  • Get the status of a device including temperature, Mac address, etc.
  • See if a device is online or not
  • Read the current state of an input switch
  • Read the current state of an output relay
  • Read an energy meter including power, energy, voltage, current and power factor (where available)
  • Get the temperature from one or more digitial probes (connected to a Shelly Add-on)
  • Change the state of an output relay (i.e. turn on or off)
  • Respond to webhooks generated by the Shelly device, so that your app can wake immediately when an event occurs, such as an input being turned on.

The package also implements a thread safe, read only cache of the device objects (the SmartDeviceView class) and a SmartDeviceWorker thread that allows your application to asynchroniously interface with the hardware.

Shelly Devices

This package supports many device types (30 at the last count) including older models no longer sold by the vendors.

This package also isolates you from having to deal with the idiosyncrasies of the Shelly APIs. The vendor completely changed the API for generation 2 devices and later, and even with the new API it’s rather complex deal with the different model types and the API calls they support. This package includes a shelly_models.json file that defines the capabilities of each model. Use the print_model_library() method to view this information.

Tasmota Devices

This package supports Tasmota smart switches (ESP32 hardware, tasmota32 v13 API). Currently this package only supports switches (including e-meters and internal temperature probes). At a later date support will be added for periphals and matter event signaling.

Installing the package

The package is available from PyPi, so to add it to your Python project use pip:

pip install sc-smart-switch

Or better yet, use UV:

uv add sc-smart-switch

Configuration File

The library uses a YAML file for configuration. An example config file (examples/switch_config.yaml) is included in this package. See the example config page for the yaml example and a reference for each section.

Code Examples

See the Example Code navigation on the left for various code examples.

API Reference

See these pages for a detailed reference of the classes available from this package: