Exposes for device integration
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.
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')],
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.
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.
then look in tree for new objects.Edit your scripts to use the new objects
clean old objects with
Exposes are used as default for all devices.
It is possible to use the new local overrides functionality described in the readme and adapter documentation, but use of this functionality is considered experimental. It links the converters to the existing legacy device definitions in the zigbee Adapter code. This code is considered abandoned as of Jun 2025. Changes will not be made by the adapter developers on this code. Changes authored and tested by uses with access to specific devices may be integrated if a PR is made. The suggested method of retaining the legacy device definition configuration is to use the respective converter as an external converter.
After installation of the Adapter version 2.0 or newer, the Adapter will color orphaned states orange in the object tree to mark them as no longer being actively managed (changes will not be sent to the device, and device changes will not feed into these states). This is done at any adapter start - any change to the local overrides will trigger this function as well. The option to remove orphaned states is displayed as long as there is at least one orphaned state within the object tree. See the in depth documentation for details.