Zigbee endpoint logger

The Zigbee endpoint logger library provides the zigbee_logger_eprxzcl_ep_handler() function. You can use this endpoint handler function for parsing incoming ZCL frames and logging their fields and command payload.

The library can work as a partial replacement of nRF Sniffer for 802.15.4 for debugging and testing purposes. Unlike the sniffer, it provides logging information only for incoming ZCL frames on a specific device.

Parsing incoming frames

When you enable the library and register the handler at an endpoint, ZCL frames directed to this endpoint are intercepted and the registered handler is called. At that point, the handler counts and parses each frame: ZCL header is read and the payload of the command is obtained.

By default, the handler returns ZB_TRUE when the frame has been processed or ZB_FALSE if the stack must process the frame (as described in the ZBOSS API documentation). This endpoint logger, however, only reads the incoming frame, but does not process the command, and so it always returns ZB_FALSE.

After parsing and gathering the data, the “Received ZCL command” packet entry is added to the log. This entry has the following fields:

  • Source address (src_addr)

  • Source endpoint (src_ep)

  • Destination endpoint (dst_ep)

  • Cluster ID (cluster_id)

  • Profile ID (profile_id)

  • Command direction (cmd_dir), with one of the following values:

    • 0 if from client to server

    • 1 if from server to client

  • Common command (common_cmd), with one of the following values:

    • 0 if the command is local or specific to a cluster

    • 1 if the command is global for all clusters

  • Command ID (cmd_id)

  • Transaction sequence number (cmd_seq)

  • Disable default response (disable_def_resp), with one of the following values:

    • 0 if the default response command is to be returned

    • 1 if the default response is to be disabled and the command is not to be returned

  • Manufacturer specific data (manuf_code; void if no data is present)

  • Payload of the command (payload)

The parentheses after the entry name and at the end of the entry indicate the packet counter.

For example, enabling the Zigbee endpoint logger library with the Zigbee: Light bulb sample allows it to log On/Off commands received from the Zigbee: Light switch:

I: Received ZCL command (0): src_addr=0x03ea(short) src_ep=1 dst_ep=10 cluster_id=0x0006 profile_id=0x0104 cmd_dir=0 common_cmd=0 cmd_id=0x00 cmd_seq=14 disable_def_resp=1 manuf_code=void payload=[] (0)
I: Received ZCL command (1): src_addr=0x03ea(short) src_ep=1 dst_ep=10 cluster_id=0x0006 profile_id=0x0104 cmd_dir=0 common_cmd=0 cmd_id=0x01 cmd_seq=15 disable_def_resp=1 manuf_code=void payload=[] (1)
I: Received ZCL command (2): src_addr=0x03ea(short) src_ep=1 dst_ep=10 cluster_id=0x0006 profile_id=0x0104 cmd_dir=0 common_cmd=0 cmd_id=0x00 cmd_seq=16 disable_def_resp=1 manuf_code=void payload=[] (2)
I: Received ZCL command (3): src_addr=0x03ea(short) src_ep=1 dst_ep=10 cluster_id=0x0006 profile_id=0x0104 cmd_dir=0 common_cmd=0 cmd_id=0x01 cmd_seq=17 disable_def_resp=1 manuf_code=void payload=[] (3)

Configuration

To enable the Zigbee endpoint logger library, set the CONFIG_ZIGBEE_LOGGER_EP Kconfig option.

To configure the logging level of the library, use the CONFIG_ZIGBEE_LOGGER_EP_LOG_LEVEL Kconfig option.

For detailed steps about configuring the library in a Zigbee sample or application, see Configuring Zigbee endpoint logger.

API documentation

Header file: include/zigbee/zigbee_logger_eprxzcl.h
Source file: subsys/zigbee/lib/zigbee_logger_ep/zigbee_logger_eprxzcl.c
group zigbee_logger_ep

Library for logging incoming ZCL packets.

Provides Zigbee endpoint handler for parsing incoming ZCL packets and logging packet’s fields and payload.

Functions

zb_uint8_t zigbee_logger_eprxzcl_ep_handler(zb_bufid_t bufid)

Handler function which may be called to log an incoming frame onto Zigbee endpoint.

When this function is called as a callback bound to endpoint via ZB_AF_SET_ENDPOINT_HANDLER(), (directly or indirectly) it produces a log line similar to the following: 

Received ZCL command (17): src_addr=0x0000(short) src_ep=64 dst_ep=64
cluster_id=0x0000 profile_id=0x0104 rssi=0 cmd_dir=0 common_cmd=1 cmd_id=0x00
cmd_seq=128 disable_def_resp=0 manuf_code=void payload=[0700] (17)

Parameters:

  • bufid – Reference to Zigbee buffer holding received zcl command to be logged

Return values:

ZB_FALSE – in all conditions. This enables possibility to use this function directly as Zigbee stack endpoint handler.