go-shelly

go-shelly is an unofficial native go client for the Shelly Gen2 API. It compliments the MongooseOS mgrpc library.

Maturity

This library is currently in active development (as of December 2024). It has meaningful gaps in testing and functionality. At this stage there is no guarantee of backwards compatibility. Once the project reaches a stable state, I will begin crafting releases with semantic versioning.

Usage

In most cases, using the library is as simple building an RPC channel and calling .Do(). See the go doc and Shelly Gen2 API documentation.

import (
	"context"
	"fmt"
    "log"

	shelly "github.com/jcodybaker/go-shelly"
	"github.com/mongoose-os/mos/common/mgrpc"
)

const (
    rpcAddr = "http://192.168.1.20/rpc"
)

func main() {
    ctx := context.Background()
	c, err := mgrpc.New(ctx, rpcAddr, mgrpc.UseHTTPPost())
	if err != nil {
		log.Fatalf("establishing rpc channel: %v", err)
	}
	defer c.Disconnect(ctx)

    req := &shelly.ShellyGetStatusRequest{}
    statusResp, _, err := req.Do(ctx, c)
    if err != nil {
        log.Fatalf("querying device status: %v", err)
    }
    for i, sw := range statusResp.Switches {
        fmt.Printf("Switch %d status: %v\n", i, *sw.Output)
    }
}

TODO

• More rigorous integration testing. Currently I have a Shelly Pro 4PM, Shelly Pro 3, Shelly Plug US, and Shelly Plus HT. All are controlling live workloads and thus I've been reluctant to test mutating actions outside the needs of my own projects.
• MQTT / WebSocket examples.
• mDNS / BLE integrations for discovery and bootstrapping. Open question: Should these be in separate projects to avoid dependency bloat?
• Stabilize API
  • It's not always clear which Go types should be used for JSON Numeric values. More validation is needed to ensure these types are correctly defined.
  • In contrast to Golang, the Shelly API appears differentiate between no-value and null. For example, in some cases (ex. Wifi.SetConfig), a JSON key with null value will clear the existing configuration, while omitting the key/value entirely leaves it untouched.
• Complete API
  • Known missing: Scripts, Outbound WebSockets, ModBus, Voltmeters, Smoke, EM(data), EM1(data), PM1, UI.
  • Wrappers for easy software updates, and configuration of multi-line scripts and certificates.
• CI testing / dependabot / release pipeline.

Contributing

Pull-requests and issues are welcome. Code should be formatted with gofmt, pass existing tests, and ideally add new testing. Test should include samples from live device request/response flows when possible.

Legal

Intellectual Property

This library and its authors (Cody Baker - [email protected]) have no affiliation with Allterco Robotics (the maker of Shelly devices) or Cesanta Software Limited (the maker of MongooseOS). All trademarks are property of their respective owners. Importantly, the "Shelly" name and names of devices are trademarks of Allterco Robotics. MongooseOS and related trademarks are property of Cesanta Software Limited.

Liability

By downloading/using this open-source library you indemnify the authors of this project (J Cody Baker) from liability to the fullest extent permitted by law. There are real risks of fire, electricution, and/or bodily injury/death with these devices and connected equipment. Errors, bugs, or misinformation may exist in this software which cause your device and attached equipment to function in unexpected and dangerous ways. That risk is your responsibility.

License

Copyright 2024 J Cody Baker and licensed under the MIT license.