Skip to content

Integrations

Jump to bottom
rstrouse edited this page Mar 20, 2023 · 13 revisions

The primary purpose of ESPSomfy-RTS was not to build a cute little user interface for my shades as much as it is intended as a platform for integrating these shades into other platforms. To that end I have included a swiss army knife of integration options to allow you to build your own.

Integration options include:

  • Rest Commands - Representation state objects using HTTP GET, POST, and PUT commands for controlling the shades.
  • Websockets - You can subscribe to the websocket interface and it will notify you in real time of movement on the shades.
  • MQTT - A bidirection MQTT connection is available for commanding the shades as well as the current state.
  • Home Assistant - An out-of-the-box integration for Home Assistant has been created. (the primary reason for this project)

Rest Commands

There is a Rest interface built into the software for controlling the shades on port 8081. This is also used by the UI to configure the shades but the most interesting command is the shadeCommand endpoint. There is also a configuration set but that is something for another day. Look at the code if you want information on how to tweak the module, shade, radio, network, or MQTT configuration.

But for shade control this couldn't be easier and can be executed using GET, POST, or PUT http methods.

For the command parameter you can use any of the following. ESPSomfy RTS will convert these into the proper radio transmission for you.

  • U, UP, or up
  • D, DOWN, or down
  • P, Prog, or prog
  • M, My, or my
  • F, Flag, or flag
  • S, SunFlag, or sunflag
  • MyUp, or mu
  • MyDown or md
  • UpDown or ud
  • MyUpDown or mud
  • StepUp or su (80-bit only thumbwheel)
  • StepDown or sd (80-bit only thumbwheel)

When using any of the HTTP methods you can supply the command parameter on the url as follows. The shade Id is displayed on the upper right corner of the Edit Shade screen.

To send the shade in any direction: /shadeCommand?shadeId=1&command=up

You may also send an optional parameter to instruct the radio to send repeats. /shadeCommand?shadeId=1&command=prog&repeat=7

To set the shade percentage to 35% closed: /shadeCommand?shadeId=1&target=35

If you use the PUT or POST http methods you can use a JSON object on the body. For instance:

{
  "shadeId":1,
  "command":"up",
  "repeat": 2 <= Optional to repeat the command.  This will send the command 3 times with the last two being repeats.
}

or...

{ "shadeId":1, "target":"35" }

MQTT

ESPSomfy-RTS publishes attributes to your MQTT broker and subscribes to topics that allow you to control the shades. To enable your broker connect it in the configuration pages under MQTT. This will begin reporting the shade status to your broker under the topic you assigned.

image

To move the shade up, down, or stop set the /{shadeId}/directon/set topic to -1 for up 0 for stop or 1 for down. This will begin moving the shade in the specified direction or stop the shade if you set it to 0. To move the shade to a position simply set the topic /{shadeId}/target/set to the percentage closed that you would like. Where 0 equals fully open and 100 equals fully closed.

image

Home Assistant

So now we are down to the real reason for all this. I want my shades in Home Assistant. So if you are a user of Home Assist run on over to this repo and install it with HACS.

Home Assistant ESPSomfy-RTS interface

Clone this wiki locally