Mastering Shelly IoT Devices: A Comprehensive Guide to the Shelly RPC BLE Client Script
.png?inst-v=1b9b26be-f1cd-40e0-b0a7-48d2a19d1cf1)
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
Clone the Repository
git clone https://github.com/ALLTERCO/Utilities.git
cd shelly-ble-rpc
Install Dependencies
Ensure you have pip installed, then run:
pip install -r requirements.txt
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:
Scanning for Devices
The script scans for nearby Shelly devices.
Discovered devices are listed with their Name, Address, and RSSI (signal strength).
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.

Choose a device and a command
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.

Getting a response
Executing Commands
Shelly.GetDeviceInfo
Retrieves detailed information about the device.
Usage: Select the command; no additional parameters required.
Shelly.GetStatus
Fetches the current status of the device.
Usage: Select the command; no additional parameters required.
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
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.
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
No Devices Found:
Ensure your Shelly device is powered on and within range.
Check if your BLE adapter is working properly.
Failed to Connect to Device:
The device might be connected to another client.
Retry connecting after a few moments.
RPC Method Not Available:
The method might not be supported by the device firmware.
Use Shelly.ListMethods to check available methods.
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: