Access to the new local API on a TaHoma Box/Switch

Share Your Projects
1

After two days of wild experimenting - here is my approach to access the local API of my TaHoma switch:

  1. the documentation to turn on the developer mode GitHub - Somfy-Developer/Somfy-TaHoma-Developer-Mode: A collection of requests to use a local API with Somfy TaHoma gateways

  2. the interactive page for testing: Swagger UI

  3. the authentication process described in [1.] can be reproduced very well with the help of the Node-Red node "HTTP-Request" and run until the registration of the token(s). Displaying the tokens and deleting them also works as described.

  4. after that I was not able to access the local API of the switch via HTTP-Requets. This was followed by various error messages. The absolutely same commands via EXEC and "curl -X ..." (as described in [2.]) worked fine and I am satisfied with the result for now.

If further information is desired, I will gladly provide information or make the corresponding flow available.

Many greetings
Hubertus

2

Nice, thanks for the info. The "developer mode" must be something recent, this used to be oauth2 only, which was horrible to work with. I use homebridge with the tahoma plugin for now.

The overkiz node (overkiz, is what somfy uses) was recently updated, maybe that works too (didnt try)

3

Please can you share examples of your curl commands that will open and close the blinds.

4

i use the same curl calls as described in the swagger ui. So for example:

curl -X 'POST' \
  'https://gateway-<your-gateway-id>.local:8443/enduser-mobile-web/1/enduserAPI/exec/apply' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <your-token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "label": "Bad/Rollladen",
  "actions": [
    {
      "commands": [
        {
          "name": "setClosure",
          "parameters": [
            "50"
          ]
        }
      ],
      "deviceURL": "io://<your-gateway-id>/<device-id>"
    }
  ]
}'

to set the blind to 50%. Also you can use the commands:
stop
down
up
open
close
my
... all without parameters
or setPosition same as setClosure

BR
Hubertus

1 Like
5

Thank you, thats really helpful at least to prove I'm not going crazy.
I have tried this but I get the really unhelpful error:

{"error":"Processing exception.","errorCode":"UNSPECIFIED_ERROR"}

My suspicion is that the difference is that my motors are rts, not io but thats just a hunch and I don't know what to try next.

6

This should make no difference whether rts or io.

Which result do you get when querying the devices?

> curl -X 'GET \
>   'https://gateway-<your-gateway-id>.local:8443/enduser-mobile-web/1/enduserAPI/setup/devices' \
>   -H 'accept: application/json' \
>   -H 'Authorization: Bearer <your-token>'

the call lists all available and controllable devices.

There you can also see which commands are supported by each device.

7 
[
  {
    "creationTime": 1666871965346,
    "deviceURL": "rts://2017-1033-8638/16774911",
    "available": true,
    "synced": true,
    "type": 1,
    "states": [],
    "label": "Gym blind",
    "definition": {
      "states": [],
      "widgetName": "UpDownScreen",
      "attributes": [],
      "uiClass": "Screen",
      "commands": [
        {
          "nparams": 0,
          "commandName": "stop",
          "paramsSig": "*p1"
        },
        {
          "commandName": "test",
          "nparams": 0
        },
        {
          "nparams": 0,
          "commandName": "open",
          "paramsSig": "*p1"
        },
        {
          "nparams": 0,
          "commandName": "close",
          "paramsSig": "*p1"
        },
        {
          "commandName": "identify",
          "nparams": 0
        },
        {
          "nparams": 0,
          "commandName": "up",
          "paramsSig": "*p1"
        },
        {
          "nparams": 0,
          "commandName": "down",
          "paramsSig": "*p1"
        },
        {
          "nparams": 0,
          "commandName": "my",
          "paramsSig": "*p1"
        },
        {
          "nparams": 0,
          "commandName": "openConfiguration",
          "paramsSig": "*p1"
        },
        {
          "nparams": 0,
          "commandName": "rest",
          "paramsSig": "*p1"
        }
      ],
      "type": "ACTUATOR"
    },
    "attributes": [],
    "enabled": true,
    "controllableName": "rts:BlindRTSComponent",
    "subsystemId": 0
  },
  {
    "creationTime": 1666871964036,
    "deviceURL": "rts://2017-1033-8638/16746440",
    "available": true,
    "synced": true,
    "type": 1,
    "states": [],
    "label": "Living room blind",
    "definition": {
      "states": [],
      "widgetName": "UpDownScreen",
      "attributes": [],
      "uiClass": "Screen",
      "commands": [
        {
          "nparams": 0,
          "commandName": "stop",
          "paramsSig": "*p1"
        },
        {
          "commandName": "test",
          "nparams": 0
        },
        {
          "nparams": 0,
          "commandName": "open",
          "paramsSig": "*p1"
        },
        {
          "nparams": 0,
          "commandName": "close",
          "paramsSig": "*p1"
        },
        {
          "commandName": "identify",
          "nparams": 0
        },
        {
          "nparams": 0,
          "commandName": "up",
          "paramsSig": "*p1"
        },
        {
          "nparams": 0,
          "commandName": "down",
          "paramsSig": "*p1"
        },
        {
          "nparams": 0,
          "commandName": "my",
          "paramsSig": "*p1"
        },
        {
          "nparams": 0,
          "commandName": "openConfiguration",
          "paramsSig": "*p1"
        },
        {
          "nparams": 0,
          "commandName": "rest",
          "paramsSig": "*p1"
        }
      ],
      "type": "ACTUATOR"
    },
    "attributes": [],
    "enabled": true,
    "controllableName": "rts:BlindRTSComponent",
    "subsystemId": 0
  }
]

Edit as I'm not allowed to post any more....

I've tried up and down etc but get the same result. I've gone back to Swagger which produces this curl:

curl -X 'POST'
'https://gateway-2017-1033-8638.local:8443/enduser-mobile-web/1/enduserAPI/exec/apply'
-H 'accept: application/json'
-H 'Authorization: Bearer 638f79237fbe15af7b48'
-H 'Content-Type: application/json'
-d '{
"label": "string",
"actions": [
{
"commands": [
{
"name": "down"
}
],
"deviceURL": "rts://2017-1033-8638/16774015"
}
]
}'

which returns an execId but also:

Failed to fetch.
Possible Reasons:

CORS
Network Failure
URL scheme must be "http" or "https" for CORS request.

The blind doesn't move.

8

ok - so you can't use the setPosition etc. commands. It seems that only "open", "close", "up", "down", "stop" and "my" can be used. A direct positioning is not possible with RTS. But if you have set a MY position you can move to it - or with UP/DOWN and then STOP.

You can also emulate the setPosition. If you know the time in seconds that is needed for opening and closing, you can also use this to move to the position ;-). If the shutter needs 12 seconds to close, you can also reach a position 50% with six seconds.

9

copy the curl command and execute it in the shell e.g. of your raspberry - than you will see it works. i had the same errors but with the shell or with the exec-node in node-red it will work fine.