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_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

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

Type Definitions

typedef enum esp_zb_apsde_tx_opt_e esp_zb_apsde_tx_opt_t

Enumeration for APSDE-DATA Request TX options.

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 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