ZigBee Smart Energy Frame Generation and Decoding

This example shows how to generate and decode ZigBee® Smart Energy frames using the Communications Toolbox™.

Background

The ZigBee standard [ 2 ] specifies network (NET or NWK) and application (APP or APL) layers of low-rate wireless personal area networks (LR-WPANs). These NET- and APP-layer specifications build upon the PHY and MAC specifications of IEEE® 802.15.4™ [ 3 ]. ZigBee devices find application in home automation and sensor networking and are highly relevant to the Internet of Things (IoT) trend.

The ZigBee application layer consists of multiple sub-layers: (i) the Application Support Sublayer (APS), and (ii) the ZigBee Cluster Library (ZCL).

The APS and ZCL headers follow a format that is common for all application profiles and ZigBee clusters (see Clauses 2.2.5 in [ 2 ] and 2.4 in [ 4 ], respectively). The ZCL payload is used only by some clusters and it follows a cluster-specific format. The generic APS and ZCL header generation and decoding is illustrated in the ZigBee Home Automation Frame Generation and Decoding example. This example illustrates the cluster-specific generation and decoding of ZigBee smart energy ZCL payloads.

Clusters and Commands

Out of the 7 clusters used in the Smart Energy application profile, this example generates and decodes frames for the following clusters:

Demand response and load control (DRLC) cluster: This cluster advertises changes to energy demand and consumption. This example illustrates frame generation and decoding for the Load Control Event command (described in Clause 10.3.2.3.1 of [ 4 ]).
Price cluster: This cluster communicates Energy, Gas or Water pricing information. This example illustrates frame generation and decoding for the Get Current Price and Publish Price commands (described in Clause 10.2.2.3.1 of [ 4 ]).
Messaging cluster: This cluster exchanges text messages between ZigBee devices. This example illustrates frame generation and decoding for the Display Message command (described in Clause 10.5.2.3.1 of [ 4 ]).

In addition to the illustrated commands, the implementation offered in this example also generates and decodes frames of the following commands:

Generating and Decoding ZCL Payload of DRLC Cluster

A zigbee.DRLCFrameConfig configuration object is used both in generating and decoding ZCL payloads for the demand response and load control (DRLC) cluster. Such objects describe a DRLC cluster payload and all applicable properties. The zigbee.DRLCFrameGenerator function accepts a zigbee.DRLCFrameConfig object describing the DRLC cluster payload and outputs the payload in bytes. The following code creates a ZCL payload for a command that sets the set point of heating devices to 23.5 C.

% Creation of DRLC cluster configuration object
drlcConfigTx = zigbee.DRLCFrameConfig( ...
    'CommandType','Load Control Event', ...
    'EventID','00000001', ...
    'DeviceClass','Strip Heaters/Baseboard Heaters', ...
    'HeatingSetPoint',23.5);

% DRLC cluster frame generation (ZCL payload)
drlcPayload = zigbee.DRLCFrameGenerator(drlcConfigTx);

The zigbee.DRLCFrameDecoder function accepts the command name and a DRLC cluster payload in bytes and outputs a zigbee.DRLCFrameConfig object describing the DRLC cluster payload. The command name is retrieved from the decoding of the ZCL header. See section 'Decoding ZCL Header of Home Automation ZigBee Radios' in the ZigBee Home Automation Frame Generation and Decoding example.

drlcConfigRx = zigbee.DRLCFrameDecoder( ...
    'Load Control Event',drlcPayload)

drlcConfigRx = 
  DRLCFrameConfig with properties:

         CommandType: 'Load Control Event'
             EventID: '00000001'
         DeviceClass: 'Strip Heaters/Baseboard Heaters'
         DeviceGroup: '00'
                Time: 0
            Duration: 0
    CriticalityLevel: 'Green'
     HeatingSetPoint: 23.5000
         RandomStart: 1
           RandomEnd: 1

Generating and Decoding ZCL Payload of Price Cluster

A zigbee.PriceFrameConfig configuration object is used both in generating and decoding ZCL payloads for the Price cluster. Such objects describe a Price cluster payload and all applicable properties. The zigbee.PriceFrameGenerator function accepts a zigbee.PriceFrameConfig object describing the Price cluster payload and outputs the payload in bytes. The following code creates a ZCL payload for a command that requests the current price of a commodity.

% Creation of Price cluster configuration object
priceConfigTx = zigbee.PriceFrameConfig( ...
    'CommandType','Get Current Price');

% Price cluster frame generation (ZCL payload)
pricePayload = zigbee.PriceFrameGenerator(priceConfigTx);

The zigbee.PriceFrameDecoder function accepts the command name and a Price cluster payload in bytes and outputs a zigbee.PriceFrameConfig object describing the Price cluster payload. The command name is retrieved from the decoding of the ZCL header. See section 'Decoding ZCL Header of Home Automation ZigBee Radios' in the ZigBee Home Automation Frame Generation and Decoding example.

priceConfigRx = zigbee.PriceFrameDecoder( ...
    'Get Current Price',pricePayload)

priceConfigRx = 
  PriceFrameConfig with properties:

      CommandType: 'Get Current Price'
    IdleReceiving: 0

Upon receiving a Get Current Price command, a server replies with a Publish Price command.

priceConfigTx = zigbee.PriceFrameConfig( ...
    'CommandType','Publish Price', ...
    'Price',0.4899, ...
    'Duration',14400);
pricePayload = zigbee.PriceFrameGenerator(priceConfigTx);

The client device can then decode the published price:

priceConfigRx = zigbee.PriceFrameDecoder( ...
    'Publish Price',pricePayload)

priceConfigRx = 
  PriceFrameConfig with properties:

       CommandType: 'Publish Price'
        ProviderID: 0
         RateLabel: ''
           EventID: 0
    GenerationTime: 0
              Unit: 'kW'
        UnitFormat: 'Binary'
          Currency: 840
         PriceTier: 1
      RegisterTier: 1
     NumPriceTiers: 0
         StartTime: 0
          Duration: 14400
             Price: 0.4899

Generating and Decoding ZCL Payload of Messaging Cluster

A zigbee.MessagingFrameConfig configuration object is used both in generating and decoding ZCL payloads for the Messaging cluster. Such objects describe a Messaging cluster payload and all applicable properties. The zigbee.MessagingFrameGenerator function accepts a zigbee.MessagingFrameConfig object describing the Messaging cluster payload and outputs the payload in bytes. The following code creates a ZCL payload for a command that displays a message.

% Creation of messaging cluster configuration object
messageID = 1234;
messagingConfigTx = zigbee.MessagingFrameConfig( ...
    'CommandType','Display Message', ...
    'MessageID',messageID, ...
    'Message','This is a custom message', ...
    'Duration',90);

% Messaging cluster frame generation (ZCL payload)
displayMessagePayload = zigbee.MessagingFrameGenerator(messagingConfigTx);

The zigbee.MessagingFrameDecoder function accepts the command name and a Messaging cluster payload in bytes and outputs a zigbee.MessagingFrameConfig object describing the Messaging cluster payload. The command name is retrieved from the decoding of the ZCL header. See section 'Decoding ZCL Header of Home Automation ZigBee Radios' in the ZigBee Home Automation Frame Generation and Decoding example.

messagingConfigRx = zigbee.MessagingFrameDecoder( ...
    'Display Message',displayMessagePayload)

messagingConfigRx = 
  MessagingFrameConfig with properties:

            CommandType: 'Display Message'
              MessageID: 1234
       TransmissionType: 'Normal Transmission Only'
               Priority: 'Low'
    MessageConfirmation: 0
               Duration: 90
                Message: 'This is a custom message'

A server that displays a message also has the ability to cancel the message using the Cancel Message command:

cancelMsgConfig = zigbee.MessagingFrameConfig( ...
    'CommandType','Cancel Message', ...
    'MessageID',messageID);
cancelMessagePayload = zigbee.MessagingFrameGenerator( ...
    messagingConfigTx);

Clients can then decode the Cancel Message command:

messagingConfigRx = zigbee.MessagingFrameDecoder( ...
    'Cancel Message',cancelMessagePayload)

messagingConfigRx = 
  MessagingFrameConfig with properties:

            CommandType: 'Cancel Message'
              MessageID: 1234
       TransmissionType: 'Normal Transmission Only'
               Priority: 'Low'
    MessageConfirmation: 0

Wireshark Decoding

The generated Messaging frames can be converted to a PCAP-formatted file, and then analyzed and visualized with Wireshark [ 5 ] to verify of compliance with the ZigBee standards.

The PCAP file needs the ZCL payloads to be enclosed with headers from all other layers and sublayers (MAC, NET, APS, ZCL). This task is performed by the following commands.

zllProfileID = zigbee.profileID('Smart Energy'); % ZLL profile ID
msgClusterID = zigbee.clusterID('Messaging'); % Messaging cluster ID

payloadsWithInfo(1) = struct( ...
    'Payload',displayMessagePayload, ...
    'ProfileID',zllProfileID, ...
    'ClusterSpecific',true, ...
    'ClusterID',msgClusterID, ...
    'CommandType','Display Message', ...
    'Direction','Downlink');
payloadsWithInfo(2) = struct( ...
    'Payload',cancelMessagePayload, ...
    'ProfileID',zllProfileID, ...
    'ClusterSpecific',true, ...
    'ClusterID',msgClusterID, ...
    'CommandType','Cancel Message', ...
    'Direction','Downlink');
                           
% Add headers from other layers/sublayers:
MPDUs = zigbeeAddProtocolHeaders(payloadsWithInfo);

% Export MPDUs to a PCAP format
zigbeeExportToPcap(MPDUs,'zigbeeSmartEnergy.pcap');

% Open PCAP file with Wireshark

Further Exploration

The example uses these undocumented utilities. The API and functionality of undocumented utilities may change in the future. To view the source code of the utilities, use the edit function.

zigbee.DRLCFrameConfig, zigbee.DRLCFrameGenerator, zigbee.DRLCFrameDecoder
zigbee.PriceFrameConfig, zigbee.PriceFrameGenerator, zigbee.PriceFrameDecoder
zigbee.MessagingFrameConfig, zigbee.MessagingFrameGenerator, zigbee.MessagingFrameDecoder