Mastering Shelly IoT Devices: A Comprehensive Guide to the Shelly RPC BLE Client Script

Introduction

In this in-depth guide we’ll be using the Shelly RPC BLE Client script to interact with Shelly IoT devices over Bluetooth Low Energy (BLE). Shelly devices are renowned for their versatility and ease of integration into smart home ecosystems. This guide aims to educate users on leveraging a Python script to scan for Shelly devices, execute Remote Procedure Calls (RPC), and manage device configurations seamlessly. This script is user-friendly with options for device selection and pre-defined commands as well as running custom RPC commands.. In case you want a more streamlined script that just runs the custom RPC command, please refer to this version of the script.

Prerequisites

Before diving into the script, ensure you have the following:

• Linux Machine using Ubuntu or another Linux distro.

• Python 3.8 or higher installed on your system.

• Bluetooth Low Energy (BLE) support on your machine.

• Python packages: Install the required packages using the command:

pip install -r requirements.txt

The requirements.txt should include:

• asyncio

• bleak

• colorama

• prettytable

• yaspin

• jq utility installed for JSON formatting (optional but recommended).

Understanding the Script

The Shelly RPC BLE Client script is a Python program designed to:

• Scan for nearby Shelly IoT devices using BLE.

• List discovered devices with signal strength indicators.

• Connect to a selected device.

• Execute RPC methods on the device to retrieve information or change settings.

• Handle errors gracefully and provide informative logs.

Key Features

• Interactive CLI: User-friendly command-line interface with color-coded outputs.

• Logging: Detailed logs are maintained in shelly_rpc.log for troubleshooting.

• Customization: Ability to input custom RPC methods and parameters.

• Retry Mechanism: Implements retries and exponential backoff for reliable communication.

Installation and Setup

Install

1. Clone the Repository

git clone https://github.com/ALLTERCO/Utilities.git
cd shelly-ble-rpc

2. Install Dependencies

Ensure you have pip installed, then run:

pip install -r requirements.txt

3. Install jq (Optional)

jq is used for pretty-printing JSON responses.

• On Ubuntu/Debian:

sudo apt-get install jq

• On macOS (using Homebrew):

brew install jq

Running the Script

Execute the script using:

python3 shelly-ble-rpc.py

Command-Line Arguments

• --scan-duration: Duration (in seconds) for scanning BLE devices. Default is 5 seconds.

• --log-level: Set logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL).

python3 shelly-ble-rpc.py --scan-duration 10 --log-level DEBUG

Navigating the User Interface

Upon running the script, you will be guided through several steps:

1. Scanning for Devices

• The script scans for nearby Shelly devices.

• Discovered devices are listed with their Name, Address, and RSSI (signal strength).

2. Selecting a Device

• Input the number corresponding to the device you wish to interact with.

• Options:

  • Enter a device number to select it.

  • Enter r to rescan for devices.

  • Enter q to quit the script.

3. Command Selection

• After selecting a device, a list of available commands is displayed.

• Commands include:

  • Shelly.ListMethods

  • Shelly.GetDeviceInfo

  • Shelly.GetStatus

  • Shelly.GetConfig

  • WiFi.SetConfig

  • WiFi.GetStatus

  • Eth.GetConfig

  • Eth.SetConfig

  • Switch.Toggle

  • Custom Command

• Options:

  • Enter a command number to execute it.

  • Enter r to go back to device selection.

  • Enter q to quit the script.

Executing Commands

1. Shelly.GetDeviceInfo

• Retrieves detailed information about the device.

• Usage: Select the command; no additional parameters required.

2. Shelly.GetStatus

• Fetches the current status of the device.

• Usage: Select the command; no additional parameters required.

3. WiFi.SetConfig

• Configures the Wi-Fi settings of the device.

• Parameters:

  • SSID: The Wi-Fi network name.

  • Password: The network password.

  • Static IP: Optionally set a static IP address, netmask, gateway, and nameserver.

Example:

Enter SSID: MyWiFiNetwork
Enter Password: mypassword
Do you want to set a static IP address? (y/n): y
Enter Static IP Address: 192.168.1.50
Enter Netmask: 255.255.255.0
Enter Gateway: 192.168.1.1
Enter Nameserver: 8.8.8.8

4. Switch.Toggle

• Toggles the state of a switch (e.g., turning a light on/off).

• Parameters:

  • ID: The ID of the switch (default is 0). If you have a device with more channels/ids you can select it.

5. Custom Command

• Allows execution of any RPC method supported by the device.

• Usage:

  • Enter the RPC method name.

  • Provide parameters as a JSON string.

Example:

Enter the RPC method name: Light.SetConfig
Enter parameters as a JSON string (or leave empty for none): {"id":0,"config":{"brightness":50}}

Advanced Usage

Logging Levels

• DEBUG: Detailed information, typically of interest only when diagnosing problems.

• INFO: Confirmation that things are working as expected.

• WARNING: An indication that something unexpected happened.

• ERROR: Due to a more serious problem, the software has not been able to perform some function.

Setting Log Level:

python3 shelly-ble-rpc.py --log-level DEBUG

Handling Timeouts and Retries

• The script automatically retries failed RPC calls with exponential backoff.

• Customization:

• Modify the retries parameter in the call_rpc method if needed.

Modifying the Script

• The script is modular, with clear separation of concerns.

• Feel free to extend functionality, such as adding new commands or improving error handling.

Troubleshooting

Common Issues

1. No Devices Found:

• Ensure your Shelly device is powered on and within range.

• Check if your BLE adapter is working properly.

2. Failed to Connect to Device:

• The device might be connected to another client.

• Retry connecting after a few moments.

3. RPC Method Not Available:

• The method might not be supported by the device firmware.

• Use Shelly.ListMethods to check available methods.

4. Invalid Arguments:

• Double-check the parameters provided for the RPC method.

• Ensure JSON strings are properly formatted.

Logs

• Check shelly_rpc.log for detailed error messages.

• Logs include timestamps and error details for easier debugging.

We Value Your Feedback!

Thank you for taking the time to read our article! Was it helpful or interesting?

Your insights can help us improve. We’d be grateful for any feedback. If you have a moment,

please share it with us at the following email:

Integration@shelly.com