Integrations
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)
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. This interface is on the default port 80 port but it may be secured so you will need to provide credentials for it to operate in the form of an apikey as an http header.
You can use Postman for trying out the Rest interface or to send a simple GET you can simply type the command into a browser. For instance http://<ip address>:8081/shadeCommand?shadeId=1&command=down will close the shade with id 1.
Returns the public controller configuration
None
JSON
See GET /shades endpoint for descriptions of shade reference objects.
See GET /groups endpoint for descriptions of group reference objects.
Return Example
{
"maxShades": 32,
"maxGroups": 16,
"maxGroupedShades": 32,
"maxLinkedRemotes": 7,
"startingAddress": 515020,
"transceiver": {
"config": {
"type": 56,
"TXPin": 13,
"RXPin": 12,
"SCKPin": 18,
"MOSIPin": 23,
"MISOPin": 19,
"CSNPin": 5,
"rxBandwidth": 99.97000122,
"frequency": 433.4200134,
"deviation": 47.59999847,
"txPower": 10,
"proto": 0,
"enabled": true,
"radioInit": true
}
},
"shades": [],
"groups": []
}Returns a discovery object that contains the unique if and firmware version of the ESPSomfy RTS device. This is similar to the /controller endpoint but does not contain the configuration information. Use this endpoint as a lighter weight configuration output. The shade and group references omit the configuration data and the transceiver config is not included.
None
JSON
-
authType- The type of authentication required for a valid api key-
0= No Authentication -
1= Pin Entry -
2= Username/Password
-
-
permissions- The bitmask permissions granted with login-
0x00- All permissions including configuration -
0x01- Only the configuration functions require authentication
-
See GET /shades endpoint for descriptions of shade reference objects.
See GET /groups endpoint for descriptions of group reference objects.
Return Example
{
"serverId": "49E4AC",
"version": "v2.0.0",
"model": "ESPSomfyRTS",
"hostname": "ESPSomfyRTS",
"authType": 1,
"permissions": 0,
"shades": [],
"groups": []
}Sends a command for a group.
-
groupId- The id of the group to send the command to [1-16]. -
command- The command to send to the group.-
m | My | my- My -
u | Up | up- Up -
d | Down | down- Down
-
-
repeat- The number of repeats to send for the group. ESPSomfy RTS sends 1 frame plus 1 repeat for a total of 2 frames.
GET /groupCommand?groupId=1&command=up - Moves all the shades in the group to the full open position.
GET /groupCommand?groupId=1&command=my - Moves all the shades in the group that are currently stationary to the favorite position.
JSON reference to the group
Gets an array of groups that are configured on the device
None
JSON
-
proto- The protocol assigned to the group for transmit communication-
0= RTS -
1= RTW -
2= RTV
-
-
linkedShades- An array of shade/motor references that are members of the group
See GET /shades endpoint for descriptions of linkedShade objects.
Return Example
[
{
"groupId": 1,
"name": "My Group",
"remoteAddress": 515023,
"lastRollingCode": 120,
"bitLength": 56,
"proto": 0,
"linkedShades": [
{
"shadeId": 1,
"name": "My Awning",
"remoteAddress": 515021,
"paired": false,
"shadeType": 3,
"bitLength": 56,
"proto": 0,
"flags": 0,
"lastRollingCode": 25
},
{
"shadeId": 2,
"name": "My Blind",
"remoteAddress": 515022,
"paired": false,
"shadeType": 1,
"bitLength": 56,
"proto": 0,
"flags": 0,
"lastRollingCode": 44
},
{
"shadeId": 3,
"name": "My Shutter",
"remoteAddress": 515024,
"paired": false,
"shadeType": 4,
"bitLength": 56,
"proto": 0,
"flags": 0,
"lastRollingCode": 13
}
]
}
]Gets an apikey for future calls that are secured. As of 2.0.0 only the configuration setters check the apikey
All parameters are passed as JSON or on as parameters on the encoded url. When the authType is Pin Entry then the pin must be supplied when the authType is Password then the username and password must be supplied.
-
pin- The pin defined in the ESPSomfy RTS security configuration -
username- The username defined in the ESPSomfy RTS security configuration -
password- The password defined in the ESPSomfy RTS security configuration
You can pass all 3 but ESPSomfy RTS will only authenticate using the applicable settings.
GET /login?pin=1234&username=myUsername&password=myPassword
Example JSON Payload
{
"pin": 1234
"username": "myUser"
"password": "myPassword"
}
JSON
-
type- The authentication type used to authenticate the user -
success- true if the login was successful -
msg- A message that is displayed for the login -
apiKey- The generated api key SHA-256 hash for the login
Return Example
{
"type": 1,
"success": true,
"msg": "Login successful",
"apiKey": "9b92ba08950cd40451eeb41d8e137e3c35bc6dc6ed0b695f7a4724cfc0ba702f"
}Sends a command to the identified shade.
Parameters can be supplied on the url or as a json object on the body.
-
shadeId- Required numeric identifier for the shade 1-32. -
target- Optional target percentage [0-100] that the shade should move to if the command is not provided. -
command- Optional command value required if target is not sent. You may use any of the forms separated by '|' below.-
m | My | my- My -
u | Up | up- Up -
d | Down | down- Down -
mu | MyUp | myup- My+Up -
md | MyDown | mydown- My+Down -
ud | UpDown | updown- Up+Down -
mud | MyUpDown | myupdown- My+Up+Down -
p | Prog | prog- Prog -
s | SunFlag | sunflag- SunFlag (Turns the sun sensor on) -
f | Flag | flag- Flag (Turns the sun sensor off) -
su | StepUp | stepup- StepUp (80-bit only simulates the thumbwheel) -
sd | StepDown | stepdown- StepDown (80-bit only simulates the thumbwheel) -
fav | Favorite | favorite- Favorite (80-bit only on motors that support it) -
stop | Stop- Stop (80-bit only on motors that support it)
-
-
repeat- Optional number of repeats to be send by default ESPSomfy RTS sends 1 repeat for a total of 2 commands sent -
stepSize- Optional number between 1-127 to indicate the size of the step command (80-bit only on motors that support it)
GET /shadeCommand?shadeId=1&command=up - Moves the shade to the full open position
GET /shadeCommand?shadeId=1&target=50 - Moves the shade to 50% closed
GET /shadeCommand?shadeId=1&command=prog&repeat=40 - Opens the shade memory so it can memorize a remote.
If you are including the command structure in the body of the request
Examples of JSON request payload
{
"shadeId":1,
"command":"up",
"repeat": 2
}or...
{
"shadeId":1,
"target":"35"
}JSON
The target shade object
Returns a reference to all the configured shades
None
JSON
An array of shade reference objects
-
shadeType- The type of shade that is referenced-
0- Roller Shade -
1- Blind -
2- Drapery -
3- Awning -
4- Shutter
-
-
tiltType- The type of tilt mechanism associated with the motor-
0- None -
1- Separate tilt motor -
2- Integrated tilt mechanism -
3- Tilt only
-
-
myPos- The percentage position for the favorite (-1 is not set) -
myTiltPos- The percentage position for the favorite tilt setting (-1 is not set) -
position- The current lift position for the shade -
tiltPosition- The current tilt position for the slats -
direction- The direction that the shade is moving-
-1- Shade is moving up -
0- Shade is at rest -
1- Shade is moving down
-
-
tiltDirection- The direction that the slats are moving-
-1- Slats are opening -
0- Slats are at rest -
1- Slats are closing
-
-
flags- Bitmask for the sensor flags-
0x01- Sun sensor is on -
0x04- Sensor is in demo mode -
0x10- It is windy -
0x20- It is sunny
-
-
inGroup- Indicates whether the shade is a member of any group (true means that it is) -
proto- The protocol assigned to the motor-
0- RTS -
1- RTW -
2- RTV
-
-
target- The target lift position for the shade [0-100]. If the shade is moving this will indicate where it is destined to stop. If it is stopped this will be equal to the position. -
tiltTarget- The target tilt position for the slats [0-100]. This is the position were the slats will end up when all movement is complete. -
linkedRemotes- An array of linked remotes associated with the shade.
Example Return
[
{
"shadeId": 1,
"name": "My Awning",
"remoteAddress": 515021,
"upTime": 10000,
"downTime": 10000,
"paired": true,
"lastRollingCode": 25,
"position": 0,
"tiltPosition": 0,
"tiltDirection": 0,
"tiltTime": 7000,
"stepSize": 100,
"tiltTarget": 0,
"target": 0,
"myPos": 38,
"myTiltPos": -1,
"direction": 0,
"tiltType": 0,
"shadeType": 3,
"bitLength": 56,
"proto": 0,
"flags": 0,
"flipCommands": false,
"flipPosition": false,
"inGroup": true,
"linkedRemotes": [
{
"remoteAddress": 4886592,
"lastRollingCode": 1054
}
]
},
{
"shadeId": 2,
"name": "My Blind",
"remoteAddress": 515022,
"upTime": 10000,
"downTime": 10000,
"paired": true,
"lastRollingCode": 44,
"position": 0,
"tiltPosition": 0,
"tiltDirection": 0,
"tiltTime": 7000,
"stepSize": 100,
"tiltTarget": 0,
"target": 0,
"myPos": 63,
"myTiltPos": 84,
"direction": 0,
"tiltType": 2,
"shadeType": 1,
"bitLength": 56,
"proto": 0,
"flags": 0,
"flipCommands": false,
"flipPosition": false,
"inGroup": true,
"linkedRemotes": [
{
"remoteAddress": 4886593,
"lastRollingCode": 1357
}
]
},
{
"shadeId": 3,
"name": "My Shutter",
"remoteAddress": 515024,
"upTime": 10000,
"downTime": 10000,
"paired": true,
"lastRollingCode": 13,
"position": 0,
"tiltPosition": 0,
"tiltDirection": 0,
"tiltTime": 7000,
"stepSize": 100,
"tiltTarget": 0,
"target": 0,
"myPos": -1,
"myTiltPos": -1,
"direction": 0,
"tiltType": 0,
"shadeType": 4,
"bitLength": 56,
"proto": 0,
"flags": 0,
"flipCommands": false,
"flipPosition": false,
"inGroup": true,
"linkedRemotes": [
{
"remoteAddress": 4886594,
"lastRollingCode": 1315
}
]
},
{
"shadeId": 4,
"name": "My Shade",
"remoteAddress": 515025,
"upTime": 10000,
"downTime": 10000,
"paired": true,
"lastRollingCode": 4,
"position": 32,
"tiltPosition": 0,
"tiltDirection": 0,
"tiltTime": 7000,
"stepSize": 100,
"tiltTarget": 0,
"target": 32,
"myPos": -1,
"myTiltPos": -1,
"direction": 0,
"tiltType": 0,
"shadeType": 0,
"bitLength": 56,
"proto": 0,
"flags": 0,
"flipCommands": false,
"flipPosition": false,
"inGroup": false,
"linkedRemotes": [
{
"remoteAddress": 4886595,
"lastRollingCode": 14415
}
]
}
]Tilts the slats for a blind
-
shadeId- The id of the shade to send the command to [1-32]. -
command- Optional tilt command to send to the shade. You must supply the target or the command.-
m | My | my- My -
u | Up | up- Up -
d | Down | down- Down -
su | StepUp | stepup- StepUp (80-bit only simulates the thumbwheel) -
sd | StepDown | stepdown- StepDown (80-bit only simulates the thumbwheel)
-
-
target- Optional target for the slat position [0-100]. -
repeat- The number of repeats to send for the shade. ESPSomfy RTS sends 1 frame plus 1 repeat for a total of 2 frames.
GET /tiltCommand?shadeId=1&command=up - Tilts the slats open.
GET /tiltCommand?shadeId=1&command=my - Moves the slats to the favorite position if stationary or stops the movement if moving.
GET /tiltCommand?shadeId=1&target=35 - Moves the slats to 35%.
JSON reference to the group
Sets the recorded position of the motor without moving the motor. This is handy for situations where other sensors are used to identify the final position of the motor. For instance, if you have a tilt sensor on a garage door or a magnetic sensor on a gate you can use this to tell ESPSomfy RTS that the position is closed or open depending on the sensor status.
-
shadeId- The id of the shade to set the position for [1-32]. -
position- Optional lift position from 0-100%. -
tiltPosition- Optional tilt position from 0-100%.
GET /setPositions?shadeId=1&position=50 - Sets the lift position to 50%.
GET /setPositions?shadeId=1&liftPosition=50 - Sets the lift position to 50%.
You can also send this information as a json payload.
JSON reference to the shade
Sends a sensor frame to the motor. These can be sent for either a shade or a group to simulate either an Eolis or Sunis sensor. You can create your own wind or sun sensors and have the motor act on these. See the documentation for the Sunis Sun/Wind sensor.
For most motors if you tell it that it is windy it will retract for at least 2 minutes after the first calm signal is sent. If you tell the motor that it is sunny it will extend the shade 2 minutes after receiving this signal and retract 20 minutes after the sunny condition is cleared. This works in conjunction with the sun flag setting on the motor. So it will only retract and extend when the sun flag is activated.
This works for either groups or shades depending on whether you send the group id or the shade id.
-
shadeId- The id of the shade to set the sunny or windy attributes [1-32]. -
groupId- The id of the group to set the sunny or windy attributes [1-16]. -
sunny- 1 for sunny 0 for not sunny. -
windy- 1 for windy 0 for calm.
GET /setSensor?shadeId=1&windy=1 - Tells the shade that there is a windy condition.
GET /setSensor?groupId=1&windy=1 - Tells a group that there is a windy condition.
GET /setSensor?shadeId=1&windy=0&sunny=1 - Tells the shade that it is sunny and calm.
GET /setSensor?groupId=1&windy=0&sunny=1 - Tells a group that it is sunny and calm.
You can also send this information as a json payload.
The example below tells the motor that it is sunny and calm so act accordingly.
{
"shadeId": 1,
"windy": 0,
"sunny": 1
}The example below tells the group members that it is sunny and calm so act accordingly.
{
"groupId": 1,
"windy": 0,
"sunny": 1
}JSON reference to the shade or group
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.
ESPSomfy RTS publishes information related to the configured shades and groups in a hierarchical tree of topics. All ESPSomfy RTS topics are published to a root topic that you set in the configuration. At startup all topics are published but ESPSomfy RTS will only publish topic data when there is a change so you can subscribe to the topic and receive real time updates. While there is a complete list of the available topics below, you should use a tool such as MQTT Explorer when developing with MQTT. This will save you countless hours of trial and error.
Last will and Testament for the MQTT client. This will be online when the ESPSomfy RTS device is attached and offline when disconnected.
The MAC address for the network adapter in the ESPSomfy RTS device.
The ip address assigned to the ESPSomfy RTS device.
The hostname assigned to the ESPSomfy RTS device.
The current firmware version loaded onto the ESPSomfy RTS device.
Derived from the chip id in the ESP32 this uniquely identifies the ESP32 device.
The shade id
The name set for the shade
The address assigned to the shade
The shade type assigned to the shade
- 0 = Roller Shade
- 1 = Blind
- 2 = Left pull drapery
- 3 = Awning
- 4 = Shutter
- 5 = Garage (1-button)
- 6 = Garage (3-button)
- 7 = Right pull drapery
- 8 = Center pull drapery
- 9 = Dry Contact
The tilt type if the shade type is blind
- 0 = None
- 1 = Tilt Motor
- 2 = Integrated Tilt
- 3 = Tilt Only
Indicates whether up is down and down is up. Valid values are true or false
Indicates whether 100% is open or closed. Valid values are true or false
The current lift position in percentage of the motor.
The current tilt position in percentage of the motor.
The current direction of the motor movement. This will be one of the following values -1 = The shade is moving up 0 = The shade is stopped 1 = The shade is moving down
The lift position that the shade is seeking
The tilt position that the shade is seeking
The last rolling code that was used to send the last command from ESPSomfy RTS
The current favorite lift position. -1 is unset
The current favorite tilt position. -1 is unset
Indicates the existence of a sun sensor. Valid values are true or false
Indicates whether the sun sensor is enabled or not. Valid values are 0 or 1
Indicates whether the shade thinks it is sunny or not. Valid values are 0 or 1
Indicates whether the shade thinks it is windy or calm. Valid values are 0 or 1
The group id
The name set for the group
The address assigned to the group
The current direction of the member motor movement. This will be one of the following values -1 = The shades are moving up 0 = The shade are stopped 1 = The shades are moving down
The last rolling code that was used to send the last command from ESPSomfy RTS
Indicates the existence of a sun sensor for at least one member of the group. Valid values are true or false
Indicates whether the sun sensor is enabled or not for at least one member of the group. Valid values are 0 or 1
Indicates whether the group thinks it is sunny or not. Valid values are 0 or 1
The whether the group thinks it is windy or calm. Valid values are 0 or 1
ESPSomfy RTS subscribes to topics on your MQTT broker. These topics are responded to immediately so please do not set a retain flag or a QoS greater than 0 for these. If you do, when ESPSomfy RTS connects to the broker it will send these commands again and just booh. Also, do not publish to topics that are published by ESPSomfy RTS. These topics should be read only in that you should only subscribe to those topics. Publishing data to those topics will have you pulling your hair out.
Moves the shade in the direction of the numeric payload. This can be 0 for stop or toggle, 1 for down, and -1 for up.
To move the shade up, down, or stop set the {root topic}/shades/{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.
Moves a shade to the position of the numeric payload from 0 to 100 percent where 0 equals fully open and 100 equal fully closed.
Moves a shade tilt to the position of the numeric payload from 0 to 100 percent where 0 equals fully open and 100 equal fully closed.
Sets the my position for the shade in percentage from 0-100 or clears the my position if you set the value to the current mypos.
Sets the my position for the shade tilt if the shade has a tilt type from 0-100 or clears the my position for the tilt if you set the value to the current myTiltPos.
Sets the current position of the shade. This will not move the motor it only sets the current synchronized position.
Sets the current tilt position of the shade. This will not move the motor it only sets the current synchronized position.
Turns the sun flag on or off for the shade. A value of 1 turns on the sun sensor and a value of 0 turns it off.
Sets the motor sensor status to sunny or not sunny. A value of 1 sets it to sunny and 0 to not sunny.
Sets the motor sensor status to windy or calm. A value of 1 sets it to windy and 0 to calm.
Moves the members of the group in the direction of the numeric payload. This can be 0 for stop or toggle, 1 for down, and -1 for up.
To move the shade up, down, or stop set the /{root topic}/groups/{groupId}/directon/set topic to -1 for up 0 for stop or 1 for down. This will begin moving the group members in the specified direction or stop the group if you set it to 0.
Turns the sun flag on or off for the group. A value of 1 turns on the sun sensor and 0 turns it off.
Sets the member motor sensors status to sunny or not sunny. A value of 1 sets them to sunny and 0 to not sunny.
Sets the member motor sensors status to windy or calm. A value of 1 sets them to windy and 0 to calm.
ESPSomfy RTS also supports MQTT auto discovery. However, if you are using Home Assistant I suggest you use the plugin. The plugin has many more features including sensor sensor support. For other platforms that support MQTT auto discovery you may find this option gets you going quickly.
To set up auto discovery, navigate to the Network section and select Publish Discovery. Then provide the root discovery topic in the field provided.
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.