APS API

APS(Application Support Sub Layer) related APIs for ESP Zigbee SDK.

API Reference

Header File

Functions

void esp_zb_aps_data_indication_handler_register(esp_zb_apsde_data_indication_callback_t cb)

Register the callback for retrieving the aps data indication.

Parameters:

cb – [in] A function pointer for esp_zb_apsde_data_indication_callback_t

esp_err_t esp_zb_aps_data_request(esp_zb_apsde_data_req_t *req)

APS data request.

Parameters:

req – [in] A pointer for apsde data request, esp_zb_apsde_data_req_s

Returns:

  • ESP_OK: on success

  • ESP_ERR_INVALID_ARG: invalid arguments

  • ESP_ERR_NO_MEM: not memory

  • ESP_FAIL: on failed

void esp_zb_aps_data_confirm_handler_register(esp_zb_apsde_data_confirm_callback_t cb)

Register the callback for retrieving the aps data confirm.

Note

If the callback is registered by the application, the application is responsible for handling APSDE confirm.

Parameters:

cb – [in] A function pointer for esp_zb_apsde_data_confirm_callback_t

esp_err_t esp_zb_aps_set_trust_center_address(esp_zb_ieee_addr_t address)

Set the APS trust center address.

Parameters:

address – [in] A 64-bit value is expected to be set to trust center address

Returns:

  • ESP_OK: On success

  • ESP_ERR_INVALID_STATE: Device is already on a network

void esp_zb_aps_get_trust_center_address(esp_zb_ieee_addr_t address)

Get the APS trust center address.

Parameters:

address – [out] A 64-bit value will be assigned from the trust center address

esp_err_t esp_zb_apsme_transport_key_request(const esp_zb_apsme_transport_key_req_t *req)

APSME-TRANSPORT-KEY Request.

Parameters:

req – [in] A pointer to the service parameters. See esp_zb_apsme_transport_key_req_t.

Returns:

  • ESP_OK: On success

  • ESP_ERR_NO_MEM: Insufficient memory for the request

  • ESP_ERR_NOT_SUPPORTED: Unsupported key or role type

  • Otherwise: Failure

esp_err_t esp_zb_apsme_switch_key_request(const esp_zb_apsme_switch_key_req_t *req)

APSME-SWITCH-KEY Request.

Parameters:

req – [in] A pointer to the service parameters. See esp_zb_apsme_switch_key_req_t.

Returns:

  • ESP_OK: On success

  • ESP_ERR_NO_MEM: Insufficient memory for the request

  • ESP_ERR_NOT_SUPPORTED: Unsupported role type

  • Otherwise: Failure

esp_err_t esp_zb_aps_set_fragment_max_window_size(uint8_t max_window_size)

Set the maximum window size for APS fragmentation.

Note

The window size must be configured with the same value on both the source and destination nodes.

Parameters:

max_window_size – [in] The maximum number of fragments in a window, ranging from 1 to 8 (default: 8), that can be sent before requiring an acknowledgment.

Returns:

  • ESP_OK: Operation successful

  • ESP_ERR_INVALID_ARG: max_window_size is out of the valid range

uint8_t esp_zb_aps_get_fragment_max_window_size(void)

Get the current maximum window size used for APS fragmentation.

Returns:

The configured APS fragment window size.

esp_err_t esp_zb_aps_set_fragment_interframe_delay(uint8_t delay_ms)

Set the delay, in milliseconds, between sending two blocks of a fragmented transmission.

Parameters:

delay_ms – [in] Delay in milliseconds between sending consecutive APS fragment blocks, default is 0.

Returns:

  • ESP_OK: Operation successful

  • Others: Operation failed

uint8_t esp_zb_aps_get_fragment_interframe_delay(void)

Get the current interframe delay for APS fragmentation.

Returns:

The interframe delay in milliseconds.

Structures

struct esp_zb_apsde_data_req_s

APSDE-DATA.request Parameters.

Public Members

uint8_t dst_addr_mode

The addressing mode for the destination address used in this primitive and of the APDU to be transferred, refer to esp_zb_aps_address_mode_t

esp_zb_addr_u dst_addr

The individual device address or group address of the entity to which the ASDU is being transferred

uint8_t dst_endpoint

The number of the individual endpoint of the entity to which the ASDU is being transferred or the broadcast endpoint (0xff).

uint16_t profile_id

The identifier of the profile for which this frame is intended.

uint16_t cluster_id

The identifier of the object for which this frame is intended.

uint8_t src_endpoint

The individual endpoint of the entity from which the ASDU is being transferred.

uint32_t asdu_length

The number of octets comprising the ASDU to be transferred

uint8_t *asdu

The set of octets comprising the ASDU to be transferred.

uint8_t tx_options

The transmission options for the ASDU to be transferred, refer to esp_zb_apsde_tx_opt_t

bool use_alias

The next higher layer may use the UseAlias parameter to request alias usage by NWK layer for the current frame.

uint16_t alias_src_addr

The source address to be used for this NSDU. If the use_alias is true

int alias_seq_num

The sequence number to be used for this NSDU. If the use_alias is true

uint8_t radius

The distance, in hops, that a transmitted frame will be allowed to travel through the network.

struct esp_zb_apsde_data_confirm_s

APSDE-DATA.confirm Parameters.

Public Members

uint8_t status

The status of data confirm. 0: success, otherwise failed

uint8_t dst_addr_mode

The addressing mode for the destination address used in this primitive and of the APDU to be transferred, refer to esp_zb_aps_address_mode_t

esp_zb_addr_u dst_addr

The individual device address or group address of the entity to which the ASDU is being transferred.

uint8_t dst_endpoint

The number of the individual endpoint of the entity to which the ASDU is being transferred or the broadcast endpoint (0xff).

uint8_t src_endpoint

The individual endpoint of the entity from which the ASDU is being transferred.

int tx_time

Reserved

uint32_t asdu_length

The length of ASDU

uint8_t *asdu

Payload

struct esp_zb_apsde_data_ind_s

APSDE-DATA.indication Parameters.

Public Members

uint8_t status

The status of the incoming frame processing, 0: on success

uint8_t dst_addr_mode

The addressing mode for the destination address used in this primitive and of the APDU that has been received, refer to esp_zb_aps_address_mode_t

uint16_t dst_short_addr

The individual device address or group address to which the ASDU is directed.

uint8_t dst_endpoint

The target endpoint on the local entity to which the ASDU is directed.

uint8_t src_addr_mode

Reserved, The addressing mode for the source address used in this primitive and of the APDU that has been received.

uint16_t src_short_addr

The individual device address of the entity from which the ASDU has been received.

uint8_t src_endpoint

The number of the individual endpoint of the entity from which the ASDU has been received.

uint16_t profile_id

The identifier of the profile from which this frame originated.

uint16_t cluster_id

The identifier of the received object.

uint32_t asdu_length

The number of octets comprising the ASDU being indicated by the APSDE.

uint8_t *asdu

The set of octets comprising the ASDU being indicated by the APSDE.

uint8_t security_status

UNSECURED if the ASDU was received without any security. SECURED_NWK_KEY if the received ASDU was secured with the NWK key.

int lqi

The link quality indication delivered by the NLDE.

int rx_time

Reserved, a time indication for the received packet based on the local clock

struct esp_zb_apsme_transport_key_req_s

APSME-TRANSPORT-KEY Request Parameters.

Public Members

esp_zb_ieee_addr_t dst_address

The extended 64-bit address of the destination device, if the DestinationAddress parameter is all zeros, this request will be broadcasted

uint8_t key_type

Identifies the type of key material that should be transported, refer to esp_zb_apsme_key_type_t

uint8_t key[ESP_ZB_CCM_KEY_SIZE]

The network key

The application link key

The Trust Center link key

esp_zb_ieee_addr_t parent_address

Indicates the address of parent when the use_parent is TRUE

uint8_t key_seq_number

A sequence number assigned to a network key by the Trust Center and used to distinguish network keys for purposes of key updates and incoming frame security operations.

bool use_parent

Indicates if the destination device’s parent shall be used to forward the key to the destination device:

struct esp_zb_apsme_transport_key_req_s::[anonymous]::[anonymous] nwk

TransportKeyData Parameter for a Network Key

esp_zb_ieee_addr_t partner_address

The extended 64-bit address of the device that was also sent this link key.

uint8_t initiator

Indicates if the destination device of this application link key requested it

struct esp_zb_apsme_transport_key_req_s::[anonymous]::[anonymous] app

TransportKeyData Parameter for an Application Link Key

struct esp_zb_apsme_transport_key_req_s::[anonymous]::[anonymous] tc

TransportKeyData Parameter for a Trust Center Link Key

union esp_zb_apsme_transport_key_req_s::[anonymous] key_data

TransportKeyData

struct esp_zb_apsme_switch_key_req_s

APSME-SWITCH-KEY Request Parameters.

Public Members

esp_zb_ieee_addr_t dst_address

The extended 64-bit address of the device to which the switch-key command is sent.

uint8_t key_seq_number

A sequence number assigned to a network key by the Trust Center and used to distinguish network keys.

Type Definitions

typedef enum esp_zb_apsde_tx_opt_e esp_zb_apsde_tx_opt_t

Enumeration for APSDE-DATA Request TX options.

typedef enum esp_zb_apsme_key_type_s esp_zb_apsme_key_type_t

Enumeration the standard key type of the Transport-Key, Verify-Key and Confirm-Key.

typedef struct esp_zb_apsde_data_req_s esp_zb_apsde_data_req_t

APSDE-DATA.request Parameters.

typedef struct esp_zb_apsde_data_confirm_s esp_zb_apsde_data_confirm_t

APSDE-DATA.confirm Parameters.

typedef struct esp_zb_apsde_data_ind_s esp_zb_apsde_data_ind_t

APSDE-DATA.indication Parameters.

typedef struct esp_zb_apsme_transport_key_req_s esp_zb_apsme_transport_key_req_t

APSME-TRANSPORT-KEY Request Parameters.

typedef struct esp_zb_apsme_switch_key_req_s esp_zb_apsme_switch_key_req_t

APSME-SWITCH-KEY Request Parameters.

typedef bool (*esp_zb_apsde_data_indication_callback_t)(esp_zb_apsde_data_ind_t ind)

APSDE data indication application callback.

Param ind:

[in] APSDE-DATA.indication

Return:

  • true: The indication has already been handled

  • false: The indication has not been handled; it will be processed by the stack.

typedef void (*esp_zb_apsde_data_confirm_callback_t)(esp_zb_apsde_data_confirm_t confirm)

APSDE data confirm application callback.

Param confirm:

[in] APSDE-DATA.confirm

Enumerations

enum esp_zb_aps_address_mode_t

Enumeration for APSDE-DATA address mode.

Values:

enumerator ESP_ZB_APS_ADDR_MODE_DST_ADDR_ENDP_NOT_PRESENT

DstAddress and DstEndpoint not present, only for APSDE-DATA request and confirm

enumerator ESP_ZB_APS_ADDR_MODE_16_GROUP_ENDP_NOT_PRESENT

16-bit group address for DstAddress; DstEndpoint not present

enumerator ESP_ZB_APS_ADDR_MODE_16_ENDP_PRESENT

16-bit address for DstAddress and DstEndpoint present

enumerator ESP_ZB_APS_ADDR_MODE_64_ENDP_PRESENT

64-bit extended address for DstAddress and DstEndpoint present

enumerator ESP_ZB_APS_ADDR_MODE_64_PRESENT_ENDP_NOT_PRESENT

64-bit extended address for DstAddress, but DstEndpoint NOT present, only for APSDE indication

enum esp_zb_apsde_tx_opt_e

Enumeration for APSDE-DATA Request TX options.

Values:

enumerator ESP_ZB_APSDE_TX_OPT_SECURITY_ENABLED

Security enabled transmission

enumerator ESP_ZB_APSDE_TX_OPT_USE_NWK_KEY_R21OBSOLETE

Use NWK key (obsolete)

enumerator ESP_ZB_APSDE_TX_OPT_NO_LONG_ADDR

Extension: do not include long src/dst addresses into NWK hdr

enumerator ESP_ZB_APSDE_TX_OPT_ACK_TX

Acknowledged transmission

enumerator ESP_ZB_APSDE_TX_OPT_FRAG_PERMITTED

Fragmentation permitted

enumerator ESP_ZB_APSDE_TX_OPT_INC_EXT_NONCE

Include extended nonce in APS security frame

enum esp_zb_apsme_key_type_s

Enumeration the standard key type of the Transport-Key, Verify-Key and Confirm-Key.

Values:

enumerator ESP_ZB_APSME_STANDARD_NETWORK_KEY

NWK key

enumerator ESP_ZB_APSME_APP_LINK_KEY

Application link key

enumerator ESP_ZB_APSME_TC_LINK_KEY

Trust-center link key