Add Girier TS130F Dual Shutter Module

[LorandBiro]

As we briefly discussed in #268 already, I would like to explore what it would take to add shutter functionality to this firmware. I have single- and dual-channel Girier shutter modules in my home, and they already provide basic shutter control reasonably well. They can be calibrated, and the motor direction can be swapped in case they are wired incorrectly. However, there are a few areas I would like to improve:

• The roller shutters I know and have used have significant dead zones at the upper and lower ends of travel. For example, my roller shutters take around 20 seconds to go from one end position to the other, but for the first 3-4 seconds there is no visible movement. Then they start moving, and after they are fully closed, the motor can still be heard running for a few more seconds. These two dead zones mess up position calculation. If I set the roller shutter from 0% to 10%, I hear the motor running for 2 seconds, but the shutter does not actually move at all. When setting a specific position, I often do not have an intuitive understanding of what percentage corresponds to the desired position. A better firmware would allow calibration of these two dead zones so the position value better matches the actual roller blind position.
• I have Velan Life Roller blind push-buttons. These have a stop button in the middle that effectively closes both direction switches at the same time. A better firmware would interpret simultaneous switch presses as a stop command.
• My 1-gang and 2-gang Girier shutter modules behave inconsistently. One can be stopped by momentarily pressing the opposite direction, while the other actually starts moving the motor in the opposite direction. One can be controlled by holding down the button, so it only moves while the button is pressed, while the other does not support this. A better firmware would be more consistent and maybe even allow these behaviors to be configured to match the home owner’s preference.

What I did

I figured out the port mapping, created a build on my fork, successfully OTA-updated the original firmware with the custom firmware on a dual-channel Girier shutter module, and verified the port mapping through the config string.

There is one quirk on this device: the on-board reset button appears to be wired to the same pin as the first switch input. I have not fully explored the PCB yet, so I do not know why another pin was not used. On this device, pressing the reset button is equivalent to pressing the first switch.

Next steps

First, I will create a PR for the new device database entry. Then I will explore options to add shutter-specific features without disturbing or complicating the existing functionality. As far as I understand, the 2-gang and 4-gang switch modules are hardware-equivalent to the 1-channel and 2-channel shutter modules, so it may make sense to allow reconfiguration between these modes if needed.

Once I have spent more time exploring the codebase in detail, I would like to follow up with ideas, proposals, and questions.

Photos

[andrei-lazarov]

Very similar to MODULE_TUYA_ZTU_TS0004:

• TS0004_switch_module (_TZ3000_ltt60asa) support request + pins #42
• That one has reset pin on B5, otherwise identical pinout
• ltt60asa;TS0004-Avv;BB5u;LC1;SB4u;RC0;SD2u;RC4;SC3u;RD4;SC2u;RD7;

Please crop and compress the pictures 😅

[LorandBiro]

Ah yes, I also found that device DB entry. I was happy to see similar hardware, but it’s not identical. Every pin matches except the reset button.

I downscaled the images to 50% and then cropped them to 1000x1000, so they have significantly fewer pixels now.

Let me know if you need any more info or adjustments.

[LorandBiro]

Hey again,

I’ve been thinking a bit about what adding shutter support to this firmware could look like, and I wanted to sanity-check a few high-level integration ideas with you before going any further. These are still very exploratory thoughts.

High-level integration options

1. Unified switch firmware with configurable shutter endpoints

   All switch modules would expose additional window covering endpoints alongside the existing switch and relay endpoints. The user could configure pairs of switches as window cover controls and pairs of relays as window cover outputs.

   The upside is flexibility. In theory, the hardware is very similar, so a device could be repurposed between switch and shutter roles without reflashing. The downside is complexity and safety. Shutter controllers must guarantee that opposing relay pairs can never be energized at the same time, and making this configurable via Zigbee fields feels risky. A few clicks in Z2M should not be able to create a short-circuit scenario.

2. Separate switch and shutter firmwares

   Shutter support could live in a separate firmware variant, with shared code where possible and switch or shutter functionality behind #ifdefs. This avoids increasing the size and complexity of the switch firmware.

   Reflashing would be the explicit step that converts a device between switch and shutter roles, which feels safer and more intentional. Z2M could also clearly identify the firmware type and expose the correct fields. The tradeoff is extra complexity around firmware variants and converters, which might be undesirable for a relatively niche use case.

3. Shutter pairing defined in the config string

   Similar to how latching relay pin pairs are defined today, shutter switch pairs and relay pairs could be described in the config string. Converters would be generated accordingly, so normal switches would remain unchanged while shutter modules would expose window covering fields.

   This would still allow advanced users to repurpose devices by changing the config string, but it would require manual converter changes on their side. It does allow some interesting flexibility, for example using a 4-gang switch module as a single-channel shutter controller on one side and an extra 2-gang switch on the other side.

This might be overthinking things, and maybe nobody actually wants to mix shutter and switch roles on the same hardware. For me it’s mostly a way to reason about how flexible or constrained the integration should be.

Endpoint and cluster ideas

For shutter control inputs, I was thinking about one endpoint per switch pair, exposing a Window Covering cluster. Roughly:

- Switch press actions
  - position_open
  - position_stop
  - position_close
  - released
  - open_press
  - open_long_press
  - close_press
  - close_long_press
  - stop_press
  - stop_long_press

- Switch mode
  - Toggle
  - Momentary
  - Momentary NC

- Switch reversal
  - Inverts up/down direction for the paired inputs

- Switch local mode
  - Detached
  - press_start
  - short_press
  - long_press
  - short_and_long_press

- Switch binded mode
  - press_start
  - short_press
  - long_press
  - short_and_long_press

- Long press duration

The switch action mode feel less relevant for shutters, because the intent of the buttons is already explicit. UP means up, DOWN means down. The main configuration need is direction reversal in case the wiring is swapped.

A reasonable default for the local and binded mode could be short_and_long_press, where a short press issues an open, close, or stop command, and a long press starts movement with stop issued on release. This would allow users to bind short and long presses differently if they want local control on one and bound control on the other.

For shutter outputs, I was thinking about one endpoint per relay pair, again using the Window Covering cluster:

- Commanded state
  - Open
  - Close
  - Stop

- Movement state
  - Up
  - Down
  - Stopped

- Motor reversal

- Position (0-100)

- Calibration time

- Calibration enable
  - On
  - Off

- Upper deadzone time (tentative)
- Lower deadzone time (tentative)

I haven’t fully worked out calibration yet. That felt like a detail that could come later once the overall structure makes sense.

Overall, this would follow the same philosophy as the existing switch functionality. Inputs and outputs can be decoupled, switches could be binded to remote devices. But whenever I try to keep more of the existing switch endpoints, it starts to feel overly complex and easier to misconfigure.

Does something along these lines sound interesting or aligned with how you see this firmware evolving? If so, I’d be happy to put together a small prototype based on whatever direction you think makes the most sense.

[andrei-lazarov]

I propose setting the device category in the config string. But we also need @romasku's opinion.
The increasing firmware size should be the only draw-back. Not sure if we should worry about it yet.

We need this for other categories too:

• module: default
• switch: change 1,2,3 numbering to left, middle, right
• outlet: hide switch options
• remote: hide relays
• curtains: what you described

We will introduce the generic converter, which generates itself on-the-spot, depending on the config string:

• Add generic converter that generates exposes based on device config #120
• user doesn't need to edit it when re-purposing the device
• goes with a generic firmware image to simplify porting
  (skip building binary and converters for every new device)

So maybe wait a bit until we merge it.

The exposed options and defaults are up-to-you. 🙂
Sounds good, and we can always tweak them later

[danielpinto8zz6]

Great work @LorandBiro , did you tested this on single channel shutter by any chance?

[LorandBiro]

@andrei-lazarov: Oh, a generic converter would be really awesome. I didn’t know that was possible. In that case, it feels like a no-brainer. Having this configurable via the config string would be very flexible. I currently have a working prototype, and the firmware size increase is minimal. The binary went from 174 KB to 177 KB.

I was thinking about a slightly different approach for the config string. My prototype currently uses this string:
j1xl73iw;TS130F-GIR-DUAL;LC1;XB4D2u;WC0C4;XC3C2u;WD4D7;

Here, X configures a pair of input pins that can be connected to a cover switch, and W configures a pair of output pins for the motor control relays. This can be used to initialize different clusters and expose different fields in the converter. With this approach, it’s possible to mix different controls and capabilities, for example:
j1xl73iw;TS130F-GIR-DUAL;LC1;XB4D2u;WC0C4;SC3u;RD4;SC2u;RD7;

@danielpinto8zz6: No, not yet, but I definitely want to make it work on the single-channel version since I have one installed. I haven’t been able to take it out yet, though. Retrieving and reinstalling the module behind the wall switch is a fairly tedious process. Do you happen to have one on hand? :)

[danielpinto8zz6]

@LorandBiro I do, let me know if you need help testing 👍

[LorandBiro]

I have opened a PR that implements the basic window covering functionality: #288. The full feature set felt too large to review in one go, so I started with the smallest reasonable subset to get things moving.

While working on this I spent quite a bit of time thinking about the terminology to use, since this area feels fairly fragmented. Personally I have roller shutters, so my first instinct was to think in terms of a shutter controller. Girier refers to these devices as curtain controllers, while the Zigbee spec defines the window covering cluster.

Using window covering would be technically accurate since that is the Zigbee cluster being exposed, but it is a bit long. I ended up going with cover cluster instead, which also aligns with Home Assistant’s terminology: https://www.home-assistant.io/integrations/cover

This is also why I changed the W in the config string to C for cover. I know there are already plans to extend the config string with additional characters and features, so I am very open to guidance here and happy to adjust this to better fit the overall direction.

I would really appreciate any feedback on the approach and the terminology.

[LorandBiro]

I have opened the second PR, which implements input processing with multiple switch types, input modes, and binding support: #297. With these changes, the firmware can now be used with physical switches, but position calculation, control, and calibration are still missing. I plan to complete those in a third PR, which should be much smaller than the first two.