User Interface Reference
ESPSomfy RTS implements a free-standing web server on the ESP32. Pages served by ESPSomfy RTS are built using a mobile first strategy. The expectation is that for most functions you should be able to use your finger to send commands and adjust data and the screen formatting should adjust to fit the boundaries of your device.
This web server provides two distinct operating modes Home and Configuration. The Home mode isolates the configuration from normal operation of your RTS controlled motors.
When first loading the ESPSomfy RTS user interface in your browser, the Home page is displayed. From here all configured motors can be operated and the configuration pages are obscured. Each of the items you have configured will appear in this listing with the groups appearing at the top of the list and the individual motorized devices appearing under the last group.
Each configured entity is separated by a dotted line with the name and position icons on the left and the button controls on the right.
The control display differs for each type of individual motor control. For instance, the blind below with an integrated tilt mechanism is shown below.
The position indicator shows the current lift position of a blind while the numeric percentage shows the current tilt position of the slats. To set the position of these items to a particular slider tap or click the position indicator icon and a positioner interface will appear with sliders to set each positional option on the motor.
The name you provide (Up to 20 characters) for the motor will appear here.
The my position is the saved position of the motor. When the motor is at rest pressing the my position will move this blind to 37% of closed and set the slats to 20% of closed.
The control buttons mirror the most common 3 buttons on RTS remotes. Awnings also provide a sun sensor control for enabling and disabling the sun function.
The positioner interface provides the ability to set a target position for each positional option for the motor. This interface is only available for individual motors as its definition is ambiguous for members of a group. After clicking on the position icon the positioner interface will be displayed obscuring the controls for the motor which the position is being set. If the motor(s) are currently in motion the sliders will be preset to the current target position.
To dismiss the interface either click/tap outside of its boundary or select a position with any slider.
The name of the current motor for which the position is to be set.
The current/new target lift position for the motor. Grab the circular thumb and slide left or right to set a new target position.
The current/new target tilt position for the motor if the configured device has tilt capabilities. If there is no tilt abilities for the device then this slider will not be included.
This setter provides the ability to configure the my position for the motor. RTS motors have exactly one favorite position that is stored on the motor. This position is activated by short pressing the my/stop button while the motor is at rest.
To set/unset the current my position press and hold the my button. While pressing this button it will nervously flicker. When the my position setter appears simply release the button. From this interface you can set a new my position or clear the existing one. When the interface first opens it will display the current position of the motor.
Only one favorite can be set at any given time and when the my position sliders are at the current my position the my favorite will be cleared. If the sliders are not set to the current position a new favorite will be stored in the motor. The text of the button will change to indicate which option is being performed. For instance, below this blind has the favorite set to 37% lift and 20% tilt. When both sliders are in the current position the my position is cleared and if either slider is in another position this new position will be set.
The user interface for setting a my position is designed to give you all the information required to successfully and reliably set a my position. Like the positioner interface this will appear obscuring the current controls for the target motor. However it can only be dismissed by pressing the command button or the cancel button. Clicking elsewhere or setting a slider will not dismiss the interface.
The name that was assigned to the motor.
The target lift position for the my favorite.
If the motor is equipped with a tilt position you can set the target with this slider. If the motor is not equipped with a tilt position this slider will not appear.
This button will either set or clear the my favorite position. If the slider(s) match the current lift and target position this button will appear red in color and the text will change to Clear My Position.
This display shows the current favorite set on the motor for lift and tilt (if so equipped). Clicking on the numeric percentages will move the sliders to the selected position.
TIP: If you previously had a my favorite set and ESPSomfy RTS was not installed when this favorite was set, you must choose a new favorite position that is different from the one stored on the motor. After that ESPSomfy RTS will be aware of the motor settings and be able to clear/set my favorites using the setter.
Configuration mode provides all the installer options for the ESPSomfy RTS device. There are many options available for configuring ESPSomfy RTS and as a result the user interface must have navigation controls.
The screen layout is defined below.
The current status of the network. The information displayed here will change depending on whether the device is connected using WiFi or hardwired ethernet.
Use this icon to switch between home mode or configuration mode. When in configuration mode the icon will change to a Home icon and when in Home mode it will switch to a gears icon.
The configuration is broken into 4 distinct sections. Each section allows you to define specific options related to its title.
The tabs displayed in this section reflect the available options for the selected section. It is designed to provide logical selections and targeted configuration options. This maintains an understandable level of complexity for the software.
The system section allows for base configuration of the software. In this sections items such as the primary server options, security, and firmware updates.
In the options tab you can set the following information for your ESPSomfy RTS device
This is the name that is broadcast for your device
From this dropdown you can select the timezone. Please note that not all available timezones have been included in the list. This is because this list is potentially very massive so where there are duplicate timezones only the first option in the timezone database is provided. If yours is not listed look for a city that shares your time zone.
The ESP32 does not have an integrated real time clock. As a result, it uses a timeserver to acquire the current coordinated time for your timezone. This can be configured to use a time server that is local to your network.
By checking this box ESPSomfy RTS will publish the universal plug and play interface on your network. This allows for discovery of the device on some networks. For instance, if you are running a windows environment each ESPSomfy RTS device will appear in the network section when the device is booted. Keep in mind ESPSomfy RTS will always publish itself and its services over MDNS.
The security tab allows you to configure your authentication options and permissions. While the permission list is limited, this should provide you with the ability to allow control of the ESPSomfy RTS device on your network.
When this box is checked users on the network will not need to login to the ESPSomfy RTS device to operate the configured motors. However, they will be required to login when the mode changes from Home Mode to Configuration Mode.
The security type allows you to set authentication in three specific modes. After selecting a mode the screen will change with the options available for that mode. The available modes are None, Pin Entry, and Password
No separate login required
A pin login is provided when the permissive mode is selected
A username and password login is provided when the permissive mode is selected.
The firmware tab provides all the interfaces for backing up and restoring your device as well as installing firmware updates.
The network section allows for configuration of the network interfaces to include the adapter, IP/DHCP settings, and MQTT interfaces
The adapter tab indicates how the ESPSomfy RTS device will connect to your network. From here you can indicate whether you will be using WiFi or hardwired ethernet and provide the options for either one of them.
When the Use Ethernet box is checked the configuration options for your ethernet adapter will be displayed.
From this tab you can set your ESPSomfy RTS device to use Domain Host Control Protocol (DHCP) from your router (recommended) or configure a static IP address. Honestly you should use the features of your router to reserve an address for the device. But if you are set in your old-school ways, I have provide you with this ability.
When this options is unchecked the ip address configuration will be displayed.
In this tab you can identify the MQTT broker for your configuration. ESPSomfy RTS will communicate its state to this broker and allow MQTT commands to operate the configured shades and groups.
In this section you can configure the individual shade motors and groups.
On this tab all configured awnings, roller shades, blinds, draperies, and shutters will appear in a list. As you add more motors to your configuration this list will add one line for each configured shade motor. To edit an existing one, click the pencil icon to the left of the name you assigned to it. To delete one click the trash can icon to the right of its address.
When you click either the Add Shade button or the pencil icon next to an existing shade, the screen will change to allow you to supply the attributes for the motor.
The protocol determines how ESPSomfy RTS talks to your motor. If the frequency is the same for all the motors you can mix and match the spoken protocols for the motor. The available options include
- RTS - Standard protocol for Somfy branded motors.
- RTW - This protocol has shown up in Europe under ASA Motors brand.
- RTV - Protocol variant where the motors are stamped to operate at 433.92Mhz.
Somfy RTS remotes with step wheels often use an 80-bit protocol for the step wheel. If you select this option, a step wheel timing option will also become available. The timing for the steps are determined by the movement over the up or down timing.
The type of motor determines the options that are configurable on the motor. For instance, blinds often have tilt capabilities and awnings add the ability for Sun/Wind sensors. The icons in ESPSomfy RTS will change to indicate their type.
- Roller Shade - Flat fabric cover which moves up and down by rolling the fabric on a roller that spans the width of the cover opening.
- Shutter - Shutters are a different type of roller consisting of interlocking solid panels. Often this type of cover is used for security where the left and right sides of the cover are secured.
- Blind - Adds tilt timing and mechanism functions to a standard roller shade.
- Drapery - Where the motor is mounted on the left or right to draw a curtain.
- Awning - Horizontal movement mechanism. Adds Sun/Wind sensor functions.
A unique identifier for the reference of the motor in ESPSomfy RTS. All remote addresses within the area of the shades must be unique and should not change after it has been paired with the motor. If you want to change this value after it has been paired you should first un-pair it, change it, then pair it again. ESPSomfy RTS will generate a unique address for all motors that is unique no matter how many ESPSomfy RTS devices you have built.
Up to 20 character name for your motor.
Represents how long it takes for full travel of the cover for up and down operations in milliseconds. 10 seconds = 10000 milliseconds. The maximum value equates to around 54 days if you have turtles turning your motor.
If the up button on your remote closes your shade, blind, awning, or shutter, click this box to continue to this silliness. Or you can perform the recommended procedure from your motor manual to change the direction of the motor.
This will change the ESPSomfy RTS display to represent the positions in percentage of open instead of percentage of closed. It's weird to me but if you can't wrap your head around percentage of closed, check this box, I'll only judge you a little bit. I'll bet your nose runs and your feet smell instead of the more logical feet running and nose smelling.
This option only appears if the type is Blind.
- None - No tilt mechanism exists on the blind
- Integrated - Integrated tilt mechanisms use a single motor for both tilt and lift. These mechanisms will tilt the slats to full open before raising the blind and tilt the slats to full closed before lowering the blind.
- Tilt Motor - A separate motor is installed in the blind hardware that uses long presses on the remote buttons to tilt the slats.
This option only appears when the motor type is Blind and the tilt type is either Integrated or Tilt Motor. The tilt time is the amount of time it takes for the tilt mechanism to go from fully open to fully closed. Unlike the up and down (lift) movement the timing is typically the same for open and closed given the way the mechanisms are constructed.
In this section you can configure the settings your CC1101 transceiver and review the communication logs. There is quite a bit of available tuning that can be done for your transceiver. These options have evolved over time to accommodate frequency differences and expand the capabilities of the software.
You can set the communication and configuration parameters for your transceiver from this tab. Initially you will need to enable the radio in this tab before ESPSomfy RTS can communicate with your motors.
By setting a protocol here ESPSomfy RTS will select this protocol as the default when adding new motors. See the protocol descriptions from the previous section. Please note that setting this value here is only the default value that is selected when adding motors to your device. It will not change the selected protocol for existing motors.
This defines the default bit length when adding new motors. This does not change the communications for existing motors in ESPSomfy RTS.
This checkbox enables or disables the transceiver on ESPSomfy RTS. When first installed, the transceiver is disabled so you can ensure the pins are set properly for your device configuration. For Ethernet connected ESP32 modules it is important that you do not share any pins with the Ethernet module as it can damage it. Often there are no protections on the Ethernet PHY pins.
The CC1101 transceiver is configured using a Serial Peripheral Interface (SPI) communication channel. These settings must match the pins used on the ESP32 for the corresponding pins on the transceiver module. Review the documentation for the transceiver you purchased or the hardware section of ESPSomfy RTS wiki to verify these values. If you cannot get the Radio not Initialized message to go away you most likely have these settings incorrect.
These settings correspond with the GPIO pins on the ESP32 that are connected to the pins used for GDO0 and GDO2 on the transceiver module. The important bit to note about the CC1101 settings for this is that the transceiver can only transmit (TX) using the pin labeled GDO0 but it can receive on either GDO0 or GDO2. So if you are receiving frames from your remote as indicated by the RSSI values changing you have these settings reversed.
ESPSomfy RTS will also allow you to share the transmit (TX) and receive (RX) functions using a single pin connected to GDO0. Simply set the dropdowns for RX and TX to the same pin connected to GDO0. ESPSomfy RTS will multiplex (switch the function back and forth) on this single pin when transmitting or receiving. There is no fundamental advantage to using two pins because the transceiver antenna can only transmit or receive at any given time.
Check your motor manual. In most cases this will be 433.42Mhz but there have been motors out there that use 433.92Mhz. Match this to the specified frequency. Also, if you are one of those folks that have a Software Defined Radio (SDR) and want to tune to a different center frequency move the slider left or right to the desired frequency.
When the transceiver is listening for your remotes, ESPSomfy RTS will tune the radio to narrow in on what is valid signal and what is noise. Frequencies on the left of the slider are more narrow and frequencies on the right are wider. Think of the transceiver having smaller ears on the narrower setting and larger ones on the wider section. Find a sweet spot here by using your remote to determine where it best receives the signal.
Somfy RTS protocols are transmitted using Amplitude Shift Keying (ASK) meaning the power of the signal passes through a maximum displacement of the signal from low to high to signify a data bit. This value determines how far it needs to move to determine what is signal and what is simply noise.
In most instances you should set this to the highest transmission level supported by your transceiver. For most transceivers this is 10dBm. There are some out there that go as high as 12dBm. If you are in a jurisdiction that limits your power output reduce it to remain in compliance. At 10dBm you will be transmitting at a much greater output than the typical Somfy remote.
ESPSomfy RTS will display the Radio Signal Strength Indicator (RSSI) for incoming frames. So when testing your remote and adjusting the radio settings you will see how strong the signal you are receiving is on each button press. The number next to the RSSI label indicates how many frames it has received and will increment each time it receives a frame. The large RSSI number will indicate how strong the signal was when the frame was received.
The strongest RSSI value will be closest to 0. So an RSSI of -20dBm is stronger than a -40dBm signal. Most antennas will stop picking up signals at around -110dBm and become less reliable around -90dBm.
The logs tab lists all received communications from any Somfy radio nearby. All frames that are identified as protocol communications will display in the listing with the most recent frame appearing at the top of the list.
ESPSomfy RTS does not store these logs on the flash of the ESP32. This is intentional as to keep the flash usage to a minimum. There are many more important uses for this resource and frames are only logged to interfaces that are currently in configuration mode. When the home mode is selected, no frames are dispatched.
A brief description of the columns is provided below:
- Key - The obfuscation key used for the frame. Depending on the protocol, this key may also contain the raw command value. ESPSomfy RTS will extract the data from this key for RTW and RTV protocols to determine the proper command byte.
- Address - The 24-bit address of the remote that sent the frame.
- Command - The button that was pressed on the remote. This will be one of the following values
- Up
- Down
- My
- My+Up
- My+Down
- My+Up+Down
- Up+Down
- Prog
- SunFlag
- Sensor
- Step Up
- Step Down
- Code - The rolling code used in the frame from the remote.
- RSSI - The Receive Signal Strength Indicator (RSSI) value for the frame.
- Bits - The number of bits that were used to reflect the frame. This is most often 56 or 80 bits.
- Time - Local time for the timezone set in the general section of the configuration.
To clear all logs from the display click the clear button.
You can copy the current detail pulse encoding for all the frames in the list to your clipboard by clicking the copy button. All information related to the frame including the pulse timings in microseconds are included in this JSON data format. Below is an example of the output for a single frame.
[{"encKey": 175,
"address": 979145,
"rcode": 111,
"command": "Up",
"rssi": -23,
"bits": 56,
"valid": true,
"sync": 4,
"pulses": [10439,7337,2559,2584,2548,2549,4857,1296,1286,1274,1272,1291,644,646,632,639,656,621,642,632,1311,621,642,631,659,642,624,1268,1310,1271,622,657,1288,643,621,659,660,614,650,1272,1284,1274,646,636,634,654,622,642,1283,1281,1317,1267,1271,1279,663,616,640,657,1290,593,667,1281,1284,642,652,615,662,624,644,648,637,1289,1293,1261,1280,644,656,1266,646,645,1277,1267,669,625,635,639,1290,1272],
"time": "2023-07-03T10:45:21.311-0700"
}]