Dimmable Ballast

The Dimmable Ballast is a lighting device that switches on/off or have its level adjusted from a controller device, such as a Dimmer Switch, or simply be switched on/off from an Occupancy Sensor.

  • The Device ID is 0x0109.

  • The header file for the device is dimmable_ballast.h.

  • The clusters supported by the device are listed in Section 3.10.1.

  • The device structure, tsZLO_DimmableBallastDevice, is listed in Section 3.10.2.

  • The endpoint registration function for the device, eZLO_RegisterDimmableBallastEndPoint, is detailed in Section 3.10.3.

Supported clusters

The clusters used by the Dimmable Ballast device are listed in the table below.

Table 23.  Clusters for Dimmable Ballast

Server (Input) side

Client (Output) side

Mandatory

Basic

Power configuration

Device temperature configuration

Identify

Groups

Scenes

On/Off

Level control

Ballast configuration

Optional

Illuminance level sensing

OTA upgrade

Touchlink commissioning

Illuminance measurement

Illuminance level sensing

Occupancy sensing

The mandatory attributes within each cluster for this device type are indicated in the ZigBee Lighting and Occupancy Device Specification (15-0014-01).

Parent topic:Dimmable Ballast

Device Structure

The following tsZLO_DimmableBallastDevice structure is the shared structure for a Dimmable Ballast device:

typedef struct
{
    tsZCL_EndPointDefinition sEndPoint;
   /* Cluster instances */
   tsZLO_DimmableBallastDeviceClusterInstances sClusterInstance;
  /* Mandatory server clusters */
  #if (defined CLD_BASIC) && (defined BASIC_SERVER)
    /* Basic Cluster - Server */
    tsCLD_Basic sBasicServerCluster;
  #endif
  #if (defined CLD_IDENTIFY) && (defined IDENTIFY_SERVER)
    /* Identify Cluster - Server */
    tsCLD_Identify sIdentifyServerCluster;
    tsCLD_IdentifyCustomDataStructure
          sIdentifyServerCustomDataStructure;
  #endif
  #if (defined CLD_ONOFF) && (defined ONOFF_SERVER)
    /* On/Off Cluster - Server */
    tsCLD_OnOff sOnOffServerCluster;
    tsCLD_OnOffCustomDataStructure sOnOffServerCustomDataStructure;
  #endif
  #if (defined CLD_LEVEL_CONTROL) && (defined LEVEL_CONTROL_SERVER)
    /* LevelControl Cluster - Server */
    tsCLD_LevelControl sLevelControlServerCluster;
    tsCLD_LevelControlCustomDataStructure
    sLevelControlServerCustomDataStructure;
  #endif
#if (defined CLD_SCENES) && (defined SCENES_SERVER)
  /* Scenes Cluster - Server */
    tsCLD_Scenes sScenesServerCluster;
    tsCLD_ScenesCustomDataStructure sScenesServerCustomDataStructure;
  #endif
  #if (defined CLD_GROUPS) && (defined GROUPS_SERVER)
  /* Groups Cluster - Server */
    tsCLD_Groups sGroupsServerCluster;
    tsCLD_GroupsCustomDataStructure sGroupsServerCustomDataStructure;
  #endif
  #if (defined CLD_POWER_CONFIGURATION) && (defined
 POWER_CONFIGURATION_SERVER)
    /* Power Configuration Cluster - Server */
    tsCLD_PowerConfiguration sPowerConfigServerCluster;
  #endif
    #if (defined CLD_DEVICE_TEMPERATURE_CONFIGURATION) && (defined
  DEVICE_TEMPERATURE_CONFIGURATION_SERVER)
    /* Device Temperature Configuration Cluster - Server */
    tsCLD_DeviceTemperatureConfiguration
          sDeviceTemperatureConfigurationServerCluster;
    #endif
    #if (defined CLD_BALLAST_CONFIGURATION) && (defined
  BALLAST_CONFIGURATION_SERVER)
    tsCLD_BallastConfiguration sBallastConfigurationServerCluster;
    #endif
  /* Recommended Optional server clusters */
  #if (defined CLD_ILLUMINANCE_LEVEL_SENSING) && (defined
  ILLUMINANCE_LEVEL_SENSING_SERVER)
    tsCLD_IlluminanceLevelSensing
        sIlluminanceLevelSensingServerCluster;
  #endif
  #if (defined CLD_ZLL_COMMISSION) && (defined ZLL_COMMISSION_SERVER)
    tsCLD_ZllCommission sZllCommissionServerCluster;
    tsCLD_ZllCommissionCustomDataStructure
        sZllCommissionServerCustomDataStructure;
  #endif
/*Recommended Optional client clusters */
  #if (defined CLD_OTA) && (defined OTA_CLIENT)
    /* OTA cluster - Client */
    tsCLD_AS_Ota sCLD_OTA;
    tsOTA_Common sCLD_OTA_CustomDataStruct;
  #endif
  #if (defined CLD_ILLUMINANCE_MEASUREMENT) && (defined
  ILLUMINANCE_MEASUREMENT_CLIENT)
    /* Illuminance Measurement Cluster - Client */
    tsCLD_IlluminanceMeasurement sIlluminanceMeasurementClientCluster;
  #endif
    #if (defined CLD_ILLUMINANCE_LEVEL_SENSING) && (defined
  ILLUMINANCE_LEVEL_SENSING_CLIENT)
    tsCLD_IlluminanceLevelSensing
      sIlluminanceLevelSensingClientCluster;
  #endif
  #if (defined CLD_OCCUPANCY_SENSING) && (defined
  OCCUPANCY_SENSING_CLIENT)
      /* Occupancy Sensing Cluster - Client */
    tsCLD_OccupancySensing sOccupancySensingClientCluster;
  #endif
} tsZLO_DimmableBallastDevice;

Parent topic:Dimmable Ballast

Registration Function

The following eZLO_RegisterDimmableBallastEndPoint() function is the endpoint registration function for a Dimmable Ballast device.

teZCL_Status eZLO_RegisterDimmableBallastEndPoint(
uint8 u8EndPointIdentifier,
tfpZCL_ZCLCallBackFunction cbCallBack,
tsZLO_DimmableBallastDevice *psDeviceInfo);

Description

This function is used to register an endpoint that supports a Dimmable Ballast device. The function must be called after eZCL_Initialise().

The specified identifier for the endpoint is a number in the range 1 to 240 (endpoint 0 is reserved for ZigBee use). Application endpoints are normally numbered consecutively starting at 1. The specified number must be less than or equal to the value of ZLO_NUMBER_OF_ENDPOINTS defined in the zcl_options.h file, which represents the highest endpoint number used for applications.

While invoking this function, specify a user-defined callback function, which is invoked when an event associated with the endpoint occurs. This callback function is defined according to the typedef:

typedef void(* tfpZCL_ZCLCallBackFunction)
(tsZCL_CallBackEvent *pCallBackEvent);

Also provide a pointer to a tsZLO_DimmableBallastDevice structure, described in Section 3.10.2. This structure stores all variables relating to the color Controller device associated with the endpoint. The sEndPoint and sClusterInstance fields of this structure are set by this function and must not be directly written to by the application. The function is called multiple times if more than one endpoint is being used - for example, if more than one Dimmable Ballast device is housed in the same hardware, sharing the same module.

Parameters

  • u8EndPointIdentifier: Endpoint that is to be associated with the registered structure and callback function.

  • cbCallBack: Pointer to the function that is used to indicate events to the application for this endpoint.

  • psDeviceInfo: Pointer to the structure that acts as storage for all variables related to the device being registered on this endpoint (see Section 3.10.2). The sEndPoint and sClusterInstance fields are set by this register function for internal use and must not be written to by the application.

Returns

  1. E_ZCL_SUCCESS

  2. E_ZCL_FAIL

  3. E_ZCL_ERR_PARAMETER_NULL

  4. E_ZCL_ERR_PARAMETER_RANGE

  5. E_ZCL_ERR_EP_RANGE

  6. E_ZCL_ERR_CLUSTER_0

  7. E_ZCL_ERR_CALLBACK_NULL

  8. E_ZCL_ERR_CLUSTER_NULL

  9. E_ZCL_ERR_SECURITY_RANGE

  10. E_ZCL_ERR_CLUSTER_ID_RANGE

  11. E_ZCL_ERR_MANUFACTURER_SPECIFIC

  12. E_ZCL_ERR_ATTRIBUTE_TYPE_UNSUPPORTED

  13. E_ZCL_ERR_ATTRIBUTE_ID_ORDER

  14. E_ZCL_ERR_ATTRIBUTES_ACCESS

The above codes are described in the ZCL User Guide (JNUG3132).

Parent topic:Dimmable Ballast

Parent topic:Lighting and Occupancy Device Types