rshelly

The rshelly Ruby library and shelly command for managing Shelly devices on a local network.

This is an unofficial project and is not affiliated with or endorsed by Shelly Group.

The gem supports the two API families used by current Shelly devices:

• Gen1 HTTP endpoints such as /shelly, /status, /settings, /relay/0, /meter/0, and /ota.
• Gen2+ RPC methods such as Shelly.GetStatus, Shelly.GetConfig, Switch.Set, RGBW.Set, Temperature.GetStatus, Input.SetConfig, Webhook.Create, MQTT.SetConfig, and Shelly.Update.

The first target is practical management of local devices from scripts, cron jobs, and Rails apps. App-specific work such as InfluxDB writes, device name maps, and automation rules should live outside this gem.

Installation

Install the gem and its shelly command:

gem install rshelly

Or add it to a Bundler-managed project:

gem "rshelly"

For local development builds:

gem build rshelly.gemspec
gem install ./rshelly-0.1.0.gem

During development:

ruby -Ilib exe/shelly help

Requirements

rshelly requires Ruby 3.1 or newer and supports Linux and macOS. Library operations and network scanning have no external runtime dependencies.

mDNS discovery uses avahi-browse on Linux and the built-in dns-sd command on macOS. On Linux, install the package providing avahi-browse if it is not already available. Devices with HTTP or RPC authentication enabled are not currently supported.

Detailed command help is available with either form:

shelly help wifi
shelly scan --help

CLI

The CLI prints human-readable output by default. Add --json when using the command from scripts or when you want the raw structured response.

Discovery:

shelly discover
shelly discover --verify
shelly discover --verify --concurrency 64
shelly scan
shelly --timeout 0.5 scan 192.168.0.0/24 --concurrency 64
shelly --json scan 192.168.0.0/24

Discovery uses avahi-browse when available, which is the normal Linux path. On macOS it uses dns-sd. With --verify, discovered IPv4 devices are checked concurrently; the default is 32 HTTP requests at a time. scan does not depend on mDNS. It probes each IPv4 address on the current network, or on a supplied CIDR, and reports hosts that answer like Shelly devices. This is useful for devices whose mDNS responder is not currently advertising. The default command and HTTP timeout for discovery is 5 seconds. Use --timeout to tune it for faster or slower networks. External discovery commands receive one additional second to shut down cleanly. Public discovery and scan results use string keys. Verified results include the original mDNS record under the string-keyed "discovery" field.

Inspection:

shelly info 192.168.0.55
shelly status 192.168.0.55
shelly config 192.168.0.55

Switch/relay control:

shelly switch 192.168.0.54 get
shelly switch 192.168.0.54 on
shelly switch 192.168.0.54 off
shelly switch 192.168.0.54 toggle --id 0

Meters and temperature:

shelly meter 192.168.0.64
shelly temp 192.168.0.78 --id 100

RGBW:

shelly light 192.168.0.85 get --id 0
shelly rgbw 192.168.0.55 get
shelly rgbw 192.168.0.55 set --id 0 --on --white 120 --transition 3
shelly rgbw 192.168.0.55 set --id 0 --off

Firmware:

shelly update check 192.168.0.55
shelly update start 192.168.0.55

Reboot:

shelly reboot 192.168.0.55

Wi-Fi migration:

shelly wifi 192.168.0.55 secondary NewSSID 'new password'
shelly wifi 192.168.0.55 primary NewSSID 'new password' --ip 192.168.10.55
shelly wifi 192.168.0.55 primary NewSSID 'new password' --ip 192.168.10.55 --netmask 255.255.255.0 --gw 192.168.10.1 --dns 192.168.10.1

primary maps to Gen2 sta and Gen1 /settings/sta; secondary maps to Gen2 sta1 and Gen1 /settings/sta1. With --ip, the command uses static IPv4. If omitted, netmask defaults to 255.255.255.0, gateway is derived as .1 in the same /24, and DNS defaults to the gateway.

MQTT:

shelly mqtt 192.168.0.55 192.168.0.10:1883
shelly mqtt 192.168.0.55 192.168.0.10:1883 --disable

Input device setup, matching the current input_setup.rb workflow:

shelly input setup 192.168.0.70 1 --base-url http://home.home/inputs

That sets the device name to input_device_1, deletes existing webhooks, configures four inputs as buttons, and creates push, longpush, and doublepush webhooks for each input.

Escape hatches:

shelly rpc 192.168.0.55 RGBW.GetStatus '{"id":0}'
shelly gen1 192.168.0.54 /relay/0 turn=on

Ruby API

require "rshelly"

device = Shelly.client("192.168.0.55")
device.gen
device.normalized_info
device.status

device.switch_set(on: true)
device.meter_status
device.temperature_status(id: 100)
device.rgbw_set(id: 0, on: true, white: 120, transition_duration: 3)
device.update_info
device.set_wifi(slot: :secondary, ssid: "NewSSID", password: "new password")
device.set_wifi(slot: :primary, ssid: "NewSSID", password: "new password", ip: "192.168.10.55")
device.reboot

When the generation is already known, pass it to avoid the initial /shelly request before a generation-specific operation:

device = Shelly.client("192.168.0.55", generation: 2, timeout: 0.5)
device.switch_set(on: true)

Network, timeout, protocol, and TLS transport failures are raised as Shelly::HttpError. RPC error responses are raised as Shelly::RpcError.

Discovery:

Shelly.discover
Shelly.discover(verify: true)
Shelly.discover(verify: true, concurrency: 64)
Shelly.scan
Shelly.scan(network: "192.168.0.0/24", timeout: 0.5, concurrency: 64)

Low-level calls:

device.get_json("/relay/0", turn: "off")
device.rpc("Switch.Set", id: 0, on: false)

Development

Install development dependencies, run the tests, and build the gem:

bundle install
bundle exec rake test
bundle exec rake build