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)

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. 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.

GET /controller

Returns the public controller configuration

Parameters:

None

Returns

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": []
}

GET /discovery

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.

Parameters

None

Returns

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": []
}

GET|PUT|POST /groupCommand

Sends a command for a group.

Parameters

• 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.

Returns

JSON reference to the group

GET /groups

Gets an array of groups that are configured on the device

Parameters

None

Returns

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
      }
    ]
  }
]

GET|PUT|POST /login

Gets an apikey for future calls that are secured. As of 2.0.0 only the configuration setters check the apikey

Parameters

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
}

Returns

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"
}

GET|PUT|POST /shadeCommand

Sends a command to the identified shade.

Parameters

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"
}

Returns

JSON

The target shade object

GET /shades

Returns a reference to all the configured shades

Parameters

None

Returns

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
      }
    ]
  }
]

GET|PUT|POST /tiltCommand

Tilts the slats for a blind

Parameters

• 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%.

Returns

JSON reference to the group

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.

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.

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