To contribute to this page, edit the following file

Ubisys C4 #

Model C4
Vendor Ubisys
Description Control unit C4
Exposes action, linkquality
Picture Ubisys C4

Notes #

General #

The ubisys C4 remote control unit seems to be primarily targeted to be directly bound to other ZigBee devices to control them. Therefore it does not emit plain “click” events or similar but can be configured to send ZigBee commands like on, off, toggle, cover up, cover down etc. from up to 6 endpoints (4 with on/off, level and scene clusters for lights and another 2 to control window covering devices). When used with Zigbee2MQTT all endpoints get bound to the coordinator automatically. Therefore all actions will be sent to the coordinator and forwarded to MQTT in addition to being sent directly via ZigBee to other devices that have potentially been bound manually (see Binding for more information). In its factory reset configuration an ubisys C4 just sends a toggle command (originating from endpoints 1 to 4 respectively) for each input. Therefore basic keypresses on attached momentary switches can be processed through Zigbee2MQTT even without further input configuration.

Configuring Inputs #

The inputs of most ubisys devices can be configured in a very flexible way to map state transitions (e.g. ‘released’ to ‘pressed’) to Zigbee commands (e.g. ‘toggle’). This even applies to the way in which these inputs control a local load (for ubisys devices other than the C4).

Templates #

By publishing to zigbee2mqtt/FRIENDLY_NAME/set using the JSON properties configure_device_setup and input_action_templates the inputs can be configured using templates. This allows to configure some common use cases without having to fully dive into the details of input_actions (see Raw Configuration below).

Valid template types are:

General attributes:

The input(s) and endpoint used will also be output to the Zigbee2MQTT log (flagged as warnings but only to make sure they do not get suppressed).

Attributes only used with dimmer templates:

Attributes only used with scene templates

On the C4, the respective outbound endpoint also needs to be bound to one or more target devices (see Binding below) for most of the template types (besides scene control).

Please also note that there seems to be a size limit on the amount of data that can successfully be written using input_action_templates, so not all combinations theoretically possible will work in reality.

Template Examples #

"//_comment" fields are really just comments only, will be ignored (as any other additional JSON properties) and can certainly be omitted. They are just used here since normal JavaScript comments (//) would not be considered valid JSON and therefore Zigbee2MQTT would throw an error.

C4 Default Configuration

{
    "configure_device_setup": {
        "input_action_templates": [
            {
                "//_comment": "will automatically use input 0 and endpoint 1",
                "type": "toggle"
            },
            {
                "//_comment": "will automatically use input 1 and endpoint 2",
                "type": "toggle"
            },
            {
                "//_comment": "will automatically use input 2 and endpoint 3",
                "type": "toggle"
            },
            {
                "//_comment": "will automatically use input 4 and endpoint 4",
                "type": "toggle"
            }
        ]
    }
}

Control a dimming light with inputs 1 (up) and 0 (down) and use input 3 to toggle a different light

{
    "configure_device_setup": {
        "input_action_templates": [
            {
                "//_comment": "will automatically use endpoint 1",
                "type": "dimmer_double",
                "inputs": [1, 0]
            },
            {
                "//_comment": "will automatically use endpoint 2",
                "type": "toggle",
                "input": 3
            }
        ]
    }
}

Use separate up and down push buttons with a D1

{
    "configure_device_setup": {
        "input_action_templates": [
            {
                "//_comment": "will automatically use inputs 0 and 1 and endpoint 2 (first outbound endpoint on a D1)",
                "type": "dimmer_double"
            }
        ]
    }
}

Use stationary switches instead of push buttons with a J1

{
    "configure_device_setup": {
        "input_action_templates": [
            {
                "//_comment": "will automatically use inputs 0 and 1 and endpoint 2 (first outbound endpoint on a J1)",
                "type": "cover_switch"
            }
        ]
    }
}

Control a dimming light with inputs 0 and 1 and recall scenes with 3 and 4

{
    "configure_device_setup": {
        "input_action_templates": [
            {
                "//_comment": "will automatically use inputs 0 and 1 and endpoint 1",
                "type": "dimmer_double"
            },
            {
                "//_comment": "will automatically use input 3 (endpoint does not really matter for scenes)",
                "type": "scene",
                "group_id": 1000,
                "scene_id": 10
            },
            {
                "//_comment": "will automatically use input 4 and group id 1000",
                "type": "scene",
                "scene_id": 11
            }
        ]
    }
}

Raw Configuration #

By publishing to zigbee2mqtt/FRIENDLY_NAME/set the following device attributes can be set to rawly configure inputs:

{
    "configure_device_setup": {
        "input_configurations": [0, 0, 0, 0],
        "input_actions": [
            [0, 13, 1, 6, 0, 2],
            [1, 13, 2, 6, 0, 2],
            [2, 13, 3, 6, 0, 2],
            [3, 13, 4, 6, 0, 2]
        ]
    }
}

For further details on these attributes please take a look at the ubisys C4 Technical Reference Manual, chapter “7.8.5. Device Setup Cluster (Server)” (or the respective ubisys reference manual of the device in use in case it’s not a C4) and the “ZigBee Device Physical Input Configurations Integrator’s Guide” (which can be obtained directly from ubisys upon request).

Please note that there seems to be a size limit on the amount of data that can successfully be written to input_actions, so not all configurations theoretically possbile might work in reality.

By publishing to zigbee2mqtt/FRIENDLY_NAME/get/configure_device_setup the values of the configuration attributes can also be read back from the device and be printed to the normal Zigbee2MQTT log.

Binding #

Most of the input_actions and input_action_templates (besides scene control) do not reference a target device directly but make use of the binding table of a specific outbound endpoint (for C4 see General above, for other ubisys devices take a look at the respective ubisys reference manual). For the C4, Zigbee2MQTT will always bind all endpoints to the coordinator automatically (so Zigbee2MQTT will be able to forward button presses to MQTT), but to control any other ZigBee device or group directly, it is necessary to bind the outbound endpoints used to the target (device or group).

When binding (or unbinding), it is important to explicitly specify the outbound endpoint as the source, e.g. zigbee2mqtt/bridge/request/device/bind payload {"from": "SOURCE_DEVICE_FRIENDLY_NAME/2", "to": "TARGET"} (also see Binding specific endpoint). Endpoints can be specified in numeric form and it is usually not necessary to specify an endpoint for the target device.

For ubisys devices other than the C4 this also allows to use the secondary input to control a different device. Example: Use the secondary input on a D1 (uses outbound endpoint 3 in the factory configuration) to control a separate ZigBee bulb:

mosquitto_pub -t zigbee2mqtt/bridge/request/device/bind -m '{"from": "DIMMER_FRIENDLY_NAME/3", "to": "ANOTHER_BULB_FRIENDLY_NAME"}'

Decoupling #

For ubisys devices other than the C4 this even allows to completely decouple the local input from the local output. Example: Unbind the switch input from the local load and use it to instead control a group of lights without cutting the power to the bulbs (the switch output can still be controlled via ZigBee, e.g. via MQTT through Zigbee2MQTT):

mosquitto_pub -t zigbee2mqtt/bridge/request/device/unbind -m '{"from": "SWITCH_FRIENDLY_NAME/2", "to": "SWITCH_FRIENDLY_NAME"}'
mosquitto_pub -t zigbee2mqtt/bridge/request/device/bind -m '{"from": "SWITCH_FRIENDLY_NAME/2", "to": "GROUP_NAME"}'

To restore the original behavior you unbind the group and rebind the device:

mosquitto_pub -t zigbee2mqtt/bridge/request/device/unbind -m '{"from": "SWITCH_FRIENDLY_NAME/2", "to": "GROUP_NAME"}'
mosquitto_pub -t zigbee2mqtt/bridge/request/device/bind -m '{"from": "SWITCH_FRIENDLY_NAME/2", "to": "SWITCH_FRIENDLY_NAME"}'

Device type specific configuration #

How to use device type specific configuration

OTA updates #

This device supports OTA updates, for more information see OTA updates.

Exposes #

Action (enum) #

Triggered action (e.g. a button click). Value can be found in the published state on the action property. It’s not possible to read (/get) or write (/set) this value. The possible values are: 1_scene_*, 1_on, 1_off, 1_toggle, 1_level_move_down, 1_level_move_up, 2_scene_*, 2_on, 2_off, 2_toggle, 2_level_move_down, 2_level_move_up, 3_scene_*, 3_on, 3_off, 3_toggle, 3_level_move_down, 3_level_move_up, 4_scene_*, 4_on, 4_off, 4_toggle, 4_level_move_down, 4_level_move_up, 5_scene_*, 5_cover_open, 5_cover_close, 5_cover_stop, 6_scene_*, 6_cover_open, 6_cover_close, 6_cover_stop.

Linkquality (numeric) #

Link quality (signal strength). Value can be found in the published state on the linkquality property. It’s not possible to read (/get) or write (/set) this value. The minimal value is 0 and the maximum value is 255. The unit of this value is lqi.

Manual Home Assistant configuration #

Although Home Assistant integration through MQTT discovery is preferred, manual integration is possible with the following configuration:

sensor:
  - platform: "mqtt"
    state_topic: "zigbee2mqtt/<FRIENDLY_NAME>"
    availability_topic: "zigbee2mqtt/bridge/state"
    value_template: "{{ value_json.action }}"
    icon: "mdi:gesture-double-tap"

sensor:
  - platform: "mqtt"
    state_topic: "zigbee2mqtt/<FRIENDLY_NAME>"
    availability_topic: "zigbee2mqtt/bridge/state"
    value_template: "{{ value_json.linkquality }}"
    unit_of_measurement: "lqi"
    enabled_by_default: false
    icon: "mdi:signal"
    state_class: "measurement"

sensor:
  - platform: "mqtt"
    state_topic: "zigbee2mqtt/<FRIENDLY_NAME>"
    availability_topic: "zigbee2mqtt/bridge/state"
    icon: "mdi:update"
    value_template: "{{ value_json['update']['state'] }}"
    enabled_by_default: false

binary_sensor:
  - platform: "mqtt"
    state_topic: "zigbee2mqtt/<FRIENDLY_NAME>"
    availability_topic: "zigbee2mqtt/bridge/state"
    payload_on: true
    payload_off: false
    value_template: "{{ value_json.update_available}}"
    enabled_by_default: false