Hi @polow,
Please, find my answers below.
“actions”, you list all events that you specifically want ControllerX to take over AND you implicitly exclude all non listed events to be taken over by ControllerX
Correct, the available events can be found in the device page, under each integration (e.g. https://xaviml.github.io/controllerx/controllers/E1524_E1810)
“exclude_actions” you list all events you specifically don’t want ControllerX to take over AND you implicitly include all non listed events to be taken over by ControllerX
Correct, exclude_actions cannot be used together with actions, you will get an error.
By default, if the key “actions” is omitted from the config, all events will be taken over by ControllerX
Correct, all the events for that controller and that integration.
“mapping”, you replace the default action of the controller to what you specify
Correct, it “removes” the default mapping and just takes into account the events you specify. The key of the mapping is the event (what you would define in actions or exclude_actions and the value is the action(s) to be taken, which is what in ControllerX is called as action types. You can read more about the mapping and merge_mapping attribute in here.
“merge_mapping”, you add an action to the default action of the controller
It basically overwrites or add the action to the default mapping. If the action exists in the default mapping, then is overwritten, otherwise it gets added.
if you omit an action from “mapping” or “merge_mapping” it will keeps its default action
That is correct.
where is it defined what a default action is, ie after I factory reset my Hue Dimmer switch, how does it know (or does it even know) that the “up” button for example is supposed to send a dim up signal to whatever light it’s been associated with?
Good question, and probably it is not well explained in the documentation, so let me explain this to you. ControllerX has a list of supported devices, but the only thing we define for new devices is a default mapping. So, if you have a controller that is not in the list of supported devices, you can still use it if it is integrated with z2m, deconz or zha (well, zha might not work, but that is a separate topic). When a new device is added to ControllerX, I define a default mapping for that controller. For example in your case for the Philips Hue Dimmer, you can see the default mapping in this page under the Controller types (Light) section:
This is the default mapping for this controller:
Click release "on/off" → Turn on
Hold "on/off" → Color temp up / Right color wheel
Click release 🔆 → Brighten up (1 step)
Hold 🔆→ Brighten up
Click release 🔅 → Dim down (1 step)
Hold 🔅 → Dim down
Click release "hue" → Turn off
Hold "hue" → Color temp down / Left color wheel
This default mapping is defined in ControllerX, and we try to mimic what the controller does by default with the original integration (Tradfri, Hue Bridge, etc). However, if the ControllerX user is not happy with the default mapping, they can change it through configuration (mapping and merge_mapping). If you disagree with the default mapping for a Controller, you can raise your concern in GitHub issues, and we can discuss it. Some of the default mappings are done by intuition and not following 100% what the controller does with the original integration since it might be unknown by me (I do not have all the controllers ControllerX supports).
if I don’t list the “up_press” event in actions in my config then, “up_press” event are implicitly ignored but if i list it in actions then it will dim up the lights I’ve associated it with in the apps.yaml (unless I map that even to something else in the config)
These are different use cases you can do for the Philips929002398602LightController class:
- If you do not add a
mapping or merge_mapping, then the up_press event will bright up your light with 1 step.
- If you add
actions: [up_press], then the up_press will do the same, but the rest of the button won’t do anything since the only action included is up_press.
- If you add
mapping with up_press: toggle, then the up_press event will toggle the light, but the rest of the button won’t do anything since you used mapping and the default mapping gets overwritten.
- If you add
merge_mapping with up_press: toggle, then the up_press event will toggle the light, and the rest of the button will do what the default mapping specifies for this controller.
Hope this clarifies all your questions, and I also recommend you to go over some of the examples to see how different use cases can be configured.
Regards,
Xavi M.
Button event triggered: 
Running 