API state/buttonevent introspection query

deCONZ 3rd Party Integrations
1

@manup
@de_employees

This is a follow up to the 2025 deCONZ Development Overview / Roadmap(ish). As detailed in PR Add introspection REST API for state and config attributes #4933
this was only functional, as of the time of release, from the button_maps.json and since then the migration to DDF has increased significantly however, this seems not to have been modified to extract when the switches use explicit DDF to map buttons (i.e. rwl02_dimmer_switch.json)

Can you please clarify if state/buttonevent introspection is functional for switches that to the DDF buttons mapping.

If not is there a current roadmap to add this or is there an alternative API query to extract the button events for all switches?

Or am I missing something?

Thanks in advance.

2

I am also very interested in this topic. I have an iOS and macOS app that lets me converge Conbee / deConz bridge along with Hue bridges to give a single interface to allow control of the devices across the separate bridges. So if I have a room / group named Office on a Hue bridge as well as a Conbee then I will aggregate the devices into that single room / group named Office. In addition to the devices I also have the ability to create a “custom scene” that lets you add individual devices as well as “groups” to the scene and set the desired states for the devices or groups in the scene.

I would like to do the same for switches that are attached to a Conbee device. This has proven to be difficult trying to get the number of switches and button events across the different switches that Conbee uses. The macOS version I am working on runs on native Apple Silicon and is designed that it can be running in the background and will trigger a custom scene from motion sensors right now and I would like to add the ability to trigger scenes that span devices across the disparate bridges as well for a event from a switch device.

I would love to see where the JSON for switch devices included in the capabilities the buttons for that particular switch, along with the button events that it is capable of responding to. The introspect API seems to work for some switches but not all. Is there anything being done to address providing an API or including in the capabilities section of the devices JSON that will give a consistent and accurate representation of the physical number of buttons and the events they are capable of handling? ie… Short Press, Double Press, etc…

1 Like
3

Hi im currently looking into this to bring the introspection of buttons and events to DDFs.
Some DDFs already describe the buttons and events, but the data isn’t parsed yet. For example the Philips Dimmer switch https://github.com/dresden-elektronik/deconz-rest-plugin/blob/master/devices/philips/rwl022_dimmer_switch.json contains:

"buttonevents": {
        "1000": {
          "action": "PRESS",
          "button": 1
        },
        "1001": {
          "action": "HOLD",
          "button": 1
        },
        "1002": {
          "action": "SHORT_RELEASE",
          "button": 1
        },
...
}

These need to be parsed and exposed via API as it is done for other switches which are described in the legacy https://github.com/dresden-elektronik/deconz-rest-plugin/blob/master/button_maps.json file.

Also the documentation on the introspection needs to be completed.

Once the parsing code is finished we need to check all existing DDFs of switches and add above button descriptions if they aren’t already present.

4

Thank you for the understanding of what is occurring behind the scenes right now for the API’s regarding switches.

When I look at the API for switches currently in Phoscon I see that there is a “capabilities” section returned in the JSON. For most switches now all that is exposed there is the “sleeper” boolean. For the Signify switch that I have it shows that it also supports “otau” information. I would think that this would be the place to also add in the info that we see now using the introspect API. Then when we get the full resources API for the Conbee we already have all th info then regarding the switches. As it is on top of getting the full data from the Conbee then we have to go back and query to get the capability of a switch using the introspect API. If this data was populated in the capabilities of the switch then it’s one and done to get all the needed info from a Conbee bridge on all its “sensors / switches”.

5

@manup

Thank you for the reply, it is greatly appreciated and I acknowledge that the transition to fully utilised the DDF is still in progress.

I know as previously you indicated that “For REST-API plans there will be separate detailed post” and this may have been an early question and feedback however, I do agree with @lakehawk feedback. It is an especially good response whilst this is still under review and development. The proposal would result in more consistent, and efficient api if this was designed similar to lights capabilities as you detailed in the 2025 deCONZ Development Overview / Roadmap(ish). In doing so, this would enable a single call to extract the full dataset and you could potentially eventually deprecaite Introspection.

REST-API

For REST-API plans there will be separate detailed post. One goal is to continue to cleanup the internals and split out device and vendor specific handlers. The devices/ endpoint reading side needs to be completed and hooked into Websocket events. Last year we got the capabilities for devices in DDFs for lights. The API should also dynamically make use of this information so we can phase out more modelid specific code.

6

Hi quick update on the button events topic. I’ve added a PR which fixes the missing button and events in the introspection API → for switches which specify them in the DDF (like the Philips Hue Dimmer).

https://github.com/dresden-elektronik/deconz-rest-plugin/pull/8151

I support the idea to expose the same information via the capabilities API (see PR comments). Here we need to figure out how the API output should look like. The introspection API output works but is a bit clumsy.

1 Like
7

@manup

Thanks for the update. Excellent work and the PR has some very constructive discussion that I see has already been productive in aligning the future api.

8

@manup

Firstly thank you for the quick action and PR. I have installed 2.29.03 released 8 Apr 2024 and I can confirm that hue switches are now displaying using introspection APi.

I note the transition to use DDF “configuration” will be addressed a separate PR and I think that will be a real positive outcome in addressing the discrepancy where the switch buttons are incorrectly mapped in the button_map.json.