Electrical Measurement Cluster

This chapter outlines the Electrical Measurement cluster, which provides an interface for obtaining electrical measurements from a device.

The Electrical Measurement cluster has a Cluster ID of 0x0B04.

Overview

The Electrical Measurement cluster provides an interface for querying devices for electrical measurements.

  • The server is located on the device which makes the electrical measurements

  • The client is located on another device and queries the server for measurements

Separate instances of the Electrical Measurement cluster server can be implemented across multiple endpoints within the same physical unit - that is, one server instance per endpoint. An example is a power extension unit containing multiple outlets, where each power outlet allows electrical measurements to be made on the supplied power (e.g. AC RMS voltage and current).

The cluster is enabled by defining CLD_ELECTRICAL_MEASUREMENT in the zcl_options.h file. Further compile-time options for the Electrical Measurement cluster are detailed in Section 30.9.

The information that can potentially be stored in this cluster is organised into the following attribute sets:

  • Basic Information

  • DC Measurement

  • DC Formatting

  • AC (Non-phase Specific) Measurements

  • AC (Non-phase Specific) Formatting

  • AC (Single Phase or Phase A) Measurements

  • AC Formatting

  • DC Manufacturer Threshold Alarms

  • AC Manufacturer Threshold Alarms

  • AC Phase B Measurements

  • AC Phase C Measurements

Note that not all of the above attribute sets are currently implemented in the NXP software and not all attributes within a supported attribute set are implemented (see Section 30.2 for the supported attribute sets and attributes).

Parent topic:Electrical Measurement Cluster

Cluster structure and attributes

The structure definition for the Electrical Measurement cluster (server) is:

typedef struct
{
#ifdef ELECTRICAL_MEASUREMENT_SERVER
zbmap32 u32MeasurementType;
#ifdef CLD_ELECTMEAS_ATTR_AC_FREQUENCY
zuint16 u16ACFrequency;
#endif
#ifdef CLD_ELECTMEAS_ATTR_RMS_VOLTAGE
zuint16 u16RMSVoltage;
#endif
#ifdef CLD_ELECTMEAS_ATTR_RMS_CURRENT
zuint16 u16RMSCurrent;
#endif
#ifdef CLD_ELECTMEAS_ATTR_ACTIVE_POWER
zint16 i16ActivePower;
#endif
#ifdef CLD_ELECTMEAS_ATTR_REACTIVE_POWER
zint16 i16ReactivePower;
#endif
#ifdef CLD_ELECTMEAS_ATTR_APPARENT_POWER
zuint16 u16ApparentPower;
#endif
#ifdef CLD_ELECTMEAS_ATTR_POWER_FACTOR
zint8 i8PowerFactor;
#endif
#ifdef CLD_ELECTMEAS_ATTR_AC_VOLTAGE_MULTIPLIER
zuint16 u16ACVoltageMultiplier;
#endif
#ifdef CLD_ELECTMEAS_ATTR_AC_VOLTAGE_DIVISOR
zuint16 u16ACVoltageDivisor;
#endif
#ifdef CLD_ELECTMEAS_ATTR_AC_CURRENT_MULTIPLIER
zuint16 u16ACCurrentMultiplier;
#endif
#ifdef CLD_ELECTMEAS_ATTR_AC_CURRENT_DIVISOR
zuint16 u16ACCurentDivisor;
#endif
#ifdef CLD_ELECTMEAS_ATTR_AC_POWER_MULTIPLIER
zuint16 u16ACPowerMultiplier;
#endif
#ifdef CLD_ELECTMEAS_ATTR_AC_POWER_DIVISOR
zuint16 u16ACPowerDivisor;
#endif
#ifdef CLD_ELECTMEAS_ATTR_MAN_SPEC_APPARENT_POWER
zuint32 u32ManSpecificApparentPower;
#endif
#ifdef CLD_ELECTMEAS_ATTR_MAN_SPEC_NON_ACTIVE_POWER
zuint32 u32NonActivePower;
#endif
#ifdef CLD_ELECTMEAS_ATTR_MAN_SPEC_FNDMTL_REACTIVE_POWER
zint32 i32FundamentalReactivePower;
#endif
#ifdef CLD_ELECTMEAS_ATTR_MAN_SPEC_FNDMTL_APPARENT_POWER
zuint32 u32FundamentalApparentPower;
#endif
#ifdef CLD_ELECTMEAS_ATTR_MAN_SPEC_FNDMTL_POWER_FACTOR
zuint16 u16FundamentalPowerFactor;
#endif
#ifdef CLD_ELECTMEAS_ATTR_MAN_SPEC_NON_FNDMTL_APPARENT_POWER
zuint32 u32NonFundamentalApparentPower;
#endif
#ifdef CLD_ELECTMEAS_ATTR_MAN_SPEC_TOTAL_HARMONIC_DISTORTION
zuint32 u32TotalHarmonicDistortion;
#endif
#ifdef CLD_ELECTMEAS_ATTR_MAN_SPEC_VBIAS
zuint32 u32VBias;
#endif
#ifdef CLD_ELECTMEAS_ATTR_MAN_SPEC_DIVISOR
zuint16 u16ManSpecDivisor;
#endif
#endif
zuint16 u16ClusterRevision;
}tsCLD_ElectricalMeasurement;

where:

‘Basic Information’ Attribute Set

u32MeasurementType is a mandatory attribute which is a bitmap indicating the types of electrical measurement that can be performed by the deivice on which the cluster server resides. The bitmap is detailed below(a bit is set to ‘1’ if the corresponding measurement type is supported, or to ‘0’ otherwise):

Bits

Measurement Type

0

Active measurement (AC)

1

Reactive measurement (AC)

2

Apparent measurement (AC)

3

Phase A measurement

4

Phase B measurement

5

Phase C measurement

6

DC measurement

7

Harmonics measurement

8

Power quality measurement

9-31

Reserved

‘AC (Non-phase Specific) Measurements’ Attribute Set

  • u16ACFrequency is an optional attribute containing the most recent measurement of the AC frequency, in Hertz(Hz). The special value 0xFFFF is used to indicate that the frequency cannot be measured.

‘AC (Single Phase or Phase A) Measurements’ Attribute Set

Note that the attributes u16RMSVoltage, u16RMSCurrent and i16ActivePower must be enabled in conjunction with the corresponding multiplier/divisor pair in the ‘AC Formatting’ attribute set.

  • u16RMSVoltage is an optional attribute containing the most recent measurement of the Root Mean Square (RMS) voltage, in Volts. The special value 0xFFFF is used to indicate that the RMS voltage cannot be measured. Note that the ‘AC Formatting’ attributes u16ACVoltageMultiplier and u16ACVoltageDivisor must be implemented with this attribute.

  • u16RMSCurrent is an optional attribute containing the most recent measurement of the Root Mean Square (RMS) current, in Amps. The special value 0xFFFF is used to indicate that the RMS current cannot be measured. Note that the ‘AC Formatting’ attributes u16ACCurrentMultiplier and u16ACCurrentDivisor must be implemented with this attribute.

  • i16ActivePower is an optional attribute containing the present single-phase or Phase-A demand for active power, in Watts (W). A positive value represents active power delivered to the premises and a negative value represents active power received from the premises. Note that the ‘AC Formatting’ attributes u16ACPowerMultiplier and u16ACPowerDivisor must be implemented with this attribute.

  • i16ReactivePower is an optional attribute containing the present single-phase or Phase-A demand for reactive power, in Volts-Amps-reactive (VAr). A positive value represents reactive power delivered to the premises and a negative value represents reactive power received from the premises.

  • u16ApparentPower is an optional attribute containing the present single-phase or Phase-A demand for apparent power, in Volts-Amps (VA). This value is the positive square-root of i16ActivePower squared plus i16ReactivePower squared.

  • i8PowerFactor is an optional attribute containing the single-phase or Phase-A power factor ratio represented as a multiple of 0.01(e.g. the attribute value 0x0C represents a ratio of 0.12).

‘AC Formatting’ Attribute Set

The following attributes come in multiplier/divisor pairs, where each pair corresponds to an attribute of the ‘AC (Single Phase or Phase A) Measurements’ attribute set and must only be enabled if the corresponding attribute is enabled.

  • u16ACVoltageMultiplier is an optional attribute containing the multiplication factor to be applied to the value of the u16RMSVoltage attribute (above). This multiplication factor must be used in conjunction with the u16ACVoltageDivisor division factor. The value 0x0000 is not valid.

  • u16ACVoltageDivisor is an optional attribute containing the division factor to be applied to the value of the u16RMSVoltage attribute (above). This division factor must be used in conjunction with the u16ACVoltageMultiplier multiplication factor. The value 0x0000 is not valid.

  • u16ACCurrentMultiplier is an optional attribute containing the multiplication factor to be applied to the value of the u16RMSCurrent attribute (above). This multiplication factor must be used in conjunction with the u16ACCurrentDivisor division factor. The value 0x0000 is not valid.

  • u16ACCurrentDivisor is an optional attribute containing the division factor to be applied to the value of the u16RMSCurrent attribute (above). This division factor must be used in conjunction with the u16ACCurrentMultiplier multiplication factor. The value 0x0000 is not valid.

  • u16ACPowerMultiplier is an optional attribute containing the multiplication factor to be applied to the value of the i16ActivePower attribute (above). This multiplication factor must be used in conjunction with the u16ACPowerDivisor division factor. The value 0x0000 is not valid.

  • u16ACPowerDivisor is an optional attribute containing the division factor to be applied to the value of the i16ActivePower attribute (above). This division factor must be used in conjunction with the u16ACPowerMultiplier multiplication factor. The value 0x0000 is not valid.

Manufacturer-specific Attributes

  • u32ManSpecificApparentPower is an optional manufacturer-defined attribute containing the demand for apparent power.

  • u32NonActivePower is an optional manufacturer-defined attribute containing the demand for non-active power.

  • i32FundamentalReactivePower is an optional manufacturer-defined attribute containing the demand for fundamental reactive power.

  • u32FundamentalApparentPower is an optional manufacturer-defined attribute containing the demand for fundamental apparent power.

  • u16FundamentalPowerFactor is an optional manufacturer-defined attribute representing the power factor of a fundamental power system u32NonFundamentalApparentPower is an optional manufacturer-defined attribute representing the power factor of a non-fundamental (harmonic) power system.

  • u32TotalHarmonicDistortion is an optional manufacturer-defined attribute representing the total harmonic distortion present in the delivered power signal.

  • u32VBias is an optional manufacturer-defined attribute representing the bias voltage.

  • u16ManSpecDivisor is an optional manufacturer-defined attribute representing a power divisor.

Global Attributes

  • u16ClusterRevision is a mandatory attribute that specifies the revision of the cluster specification on which this cluster instance is based. The cluster specification in the ZCL r6 corresponds to a cluster revision of 1. The value is incremented by one for each subsequent revision of the cluster specification. This attributeis also described in Section2.4.

Parent topic:Electrical Measurement Cluster

Initialisation and Operation

The Electrical Measurement cluster must be initialised on both the cluster server and client. This can be done using the function eCLD_ElectricalMeasurementCreateElectricalMeasurement(), which creates an instance of the Electrical Measurement cluster on a local endpoint.

Once the cluster has been initialized, the application on the server should maintain the cluster attributes (see Section 30.2) with the electrical measurements made by the local device. The application on a client can remotely read these measured values using the ZCL ‘Read Attribute’ functions, as described in Section 2.3.2.

Parent topic:Electrical Measurement Cluster

Electrical Measurement Events

There are no events specific to the Electrical Measurement cluster.

Parent topic:Electrical Measurement Cluster

Functions

The following Electrical Measurement cluster function is provided:

eCLD_ElectricalMeasurementCreateElectricalMeasurement

teZCL_Status eCLD_ElectricalMeasurementCreateElectricalMeasurement(
    tsZCL_ClusterInstance *psClusterInstance,
    bool_t bIsServer,
    tsZCL_ClusterDefinition *psClusterDefinition,
    void *pvEndPointSharedStructPtr,
    uint8 *pu8AttributeControlBits);

Description

This function creates an instance of the Electrical Measurement cluster on an endpoint. The cluster instance is created on the endpoint which is associated with the supplied tsZCL_ClusterInstance structure and can act as a server or a client, as specified.

The function should only be called when setting up a custom endpoint containing one or more selected clusters (rather than the whole set of clusters supported by a standard ZigBee device). This function will create an Electrical Measurement cluster instance on the endpoint, but instances of other clusters may also be created on the same endpoint by calling their corresponding creation functions. For more details of creating cluster instances on custom endpoints, refer to Appendix D.

Note: This function must not be called for an endpoint on which a standard ZigBee device is used. In this case, the device and its supported clusters must be registered on the endpoint using the relevant device registration function from those described in the ZigBee Devices User Guide (JNUG3131).

When used, this function must be called after the stack has been started and after the ZCL has been initialized.

The function requires an array to be declared for internal use, which contains one element (of type uint8) for each attribute of the cluster. The array length is automatically adjusted by the compiler using the following declaration:

uint8 au8ElectricalMeasurementAttributeControlBits
[(sizeof(asCLD_ElectricalMeasurementClusterAttributeDefinitions) / sizeof(tsZCL_AttributeDefinition))];

Parameters

  • psClusterInstance        Pointer to structure containing information about the cluster instance to be created (see Section 6.1.16). This structure is updated by the function by initialising individual structure fields.

  • bIsServer         Type of cluster instance (server or client) to be created:

  • TRUE - server

  • FALSE - client

  • psClusterDefinition        Pointer to structure indicating the type of cluster to be created (see Section 6.1.2). In this case, this structure must contain the details of the Electrical Measurement cluster. This parameter can refer to a pre-filled structure called sCLD_``ElectricalMeasurement which is provided in the ElectricalMeasurement.h file.

  • pvEndPointSharedStructPtr        Pointer to the shared structure used for attribute storage. This parameter should be the address of the structure of type tsCLD_``ElectricalMeasurement which defines the attributes of Electrical Measurement cluster. The function initializes the attributes with default values.

  • pu8AttributeControlBits        Pointer to an array of uint8 values, with one element for each attribute in the cluster (see above). For a cluster client, set this pointer to NULL.

Returns

  • E_ZCL_SUCCESS

  • E_ZCL_FAIL

  • E_ZCL_ERR_PARAMETER_NULL

  • E_ZCL_ERR_INVALID_VALUE

Parent topic:Functions

Parent topic:Electrical Measurement Cluster

Return codes

The Electrical Measurement cluster function uses the ZCL return codes, listed in Section 7.2.

Parent topic:Electrical Measurement Cluster

Enumerations

‘Attribute ID’ Enumerations

The following structure contains the enumerations used to identify the attributes of the Electrical Measurement cluster.

typedef enum 
{
    E_CLD_ELECTMEAS_ATTR_ID_MEASUREMENT_TYPE
    E_CLD_ELECTMEAS_ATTR_ID_AC_FREQUENCY
    E_CLD_ELECTMEAS_ATTR_ID_RMS_VOLTAGE                   = 0x0505, 
    E_CLD_ELECTMEAS_ATTR_ID_RMS_CURRENT                   = 0x0508,
    E_CLD_ELECTMEAS_ATTR_ID_ACTIVE_POWER                  = 0x050B,
    E_CLD_ELECTMEAS_ATTR_ID_REACTIVE_POWER                = 0x050E,
    E_CLD_ELECTMEAS_ATTR_ID_APPARENT_POWER                = 0x050F,
    E_CLD_ELECTMEAS_ATTR_ID_POWER_FACTOR                  = 0x0510,
    E_CLD_ELECTMEAS_ATTR_ID_AC_VOLTAGE_MULTIPLIER         = 0x0600,
    E_CLD_ELECTMEAS_ATTR_ID_AC_VOLTAGE_DIVISOR            = 0x0601,
    E_CLD_ELECTMEAS_ATTR_ID_AC_CURRENT_MULTIPLIER         = 0x0602,
    E_CLD_ELECTMEAS_ATTR_ID_AC_CURRENT_DIVISOR            = 0x0603,
    E_CLD_ELECTMEAS_ATTR_ID_AC_POWER_MULTIPLIER           = 0x0604,
    E_CLD_ELECTMEAS_ATTR_ID_AC_POWER_DIVISOR              = 0x0605,
    E_CLD_ELECTMEAS_ATTR_ID_MAN_SPEC_APPARENT_POWER       = 0xFF00,
    E_CLD_ELECTMEAS_ATTR_ID_MAN_SPEC_NON_ACTIVE_POWER,
    E_CLD_ELECTMEAS_ATTR_ID_MAN_SPEC_FNDMTL_REACTIVE_POWER,
    E_CLD_ELECTMEAS_ATTR_ID_MAN_SPEC_FNDMTL_APPARENT_POWER,
    E_CLD_ELECTMEAS_ATTR_ID_MAN_SPEC_FNDMTL_POWER_FACTOR,
    E_CLD_ELECTMEAS_ATTR_ID_MAN_SPEC_NON_FNDMTL_APPARENT_POWER,
    E_CLD_ELECTMEAS_ATTR_ID_MAN_SPEC_TOTAL_HARMONIC_DISTORTION,
    E_CLD_ELECTMEAS_ATTR_ID_MAN_SPEC_VBIAS,
    E_CLD_ELECTMEAS_ATTR_ID_MAN_SPEC_DIVISOR,
} teCLD_ElectricalMeasurement_AttributeID;

Parent topic:Enumerations

Parent topic:Electrical Measurement Cluster

Structures

There are no structures specific to the Electrical Measurement cluster.

Parent topic:Electrical Measurement Cluster

Compile-time options

This section describes the compile-time options that may be enabled in the zcl_options.h file of an application that uses the Electrical Measurement cluster.

To enable the Electrical Measurement cluster in the code to be built, it is necessary to add the following line to the file:

#define CLD_ELECTRICAL_MEASUREMENT

In addition, to enable the cluster as a client or server, it is also necessary to add one of the following lines to the same file:

#define ELECTRICAL_MEASUREMENT_SERVER
#define ELECTRICAL_MEASUREMENT_CLIENT

Optional Attributes

The optional attributes for the Electrical Measurement cluster (see Section 30.2) are enabled by defining:

  • CLD_ELECTMEAS_ATTR_AC_FREQUENCY

  • CLD_ELECTMEAS_ATTR_RMS_VOLTAGE

  • CLD_ELECTMEAS_ATTR_RMS_CURRENT

  • CLD_ELECTMEAS_ATTR_ACTIVE_POWER

  • CLD_ELECTMEAS_ATTR_REACTIVE_POWER

  • CLD_ELECTMEAS_ATTR_APPARENT_POWER

  • CLD_ELECTMEAS_ATTR_POWER_FACTOR

  • CLD_ELECTMEAS_ATTR_AC_VOLTAGE_MULTIPLIER

  • CLD_ELECTMEAS_ATTR_AC_VOLTAGE_DIVISOR

  • CLD_ELECTMEAS_ATTR_AC_CURRENT_MULTIPLIER

  • CLD_ELECTMEAS_ATTR_AC_CURRENT_DIVISOR

  • CLD_ELECTMEAS_ATTR_AC_POWER_MULTIPLIER

  • CLD_ELECTMEAS_ATTR_AC_POWER_DIVISOR

  • CLD_ELECTMEAS_ATTR_MAN_SPEC_APPARENT_POWER

  • CLD_ELECTMEAS_ATTR_MAN_SPEC_NON_ACTIVE_POWER

  • CLD_ELECTMEAS_ATTR_MAN_SPEC_FNDMTL_REACTIVE_POWER

  • CLD_ELECTMEAS_ATTR_MAN_SPEC_FNDMTL_APPARENT_POWER

  • CLD_ELECTMEAS_ATTR_MAN_SPEC_FNDMTL_POWER_FACTOR

  • CLD_ELECTMEAS_ATTR_MAN_SPEC_NON_FNDMTL_APPARENT_POWER

  • CLD_ELECTMEAS_ATTR_MAN_SPEC_TOTAL_HARMONIC_DISTORTION

  • CLD_ELECTMEAS_ATTR_MAN_SPEC_VBIAS

  • CLD_ELECTMEAS_ATTR_MAN_SPEC_DIVISOR

Global Attributes

Add this line to define the value (n) of the Cluster Revision attribute:

#define CLD_APPLIANCE_STATISTICS_CLUSTER_REVISION <n>

The default value is 1, which corresponds to the revision of the cluster in the ZCL r6 specification (see Section 2.4).

Parent topic:Electrical Measurement Cluster