The ZigBee HDM adapter uses the ZigBee HomeDevice Customizer to change the values of device properties or add new ones.

The ZigBee HomeDevice Customizer

The customizer com.prosyst.mbs.services.zigbee.hdm.adapter.ZigBeeHomeDeviceCustomizer can be registered with matching filter specifying which ZigBee devices are subject of customization. If the service is registered without filter all ZigBee devices will pass through customizer. For security reasons ZigBee controllers are excluded by default.

The ZigBeeHomeDeviceCustomizer service defines the following matching criteria:

• MATCH_MANUFACTURER_CODE - A key for matching the manufacturer code field of the node descriptor.

  It filters only ZigBee devices corresponding to a specified manufacturer code. The node descriptor is defined for ZigBee device nodes (device root) which means that if this condition is not satisfied the device and its children will be skipped by the customizer.

• MATCH_ENDPOINTS_POLICY - A key which defines how to match and customize a device and its children. It specifies which endpoints must satisfy a given filter and how the customizer is applied to the device tree. There are three options:
  • CUSTOMIZE_ALL_ENDPOINTS - all child devices must fulfill the specified filter condition for the customizer to be applied on the whole device tree.
  • CUSTOMIZE_MATCHED_ENDPOINTS - only child devices whose endpoints fulfill the specified filter condition will be customized; this includes all descendants of the device sub-tree.
  • If this key specifying a concrete endpoint ID and the filter is matching an endpoint then the customizer is applied only to the corresponding device endpoint and its children.
• MATCH_ENDPOINTS_PROFILE_ID - A key for matching the profile identifier field of the endpoint descriptor.

  This field is used in conjunction with the provided endpoint(s) quantifier defining which endpoint(s) to be taken into account for customization.

  This filter entry requires MATCH_ENDPOINT to be specified. The type of the filter value is Integer.

• MATCH_ENDPOINTS_DEVICE_ID - A key for matching the device identifier field of the endpoint descriptor.

  This field is used in conjunction with the provided endpoint(s) quantifier defining which endpoint(s) to be taken into account for customization.

  This filter entry requires MATCH_ENDPOINT to be specified. The type of the filter value is Integer.

• MATCH_ENDPOINTS_DEVICE_VERSION - A key for matching the device version field of the endpoint descriptor.

  This field is used in conjunction with the provided endpoint(s) quantifier defining which endpoint(s) to be taken into account for customization.

  This filter entry requires MATCH_ENDPOINT to be specified. The type of the filter value is Integer.

The ZigBeeHomeDeviceCustomizer has the following properties:

• PROPERTY_HIDDEN_ENDPOINT - This configuration property is meaningful only for first level children representing device endpoints. If this property is set TRUE the corresponding endpoint will not be represented as Home Device. It is useful when it's necessary to filter some sort of devices in before they are added as home devices.
• PROPERTY_OCTET_STRING_ENCODING - Returns octet string encoding which can be used to parse or generate ZCL frame payload. The encoding can be set as property by home device customizer. If there is not particular string encoding for the device then ZCL payload will be handled with the common (default) octet string encoding.
• PROPERTY_CHAR_STRING_ENCODING - Returns char string encoding which can be used to parse or generate ZCL frame payload. The encoding can be set as property by home device customizer. If there is not particular string encoding for the device then ZCL payload will be handled with the common (default) char string encoding.

ZigBeeHomeDeviceCustomizer Methods

• public void beforeInit(HomeDeviceSpiAccess homeDeviceSpi, Map properties)

  This method is invoked before device initialization and before reading the basic properties. If some basic property is set in this method, that indicates it is already provided and will be skipped for reading from the remote device. It can be used to configure a home device before processing any ZigBee operations, i.e. to configure the encoding of character and octet strings, which are used in ZigBee as data types or to hide an endpoint device at the beginning. This method is called for each matching endpoint and ended with the root device. The last invocation with the root device guarantees that the whole device structure is created. On execution of this method the device class objects are not created yet.

• public void onInit(HomeDeviceSpiAccess homeDeviceSpi, Map properties)

  This method is invoked on device initialization after the basic properties are read. If some property is already set in a map it will be overridden. This method is called for each matching endpoint and ends with the root device. The last invocation with the root device guarantees that the whole device structure is created. On execution of this method the device class objects are not created yet.

• public void onAdd(HomeDeviceSpiAccess homeDeviceSpi, Map properties)

  This method is invoked after devices are added to HDM and all device class objects are created. It guarantees that the whole device structure is already created and device class objects are activated, then it is called for the first root device downwards through its children.

• public void onUpdate(HomeDeviceSpiAccess homeDeviceSpi, Map properties)

  This method is invoked on device update. It guarantees that the whole device structure is already created and all device class objects are activated, then it is called for the first root device downwards through its children.

• public void onRemove(HomeDeviceSpiAccess homeDeviceSpi)

  This method is invoked when a home device is removed.

Examples

The following code snippet is an example registration of a customizer with a filter matching all devices with ZigBee profile ID: 0x1001. CUSTOMIZE_ALL_ENDPOINTS requires that all active endpoints of a device have ZigBee profile ID: 0x1001. In this case the customizer is applied to the root device and all endpoint devices (including their children). If some of the endpoints of a device do not have profile ID: 0x1001 the customizer is not applied to this device.

Properties matching = new Properties();
matching.put(ZigBeeHomeDeviceCustomizer.MATCH_ENDPOINTS_POLICY, ZigBeeHomeDeviceCustomizer.CUSTOMIZE_ALL_ENDPOINTS);
matching.put(ZigBeeHomeDeviceCustomizer.MATCH_ENDPOINTS_PROFILE_ID,  new Integer(0x1001));
customizerReg = context.registerService(ZigBeeHomeDeviceCustomizer.class.getName(), customizer, matching);

The following code snippet is an example registration of a customizer with a filter matching all endpoints with ZigBee profile ID: 0x1001 and device ID: 0x0001. The customizer is applied to all endpoint devices matching the above criteria, as well as to their root devices. If some of the endpoints do not have the specified profile ID or device ID the customizer is not applied to them.

Properties matching = new Properties();
matching.put(ZigBeeHomeDeviceCustomizer.MATCH_ENDPOINTS_POLICY, ZigBeeHomeDeviceCustomizer.CUSTOMIZE_MATCHED_ENDPOINTS);
matching.put(ZigBeeHomeDeviceCustomizer.MATCH_ENDPOINTS_PROFILE_ID,  new Integer(0x1001));
matching.put(ZigBeeHomeDeviceCustomizer.MATCH_ENDPOINTS_DEVICE_ID,  new Integer(0x0001));
customizerReg = context.registerService(ZigBeeHomeDeviceCustomizer.class.getName(), customizer, matching);

The following code snippet is an example registration of a customizer with a filter matching all devices with manufacturer code: 0x1234. Note that the manufacturer code is obtained from the ZigBee node descriptor, which represents the whole ZigBee device structure, and there is no need to specify which endpoints have to be checked. The customizer is applied to the root device and its children and downwards through the whole device structure.

Properties matching = new Properties();
matching.put(ZigBeeHomeDeviceCustomizer.MATCH_MANUFACTURER_CODE,  new Integer(0x1234));
customizerReg = context.registerService(ZigBeeHomeDeviceCustomizer.class.getName(), customizer, matching);

The following code snippet is an example registration of a customizer with a filter matching all devices with manufacturer code: 0x1234, profile ID: 0x1001 and device ID: 0x0001. If MATCH_ENDPOINTS_POLICY has the value CUSTOMIZE_ALL_ENDPOINTS the customizer will be applied to all devices with manufacturer code: 0x1234 whose endpoints all have profile ID: 0x1001 and device ID: 0x0001.

Properties matching = new Properties();
matching.put(ZigBeeHomeDeviceCustomizer.MATCH_MANUFACTURER_CODE,  new Integer(0x1234));
matching.put(ZigBeeHomeDeviceCustomizer.MATCH_ENDPOINTS_POLICY, ZigBeeHomeDeviceCustomizer.CUSTOMIZE_MATCHED_ENDPOINTS);
matching.put(ZigBeeHomeDeviceCustomizer.MATCH_ENDPOINTS_PROFILE_ID,  new Integer(0x1001));
matching.put(ZigBeeHomeDeviceCustomizer.MATCH_ENDPOINTS_DEVICE_ID,  new Integer(0x0001));
customizerReg = context.registerService(ZigBeeHomeDeviceCustomizer.class.getName(), customizer, matching);