Shelly binding - support shelly 1 plus

Add-ons Bindings
7

EDITED 19.01 due to better understanding of return payloads

Getting into the entire home automation as of recently, and faced the same obstacle of binding and connecting with a Shelly Plus 1. The posts by @Michael_Andres and @xsived didn’t work entirely, but they were valuable breadcrumps, so I figured I would contribute for everyone else who comes across this thread trying to deal with the Shelly Plus 1 and its API. (I kind of get why it’s shaped as it is, but What The Hell Documentation…)

Enviroment

  • Shelly Plus 1, Firmware 0.9.2
  • Raspberry Pi 4
  • openHAB 3.2 on openhabian
    • MQTT Binding 3.2.0
    • Mosquitto MQTT Broker, version 2.0.11, via the openhabian configuration tool

Shelly Configuruation

  • Connection Type was MQTT
  • Device name was as generated, so shellyplus1-<alphanumerics> though one should be able to change this without much issue… just didn’t want to touch this after everything else worked fine.
  • RPC status notifications over MQTT was enabled
  • Generic status update over MQTT was disabled
  • broker and IP was set as normal
  • as were the credentials

Channel Configuration

This channel configuration can be done with either code or over the UI with advanced settings shown.

State Topic was <shelly-name>/events/rpc. On this topic the Shelly publishes JSON files whenever events happen to it, such as that the connected switch is operated manually.

CommandTopic was <shelly-name>/rpc.

QoS was set to “Exactly once”.

Retained was on.

IsCommand was Off.

Custom On/Open Value was true. Custom Off/Closed Value was false.

Incoming Value Transformation should be set to JSONPATH:$params.switch:0.output to get the status of the relay. ( JSONPATH:$params.input:0.state gets you the event properties of the switch input to the Shelly)

Outgoing Value Transformation was empty.

Outgoing Value Format was {"id":123,"src":"light","method":"Switch.Set", "params":{"id":0,"on":%s}}

To explain this format a bit. One must provide an ID and source statement. The ID statement is basically arbitrary but is supposed to let different command entities be differentiated. The src statement will be used for publishing a return message on the MQTT topic <shelly-name>/<src-argument>/rpc sent by the Shelly on reception of one’s command message. This will be a message about the previous state of the switch if successfull, and an error message if the JSON is invalid. One must provide a method argument, and then a params JSON object. This object contains the ID of the switch (in the case of the Shelly Plus 1, this is just “0”) and a boolean statement about whether the switch being on is true, or false.

If this fails to work, chances are

  • one isn’t publishing messages to the right topic where the Shelly is actually listening. In this case it can help to have the MQTT broker log all subscription and messaging activities, which will include subscription messages from the Shelly, or have a Broker that can provide this information to you over some UI.
  • one is subscribed to the wrong topic for getting the event messages the Shelly posts when it is controlled through a hardwired (light) switch, or reading the JSON incorrectly. In this case, use console utilities like mosquitto_sub subscribe to the topic where the Shelly is posting events and read out the JSON for yourself, or again, use other MQTT tools to get a handle on the traffic that’s happening.

Doing those two things is what ultimately solved it for me.

In the case of this set-up, when the manual light switch was used, the Shelly posted two updates over the topic <shelly-name>/events/rpc. One was this:

{
	"src": "shellyplus1-<name>",
	"dst": "shellyplus1-<name>/events",
	"method": "NotifyStatus",
	"params": {
		 "ts": <number>,
		 "input:0": {
			 "id": 0,
			 "state": <boolean>
		 }
	}
}

this informs you about the state of the input:0 switch input to the Shelly, you might have wired a light switch to that one.

Another one has a format like this:

{
	"src": "shellyplus1-<name>",
	"dst": "shellyplus1-<name>/events",
	"method": "NotifyStatus",
	"params": {
		"ts": <number>,
		"switch:0": {
			"id": 0,
			"output": <boolean>,
			"source": "switch"
		}
	}
}

this is the interesting one if you want the current output status, be it due to your own commands or because the lightswitch was used to toggle the Shelly via hardware. Hence JSONPATH:$params.switch:0.output is the correct incoming value transform.

this is all of as 0.9.2, and Shelly seems to be pushing out new versions all the time, so this may stop working at some point.

I hope this helps some people.

4 Likes