mirror of
https://github.com/rstrouse/ESPSomfy-RTS.git
synced 2025-12-15 03:52:11 +01:00
Updated Integrations (markdown)
rstrouse
parent
abd26f2a1a
commit
0a8f43062e
1 changed files with 436 additions and 27 deletions
463
Integrations.md
463
Integrations.md
|
|
@ -7,58 +7,467 @@ Integration options include:
|
|||
* 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.
|
||||
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.
|
||||
|
||||
But for shade control this couldn't be easier and can be executed using GET, POST, or PUT http methods.
|
||||
## GET /controller
|
||||
Returns the public controller configuration
|
||||
|
||||
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)
|
||||
### Parameters:
|
||||
None
|
||||
|
||||
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.
|
||||
### Returns
|
||||
JSON
|
||||
|
||||
To send the shade in any direction:
|
||||
`/shadeCommand?shadeId=1&command=up`
|
||||
See `GET /shades` endpoint for descriptions of shade reference objects.
|
||||
|
||||
You may also send an optional parameter to instruct the radio to send repeats.
|
||||
`/shadeCommand?shadeId=1&command=prog&repeat=7`
|
||||
See `GET /groups` endpoint for descriptions of group reference objects.
|
||||
|
||||
To set the shade percentage to 35% closed:
|
||||
`/shadeCommand?shadeId=1&target=35`
|
||||
<details>
|
||||
<summary>Return Example</summary>
|
||||
|
||||
If you use the PUT or POST http methods you can use a JSON object on the body. For instance:
|
||||
```json
|
||||
{
|
||||
"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": []
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
## 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.
|
||||
|
||||
<details>
|
||||
<summary>Return Example</summary>
|
||||
|
||||
```json
|
||||
{
|
||||
"serverId": "49E4AC",
|
||||
"version": "v2.0.0",
|
||||
"model": "ESPSomfyRTS",
|
||||
"hostname": "ESPSomfyRTS",
|
||||
"authType": 1,
|
||||
"permissions": 0,
|
||||
"shades": [],
|
||||
"groups": []
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
## 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.
|
||||
|
||||
<details>
|
||||
<summary>Return Example</summary>
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"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
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
## 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`
|
||||
|
||||
<details>
|
||||
<summary>Example JSON Payload</summary>
|
||||
|
||||
```json
|
||||
{
|
||||
pin: 1234
|
||||
username: myUser
|
||||
password: myPassword
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
### 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
|
||||
|
||||
<details>
|
||||
<summary>Return Example</summary>
|
||||
|
||||
```json
|
||||
{
|
||||
"type": 1,
|
||||
"success": true,
|
||||
"msg": "Login successful",
|
||||
"apiKey": "9b92ba08950cd40451eeb41d8e137e3c35bc6dc6ed0b695f7a4724cfc0ba702f"
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
## 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
|
||||
|
||||
<details>
|
||||
<summary>Examples of JSON request payload</summary>
|
||||
|
||||
```json
|
||||
{
|
||||
"shadeId":1,
|
||||
"command":"up",
|
||||
"repeat": 2 <= Optional to repeat the command. This will send the command 3 times with the last two being repeats.
|
||||
"repeat": 2
|
||||
}
|
||||
```
|
||||
or...
|
||||
|
||||
```json
|
||||
{
|
||||
"shadeId":1,
|
||||
"target":"35"
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
### 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.
|
||||
|
||||
<details>
|
||||
<summary>Example Return</summary>
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"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
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
# 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.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue