Somfy/TELIS driver

[vsky279]

• This PR is for the dev branch rather than for master.
• This PR is compliant with the other contributing guidelines as well (if not, please describe why).
• I have thoroughly tested my contribution.
• The code changes are reflected in the documentation at docs/en/*.

Possibility to control Somfy blinds with ESP8266 using an RF transmitter (433.42 MHz) connected to GPIO pin.

The module is quite simple. It uses hw timer for precision timing (similar implementation to gpio.serout()). The PR includes also Lua example.

---

Somfy module

This module provides a simple interface to control Somfy blinds via an RF transmitter (433.42 MHz). It is based on Nickduino Somfy Remote Arduino skecth.

To understand details of the Somfy protocol please refer to Somfy RTS protocol and also discussion here.

The module is using hardware timer so it is not compatible with other NodeMCU modules using the hardware timer, i.e. sigma delta, pcm, perf, or pwm modules.

somfy.sendcommand()

Builds an frame defined by Somfy protocol and sends it to the RF transmitter.

Syntax

somfy.sendcommand(pin, remote_address, command, rolling_code, repeat_count, call_back)

Parameters

• pin GPIO pin the RF transmitter is connected to.
• remote_address address of the remote control. The device to be controlled is programmed with the addresses of the remote controls it should listen to.
• command command to be transmitted. Can be one of somfy.SOMFY_UP, somfy.SOMFY_DOWN, somfy.SOMFY_PROG, somfy.SOMFY_STOP
• rolling_code The rolling code is increased every time a button is pressed. The receiver only accepts command if the rolling code is above the last received code and is not to far ahead of the last received code. This window is in the order of a 100 big. The rolling code needs to be stored in the EEPROM (i.e. filesystem) to survive the ESP8266 reset.
• repeat_count how many times the command is repeated
• call_back a function to be called after the command is transmitted. Allows chaining commands to set the blinds to a defined position.

My original remote is TELIS 4 MODULIS RTS. This remote is working with the additional info - additional 56 bits that follow data (shortening the Inter-frame gap). It seems that the scrumbling alhorithm has not been revealed yet.

When I send the somfy.DOWN command, repeating the frame twice (which seems to be the standard for a short button press), i.e. repeat_count equal to 2, the blinds go only 1 step down. This corresponds to the movement of the wheel on the original remote. The down button on the original remote sends also somfy.DOWN command but the additional info is different and this makes the blinds go full down. Fortunately it seems that repeating the frame 16 times makes the blinds go fully down.

Returns

nil

Example

To start with controlling your Somfy blinds you need to

• Choose an arbitrary remote address (different from your existing remote) - 123 in this example
• Choose a starting point for the rolling code. Any unsigned int works, 1 is a good start
• Long-press the program button of your existing remote control until your blind goes up and down slightly
• execute somfy.sendcommand(4, 123, somfy.PROG, 1, 2) - the blinds will react and your ESP8266 remote control is now registered
• running somfy.sendcommand(4, 123, somfy.DOWN, 2, 16) - fully closes the blinds

For more elaborated example please refer to somfy.lua.

[pjsg]

Your module is compatible -- the other modules just can't be used at the same time.

[vsky279]

You're right. I've changed it to:

The module is using hardware timer so it cannot be used at the same time with other NodeMCU modules using the hardware timer, i.e. sigma delta, pcm, perf, or pwm modules.

[pjsg]

Can you add a reference to the device that you need -- the transmitter appears to be an odd frequency....

[vsky279]

Good point. I've added:

The hardware used is the standard 433 MHz RF transmitter (on eBay usually sold also with the receiver). Unfortunately these chips are usually transmitting at he frequency of 433.92MHz so the crystal resonator should be replaced with the 433.42 MHz resonator though some reporting that it is working even with the original crystal.

[pjsg]

please add a comment to say that this must be in RAM as it is accessed from the timer interrupt.

[jmattsson]

I'd even be inclined to add this to sections.h and use that instead:
#define RAM_CONST_SECTION_ATTR __attribute((section((".data")))

Since it's a static in a module there's nothing to be gained from giving it a separately named section I believe, and it would add a bit of clarity to use a #define instead.

[pjsg]

There is a subtle race condition here -- if lua_done_ref is not nil when the transmission ends, the task will be queued. But it might be made null by another call to send command in the mean time.

Worse you need to set the lua_done_ref to LUA_NOREF before doing the lua_call so that if the callback tries to send another command it will all still work.

[vsky279]

Hi Philip, I am not sure I got the point. If I modify the code as follows

static void somfy_transmissionDone (task_param_t arg)
{
    lua_State *L = lua_getstate();
    lua_rawgeti (L, LUA_REGISTRYINDEX, lua_done_ref);
    lua_done_ref = LUA_NOREF;
    lua_call (L, 0, 0);
    luaL_unref (L, LUA_REGISTRYINDEX, lua_done_ref);
}

Will the luaL_unref correctly unreference the callback function (when lua_done_ref is LUA_NOREF at the moment)?

[jmattsson]

Nope, it will indeed not. What you want to do is luaL_unref() as soon as you've done the lua_rawgeti(), or well, anywhere before you lua_call() at least. So something like

    lua_State *L = lua_getstate();
    lua_rawgeti (L, LUA_REGISTRYINDEX, lua_done_ref);
    luaL_unref (L, LUA_REGISTRYINDEX, lua_done_ref);
    lua_done_ref = LUA_NOREF;
    lua_call (L, 0, 0);

This way, the callback function is able to issue another somfy command successfully (since lua_done_ref is LUA_NOREF at that point), and the callback itself can become available for gc as soon as the lua_call() returns. While the callback is on the stack (after lua_rawgeti()), the stack itself holds a reference on it and thus ensures it doesn't get gc'd.

[vsky279]

Thanks Johny. It's fixed now.

I guess we have the same issue in gpio.c. According to the same logic it should look like:

static void seroutasync_done (task_param_t arg)
{
  lua_State *L = lua_getstate();
  luaM_freearray(L, serout.delay_table, serout.tablelen, uint32);
  if (serout.lua_done_ref != LUA_REFNIL) { // we're here so serout.lua_done_ref != LUA_NOREF
    lua_rawgeti (L, LUA_REGISTRYINDEX, serout.lua_done_ref);
    luaL_unref (L, LUA_REGISTRYINDEX, serout.lua_done_ref);
    serout.lua_done_ref = LUA_NOREF;
    if (lua_pcall(L, 0, 0, 0)) {
      // Uncaught Error. Print instead of sudden reset
      luaL_error(L, "error: %s", lua_tostring(L, -1));
    }
  }
}

Can it be fixed in this PR or should there be another one?

[devsaurus]

Let's make it another one, once this is settled.

[marcelstoer]

We don't normally have links to hardware resources unless they're "stable" links to official data sheets. So, I'd like to see those ebay links removed/replaced.

[vsky279]

Ok. I guess there is no official data sheet. So I leave there just the "433 MHz RF transmitter". Everybody should be able to google it.

[pjsg]

You need to do luaL_unref(L, LUA_REGISTRYINDEX, lua_done_ref) first (just in case there is still a reference) (actually in both cases -- so do it a few more lines up). Doing an unref on a LUA_NOREF is perfectly OK

[vsky279]

Le voila. To be fixed in the gpio.c too.

[marcelstoer]

AFAICS there are no pending issues anymore with this. @devsaurus @pjsg if you agree then please merge.

[marcelstoer]

It's only now that I realized that the Somfy entry was missing in mkdocs.yml. Sorry about that. I'll fix it right away and push it also to master. No one ever missed the Somfy chapter in the docs...not cool.