API/Product suggestions

[kinnkler]

@woodworm @oliver-joos
Hello everyone
I have been using Wiser (20 devices) for 1 year now and have been very satisfied so far. 😃
I still have a few wishes/suggestions, which I would like to mention below:

• Integration of MQTT (sending switch-on commands via MQTT or status change communication via MQTT)
• Possibility to change the button type (scene / groupctrl) of the smartbuttons (Nebenstelle): It would be great if the button type could be changed from scene to groupctrl via API. I have several 4 scene buttons (4 Szenentaster) and would like to make e.g. 2 groupctrl (Nebenstelle) and 2 scene buttons out of them. 2 scenes on the left and 2 toggle groupctrl (not I/O) on the right.
• Also use main switch (Hauptstelle) as groupctrl (control also other "Hauptstellen"): I have a 1T pushbutton switch at one place, where I also want to switch on another light (load) in the house in addition to the load underneath it. Currently I have to do this via 2 separate switches (main unit and extension unit) and therefore 2 clicks.
• With the Groupctrl buttons, a distinction is made between click and push (longer press). It would also be cool if a distinction were made with the scene buttons so that 2 scenes can be stored for a scene button (short press and long press).
• different lighting colors for on/off instead of just different brightness
• Import of own python libraries

It would be cool to hear from you whether certain things can be implemented in the future.
Many thanks

[grobotka]

Hi,
I find the suggestion "different lighting colors for on/off" very useful.
I miss this feature very much.

[woodworm]

What I can say at the moment... An open MQTT client and more flexible color settings for the LEDs are on our roadmap.
It is difficult to change the behavior of a scene-button because it is deeply embedded in the DNA of the Wiser system.
It is important to us that many things work immediately after installing a device. That's why the scene-button behaves like this 🤷‍♂️.
But you can change the function of the button-type. But it is secret like the spiciest secret of Switzerland 🤫

If you have this Nebenstelle device

+---------------------------+
|  +--------+   +--------+  |
|  |        |   |        |  |
|  |   S1   |   |   S3   |  |
|  |        |   |        |  |
|  +--------+   +--------+  |
|  +--------+   +--------+  |
|  |        |   |        |  |
|  |   S2   |   |   S4   |  |
|  |        |   |        |  |
|  +--------+   +--------+  |
+---------------------------+

and you would love to have one like this

+---------------------------+
|  +--------+   +--------+  | 
|  |        |   |        |  |
|  |   I    |   |    I   |  |
|  |        |   |        |  |
|  +--------+   +--------+  |
|  +--------+   +--------+  |
|  |        |   |        |  |
|  |   0    |   |    0   |  |
|  |        |   |        |  |
|  +--------+   +--------+  |
+---------------------------+ 

run this curl line
curl -X PUT http://<ip>/api/devices/<device-id>/register/c/0x9000 -d '{"value": "0x0002"}'
a power-up of the device or
curl -X PUT http://<ip>/api/devices/<device-id>/register/a/0x0A00 -d '{"value": "0x0001"}'
is necessary afterwards.
⚠️ Please be careful with further commands... make sure the device-id is correct... you can break a lot of things!

[woodworm]

the whole thing would also be possible via the web interface.
but... ⚠️ please be careful!

[kinnkler]

@woodworm Thank you very much for your answer. I still have a couple of follow-up questions:

Regarding the change of the 4 scene buttons to groupctrl buttons: Is there no possibility to use only 1 button (toggle-button) per light group? I consider the implementation with a separate on (I) and off (O) button to be inconvenient, as the I button no longer has any function when the light is switched on. And this implementation could also be solved with the scene button for undimmed lamps. Scene on and scene off. It would also be cool if 4 separate lamp groups could be controlled with one device.
I think the best solution would be if the group-ctrl part of a job could also be executed for scene buttons. I think the distinction between scene and groupctrl makes no sense for people who configure with the API. The job has 4 parts (target_state, group_ctrl, script, system flag) and these should simply be executed by a smartbutton. All 4 parts always and not just 3 depending on the button would be cool. I can understand that many things should work simply by plugging in the system and without configuration and therefore 2 push buttons (I and O) in the grid of 4 are considered as one group. However, is there no way to have the 4 buttons separately via API and assign 4 separate jobs to them. So I could then assign 4 different group-ctrl jobs and configure the buttons as toggle.

It's cool that the button layout can be adjusted afterwards using the Write register. In the GUI, it says at 0x9000 See TODO_DOC_NAME. Could you provide me with this documentation? I would also like to know the values for other button configurations like this one:

I have already analyzed that the format 0x0abc, a is the button type, b is the number of scene buttons and c is the number of group_buttons. Unfortunately I don't know what the button type is, does it have anything to do with I/O seperat = 0 and toggle = 1? So could I write value 0x0104 in register 0x9000 and then have 4 group-ctrl buttons?

My absolute "Dream-Nebenstelle" would be this one 😃 :

+---------------------------+
|  +--------+   +--------+  | 
|  |        |   |        |  |
|  |  I/0   |   |   S1   |  |
|  |        |   |        |  |
|  +--------+   +--------+  |
|  +--------+   +--------+  |
|  |        |   |        |  |
|  |  I/0   |   |   S2   |  |
|  |        |   |        |  |
|  +--------+   +--------+  |
+---------------------------+ 

By the way, it would be really great if you could publish a more detailed documentation. The system has many possibilities that are not really known, such as the register changes (to change button config). I have also started with system flags. Since there is no documentation regarding these things, it is very difficult to implement or change things because the exact implementation details are unknown. I think there are also some crazy nerds out there who would like to play more with the system 😃
Thanks a lot!

[woodworm]

I agree that a toggle button is usually sufficient... especially to turn a light on or off. Dimmers are a bit tricky... if you press the button for a long time, it's not clear to everyone whether it should dim up or down. It gets difficult with motors. These are almost impossible to operate with a toggle switch.

But thank you very much for your input. Here is the complete overview of the possible configurations that are possible today.

0x0001
+---------------------------+     +---------------------------+     +---------------------------+
|        +--------+         |     |        +--------+         |     |        +--------+         |
|        |        |         |     |        |        |         |     |        |        |         |
|        |   I    |         |     |        |   +    |         |     |        |   ^    |         |
|        |        |         |     |        |        |         |     |        |        |         |
|        +--------+         |     |        +--------+         |     |        +--------+         |
|        +--------+         |     |        +--------+         |     |        +--------+         |
|        |        |         |     |        |        |         |     |        |        |         |
|        |   0    |         |     |        |   -    |         |     |        |   v    |         |
|        |        |         |     |        |        |         |     |        |        |         |
|        +--------+         |     |        +--------+         |     |        +--------+         |
+---------------------------+     +---------------------------+     +---------------------------+


0x0002
+---------------------------+     +---------------------------+     +---------------------------+
|  +--------+   +--------+  |     |  +--------+   +--------+  |     |  +--------+   +--------+  |
|  |        |   |        |  |     |  |        |   |        |  |     |  |        |   |        |  |
|  |   I    |   |    I   |  |     |  |   +    |   |   +    |  |     |  |    ^   |   |   ^    |  |
|  |        |   |        |  |     |  |        |   |        |  |     |  |        |   |        |  |
|  +--------+   +--------+  |     |  +--------+   +--------+  |     |  +--------+   +--------+  |
|  +--------+   +--------+  |     |  +--------+   +--------+  |     |  +--------+   +--------+  |
|  |        |   |        |  |     |  |        |   |        |  |     |  |        |   |        |  |
|  |   0    |   |    0   |  |     |  |   -    |   |   -    |  |     |  |    v   |   |   v    |  |
|  |        |   |        |  |     |  |        |   |        |  |     |  |        |   |        |  |
|  +--------+   +--------+  |     |  +--------+   +--------+  |     |  +--------+   +--------+  |
+---------------------------+     +---------------------------+     +---------------------------+


0x0021
+---------------------------+     +---------------------------+     +---------------------------+
|  +--------+   +--------+  |     |  +--------+   +--------+  |     |  +--------+   +--------+  |
|  |        |   |        |  |     |  |        |   |        |  |     |  |        |   |        |  |
|  |   I    |   |   S1   |  |     |  |   +    |   |   S1   |  |     |  |   ^    |   |   S1   |  |
|  |        |   |        |  |     |  |        |   |        |  |     |  |        |   |        |  |
|  +--------+   +--------+  |     |  +--------+   +--------+  |     |  +--------+   +--------+  |
|  +--------+   +--------+  |     |  +--------+   +--------+  |     |  +--------+   +--------+  |
|  |        |   |        |  |     |  |        |   |        |  |     |  |        |   |        |  |
|  |   0    |   |   S2   |  |     |  |   -    |   |   S2   |  |     |  |   v    |   |   S2   |  |
|  |        |   |        |  |     |  |        |   |        |  |     |  |        |   |        |  |
|  +--------+   +--------+  |     |  +--------+   +--------+  |     |  +--------+   +--------+  |
+---------------------------+     +---------------------------+     +---------------------------+


0x0040
+---------------------------+
|  +--------+   +--------+  |
|  |        |   |        |  |
|  |   S1   |   |   S3   |  |
|  |        |   |        |  |
|  +--------+   +--------+  |
|  +--------+   +--------+  |
|  |        |   |        |  |
|  |   S2   |   |   S4   |  |
|  |        |   |        |  |
|  +--------+   +--------+  |
+---------------------------+


0x0101
+---------------------------+
|                           |
|    +-----------------+    |
|    |                 |    |
|    |                 |    |
|    |       T1        |    |
|    |                 |    |
|    |                 |    |
|    |                 |    |
|    +-----------------+    |
|                           |
+---------------------------+


0x0110
+---------------------------+
|                           |
|    +-----------------+    |
|    |                 |    |
|    |                 |    |
|    |                 |    |
|    |       S1        |    |
|    |                 |    |
|    |                 |    |
|    +-----------------+    |
|                           |
+---------------------------+


0x0102
+---------------------------+
|                           |
|                           |
|                           |
|  +--------+   +--------+  |
|  |        |   |        |  |
|  |   I/0  |   |   I/0  |  |
|  |        |   |        |  |
|  +--------+   +--------+  |
|                           |
|                           |
|                           |
+---------------------------+


0x0111
+---------------------------+
|                           |
|                           |
|                           |
|  +--------+   +--------+  |
|  |        |   |        |  |
|  |   I/0  |   |   S1   |  |
|  |        |   |        |  |
|  +--------+   +--------+  |
|                           |
|                           |
|                           |
+---------------------------+

[woodworm]

We are aware that the documentation could be more detailed 🙈. As soon as we find time we will work on it 😑

[kinnkler]

@woodworm Thank you very much for your answer. Nice to hear that you have taken note of my input regarding toggle switch implementation.

Also thanks for sharing the buttons configuration codes.
If I write 0x0104 in register 0x9000, is there any chance that this will work and create 4 groupctrl toggles or will the device stop responding because it considers it invalid? 🙈

Another question regarding something completely different, where I am currently looking for a solution for implementation 😃 :
I would like enable or disable a timer via a button (I guess a scene button). This can be done for the "Anwesenheitssimulator" and then it can be assigned to a scene button. This is solved there using the "present" system flag, and "blocked_if_present: true" is then added to the timer according to the API. I would now like to be able to enable and disable another timer besides the "Anwesenheitssimulator" with a button. Is there a way (possibly with system flags) to implement this?
Thanks for your help!

btw: what is the difference between timer and scheduler or system flags and system conditions in the API? I have only seen that a scheduler is created for several timers...

[woodworm]

0x0104 currently not working... only the µGW itself can do this. But it is not tested!

Do not use "blocked_if_present" it is deprecated!

create a new system flag
POST /api/system/flags {"symbol": "automation", "value": true, "name": "Alles got vu allei"}

create a new system conditions (could be more complex "automation and not cleaning or not weather_alarm")
POST /api/system/conditions {"expression": "not automation"}

now you can create all jobs you need for your automation
POST /api/jobs and add {"blocked_by": <conditions_id>, ....} in the job

and finally all timers with a reference to your jobs
POST /api/timers

[woodworm]

Totally forgot!
Now you can set the system_flag via the API or create a job again with "flag_values": [{"flag": <automation_flag_id>, "value": true}]. If you now link this job with a smart_button, you can switch on your automation with a Scene-Button. If the Button-LED is switched on, the LED lights up if automation==true

[kinnkler]

0x0104 currently not working... only the µGW itself can do this. But it is not tested!

Do not use "blocked_if_present" it is deprecated!

create a new system flag POST /api/system/flags {"symbol": "automation", "value": true, "name": "Alles got vu allei"}

create a new system conditions (could be more complex "automation and not cleaning or not weather_alarm") POST /api/system/conditions {"expression": "not automation"}

now you can create all jobs you need for your automation POST /api/jobs and add {"blocked_by": <conditions_id>, ....} in the job

and finally all timers with a reference to your jobs POST /api/timers

@woodworm Thank you very much. This is exactly what I was looking for.

Regarding "blocked_if_present":
I did not create this job myself, but via the "Anwesenheitsimulator" in the iOS app. This apparently still uses "blocked_if_present". Do I have to change anything or will this continue to work? I also see an offset = random there. Can you give more details on how this offset works exactly? Can I also use offsets for other timers to implement a temporal randomness or is there only the offset regarding sunrise/sunset?
That is the timer, which was created by the iOS-App "Anwesenheitsimulator"
{
"job": 478,
"offsets": "Random",
"when": {
"every": "Mon,Tue,Wed,Thu,Fri,Sat,Sun",
"at": "15:23"
},
"blocked_if_present": true,
"id": 479,
"enabled": true
},

[kinnkler]

0x0104 currently not working... only the µGW itself can do this. But it is not tested!

Do not use "blocked_if_present" it is deprecated!

create a new system flag POST /api/system/flags {"symbol": "automation", "value": true, "name": "Alles got vu allei"}

create a new system conditions (could be more complex "automation and not cleaning or not weather_alarm") POST /api/system/conditions {"expression": "not automation"}

now you can create all jobs you need for your automation POST /api/jobs and add {"blocked_by": <conditions_id>, ....} in the job

and finally all timers with a reference to your jobs POST /api/timers

A few more questions about the implementation of the "automation button" before I put it into practice.

1. Can POST /api/jobs {"blocked_by": <conditions_id>, ....} also be a system flag directly or is the path via conditions necessary? Does the blocked function only work for jobs that are assigned to a timer or can I also define this for normal jobs so that certain smart buttons no longer works when I am absent (and set a according system flag), for example?

2. I have seen that there are also triggers in the jobs API. Can you say more about these? Are these system flags/conditions or loads id's that trigger the job?

3. You wrote that it is possible to set the system flag in a job. I have tested this. Is it possible that this only works for scene buttons and that the "flag_values" of the job is not executed for "Nebenstellen"-smartbuttons?

4. Another question about toggling (my favorite topic 😜). Is it possible to toggle the system flag in the job instead of assigning a true or false value to the system flag? So if true, then toggle to false or if false then to true. That way I wouldn't have to sacrifice two buttons to switch the timer on and off, but could do the whole thing with one button. With the current implementation, I would need two buttons for on and off. It would be cool to have a button where you can see from the LED whether the timer (system flag) is active or not. I have seen that "flag_values": [{"flag": <automation_flag_id>, "value": true}] only accepts boolean and no logic. Perhaps this is possible using the script function? Is there a way to change the value of the systemflags object directly with the python script without the need for localhost API CALLs?

5. What is the correct way to remove a job from a smartbutton? do you have to delete the job or should you simply assign an empty job to the smartbutton?

I would be really grateful if you could answer my 5 points. The API really has a lot of great "hidden functions" with which you can implement a lot of gimmicks 😃 . Thank you very much for your great support!

[woodworm]

1. {"blocked_by": <systemflag_id>, ....} can also be a system flag. "blocked_by" works for all jobs, no matter how they are called.

2. api/jobs//trigger checks "blocked_by" and handles "flag_values", "target_states", "button_ctrl" and "scripts"
   api/jobs//setflags checks "blocked_by" and handles "flag_values"
   api/jobs//run checks "blocked_by" and handles "target_states"
   api/jobs//ctrl checks "blocked_by" and handles "button_ctrl"
   api/jobs//execute checks "blocked_by" and handles "scripts"

3. Smart-Button of type "ctrl", checks "blocked_by" and handles "button_ctrl" and "scripts"
   Smart-Button of type "scene", checks "blocked_by" and handles "target_states" and "scripts" and "flag_values"

4. Doesn't work today... but I recorded it 👍️
   But with a script it would be possible. I can support you with this.

5. Delete the job or set the job reference to "null" in the Smart-Button.

[kinnkler]

Thank you very much for your fast reply and for recording the thing with the system flag "toggle". I would therefore like to solve it with a script in the meantime. Can you help me with how I can access the objects directly in the script? I mean system flags, jobs or, if possible, loads. To switch the lights on and off, start a job or change the system flags value using the script engine. 😃

EDIT: I have just noticed that timers that are created via the API are not displayed in the Mobile APP, or that it is not visible in the Mobile APP that a timer job is blocked due to a system flag. Therefore, I think the best option would be if I could access the timer object via script and set the "enabled" attribute to true or false with the script. This would allow me to activate or deactivate the timer with the smart button and the mobile app and I would always have an insight into whether the timer is active or not via the mobile app. Is there a way to access this "enabled" attribute directly with the script engine? In short, is there a way to directly access and change these system objects (timers, jobs, loads, system flags) with the script engine?

In short, is there a way to directly access and change these system objects (timers, jobs, loads, system flags) with the script engine?

Regarding point 2, I may have expressed myself too unclearly. In the job (see example 1 below from the Swagger UI) it also has triggers after "blocked by". Are these the IDs of the smart buttons that trigger this job? However, I do not have this attribute "triggers" anywhere in my jobs, although certain jobs are linked to smartbutton. On the other hand, I have "scene_input_channel": 16 (see example 2), which are automatically added to the job after I link the job to a smartbutton. can you say more about these "triggers" and "scene_input_channel"?

example 1:

example 2:

Thank you very much for your support!

[woodworm]

To get more information about the scripting write an email to our Customercare Center with the note "API request at woodworm".

"Trigger" has no effect and should really be removed from the documentation (more confusing than useful). The idea was that user objects like scenes that trigger a job can be referenced.

"scene_input_channel" is an internal reference to the binding on the devices. This allows you to control all loads in a job at the same time with one kPlus frame.

[senadjukic]

Is there any timeline for the MQTT roadmap item? I see huge potential with lightweight integrations over NodeRed to Homey and other automation gateways, without the need to write a custom plugin.

Additionally to the wished (color) frontset settings, it woule be good to control frontset by time. E. g. if it is 10pm, change the frontset of all devices to minimal lightning and turn off frontset lights at 7am.

[woodworm]

In the next release for µGWv2 we will introduce MQTT client support in the scripting framework! Once we're ready, we'll provide sample scripts to help you get started.

For flexible access to the LED colors, a firmware adjustment on the device side would be necessary. This is in the roadmap, but I cannot say anything more specific about it yet.

[thomail]

What about MQTT for uGWv1?

[woodworm]

I will check it for the next µGWv1 release ... However, I’m concerned that this solution might not meet our expectations due to performance issues.

alternatively... contact Feller Support and ask for Woodworm... we will find a solution for you 😉

[PhilippImhof]

1. {"blocked_by": <systemflag_id>, ....} can also be a system flag. "blocked_by" works for all jobs, no matter how they are called.

It might be obvious for some, but does "blocked_by" prevent the job from running if the condition (or flag) is TRUE or if it is FALSE? (I think it is the former, because we have "not absent" as a condition that blocks simulation timers, but I'd rather be sure.)

If one can directly use a flag, what is the use in creating a condition with only one flag? Particularly, why is there a flag "absent" and a condition "not absent" rather than a flag "present" that could be used directly? Is that about backwards compatibility?

[woodworm]

A job can be blocked by one or more system states, each represented by a system flag. For instance, if there is a storm system flag, you may want to block all jobs that move the "Sonnenstoren", regardless of whether the job is triggered via the cloud as a scene, through a timer, or by a button on the wall. In this example, since there is only one system state, the job can be blocked using 'blocked_by': <storm_id>... so blocked if Storm is true.

However, if there are multiple conditions, you can use a conditions id instead of a single system flag. A condition can be defined using 'POST /api/system/conditions' {"expression": "(absent or storm) and not cleaning"}. The expression may only include system flag symbols and the operators "and," "or," "not," and "( )". The condition’s "value" is determined by evaluating the expression.

[PhilippImhof]

Perfect, thanks! So conditions "not absent" and "not vacation" are equivalent in the sense that one is to be used if the flag is named "absent" and the other if the flag is "vacation". That's a very nice implementation.