Somfy : How to control your devices in Php ?

Background

I recently bought a pergola with solar blinds, dimmable LEDs and a orientable roof blades. This is great to enjoy the summer without getting too much hot air or direct sun. It is coming with a Somfy Tahoma controller box that allows controlling the different devices with a SmartPhone. How cool is this ? Ok, but how does it work ? Can I control this myself with my own scripts and integrate it into an home automation system ? Let's have a look !

Hey, Somfy is on GitHub !

Indeed, I have found this interesting page : https://github.com/Somfy-Developer/Somfy-TaHoma-Developer-Mode.

So, there is a developer mode and you can activate it ! Cool. While we are on the somfy website, it is important to note your Tahoma PIN. It will be required later.

STOP ! Tahoma ? What is this ? Ok, let's rewind a little bit before we start coding. Somfy is a wireless system that controls objects like blinds, lights, gates, air conditioning systems, .... They have developed 2 protocols : RTS (old) and IO (the current one). You can control devices using a remote control. To be able to use the IP protocol, you need a gateway that converts the IP commands sent via APIs to the Somfy wireless protocol (using the 433 MHz wavelength). One of the gateway for the Somfy ecosystem is called Somfy Tahoma. This is the box, I'm talking about from now on. Ok, let's continue now.

The below screenshot is in French - I have no way to display it in English since this is tighten to your installation location. But in short, Code PIN is the PIN you require to generate the token in the next step and the button on the right is where you activate the developer mode.

You can follow the procedure on the GitHub page to get your token. This is how you will authenticate your API calls. Of course, firstly, you have to generate that token. The process is not straightforward and then I decided to automate all actions into one function.

According to the documentation found on GitHub, there are 3 steps to get the token : 

• Authenticate with your Somfy username and password to get a cookie ID
• Use the cookie ID to generate the token
• Use the cookie ID to activate the token.

Once you have the token, you do not need to do this step again. Store the token in a safe place. Apparently it is valid for a long time - I do not know the TTL of that token. Maybe when something is not working anymore, this is probably the right time to generate a new one.

The function is available on my GitHub and is called syGetToken($syUsername,$syPassword). The provided syUsername and syPassword are the same credentials as the one your use on the Somfy website to access your profile.

If everything went well, you will be able to get your token.

I have a Token, what now ?

When you have the token, you can start to explore the API stack. Important notice : all API calls you will initiate are to the local Tahoma. It means the scripts you will create only work once on the same network of your own Tahoma. The Somfy mobile app allows you to open your blinds when away from home over the public Internet, but here it is different, you need to be on the same network.

To debug API calls, they are providing a Swagger URL to play around : https://somfy-developer.github.io/Somfy-TaHoma-Developer-Mode/ 

If you want to play with the swagger, do not forget to enter your PIN in the field on the top left and then click on authorize and provide your token. Then, choose a endpoint and click on "try it out".

Good news : you do not need to spend time on this UI, I already created functions for you ;-)

Here are the functions I have created so far : 

• syGetDevices($tahomaPin,$token) 
• syGetToken($syUsername,$syPassword)       <- use this only once
• syLedOff($tahomaPin,$token,$LEDiD) 
• syLedOn($tahomaPin,$token,$LEDiD) 
• syLedSetIntensity($tahomaPin,$token,$LEDiD,$intensity) 
• syRoofClose($tahomaPin,$token,$roofID) 
• syRoofOpen($tahomaPin,$token,$roofID) 
• syRoofSetOrientation($tahomaPin,$token,$roofID,$position) 
• syRoofStop($tahomaPin,$token,$roofID) 
• syScreenDown($tahomaPin,$token,$screenID) 
• syScreenStop($tahomaPin,$token,$screenID) 
• syScreenUp($tahomaPin,$token,$screenID)

Example, in order to lower my blinds to the middle of the window, I need to deploy them for 8 seconds : 

<?php

    include_once 'syFramework.php';

    $token="<insert-yours>";

    syScreenDown($tahomaPin,$token,"io://20xx-30xx-05xx/16249868");

    syScreenDown($tahomaPin,$token,"io://20xx-30xx-05xx/5247014");

    syScreenDown($tahomaPin,$token,"io://20xx-30xx-05xx/6245842");

    

    sleep(8);

    // Stop all screens

    syScreenStop($tahomaPin,$token,"io://20xx-30xx-05xx/16249868");

    syScreenStop($tahomaPin,$token,"io://20xx-30xx-05xx/5247014");

    syScreenStop($tahomaPin,$token,"io://20xx-30xx-05xx/6245842");

?>

In the above example, there is a "io://...." ID. How am I getting the correct id ? With a small script calling the syGetDevices($tahomaPin,$token) function.

[...]

    $listDevices=syGetDevices($tahomaPin,$token);
    for($i=0;$i<count($listDevices);$i++)
    {
        print("Device Name : ".$listDevices[$i]["name"]."\n");
print("Device Type : ".$listDevices[$i]["type"]."\n");
print("Device Address : ".$listDevices[$i]["url"]."\n\n");
    }

[...]

This is returning all the available devices in my environment. Here is an extract : 

[...]

Device Name : Led 1

Device Type : DimmerLight

Device Address : io://20xx-30xx-05xx/5101624

Device Name : Led 2

Device Type : DimmerLight

Device Address : io://20xx-30xx-05xx/5839490

[...]

Of course, these addresses are only valid in my environment, with my Tahoma PIN and my token. You have to adjust all the parameters with yours.

At the top of your scripts, you will have to declare the following variables matching your own environment : 

$endPointURL="https://ha101-1.overkiz.com/";

$tahomaPin="<your-pin>";

$localTahomaIP="https://gateway-".$tahomaPin.".local:8443";

$syUsername="<your-username>" ;

$syPassword="<your-password>";

$token="<your-token>";

It is even better to maintain a separate file called syCredentials.php that could easily be called with a include_once statement for better security.

The localTahomaIP is constructed using your pin and it is resolved using mDNS protocol, there is no need to run a local DNS at your home of course. If mDNS is not available, you can use an IP LAN scanner and record the IP found into a hosts file. But, in that case, make sure the IP is the same after a power cycle.

What's next ?

Indeed, what's next ? I would say your imagination and creativity will do the rest ! You can insert home made scripts into any home automation platform and start creating scenario based on the weather, the time of the day, specific conditions like inside or outside temperatures.....

You can already access my GitHub for the scripts described above.

I will continue to explore this and you'll hear from me soon.

I hope this helps !