Exposes for device integration

What are exposes and why are they good for us

Using exposes the converters can tell a client (i.e. the iobroker.zigbee adapter) which functionalities a device can offer. This definition includes additional data which enables the client to set up its own actions automatically based on the provided information. This means that a device which is exposing all its functions can be supported by the zigbee adapter with no code change in the adapter itself.

How are they defined

The definitions for each device in the zigbee-herdsman-converters are placed device description contained in the file devices.js.

    {
        zigbeeModel: ['TS130F'],
        model: 'TS130F',
        vendor: 'TuYa',
        description: 'Curtain/blind switch',
        fromZigbee: [fz.cover_position_tilt, fz.tuya_backlight_mode, fz.tuya_cover_options],
        toZigbee: [tz.cover_state, tz.cover_position_tilt, tz.tuya_cover_calibration, tz.tuya_cover_reversal, tz.tuya_backlight_mode],
        exposes: [e.cover_position(), exposes.enum('moving', exposes.access.STATE, ['UP', 'STOP', 'DOWN']),
            exposes.binary('calibration', exposes.access.ALL, 'ON', 'OFF'),
            exposes.enum('backlight_mode', exposes.access.ALL, ['LOW', 'MEDIUM', 'HIGH']),
            exposes.binary('motor_reversal', exposes.access.ALL, 'ON', 'OFF')],
    },

The code above describes a specific Curtain/blind switch. The hardware is identified by the model ID sent through the zigbee network. This must match one of the strings listed as zigbeeModel. For some devices - most notably TuYa and TuYa compatible devices, the model ID sent by the device is not unique, so instead of the zigbeeModel entry, a fingerprint entry can be used to identify the device. fingerprint: [{modelID: 'TS0601', manufacturerName: '_TZE200_nkjintbl'}], In this case, all items in the fingerprint must match the description in order for the device being matched to the configuration.

model, vendor and description are made available to the client for information.

fromZigbee and toZigbee contain references to the converters used to convert zigbee datagrams into standard Key/Value pairs for or vice versa for further processing. Without these converters, the zigbee adapter cannot communicate with the device outside the developer tab.

exposes is what this page is about.

Note: Some devices, especially lights and lamps will lack fromZigbee, toZigbee and exposes definitions. Instead, they feature a single extends entry. In this case, the extended entry already provides fitting converters and exposes for the device. When implementing a light device in the zigbee-herdsman-converters, extending a preset is preferred over copying entries.

The exposes reference to a number of functions defined in the file lib/exposes. There are a number of "generic" expose types (binary, composite, enum, numeric, text), a number of complex types (climate, cover, light, switch) as well as a large number of detailed presets. Presets should be used rather than generic types wherever feasible. Most presets only require the name of the preset (e.conver_position()) with no parameters, where type exposes need to be set with the correct number of parameters (exposes.enum('backlight_mode', exposes.access.ALL, ['LOW', 'MEDIUM', 'HIGH']),). As default, all type based exposes require as first parameter the name of the state to be exposed to the client and as second parameter the access to this state (options being exposes.access.STATE, exposes.access.SET, exposes.access.STATE_SET, expose.access.STATE_GET, expose.access.ALL). Note that the type enum also requires definition of the different selections. These will be made available as selections in the respective iobroker state as well. Complex types require additional parameters to define the features available for this device. These need to match the options given in the expose definition and usually are defined this form: exposes: [e.switch().withEndpoint('top'), e.switch().withEndpoint('bottom')],

How are they used

The exposes define which states will be available for a device as well as details to the state including a unit, limits or selection options. The zigbee adapter generates these states automatically for any device which does not contain a local state definition. This offers the chance of supporting base functionality for a device without any device specific code changes in the zigbee adapter.

What do i do if a device exposes a feature but no states are generated for this feature.

Most exposes defined by the zigbee-herdsman-converters should automatically lead to states being generated in the zigbee adapter. In the unlikely case that no states are generated, it is advised to create an issue listing

• which device is affected
• the exposes from the device descriptions which do not generate states
• expected behaviour of the device.

How are they used in adapter

then look in tree for new objects.Edit your scripts to use the new objects

clean old objects with