-
Notifications
You must be signed in to change notification settings - Fork 41
Backup File Anatomy
rstrouse edited this page Feb 25, 2024
·
6 revisions
ESPSomfy-RTS backup files are assigned a version number so that over time, additional functionality can be added while still allowing older versions of the backup files to be restored to the device. Data and record elements in this document indicate when each of them were first seen in the wild.
The backup file has evolved over time but its structure and data layout has remained consistent. It consists of a header on the first line followed by one record per line. All data in the file is represented in text format for easy reading. Each data element is delimited by a comma or end of line to signify the end of the data element with spaces padding numeric values on the left and spaces padding text values on the right. In cases where the strings are variable in length the string is bound by quotes.
21, 76, 29, 9, 276, 22, 194, 0, 77, 1, 76, 112, 74,579828
1,Kitchen , 1
2,Living Room , 2
3,Theater , 3
4,Dining Room , 4
5,Garage , 5
6,Patio , 6
7,Master , 7
8,Bedroom 1 , 8
9,Bedroom 2 , 9
1,false, 1, 842461,Over Sink , 0, 0, 56, 10000, 10000, 7000, 100, 0, 0, 0, 0, 0, 0, 0, 200, 0, -1.00000, -1.00000, 0.00000, 0.00000,false,false, 0, 0, 0, 0, 0, 0, 1
2,false, 1, 842462,Nook Left , 0, 0, 56, 10000, 10000, 7000, 100, 0, 0, 0, 0, 0, 0, 0, 0, 0, -1.00000, -1.00000, 0.00000, 0.00000,false,false, 0, 1, 0, 0, 0, 0, 1
3,false, 1, 842463,Nook Right , 0, 0, 56, 10000, 10000, 7000, 100, 0, 0, 0, 0, 0, 0, 0, 0, 0, -1.00000, -1.00000, 0.00000, 0.00000,false,false, 0, 2, 0, 0, 0, 0, 1
4,false, 1, 842464,Left Side , 0, 0, 56, 10000, 10000, 7000, 100, 0, 0, 0, 0, 0, 0, 0, 0, 0, -1.00000, -1.00000, 0.00000, 0.00000,false,false, 0, 3, 0, 0, 0, 0, 2
5,false, 1, 842465,Right Side , 0, 0, 56, 10000, 10000, 7000, 100, 0, 0, 0, 0, 0, 0, 0, 0, 0, -1.00000, -1.00000, 0.00000, 0.00000,false,false, 0, 4, 0, 0, 0, 0, 2
6,false, 0, 842466,Screen , 0, 0, 56, 10000, 10000, 7000, 100, 0, 0, 0, 0, 0, 0, 0, 0, 0, -1.00000, -1.00000, 0.00000, 0.00000,false,false, 0, 5, 0, 0, 0, 0, 3
7,false, 2, 842467,Blackout Front , 0, 0, 56, 10000, 10000, 7000, 100, 0, 0, 0, 0, 0, 0, 0, 0, 0, -1.00000, -1.00000, 0.00000, 0.00000,false,false, 0, 6, 0, 0, 0, 0, 3
8,false, 7, 842468,Blackout Back , 0, 0, 56, 10000, 10000, 7000, 100, 0, 0, 0, 0, 0, 0, 0, 0, 0, -1.00000, -1.00000, 0.00000, 0.00000,false,false, 0, 7, 0, 0, 0, 0, 3
9,false, 8, 842469,Slider , 0, 0, 56, 10000, 10000, 7000, 100, 0, 0, 0, 0, 0, 0, 0, 0, 0, -1.00000, -1.00000, 0.00000, 0.00000,false,false, 0, 8, 0, 0, 0, 0, 4
10,false, 1, 842470,Side Window , 0, 0, 56, 10000, 10000, 7000, 100, 0, 0, 0, 0, 0, 0, 0, 0, 0, -1.00000, -1.00000, 0.00000, 0.00000,false,false, 0, 9, 0, 0, 0, 0, 4
11,false, 6, 842471,Car 1 , 0, 0, 56, 10000, 10000, 7000, 100, 0, 0, 0, 0, 0, 0, 0, 0, 0, -1.00000, -1.00000, 0.00000, 0.00000,false,false, 0, 10, 0, 0, 0, 0, 5
12,false, 5, 842472,Car 2 , 0, 0, 56, 10000, 10000, 7000, 100, 0, 0, 0, 0, 0, 0, 0, 0, 0, -1.00000, -1.00000, 0.00000, 0.00000,false,false, 0, 11, 0, 0, 0, 0, 5
13,false, 6, 842473,Golf Stall , 0, 0, 56, 10000, 10000, 7000, 100, 0, 0, 0, 0, 0, 0, 0, 0, 0, -1.00000, -1.00000, 0.00000, 0.00000,false,false, 0, 12, 0, 0, 0, 0, 5
14,false, 8, 842474,Slider , 0, 0, 56, 10000, 10000, 7000, 100, 0, 0, 0, 0, 0, 0, 0, 0, 0, -1.00000, -1.00000, 0.00000, 0.00000,false,false, 0, 13, 0, 0, 0, 0, 7
15,false, 1, 842475,Side Left , 0, 0, 56, 10000, 10000, 7000, 100, 0, 0, 0, 0, 0, 0, 0, 0, 0, -1.00000, -1.00000, 0.00000, 0.00000,false,false, 0, 14, 0, 0, 0, 0, 7
16,false, 1, 842476,Side Right , 0, 0, 56, 10000, 10000, 7000, 100, 0, 0, 0, 0, 0, 0, 0, 0, 0, -1.00000, -1.00000, 0.00000, 0.00000,false,false, 0, 15, 0, 0, 0, 0, 7
17,false, 3, 842477,Left Side , 0, 0, 56, 10000, 10000, 7000, 100, 0, 0, 0, 0, 0, 0, 0, 0, 2, -1.00000, -1.00000, 0.00000, 0.00000,false,false, 0, 16, 0, 0, 0, 0, 6
18,false, 3, 842478,Right Side , 0, 0, 56, 10000, 10000, 7000, 100, 0, 0, 0, 0, 0, 0, 0, 0, 2, -1.00000, -1.00000, 0.00000, 0.00000,false,false, 0, 17, 0, 0, 0, 0, 6
19,false, 1, 842479,Front Window , 0, 0, 56, 10000, 10000, 7000, 100, 0, 0, 0, 0, 0, 0, 0, 0, 0, -1.00000, -1.00000, 0.00000, 0.00000,false,false, 0, 18, 0, 0, 0, 0, 8
20,false, 1, 842480,Side Window , 0, 0, 56, 10000, 10000, 7000, 100, 0, 0, 0, 0, 0, 0, 0, 0, 0, -1.00000, -1.00000, 0.00000, 0.00000,false,false, 0, 19, 0, 0, 0, 0, 8
21,false, 1, 842481,Front Window , 0, 0, 56, 10000, 10000, 7000, 100, 0, 0, 0, 0, 0, 0, 0, 0, 0, -1.00000, -1.00000, 0.00000, 0.00000,false,false, 0, 20, 0, 0, 0, 0, 9
22,false, 1, 842482,Side Window , 0, 0, 56, 10000, 10000, 7000, 100, 0, 0, 0, 0, 0, 0, 0, 0, 0, -1.00000, -1.00000, 0.00000, 0.00000,false,false, 0, 21, 0, 0, 0, 0, 9
0, 0, 0, 0, 0, 0, 0
"v2.4.0","ESPSomfyS3-2","pool.ntp.org","PST8PDT,M3.2.0,M11.1.0",true ,true
1,true ,"192.168.1.183","192.168.1.1","255.255.255.0","192.168.1.1","0.0.0.0", 0, 0, 0, 0, -1, 23, 18
true , 0, 56, 8, 9, 7, 44, 4, 5, 433.420, 99.97, 47.60, 10
To ensure ESPSomfy-RTS does not try to digest an invalid file, the total size is calculated for all records in the file as well as each record length is verified. While this cannot catch all possible cases of a corrupt file it does capture any instances of incomplete or incorrect files while still allowing it to be edited.
Each data element in the header record is fixed length followed by a comma. The end of the record is signified by a new line. The header record will always be the first line in the file.
| Name | Length | Comments | HDR Version |
|---|---|---|---|
| Version | 3 | This is the version of the backup file | 1+ |
| Header Length | 3 | The total length of the header | 1+ |
| Room Rec Length | 5 | The total length of a single room record | 19+ |
| Room Rec Count | 3 | The number of room records in the file | 19+ |
| Shade Rec Length | 5 | The total length of a single shade record | 1+ |
| Shade Rec Count | 3 | The number of shade records in the file | 1+ |
| Group Rec Length | 5 | The total length of a single group record | 10+ |
| Group Rec Count | 3 | The number of group records in the file | 10+ |
| Repeater Rec Length | 5 | The total length of 7 repeater addresses | 21+ |
| Repeater Rec Count | 3 | The number of repeater dictionary records in the file | 21+ |
| Settings Rec Length | 5 | The total length of the settings record | 10+ |
| Network Rec Length | 5 | The total length of the network record | 13+ |
| Radio Rec Length | 5 | The total length of the radio record | 13+ |
| Chip Id | 9 | The hex chip id for the ESP32 | 13+ |
There will be one room record for each room shade. All data in a room record is fixed length and each record must match the length defined in the header record.
| Name | Length | Comments | HDR Version |
|---|---|---|---|
| Room Id | 3 | The identifier assigned to the room 1-16 | 19+ |
| Name | 20 | The name assigned to the room | 19+ |
| Sort Order | 3 | The order in which to display in the interface | 19+ |
There will be one shade record for each configured shade. All data in a shade record is fixed length and each record must match the length defined in the header record.
| Name | Length | Comments | HDR Version |
|---|---|---|---|
| Shade Id | 3 | The identifier assigned to the shade 1-32 | 1+ |
| Paired | 5 | Indicates whether the shade is paired or not. true or false | 1+ |
| Shade Type | 3 | Numeric value for the shade type 0 = roller, 1 = blind, 2 = ldrapery, 3 = awning, 4 = shutter, 5 = garage (one button), 6 = garage (3 button), 7 = rdrapery, 8 = cdrapery, 9 = drycontact | 1+ |
| Address | 10 | The address assigned to the shade | 1+ |
| Name | 20 | The name assigned to the shade | 1+ |
| Tilt Type | 3 | Numeric value for the tilt type 0 = None, 1 = tiltmotor, 2 = integrated, 3 = titlonly, 4 = euromode | 3+ |
| Protocol | 3 | Numeric value for the protocol 0 = RTS, 1 = RTW, 2 = RTV, 8 = GP_Relay, 8 = GP_Remote | 6+ |
| Bit Length | 3 | Either 56 or 80 | 1+ |
| Up Time | 10 | The timing in ms | 1+ |
| Down Time | 10 | The timing in ms | 1+ |
| Tilt Time | 10 | The timing in ms | 1+ |
| Step Size | 5 | The relative size used for step calculations 1-1000 | 5+ |
| Linked Remote 1 | 10 | The address of the remote | 1+ |
| Linked Remote 2 | 10 | The address of the remote | 1+ |
| Linked Remote 3 | 10 | The address of the remote | 1+ |
| Linked Remote 4 | 10 | The address of the remote | 1+ |
| Linked Remote 5 | 10 | The address of the remote | 1+ |
| Linked Remote 6 | 10 | The address of the remote | 4+ |
| Linked Remote 7 | 10 | The address of the remote | 4+ |
| Rolling Code | 5 | The last rolling code used by ESPSomfy RTS | 1+ |
| Flags | 3 | A bitmask of the sensor data | 8+ |
| My Pos | 12 | The currently stored my position to 5 decimal places. -1.0 is not set. | 1+ |
| My Tilt Pos | 12 | The currently stored my tilt position to 5 decimal places -1 is not set | 4+ |
| Current Pos | 12 | The current lift position of the motor to 5 decimal places 0-100 | 1+ |
| Current Tilt Pos | 12 | The current tilt position of the motor to 5 decimal places 0-100 | 1+ |
| Flip Commands | 5 | Indicates whether up is down and down is up. true or false | 9+ |
| Flip Position | 5 | Indicates whether 0% is closed or open. true or false | 10+ |
| Repeats | 3 | The number of repeats to send when sending a command | 12+ |
| Sort order | 3 | The sort order to be shown in the interface | 13+ |
| GPIO Up | 3 | The GPIO pin assigned to the up command if a GP_* type | 15+ |
| GPIO Down | 3 | The GPIO Pin assigned to the down command if a GP_* type | 15+ |
| GPIO My | 3 | The GPIO Pin assigned to the my command if a GP_* type | 16+ |
| GPIO Flags | 3 | Flags associated with the pin configuration for GP_* types. Bit 1 indicates whether the pins use a low level trigger | 17+ |
| Room Id | 3 | The id of the room that the shade belongs to | 19+ |
Group records follow the shade records in the file. There is one group record per line and each data element is fixed length. Prior to header version 10 groups did not exist and there will be no group records in the file.
| Name | Length | Comments | HDR Version |
|---|---|---|---|
| Group Id | 3 | The id assigned to the group 0-16 | 10+ |
| Group Type | 3 | This is currently only 0 | 10+ |
| Address | 10 | The remote address assigned to the group | 10+ |
| Name | 20 | The name assigned to the group | 10+ |
| Protocol | 3 | Numeric value for the protocol 0 = RTS, 1 = RTW, 2 = RTV, 8 = GP_Relay, 8 = GP_Remote | 10+ |
| Bit Length | 3 | Either 56 or 80 | 10+ |
| Member Id 1 | 3 | The id of the shade member | 10+ |
| Member Id 2 | 3 | The id of the shade member | 10+ |
| Member Id 3 | 3 | The id of the shade member | 10+ |
| Member Id 4 | 3 | The id of the shade member | 10+ |
| Member Id 5 | 3 | The id of the shade member | 10+ |
| Member Id 6 | 3 | The id of the shade member | 10+ |
| Member Id 7 | 3 | The id of the shade member | 10+ |
| Member Id 8 | 3 | The id of the shade member | 10+ |
| Member Id 9 | 3 | The id of the shade member | 10+ |
| Member Id 10 | 3 | The id of the shade member | 10+ |
| Member Id 11 | 3 | The id of the shade member | 10+ |
| Member Id 12 | 3 | The id of the shade member | 10+ |
| Member Id 13 | 3 | The id of the shade member | 10+ |
| Member Id 14 | 3 | The id of the shade member | 10+ |
| Member Id 15 | 3 | The id of the shade member | 10+ |
| Member Id 16 | 3 | The id of the shade member | 10+ |
| Member Id 17 | 3 | The id of the shade member | 10+ |
| Member Id 18 | 3 | The id of the shade member | 10+ |
| Member Id 19 | 3 | The id of the shade member | 10+ |
| Member Id 20 | 3 | The id of the shade member | 10+ |
| Member Id 21 | 3 | The id of the shade member | 10+ |
| Member Id 22 | 3 | The id of the shade member | 10+ |
| Member Id 23 | 3 | The id of the shade member | 10+ |
| Member Id 24 | 3 | The id of the shade member | 10+ |
| Member Id 25 | 3 | The id of the shade member | 10+ |
| Member Id 26 | 3 | The id of the shade member | 10+ |
| Member Id 27 | 3 | The id of the shade member | 10+ |
| Member Id 28 | 3 | The id of the shade member | 10+ |
| Member Id 29 | 3 | The id of the shade member | 10+ |
| Member Id 30 | 3 | The id of the shade member | 10+ |
| Member Id 31 | 3 | The id of the shade member | 10+ |
| Member Id 32 | 3 | The id of the shade member | 10+ |
| Repeats | 3 | The number of repeats to send when sending a command | 12+ |
| Sort Order | 3 | The order in which to display in the interface | 13+ |
| Room Id | 3 | The id of the room that the group belongs to | 19+ |
The repeaters are stored in the file in sets of 7. Currently only one repeater record (7 repeaters) are available for setup.
| Name | Len | Comments | HDR Version |
|---|---|---|---|
| Repeater Address 1 | 10 | The id of the shade member | 21+ |
| Repeater Address 2 | 10 | The id of the shade member | 21+ |
| Repeater Address 3 | 10 | The id of the shade member | 21+ |
| Repeater Address 4 | 10 | The id of the shade member | 21+ |
| Repeater Address 5 | 10 | The id of the shade member | 21+ |
| Repeater Address 6 | 10 | The id of the shade member | 21+ |
| Repeater Address 7 | 10 | The id of the shade member | 21+ |
The general settings record contains stored public information from the System tab. Prior to header version 10 this record was not included in the file. Unlike the shade and group records this record contains variable length string data encapsulated in quotes. The total length of the record must match the defined length on the header record.
| Name | Type | Len | Comments | HDR Version |
|---|---|---|---|---|
| Firmware | String | Variable | The firmware version at the time of the backup | 10+ |
| Hostname | String | Variable | The hostname configured for the mDNS | 10+ |
| Time Server | String | Variable | The url for the time server | 10+ |
| Time Zone | String | Variable | NTP Time zone setting | 10+ |
| SSDP Cast | Boolean | 5 | true or false indicating whether to broadcast over SSDP | 10+ |
The network adapter settings record is used primarily to store information related to the configuration of the network adapter. Prior to header version 13, this record was not included in the file. No SSID or passphrase data is contained in the file to preserve security and ensure current sensitive connection information is not overwritten.
| Name | Type | Len | Comments | HDR Version |
|---|---|---|---|---|
| Connect Type | Number | 3 | 0 = Unset, 1 = WiFi, 2 = Ethernet, 3 = Ethernet Preferred | 13+ |
| DHCP | Boolean | 5 | Indicates whether to use DHCP or not. true or false | 13+ |
| IP Address | String | Variable | The IP Address for the device | 13+ |
| Gateway | String | Variable | The gateway address for the network | 13+ |
| Subnet | String | Variable | The subnet mask assigned to the device | 13+ |
| DNS1 | String | Variable | The DNS server address | 13+ |
| DNS2 | String | Variable | The alternate DNS server address | 13+ |
| MQTT Protocol | String | Variable | The protocol used for MQTT | 21+ |
| MQTT Host | String | Variable | Hostname for the MQTT broker | 21+ |
| MQTT Port | Number | 5 | Port setting for the MQTT broker | 21+ |
| MQTT Disco | Boolean | 5 | Indicates whether the MQTT discovery topics should be published | 21+ |
| MQTT Root Topic | String | Variable | The root topic for MQTT | 21+ |
| MQTT Disco Topic | String | Variable | The discovery topic for MQTT | 21+ |
| Board Type | Number | 3 | 0 = Custom, 1 = WT32-ETH01, 2 = Olimex ESP32-POE, 3 = Olimex ESP32-PVB, 4 = LilyGO T-Internet POE, 5 = wESP32 v7+, 6 = wESP32 < v7 | 13+ |
| PHY Type | Number | 3 | 0 = LAN8720, 1 = TLK110, 2 = RTL8201, 3 = DP83848, 4 = DM9501, 5 = KZ8081 | 13+ |
| CLK Mode | Number | 3 | 0 = GPIO0 In, 1 = GPIO0 Out, 2 = GPIO16 Out, 3 = GPIO17 Out | 13+ |
| PHY Address | Number | 4 | Address of the physical adapter 0 or 1 | 13+ |
| PWR Pin | Number | 4 | GPIO power pin for the adapter | 13+ |
| MDC Pin | Number | 4 | GPIO pin assigned to the MDC of the adapter | 13+ |
| MDIO Pin | Number | 4 | GPIO pin assigned to the MDIO of the adapter | 13+ |
This record contains all the configurable settings for the transceiver and did not exist prior to header version 13. All data in this record is fixed length.
| Name | Length | Comments | HDR Version |
|---|---|---|---|
| Enabled | 5 | Indicates whether the transceiver is enabled or not. true or false | 13+ |
| Protocol | 3 | Numeric value for the protocol 0 = RTS, 1 = RTW, 2 = RTV | 13+ |
| Bit Length | 3 | Either 56 or 80 | 13+ |
| SCKPin | 3 | GPIO Pin for the transceiver | 13+ |
| CSNPin | 3 | GPIO Pin for the transceiver | 13+ |
| MOSIPin | 3 | GPIO Pin for the transceiver | 13+ |
| MISOPin | 3 | GPIO Pin for the transceiver | 13+ |
| TXPin | 3 | GPIO Pin for the transceiver | 13+ |
| RXPin | 3 | GPIO Pin for the transceiver | 13+ |
| Frequency | 10 | The base frequency assigned to the transceiver to 3 decimal places | 13+ |
| RX Bandwidth | 9 | The receive bandwidth assigned to the transceiver to 2 decimal places | 13+ |
| Deviation | 9 | The frequency deviation assigned to the transceiver to 2 decimal places | 13+ |
| TX Power | 4 | The transmit power for the transceiver | 13+ |