Appendix D: Custom endpoints

A ZigBee device and its associated clusters can be registered on an endpoint using the relevant device registration function, from those listed and described in the ZigBee Devices User Guide (JNUG3131). However, it is also possible to set up a custom endpoint which supports selected clusters (rather than a whole ZigBee device and all of its associated clusters). Custom endpoints are particularly useful when using multiple endpoints on a single node - for example, the first endpoint may support a complete ZigBee device (such as a Light Sensor) while one or more custom endpoints are used to support selected clusters.

Appendix D.1: Devices and Endpoints

When using custom endpoints, it is important to note the difference between the following ‘devices’:

  • Physical device: This is the physical entity which is the network node

  • Logical device: This is a software entity which implements a specific set of functionality on the node, e.g. On/Off Switch device

A ZigBee network node may contain multiple endpoints, where one endpoint is used to represent the ‘physical device’ and other endpoints are used to support ‘logical devices’. The following rules apply to cluster instances on endpoints:

  • All cluster instances relating to a single ‘logical device’ must reside on a single endpoint.

  • The Basic cluster relates to the ‘physical device’ rather than a ‘logical device’ instance. There can be only one Basic cluster server for the entire node, which can be implemented in either of the following ways:

    • A single cluster instance on a dedicated ‘physical device’ endpoint

    • A separate cluster instance on each ‘logical device’ endpoint, but each cluster instance must use the same tsZCL_ClusterInstance structure (and the same attribute values)

Parent topic:Appendix D: Custom endpoints

Appendix D.2: Cluster Creation Functions

For each of the following clusters, a creation function is provided which creates an instance of the cluster on an endpoint:

  • Basic: eCLD_BasicCreateBasic()

  • Power Configuration: eCLD_PowerConfigurationCreatePowerConfiguration()

  • Device Temperature Configuration: eCLD_DeviceTemperatureConfigurationCreateDeviceTemperatureConfiguration()

  • Identify: eCLD_IdentifyCreateIdentify()

  • Groups: eCLD_GroupsCreateGroups()

  • Scenes: eCLD_ScenesCreateScenes()

  • On/Off: eCLD_OnOffCreateOnOff()

  • On/Off Switch Configuration: eCLD_OOSCCreateOnOffSwitchConfig()

  • Level Control: eCLD_LevelControlCreateLevelControl()

  • Alarms: eCLD_AlarmsCreateAlarms()

  • Time: eCLD_TimeCreateTime()

  • Analogue Input (Basic): eCLD_AnalogInputBasicCreateAnalogInputBasic()

  • Analogue Output (Basic): eCLD_AnalogOutputBasicCreateAnalogOutputBasic()

  • Binary Input (Basic): eCLD_BinaryInputBasicCreateBinaryInputBasic()

  • Binary Output (Basic): eCLD_BinaryOutputBasicCreateBinaryOutputBasic()

  • Multistate Input (Basic): eCLD_MultistateInputBasicCreateMultistateInputBasic()

  • Multistate Output (Basic): eCLD_MultistateOutputBasicCreateMultistateOutputBasic()

  • Poll Control: eCLD_PollControlCreatePollControl()

  • Power Profile: eCLD_PPCreatePowerProfile()

  • Diagnostics: eCLD_DiagnosticsCreateDiagnostics()

  • Illuminance Measurement: eCLD_IlluminanceMeasurementCreateIlluminanceMeasurement()

  • Illuminance Level Sensing: eCLD_IlluminanceLevelSensingCreateIlluminanceLevelSensing()

  • Temperature Measurement: eCLD_TemperatureMeasurementCreateTemperatureMeasurement()

  • Pressure Measurement: eCLD_PressureMeasurementCreatePressureMeasurement()

  • Flow Measurement: eCLD_FlowMeasurementCreateFlowMeasurement()

  • Relative Humidity Measurement: eCLD_RelativeHumidityMeasurementCreateRelativeHumidityMeasurement()

  • Occupancy Sensing: eCLD_OccupancySensingCreateOccupancySensing()

  • Electrical Measurement: eCLD_ElectricalMeasurementCreateElectricalMeasurement()

  • Colour Control: eCLD_ColourControlCreateColourControl()

  • Ballast Configuration: eCLD_BallastConfigurationCreateBallastConfiguration()

  • Thermostat: eCLD_ThermostatCreateThermostat()

  • Thermostat User Interface Configuration: eCLD_ThermostatUIConfigCreateThermostatUIConfig()

  • Door Lock: eCLD_DoorLockCreateDoorLock()

  • IAS Zone: eCLD_IASZoneCreateIASZone()

  • IAS Ancillary Control Equipment (ACE): eCLD_IASACECreateIASACE()

  • IAS Warning Device (WD): eCLD_IASWDCreateIASWD()

  • Price: eSE_PriceCreate()

  • Demand-Response and Load Control (DRLC): eSE_DRLCCreate()

  • Simple Metering: eSE_SMCreate()

  • Commissioning:eCLD_CommissioningClusterCreateCommissioning()

  • Touchlink Commissioning: eCLD_ZllCommissionCreateCommission()

  • Appliance Control: eCLD_ApplianceControlCreateApplianceControl()

  • Appliance Identification: eCLD_ApplianceIdentificationCreateApplianceIdentification()

  • Appliance Events and Alerts: eCLD_ApplianceEventsAndAlertsCreateApplianceEventsAndAlerts()

  • Appliance Statistics: eCLD_ApplianceStatisticsCreateApplianceStatistics()

  • Over-The-Air (OTA) Upgrade: eOTA_Create()

More than one of the above functions can be called for the same endpoint in order to create multiple cluster instances on the endpoint.

Note: No more than one server instance and one client instance of a given cluster can be created on a single endpoint (e.g. one Identify cluster server and one Identify cluster client, but no further Identify cluster instances).

The creation functions for clusters are described in the corresponding chapters of this manual.

Parent topic:Appendix D: Custom endpoints

Appendix D.3: Custom Endpoint Set-up

In order to set up a custom endpoint (supporting selected clusters), you must do the following in your application code:

  1. Create a structure for the custom endpoint containing details of the cluster instances and attributes supported - see Custom Endpoint Structure below.

  2. Initialise the fields of the tsZCL_EndPointDefinition structure for the endpoint.

  3. Call the relevant cluster creation function(s) for the cluster(s) to be supported on the endpoint - see Appendix D.2.

  4. Call the ZCL function eZCL_Register() for the endpoint.

Custom Endpoint Structure

In your application code, to set up a custom endpoint you must create a structure containing details of the cluster instances and attributes to be supported on the endpoint. This structure must include the following:

  • A definition of the custom endpoint through a tsZCL_EndPointDefinition structure - for example:

    • tsZCL_EndPointDefinition sEndPoint

  • A structure containing a set of tsZCL_ClusterInstance structures for the supported cluster instances - for example:

typedef struct
{
    tsZCL_ClusterInstance sBasicServer;
    tsZCL_ClusterInstance sBasicClient;
    tsZCL_ClusterInstance sIdentifyServer;
    tsZCL_ClusterInstance sOnOffCluster;
    tsZCL_ClusterInstance sDoorLockCluster;
} tsHA_AppCustomDeviceClusterInstances

  • For each cluster instance that is not shared with another endpoint, the following should be specified via the relevant tsZCL_ClusterInstance structure:

  • Attribute definitions, if any - for example, the tsCLD_Basic structure for the Basic cluster

  • Custom data structures, if any - for example, the tsIdentify_CustomStruct structure for the Identify cluster

  • Memory for tables or any other resources, if required by the cluster creation function

Note: If a custom endpoint is to co-exist with a device endpoint, the endpoints can share the structures for the clusters that they have in common. Therefore, it is not necessary to define these cluster structures for the custom endpoint, since they already exist for the device endpoint.

Parent topic:Appendix D: Custom endpoints