nRF5 SDK for Thread and Zigbee v1.0.0
Choose documentation:
ZCL commands

Data Structures

struct  log_ctx_t
 
struct  ping_reply_s
 The row of the table which holds the replies which are to be sent. More...
 
struct  attr_query_s
 The row of the table which holds the requests which were sent. More...
 
struct  tsn_ctx_t
 
struct  configure_reporting_req_t
 

Macros

#define NRF_LOG_SUBMODULE_NAME   ping
 Name of the submodule used for logger messaging.
 
#define ATTRIBUTE_TABLE_SIZE   20
 
#define ATTRIBUTE_ROW_TIMEOUT_S   10
 
#define ZIGBEE_CLI_CONFIGURE_REPORT_TSN   3
 
#define ZIGBEE_CLI_CONFIGURE_REPORT_RESP_TIMEOUT   5
 
#define ZIGBEE_CLI_CONFIGURE_REPORT_DEFAULT_MIN_INTERVAL   1
 
#define ZIGBEE_CLI_CONFIGURE_REPORT_DEFAULT_MAX_INTERVAL   60
 
#define ZIGBEE_CLI_CONFIGURE_REPORT_DEFAULT_VALUE_CHANGE   NULL
 
#define ZIGBEE_CLI_CONFIGURE_REPORT_OFF_MIN_INTERVAL   0x000F
 
#define ZIGBEE_CLI_CONFIGURE_REPORT_OFF_MAX_INTERVAL   0xFFFF
 
#define NRF_LOG_SUBMODULE_NAME   report
 Name of the submodule used for logger messaging.
 

Typedefs

typedef struct ping_reply_s ping_reply_t
 The row of the table which holds the replies which are to be sent. More...
 
typedef enum attr_type_e attr_req_type_t
 
typedef struct attr_query_s attr_query_t
 The row of the table which holds the requests which were sent. More...
 

Enumerations

enum  attr_type_e { ATTR_READ_REQUEST, ATTR_WRITE_REQUEST }
 

Functions

 NRF_LOG_INSTANCE_REGISTER (zigbee, ping, ZIGBEE_CLI_CONFIG_INFO_COLOR, ZIGBEE_CLI_CONFIG_DEBUG_COLOR, ZIGBEE_CLI_CONFIG_LOG_INIT_FILTER_LEVEL, ZIGBEE_CLI_CONFIG_LOG_ENABLED?ZIGBEE_CLI_CONFIG_LOG_LEVEL:NRF_LOG_SEVERITY_NONE)
 
static zb_uint32_t get_request_duration (ping_request_t *p_request)
 Get time difference, in microseconds between ping request identified by row number and current time. More...
 
ping_request_t * zb_ping_acquire_request (void)
 
zb_void_t zb_ping_release_request (ping_request_t *p_reply)
 
static ping_reply_tping_aquire_reply (void)
 Acquire ping reply context. More...
 
zb_void_t ping_release_reply (ping_reply_t *p_reply)
 Release ping reply context. More...
 
static zb_void_t invalidate_row_cb (zb_uint8_t row)
 Invalidate Ping Request row after the timeout - ZBOSS callback. More...
 
static ping_request_t * find_request_by_short (zb_uint16_t addr_short)
 Get the first row with request sent to addr_short, return NULL if none. More...
 
static ping_request_t * find_request_by_sn (zb_uint8_t seqnum)
 Get the taken row with the selected seq_num, return NULL if none. More...
 
static zb_int8_t get_request_row (ping_request_t *p_request)
 Get row number for the ping request. More...
 
static time_abs_t abs_time_now (void)
 Get current abs time.
 
static zb_void_t dispatch_user_callback (zb_uint8_t param)
 
static void ping_cli_evt_handler (ping_time_evt_t evt, zb_uint32_t delay_us, ping_request_t *p_request)
 Default ping event handler. Prints out measured time on the CLI and exits. More...
 
zb_void_t ping_request_send (ping_request_t *p_request)
 
static zb_void_t ping_reply_send (ping_reply_t *p_reply)
 Actually construct the Ping Reply frame and send it. More...
 
static zb_uint8_t cli_agent_ep_handler_ping (zb_uint8_t param)
 The Handler to 'intercept' every frame coming to the endpoint. More...
 
static void cmd_zb_ping (nrf_cli_t const *p_cli, size_t argc, char **argv)
 ping over ZCL More...
 
 NRF_SECTION_ITEM_REGISTER (zb_ep_handlers, zb_device_handler_t const CONCAT_2(zb_ep_, ping))
 Endpoint handlers.
 
 NRF_CLI_CMD_REGISTER (ping, NULL,"ping over ZCL", cmd_zb_ping)
 Command set array.
 
static zb_int8_t get_free_row_attr_table ()
 Get the first free row in the attributes table, return -1 if none.
 
static zb_int8_t get_attr_table_row_by_sn (zb_uint8_t sernum)
 Get the taken row with the selected seq_num, return -1 if none. More...
 
static zb_void_t invalidate_row (zb_uint8_t row)
 Invaidate row after the timeout. More...
 
static zb_bool_t is_response (zb_zcl_parsed_hdr_t *p_hdr, attr_query_t *p_row)
 Check if the frame we received is the response to our request in the table. More...
 
static void print_read_attr_response (zb_buf_t *p_zcl_cmd_buf, attr_query_t *p_row)
 Print the Read Attribute Response. More...
 
static void print_write_attr_response (zb_buf_t *p_zcl_cmd_buf, attr_query_t *p_row)
 Print the Write Attribute Response. More...
 
static zb_uint8_t cli_agent_ep_handler_attr (zb_uint8_t param)
 The Handler to 'intercept' every frame coming to the endpoint. More...
 
static zb_void_t readattr_send (zb_uint8_t param, zb_uint16_t cb_param)
 Actually construct the Read Attribute frame and send it. More...
 
static zb_void_t writeattr_send (zb_uint8_t param, zb_uint16_t cb_param)
 Actually construct the Write Attribute frame and send it. More...
 
static void cmd_zb_readattr (nrf_cli_t const *p_cli, size_t argc, char **argv)
 Retrieve the attribute value of the remote node. More...
 
static void cmd_zb_writeattr (nrf_cli_t const *p_cli, size_t argc, char **argv)
 Write the attribute value to the remote node. More...
 
 NRF_SECTION_ITEM_REGISTER (zb_ep_handlers, zb_device_handler_t const CONCAT_2(zb_ep_, attr))
 Endpoint handlers.
 
 NRF_CLI_CMD_REGISTER (readattr, NULL,"readattr", cmd_zb_readattr)
 Command set array.
 
 NRF_CLI_CMD_REGISTER (writeattr, NULL,"writeattr", cmd_zb_writeattr)
 
 NRF_LOG_INSTANCE_REGISTER (zigbee, report, ZIGBEE_CLI_CONFIG_INFO_COLOR, ZIGBEE_CLI_CONFIG_DEBUG_COLOR, ZIGBEE_CLI_CONFIG_LOG_INIT_FILTER_LEVEL, ZIGBEE_CLI_CONFIG_LOG_ENABLED?ZIGBEE_CLI_CONFIG_LOG_LEVEL:NRF_LOG_SEVERITY_NONE)
 
static tsn_ctx_tget_ctx_by_tsn (uint8_t tsn)
 Return a pointer to context with the given transaction sequence number. More...
 
static tsn_ctx_tget_free_tsn_ctx (void)
 Get a pointer to a free context. More...
 
static void invalidate_ctx (tsn_ctx_t *p_tsn_ctx)
 
static void cmd_zb_subscribe_unsubscribe_timeout (zb_uint8_t param)
 Handles timeout error and invalidates configure reporting transaction. More...
 
static void cmd_zb_subscribe_unsubscribe_cb (tsn_ctx_t *p_tsn_ctx, zb_uint8_t param)
 Print the Configure Reporting Response. More...
 
static void print_attr_update (zb_zcl_parsed_hdr_t *p_zcl_hdr, zb_uint8_t param)
 Print the Report Attribute Command. More...
 
static zb_uint8_t cli_agent_ep_handler_report (zb_uint8_t param)
 The Handler to 'intercept' every frame coming to the endpoint. More...
 
static void cmd_zb_subscribe (nrf_cli_t const *p_cli, size_t argc, char **argv)
 Subscribe to the attribute changes on the remote node. More...
 
static void cmd_zb_unsubscribe (nrf_cli_t const *p_cli, size_t argc, char **argv)
 Unsubscribe from attribute reports. More...
 
 NRF_SECTION_ITEM_REGISTER (zb_ep_handlers, zb_device_handler_t const CONCAT_2(zb_ep_, report))
 Endpoint handlers.
 
 NRF_CLI_CMD_REGISTER (subscribe, NULL,"subscribe to remote attribute changes", cmd_zb_subscribe)
 Command set array.
 
 NRF_CLI_CMD_REGISTER (unsubscribe, NULL,"unsubscribe from remote attribute changes", cmd_zb_unsubscribe)
 

Variables

static ping_request_t m_ping_request_table [10]
 
static ping_reply_t m_ping_reply_table [10]
 
static uint8_t m_ping_seq_num
 
static log_ctx_t m_log
 
static attr_query_t m_attr_table [20]
 
static log_ctx_t m_log
 
static tsn_ctx_t m_tsn_ctx [3]
 

Detailed Description

Typedef Documentation

typedef struct attr_query_s attr_query_t

The row of the table which holds the requests which were sent.

We compare the incoming responses with the rows contents to determine if it is the answer. The structure corresponds to both read and write requests. The key parameter is the sequence number.

typedef struct ping_reply_s ping_reply_t

The row of the table which holds the replies which are to be sent.

We use the table to temporarily store the parameters of the ping reply while it is traversing the ZBOSS callback system. The key parameter is the sequence number.

Function Documentation

static zb_uint8_t cli_agent_ep_handler_attr ( zb_uint8_t  param)
static

The Handler to 'intercept' every frame coming to the endpoint.

Parameters
paramReference to a ZBOSS buffer
static zb_uint8_t cli_agent_ep_handler_ping ( zb_uint8_t  param)
static

The Handler to 'intercept' every frame coming to the endpoint.

Parameters
paramReference to a ZBoss buffer
static zb_uint8_t cli_agent_ep_handler_report ( zb_uint8_t  param)
static

The Handler to 'intercept' every frame coming to the endpoint.

Parameters
param[in]Reference to a ZBOSS buffer
Returns
ZB_TRUE if ZCL command was processed.
static void cmd_zb_ping ( nrf_cli_t const *  p_cli,
size_t  argc,
char **  argv 
)
static

ping over ZCL

ping [--no-echo] [--aps-ack] <h:eui64> <d:payload size>

Example:

ping 0b010eaafd745dfa 32
Precondition
Only after starting zigbee.

Issue a ping-style command to another CLI device of the address dst_addr by using payload_size bytes of payload.

Optionally, the device can request an APS acknowledgement (--aps-ack) or ask destination not to sent ping reply (--no-echo).

To implement the ping-like functionality, a new custom cluster has been defined with ID 64. There are four custom commands defined inside it, each with its own ID.

See the following flow graphs for details.

  • Case 1: Ping with echo, without the APS acknowledgement (default mode):

    App 1 Node 1 Node 2
    | -- ping -> | -- ping request -> | (command ID: 0x02 - ping request without the APS acknowledgement)
    | | <- MAC ACK -- |
    | | <- ping reply -- | (command ID: 0x01 - ping reply)
    | | -- MAC ACK -> |
    | <- Done -- | |

    In this default mode, the ping command measures the time needed for a Zigbee frame to travel between two nodes in the network (there and back again). The command uses a custom "overloaded" ZCL frame, which is constructed as a ZCL frame of the new custom ping ZCL cluster (ID 64).

  • Case 2: Ping with echo, with the APS acknowledgement:
    App 1 Node 1 Node 2
    | -- ping -> | -- ping request -> | (command ID: 0x00 - ping request with the APS acknowledgement)
    | | <- MAC ACK -- |
    | | <- APS ACK -- |
    | | -- MAC ACK -> |
    | | <- ping reply -- | (command ID: 0x01 - ping reply)
    | | -- MAC ACK -> |
    | | -- APS ACK -> |
    | | <- MAC ACK -- |
    | <- Done -- | |
  • Case 3: Ping without echo, with the APS acknowledgement:
    App 1 Node 1 Node 2
    | -- ping -> | -- ping request -> | (command ID: 0x03 - ping request without echo)
    | | <- MAC ACK -- |
    | | <- APS ACK -- |
    | | -- MAC ACK -> |
    | <- Done -- | |
  • Case 4: Ping without echo, without the APS acknowledgement:
    App 1 Node 1 Node 2
    | -- ping -> | -- ping request -> | (command ID: 0x03 - ping request without echo)
    | <- Done -- | |
    | | <- MAC ACK -- |
static void cmd_zb_readattr ( nrf_cli_t const *  p_cli,
size_t  argc,
char **  argv 
)
static

Retrieve the attribute value of the remote node.

readattr <h:dst_addr> <d:ep> <h:cluster> <h:profile> <h:attr_id>

Read the value of the attribute attr_id in the cluster cluster. The cluster belongs to the profile profile, which resides on the endpoint ep of the remote node dst_addr.

static void cmd_zb_subscribe ( nrf_cli_t const *  p_cli,
size_t  argc,
char **  argv 
)
static

Subscribe to the attribute changes on the remote node.

subscribe <h:eui64> <d:ep> <h:cluster> <h:profile>
<h:attr ID> <d:attr type>
[<d:min interval (s)>] [<d:max interval (s)>]

Enable reporting on the node identified by eui64, with the endpoint ep that uses the profile profile of the attribute attr ID with the type attr type in the cluster cluster.

Reports must be generated in intervals not shorter than min interval (1 second by default) and not longer than max interval (60 seconds by default).

static void cmd_zb_subscribe_unsubscribe_cb ( tsn_ctx_t p_tsn_ctx,
zb_uint8_t  param 
)
static

Print the Configure Reporting Response.

Parameters
p_zcl_cmd_buf[in]Pointer to a ZBOSS buffer
p_row[in]Pointer to a row in attr table
static void cmd_zb_subscribe_unsubscribe_timeout ( zb_uint8_t  param)
static

Handles timeout error and invalidates configure reporting transaction.

Parameters
[in]paramZBOSS transaction sequence number
static void cmd_zb_unsubscribe ( nrf_cli_t const *  p_cli,
size_t  argc,
char **  argv 
)
static

Unsubscribe from attribute reports.

unsubscribe <h:eui64> <d:ep> <h:cluster> <h:profile> <h:attr ID> <d:attr type>

Disable reporting on the node identified by eui64, with the endpoint ep that uses the profile profile of the attribute attr ID with the type attr type in the cluster cluster.

static void cmd_zb_writeattr ( nrf_cli_t const *  p_cli,
size_t  argc,
char **  argv 
)
static

Write the attribute value to the remote node.

writeattr <h:dst_addr> <d:ep> <h:cluster> <h:profile> <h:attr_id> <h:attr_type> <h:attr_value>

Write the attr_value value of the attribute attr_id of the type attr_type in the cluster cluster. The cluster belongs to the profile profile, which resides on the endpoint ep of the remote node dst_addr.

Note
The attr_value value must be in hexadecimal format, unless it is a string (attr_type == 42), then it must be a string.
static zb_void_t dispatch_user_callback ( zb_uint8_t  param)
static

Default handler for incoming ping request APS acknowledgements.

If there is a user callback defined for the acknowledged request, the callback with PING_EVT_ACK_RECEIVED event will be called.

Parameters
[in]paramReference to a ZBoss buffer containing APC ACK data,
static ping_request_t* find_request_by_short ( zb_uint16_t  addr_short)
static

Get the first row with request sent to addr_short, return NULL if none.

Parameters
addr_shortShort network address to look for.
Returns
Pointer to the ping request context.
static ping_request_t* find_request_by_sn ( zb_uint8_t  seqnum)
static

Get the taken row with the selected seq_num, return NULL if none.

Parameters
seqnumSequence Number to look for
static zb_int8_t get_attr_table_row_by_sn ( zb_uint8_t  sernum)
static

Get the taken row with the selected seq_num, return -1 if none.

Parameters
sernumSequence Number to look for
static tsn_ctx_t* get_ctx_by_tsn ( uint8_t  tsn)
static

Return a pointer to context with the given transaction sequence number.

Parameters
[in]tsnZBOSS transaction sequence number
Returns
a pointer to context or NULL if context for given TSN wasn't found.
static tsn_ctx_t* get_free_tsn_ctx ( void  )
static

Get a pointer to a free context.

Returns
a pointer to context structure or NULL if all contexts are taken.
static zb_uint32_t get_request_duration ( ping_request_t *  p_request)
static

Get time difference, in microseconds between ping request identified by row number and current time.

Parameters
[in]p_rowPointer to the ping request structure, from which the time difference should be calculated.
Returns
Time difference in microseconds.
static zb_int8_t get_request_row ( ping_request_t *  p_request)
static

Get row number for the ping request.

Parameters
[in]p_rowPointer to the ping request context.
Returns
Row number, -1 if not found.
static void invalidate_ctx ( tsn_ctx_t p_tsn_ctx)
static

Invalidate context.

Parameters
[in]p_tsn_ctxa pointer to transaction context.
static zb_void_t invalidate_row ( zb_uint8_t  row)
static

Invaidate row after the timeout.

Parameters
rowNumber of row to invalidate
static zb_void_t invalidate_row_cb ( zb_uint8_t  row)
static

Invalidate Ping Request row after the timeout - ZBOSS callback.

Parameters
rowNumber of row to invalidate
static zb_bool_t is_response ( zb_zcl_parsed_hdr_t p_hdr,
attr_query_t p_row 
)
static

Check if the frame we received is the response to our request in the table.

Parameters
p_hdrPointer to the parsed header of the frame
p_rowPointer to the row in the table to check against
Returns
Whether it is response or not
static ping_reply_t* ping_aquire_reply ( void  )
static

Acquire ping reply context.

Returns
Pointer to a free ping reply context or NULL on failure.
static void ping_cli_evt_handler ( ping_time_evt_t  evt,
zb_uint32_t  delay_us,
ping_request_t *  p_request 
)
static

Default ping event handler. Prints out measured time on the CLI and exits.

Parameters
[in]evt_typeType of received ping acknowledgment
[in]delay_usTime, in microseconds, between ping request and the event.
[in]p_requestPointer to the ongoing ping request context structure.
zb_void_t ping_release_reply ( ping_reply_t p_reply)

Release ping reply context.

Parameters
p_replyPointer to the reply context structure to release.
static zb_void_t ping_reply_send ( ping_reply_t p_reply)
static

Actually construct the Ping Reply frame and send it.

Parameters
p_rowPointer to the ping reply context structure.
static void print_attr_update ( zb_zcl_parsed_hdr_t p_zcl_hdr,
zb_uint8_t  param 
)
static

Print the Report Attribute Command.

Parameters
p_zcl_cmd_buf[in]Pointer to a ZBOSS buffer
p_row[in]Pointer to a row in attr table
static void print_read_attr_response ( zb_buf_t p_zcl_cmd_buf,
attr_query_t p_row 
)
static

Print the Read Attribute Response.

Parameters
p_zcl_cmd_bufPointer to a ZBOSS buffer
p_rowPointer to a row in attr table
static void print_write_attr_response ( zb_buf_t p_zcl_cmd_buf,
attr_query_t p_row 
)
static

Print the Write Attribute Response.

Parameters
p_zcl_cmd_bufPointer to a ZBOSS buffer
p_rowPointer to a row in attr table
static zb_void_t readattr_send ( zb_uint8_t  param,
zb_uint16_t  cb_param 
)
static

Actually construct the Read Attribute frame and send it.

Parameters
paramZBOSS buffer to fill.
cb_paramRow of the read attribute table to refer to.
static zb_void_t writeattr_send ( zb_uint8_t  param,
zb_uint16_t  cb_param 
)
static

Actually construct the Write Attribute frame and send it.

Parameters
paramZBOSS buffer to fill.
cb_paramRow of the read attribute table to refer to.

Variable Documentation

log_ctx_t m_log
static
Initial value:
= {
}
log_ctx_t m_log
static
Initial value:
= {
}