To control Somfy Tahoma Switch over Local API

Post Reply
User avatar
Bamsefar
Z-Wave Kung
Posts: 1230
Joined: 25 Nov 2013, 15:06
10
Location: Stockholm

This post is in English, although this forum is actually in Swedish normally. This is since I am not allowed to format messages, or write them it seems, in git - for what ever ugly reason...

Please remember that this is how I did - your own environment may very well work in other ways, and with different syntax for the cURL command I am going to use for this.
And I just like to add that if there is a typo of any kind, please be gentle ;) I am just doing this to learn, and I do have some more to learn...

First, I will be using Windows command window, that is cmd.exe. This will need some special syntax later, for "escaping" some characters. Just be aware.

Do note that you will be needing:

1) The so called <PID> for your Somy Tahoma Switch - this can for example be extracted from the gateway-xxxx-xxxx-xxxx name, where the <PID> is <xxxx-xxxx-xxxx>. You can easily find it from your routers IP leases or something like that.
2) You userid and password to Somfy Home Page
3) Rememeber to turn on developer mode in the Somfy Home Page.... I forgott and spent alot of time.........
4) Update the Somfy Tahoma Switch to latest and greatest firmware - it will solve a few things... I am currently on 2023.1.4-9 - and after this I turned off auto update.


Let's get starting then:

a) Start by opening cmd.exe from Windows (10 in my case, no I am not at Windows 11).

b) First we need a JsessionID, and we get that from this command - please change <userId> and <userPassword> to your own:

Code: Select all

curl -X POST https://ha101-1.overkiz.com/enduser-mobile-web/enduserAPI/login -d "userId=<userId>&userPassword=<userPassword>" -H "Content-Type: application/x-www-form-urlencoded" -c ./cookie
c) this will generate a cookie file (-c ./cookie) in the current folder, where the JsessionID is the last info in that file, so go ahead and do a:

Code: Select all

more cookie
And extract something that looks like 4EBE128847A462E3394A3CDA52DA2A7A, and this is the <JsessionID> - it will only be valid for a very limited time (10 minutes it says somewhere, I on the other hand think it is way less than 10 minutes).

d) Time to generate that "token" that will be needed for local API calls later. It is a 2 stage process, first generate and then activate. We will start with generating that "token" by this command - please change the <xxxx-xxxx-xxxx> to the <PID> one extracted earlier, and then change the <JsessionID> to the one we got from the step above:

Code: Select all

curl https://ha101-1.overkiz.com/enduser-mobile-web/enduserAPI/config/<xxxx-xxxx-xxxx>/local/tokens/generate -b "JSESSIONID=<JsessionID>" -H "Accept:application/json”
This command will return an output that might look something like this:

{"token":"4111f6d39555004b57e9"}

What is in the last part, the hex-kind-of-thing is the "token" - we are in desperate need of that one ;-)

e) Now we are getting to the interesting stuff, to active the "token" that is returned from the above command... This one costed me a lot of time, due to syntax for the command to work, and this might very well be a Windows cmd.exe thing - so just be aware of syntax challenges...

This command needs a few bits to be changed also, so start with the <PID> and change from <xxxx-xxxx-xxxx> to the one extracted earlier, and then change the <JsessionID> to the one we got from two steps above, and finally change the <token> to the one from the step above:

Code: Select all

curl https://ha101-1.overkiz.com/enduser-mobile-web/enduserAPI/config/<xxxx-xxxx-xxxx>/local/tokens -H "Content: application/json" -b "JSESSIONID=<JsessionID>" -H "Content-Type:application/json" -d "{\"label\":\"Test token\",\"token\":\"<token>\",\"scope\":\"devmode\"}"
This command will return some text that says basically activated with success or something - trust me, you will note if this works. Although I don't remember exactly what was outputted...

So now you will have a <token> that is active . This active <token> will be the "gateway" to talk direct to the Somfy Tahoma Switch over what has been called "local API". This will be active for ever they say, however expect to be ready to re-activate this again if you update firmware on your Somfy Tahoma Switch - I simply have turned of auto update of firmware and hope it will never stop working....

After this, one good thing to do is to ask the Somfy Tahoma Switch what is defined within the box, so we get a "blueprint" of what is available. This is a rather simple command we can run in Windows cmd.exe while we are at it - please change your <PID> from <xxxx-xxxx-xxxx> to what you extracted above , and <token> from above (the --insecure we se below is to eliminate the SSL check for the not signed certificate problem we might get otherwise):

Code: Select all

curl --insecure https://gateway-<xxxx-xxxx-xxxx>.local:8443/enduser-mobile-web/1/enduserAPI/setup/devices -H "Authorization: Bearer <token>" -H "accept: application/json" -H "Content-Type: application/json"
The result will be depending on what you have defined within the box from earlier. I have for example 8 curtains defined and well part of that result looks like this for ONE (do note, this is just a minor part - my result from the command was very loooooooong and I had to reformat it to JSON with an online service to get a readable bunch of lines):

Code: Select all

{
"creationTime": 1682354184459,
"deviceURL": "rts:///16751535",
"available": true,
"synced": true,
"type": 1,
"states": [],
"label": "Innergardin - Vardagsrum",
"definition": {
"states": [],
"widgetName": "UpDownCurtain",
"attributes": [],
"uiClass": "Curtain",
"commands": [
{
"nparams": 0,
"commandName": "stop",
"paramsSig": "*p1"
},
{
"commandName": "test",
"nparams": 0
},
{
"nparams": 0,
"commandName": "open",
"paramsSig": "*p1"
},
{
"nparams": 0,
"commandName": "close",
"paramsSig": "*p1"
},
The interesting part of this is the <deviceURL and then the commandName. The last one we find a lot of, and it is the commands we can send to the Somfy Tahoma Switch to control this particular defined device, or curtain in my case.

So if I for example would like to close (the last command from above) my curtain in Windows cmd.exe it will look like this - and as always replace <xxxx-xxxx-xxxx> (do note, you need to change this in two places) with the <PID> from earlier, and then the <token> from above:

Code: Select all

curl --insecure https://gateway-<xxxx-xxxx-xxxx>.local:8443/enduser-mobile-web/1/enduserAPI/exec/apply -H "Authorization: Bearer <token>" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"label\":\"Testarlite\",\"actions\":[{\"commands\":[{\"name\":\"close\"}],\"deviceURL\":\"rts:\/\/<xxxx-xxxx-xxxx>\/16751535\"}]}"
If everything works, this command will close my curtain, and just before "deviceURL" in the line above you can change from "close" to "open" for well opening that curtain instead of closing. This "command" is one of the ones from the output above which shows what devices you have defined in Somfy Tahoma Switch, and what you might be able to do with the device.

So by now you can, from Windows cmd.exe, control everything, well close to anyway.

Let's implement this in Home Assistant then. And there is most likely a number of ways to do this, so feel free to suggest better or just different solutions. My way turned out to be shell_command. To use this one needs to change configuration.yaml to include a few lines for getting shell_command to work. So somewhere in configuration.yaml add the following lines (and if you already have a shell_command section, well then just add the somfy_command will do of course) - and as usually just change the <xxxx-xxxx-xxxx> and <token> as you have done above:

Code: Select all

shell_command:
  somfy_command: "curl --insecure https://gateway-<xxxx-xxxx-xxxx>.local:8443/enduser-mobile-web/1/enduserAPI/exec/apply -H 'Authorization: Bearer <token>' -H 'accept: application/json' -H 'Content-Type: application/json' -d '{{ data }}'"
Do note the double space before the "somfy_command" above - intendation is vital I have learned the hard way (and if you are using VS code to alter this, be aware of that there is some sort of challenge with the first lines in that file due to a dependency - it is not wrong in VS code, just a module that addon is depending on, so maybe use vi editor instead?).

Also note that we will be using "data" as a well I think it is called a variable in Home Assistant, but someone might need to correct me on this.

Anyway, after this, please RESTART Home Assistant. Reloading the configure.yaml will simply NOT be enough, you will need to restart. Don't know why, I just did it, and then it started working.

After this you will be able to access a service called "shell_command.somfy_command".

So for example, in an automation you might need to turn on YAML edit (I do, but I think one might get away with the normal User Interface, I just have not tested that), and under "action", well something like this will do - just remember to replace <xxxx-xxxx-xxxx> with the <PID> from above... (Do note, that the important <token> is inserted in the configure.yaml - so not needed in this part)

Code: Select all

action:
  - service: shell_command.somfy_command
    data:
      data: '{"label":"Testarlite","actions":[{"commands":[{"name":"close"}],"deviceURL":"rts://<xxxx-xxxx-xxxx>/16751535"}]}'
Also do note that I have curtains that are controlled over rts:// - there are items that is controlled over io:// - so might need to change more to get your own devices working - i simply do not know, look in the output above from when you asked what was defined in the Somfy Tahoma Switch.

So now you have a-kind-of-work-around for local API connection until some add-on will start working.
Testar Home Assistant på Raspberry Pi4B - nice :mrgreen:
User avatar
Bamsefar
Z-Wave Kung
Posts: 1230
Joined: 25 Nov 2013, 15:06
10
Location: Stockholm

I got somewhat tired of the constant misses in communication from the Somfy Tahoma Switch and all the Somfy Glydea motors, even with local API enabled.
This is of course since the communication is on 433MHz and is one way only. There is no way to know if a command has been received....

So a friend of mine recommended ESP solution. I did some research and ended up with a bunch (10) of Sparkfun ESP32-C6 development boards.

A rather simple WEB server to take care of the Open/Close/My Position (Stop) and a status page to tell what status the cartains are in. Then a minor modification to each Glydea 35 motor to support +3.3v plus the RJ12 outlet (I kind of borrowed the IR pin on that RJ12 to the +3.3v - very large thanks to my friend Magnus for all the support and help to figure that one out!).

So in the end I have e ESP32-C6 board hanging under each motor attached to the RJ12 outlet on the motor - and I have removed the RTS module inside.

The end result is: quick as nothing else! It is so fast that all my 8 Glydea motors can start more or less at the same time! RTS is not ever close, I had to put in delays between each transmission to "help" Somfy Tahoma Switch for be able to communicate... And so far, no missed transmission at all. It just works.

Note: Noticed that finally Somfy seems to released ZigBee version of each motor for about a week or two ago. However, buying new motors is an expensive solution. My ESP32-C6 solution was less than a Somfy Tahoma Switch, actually it was not even half the cost....
Testar Home Assistant på Raspberry Pi4B - nice :mrgreen:
User avatar
Bamsefar
Z-Wave Kung
Posts: 1230
Joined: 25 Nov 2013, 15:06
10
Location: Stockholm

I put the code needed to control, and how to modify the Glydea motors, on GitHub:

https://github.com/larhedse/ESP32-SomfyGlydea
Testar Home Assistant på Raspberry Pi4B - nice :mrgreen:
Post Reply