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.
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": []
}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)
-
-
repeat- Optional number of repeats to be send by default ESPSomfy RTS sends 1 repeat for a total of 2 commands sent
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
}
]
}
]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.
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.
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.