To control Somfy Tahoma Switch over Local API
Posted: 26 Apr 2023, 14:58
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:
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:
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:
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:
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):
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):
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:
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:
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)
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.
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
Code: Select all
more cookie
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”
{"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\"}"
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"
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"
},
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\"}]}"
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 }}'"
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"}]}'
So now you have a-kind-of-work-around for local API connection until some add-on will start working.