rshelly 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ca07a064003f9ff3a668a6843b5e1c744b3d8fc052a9f0e9f31cd59d692753c6
+  data.tar.gz: b99d16ede13379fe93b63276c39a05bb4a12348ee681abd674e71ac7f11a31e5
+SHA512:
+  metadata.gz: 734fe0ff8bd8f94d3f307f6603c1bc35e809921b6ca27e08be93e73bd550b6bb33ebfd064c6c5bde03e4081c2c1f56f642a9a6317c606d9d773f3cb1c97a3cea
+  data.tar.gz: a671a41acbec14cc49b0d9c54c8417d8a44c7d4745543976f727cf23f4e12473186ad6b5a7e804da273e772084d9a7ec79252455821b816bcb265625d073952e

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.0] - 2026-09-02
+
+### Added
+
+- Gen1 HTTP and Gen2+ RPC device clients.
+- mDNS discovery on Linux and macOS.
+- Concurrent IPv4 network scanning and verified discovery.
+- Human-readable CLI output with optional JSON output.
+- Device inspection, switch, meter, temperature, light, RGBW, firmware, reboot, Wi-Fi, MQTT, input, webhook, raw RPC, and raw Gen1 commands.
+- Normalized device information across Shelly generations.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jonas Egton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,207 @@
+# 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:
+
+```sh
+gem install rshelly
+```
+
+Or add it to a Bundler-managed project:
+
+```ruby
+gem "rshelly"
+```
+
+For local development builds:
+
+```sh
+gem build rshelly.gemspec
+gem install ./rshelly-0.1.0.gem
+```
+
+During development:
+
+```sh
+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:
+
+```sh
+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:
+
+```sh
+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:
+
+```sh
+shelly info 192.168.0.55
+shelly status 192.168.0.55
+shelly config 192.168.0.55
+```
+
+Switch/relay control:
+
+```sh
+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:
+
+```sh
+shelly meter 192.168.0.64
+shelly temp 192.168.0.78 --id 100
+```
+
+RGBW:
+
+```sh
+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:
+
+```sh
+shelly update check 192.168.0.55
+shelly update start 192.168.0.55
+```
+
+Reboot:
+
+```sh
+shelly reboot 192.168.0.55
+```
+
+Wi-Fi migration:
+
+```sh
+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:
+
+```sh
+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:
+
+```sh
+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:
+
+```sh
+shelly rpc 192.168.0.55 RGBW.GetStatus '{"id":0}'
+shelly gen1 192.168.0.54 /relay/0 turn=on
+```
+
+## Ruby API
+
+```ruby
+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:
+
+```ruby
+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:
+
+```ruby
+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:
+
+```ruby
+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:
+
+```sh
+bundle install
+bundle exec rake test
+bundle exec rake build
+```

data/exe/shelly

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+
+require "rshelly/cli"
+
+exit Shelly::CLI.new(ARGV).run