5.2.2. Platform Interface

The platform interface of ESP Zigbee Core.

5.2.2.1. Tasklet

5.2.2.1.1. Header File

5.2.2.1.2. Functions

void ezb_tasklet_process(void)

Process all queued tasklets.

bool ezb_tasklet_has_pendings(void)

Check whether there is pending tasklet.

Returns:

TRUE If there are pending tasklets.

Returns:

FALSE If there are not pending tasklets.

void ezb_tasklet_signal_pending(void)

Called by Stack when the tasklet queue transitions from empty to non-empty. Implement this function to get notification when there are tasklets added.

5.2.2.1.3. Macros

ESP_ZIGBEE_TASKLET_H

5.2.2.2. Alarm

5.2.2.2.1. Header File

5.2.2.2.2. Functions

void ezb_plat_micro_alarm_start_at(uint32_t t0, uint32_t dt)

Start the microsecond alarm and set it to fire at t0 after dt.

Note

The platform MUST support:

  • all values in [0, 2^32-1], for t0, and

  • all values in [0, 2^31-1], for dt.

Parameters:

  • t0 -- [in] The reference time in microseconds.

  • dt -- [in] The delay in microseconds from t0.

void ezb_plat_micro_alarm_stop(void)

Stop the microsecond alarm.

uint32_t ezb_plat_micro_alarm_get_now(void)

Get the current time.

Note

The current time MUST represent a 32-bit free-running timer. The time value MUST utilize the entire range [0, 2^32-1] and MUST NOT wrap before 2^32.

Returns:

The current time in microseconds.

void ezb_plat_signal_micro_alarm_fired(void)

Signal that the microsecond alarm has fired.

void ezb_plat_milli_alarm_start_at(uint32_t t0, uint32_t dt)

Start the millisecond alarm and set it to fire at t0 after dt.

Note

The platform MUST support:

  • all values in [0, 2^32-1], for t0, and

  • all values in [0, 2^31-1], for dt.

Parameters:

  • t0 -- [in] The reference time in milliseconds.

  • dt -- [in] The delay in milliseconds from t0.

void ezb_plat_milli_alarm_stop(void)

Stop the millisecond alarm.

uint32_t ezb_plat_milli_alarm_get_now(void)

Get the current time.

Note

The current time MUST represent a 32-bit free-running timer. The time value MUST utilize the entire range [0, 2^32-1] and MUST NOT wrap before 2^32.

Returns:

The current time in milliseconds.

void ezb_plat_signal_milli_alarm_fired(void)

Signal that the millisecond alarm has fired.

5.2.2.2.3. Macros

ESP_ZIGBEE_PLATFORM_ALARM_H

5.2.2.3. Crypto

5.2.2.3.1. Header File

5.2.2.3.2. Functions

ezb_err_t ezb_plat_crypto_aes_init(ezb_crypto_context_t *context)

Initialize the AES operation.

Parameters:

context -- [in] Context for AES operation.

Returns:

EZB_ERR_NONE Successfully Initialised AES operation. EZB_ERR_FAIL Failed to Initialise AES operation. EZB_ERR_INV_ARG context was NULL. EZB_ERR_NO_MEM Cannot allocate the context.

ezb_err_t ezb_plat_crypto_aes_setkey_enc(ezb_crypto_context_t *context, const ezb_crypto_key_t *key)

Set the key for AES encryption.

Parameters:

  • context -- [in] Context for AES operation.

  • key -- [in] Key to use for AES operation.

Returns:

EZB_ERR_NONE Successfully set the key for AES operation. EZB_ERR_FAIL Failed to set the key for AES operation. EZB_ERR_INV_ARG context or key was NULL

ezb_err_t ezb_plat_crypto_aes_setkey_dec(ezb_crypto_context_t *context, const ezb_crypto_key_t *key)

Set the key for AES decryption.

Parameters:

  • context -- [in] Context for AES operation.

  • key -- [in] Key to use for AES operation.

Returns:

EZB_ERR_NONE Successfully set the key for AES operation. EZB_ERR_FAIL Failed to set the key for AES operation. EZB_ERR_INV_ARG context or key was NULL

ezb_err_t ezb_plat_crypto_aes_encrypt(ezb_crypto_context_t *context, const uint8_t *input, uint8_t *output)

Encrypt the data by AES(-ECB).

Parameters:

  • context -- [in] Context for AES operation.

  • input -- [in] Pointer to the input buffer.

  • output -- [out] Pointer to the output buffer.

Returns:

EZB_ERR_NONE Successfully encrypted input. EZB_ERR_FAIL Failed to encrypt input. EZB_ERR_INV_ARG context or key or output were NULL.

ezb_err_t ezb_plat_crypto_aes_decrypt(ezb_crypto_context_t *context, const uint8_t *input, uint8_t *output)

Decrypt the data by AES(-ECB).

Parameters:

  • context -- [in] Context for AES operation.

  • input -- [in] Pointer to the input buffer.

  • output -- [out] Pointer to the output buffer.

Returns:

EZB_ERR_NONE Successfully decrypted input. EZB_ERR_FAIL Failed to decrypted input. EZB_ERR_INV_ARG context or key or output were NULL.

ezb_err_t ezb_plat_crypto_aes_free(ezb_crypto_context_t *context)

Free the AES context.

Parameters:

context -- [in] Context for AES operation.

Returns:

EZB_ERR_NONE Successfully freed AES context. EZB_ERR_FAIL Failed to free AES context. EZB_ERR_INV_ARG context was NULL.

void ezb_plat_crypto_random_init(void)

Initialize cryptographically-secure pseudorandom number generator (CSPRNG).

void ezb_plat_crypto_random_deinit(void)

Deinitialize cryptographically-secure pseudorandom number generator (CSPRNG).

ezb_err_t ezb_plat_crypto_random_get(uint8_t *output, uint16_t output_length)

Fill buffer with cryptographically secure random bytes.

Parameters:

  • output -- [out] A pointer to where the true random values are placed. Must not be NULL.

  • output_length -- [in] Length in bytes of output.

Returns:

EZB_ERR_NONE Successfully filled output with true random values. EZB_ERR_FAIL Failed to fill output with true random values. EZB_ERR_INV_ARG output was NULL.

ezb_err_t ezb_plat_crypto_entropy_get(uint8_t *output, uint16_t output_length)

Fill buffer with entropy.

MUST be implemented using a true random number generator (TRNG).

Parameters:

  • output -- [out] A pointer to where the true random values are placed. Must not be NULL.

  • output_length -- [in] Length in bytes of output.

Returns:

EZB_ERR_NONE Successfully filled output with true random values. EZB_ERR_FAIL Failed to fill output with true random values. EZB_ERR_INV_ARG output was NULL.

5.2.2.3.3. Structures

struct ezb_crypto_key_s

Key Material required for Crypto operations.

Public Members

const uint8_t *key

Pointer to the buffer containing key.

uint16_t key_len

The key length in bytes (applicable when mKey is not NULL).

struct ezb_crypto_context_s

Context object for platform APIs.

Public Members

void *ctx

Pointer to the context.

uint16_t ctx_size

The length of the context in bytes.

5.2.2.3.4. Macros

ESP_ZIGBEE_PLATFORM_CRYPTO_H

5.2.2.3.5. Type Definitions

typedef struct ezb_crypto_key_s ezb_crypto_key_t

Key Material required for Crypto operations.

typedef struct ezb_crypto_context_s ezb_crypto_context_t

Context object for platform APIs.

5.2.2.4. Datasets

5.2.2.4.1. Header File

5.2.2.4.2. Functions

void ezb_plat_datasets_init(void)

Initialize the datasets subsystem, for non-volatile storage.

void ezb_plat_datasets_deinit(void)

De-initialize the datasets subsystem.

ezb_err_t ezb_plat_datasets_get(uint16_t key, int index, uint8_t *value, uint16_t *length)

Fetch the value of a dataset.

Parameters:

  • key -- [in] The key associated with the requested dataset.

  • index -- [in] The index of the specific item to get.

  • value -- [out] A pointer to where the value of the dataset should be written. May be set to NULL if just testing for the presence or length of a dataset.

  • length -- [inout] A pointer to the length of the value. This will be overwritten by the actual length of data that writes to value

Return values:

  • EZB_ERR_NONE -- The given dataset was found and fetched successfully.

  • EZB_ERR_NOT_FOUND -- The given dataset was not found in the dataset storage.

  • EZB_ERR_NOT_SUPPORTED -- This function is not implemented on this platform.

ezb_err_t ezb_plat_datasets_set(uint16_t key, const uint8_t *value, uint16_t length)

Set or replace the value of a dataset.

Parameters:

  • key -- [in] The key associated with the requested dataset.

  • value -- [in] A pointer to where the new value of the dataset should be read from. MUST NOT be NULL if length is non-zero.

  • length -- [in] The length of the data pointed to by aValue. May be zero.

Return values:

  • EZB_ERR_NONE -- The given dataset was changed or staged.

  • EZB_ERR_NO_MEM -- No space remaining to store the given dataset.

  • EZB_ERR_NOT_SUPPORTED -- This function is not implemented on this platform.

ezb_err_t ezb_plat_datasets_add(uint16_t key, const uint8_t *value, uint16_t length)

Add a value to a dataset.

Adds the value to a dataset identified by aKey, without replacing any existing values.

Parameters:

  • key -- [in] The key associated with the dataset to change.

  • value -- [in] A pointer to where the new value of the dataset should be read from. MUST NOT be NULL if aValueLength is non-zero.

  • length -- [in] The length of the data pointed to by aValue. May be zero.

Return values:

  • EZB_ERR_NONE -- The given dataset was changed or staged.

  • EZB_ERR_NO_MEM -- No space remaining to store the given dataset.

  • EZB_ERR_NOT_SUPPORTED -- This function is not implemented on this platform.

ezb_err_t ezb_plat_datasets_delete(uint16_t key, int index)

Removes a dataset from the dataset storage.

Deletes a specific value from the dataset identified by key from the datasets store.

Parameters:

  • key -- [in] The key associated with the requested dataset.

  • index -- [in] The index of the value to be removed. If set to -1, all values for this key will be removed.

Return values:

  • EZB_ERR_NONE -- The given dataset was found and fetched successfully.

  • EZB_ERR_NOT_FOUND -- The given dataset was not found in the dataset storage.

  • EZB_ERR_NOT_SUPPORTED -- This function is not implemented on this platform.

void ezb_plat_datasets_wipe(void)

Removes all datasets from the dataset storage.

5.2.2.4.3. Macros

ESP_ZIGBEE_PLATFORM_DATASETS_H

5.2.2.5. Logging

5.2.2.5.1. Header File

5.2.2.5.2. Functions

void ezb_plat_log(ezb_log_level_t log_level, const char *format, ...)

Outputs logs.

Parameters:

  • log_level -- [in] The log level.

  • format -- [in] A pointer to the format string.

  • ... -- [in] Arguments for the format specification.

5.2.2.5.3. Macros

ESP_ZIGBEE_PLATFORM_LOG_H
EZB_LOG_LEVEL_NONE

Log level None.

EZB_LOG_LEVEL_ERROR

Log level Error.

EZB_LOG_LEVEL_WARN

Log level Informational.

EZB_LOG_LEVEL_INFO

Log level Warning.

EZB_LOG_LEVEL_DEBUG

Log level Debug.

EZB_LOG_LEVEL_VERBOSE

Log level Verbose.

5.2.2.5.4. Type Definitions

typedef int ezb_log_level_t

Log level representation.

5.2.2.6. Radio

5.2.2.6.1. Header File

5.2.2.6.2. Functions

void ezb_plat_radio_set_panid(ezb_panid_t panid)

Set the PAN ID on the platform.

Parameters:

panid -- [in] The IEEE 802.15.4 PAN ID.

void ezb_plat_radio_set_shortaddr(ezb_shortaddr_t addr)

Set the Short Address on the platform.

Parameters:

addr -- [in] The IEEE 802.15.4 16-bit Short Address.

void ezb_plat_radio_set_extaddr(const ezb_extaddr_t *extaddr)

Set the Extended Address on the platform.

Parameters:

extaddr -- [in] A pointer to the IEEE 802.15.4 64-bit Extended Address stored in little-endian byte order.

void ezb_plat_radio_get_macaddr(uint8_t *macaddr)

Get the IEEE EUI-64 MAC Address factory-assigned on the platform.

Parameters:

macaddr -- [out] A pointer to the MAC Address.

void ezb_plat_radio_set_promiscuous(bool enable)

Set the status of promiscuous mode.

Parameters:

enable -- [in] True/False to enable/disable promiscuous mode.

bool ezb_plat_radio_get_promiscuous(void)

Get the status of promiscuous mode.

Returns:

  • True The promiscuous mode is enabled.

  • False The promiscuous mode is disabled.

void ezb_plat_radio_set_tx_power(int8_t power)

Set the radio's transmit power in dBm for all channels.

Parameters:

power -- [in] The transmit power in dBm.

void ezb_plat_radio_get_tx_power(int8_t *power)

Get the radio's transmit power in dBm.

Parameters:

power -- [out] A pointer to the transmit power in dBm.

ezb_err_t ezb_plat_radio_set_rx_when_idle(bool enable)

Set rx-on-when-idle state to the radio platform.

Parameters:

enable -- [in] True to keep radio in Receive state, False to put to Sleep state during idle periods.

Returns:

EZB_ERR_NONE on success, EZB_ERR_FAIL otherwise.

ezb_err_t ezb_plat_radio_enable(void)

Enable the radio.

Returns:

EZB_ERR_NONE on success, EZB_ERR_FAIL otherwise.

ezb_err_t ezb_plat_radio_disable(void)

Disable the radio.

Returns:

EZB_ERR_NONE on success, EZB_ERR_FAIL otherwise.

bool ezb_plat_radio_is_enabled(void)

Check if the radio is enabled or not.

Returns:

True if the radio is enabled, False otherwise.

ezb_err_t ezb_plat_radio_sleep(void)

Set state of the radio to Sleep (from Receive).

Returns:

EZB_ERR_NONE on success, EZB_ERR_FAIL otherwise.

ezb_err_t ezb_plat_radio_receive(uint8_t channel)

Set state of the radio to Receive (from Sleep).

Parameters:

channel -- [in] The radio channel on which to receive.

Returns:

EZB_ERR_NONE on success, EZB_ERR_FAIL otherwise.

void ezb_plat_radio_receive_done(ezb_radio_frame_t *frame, ezb_err_t error)

Signal that the radio platform has done the receiving of a frame.

Parameters:

  • frame -- [in] A pointer to the received frame or NULL if the receive operation failed.

  • error -- [in] EZB_ERR_NONE if a frame successfully received, EZB_ERR_NO_MEM if a frame reception failed due to lack of rx buffer.

ezb_radio_frame_t *ezb_plat_radio_get_transmit_buffer(void)

Get a radio frame buffer for transmit.

Returns:

A pointer to the radio frame buffer

ezb_err_t ezb_plat_radio_transmit(ezb_radio_frame_t *frame)

Start the transmit sequence on the radio.

Parameters:

frame -- [in] A pointer to the frame to be transmitted.

Returns:

EZB_ERR_NONE Successfully transitioned to Transmit state. EZB_ERR_INV_STATE The radio was not in Receive state.

void ezb_plat_radio_transmit_started(ezb_radio_frame_t *frame)

Signal that the radio platform has started the transmission.

Parameters:

frame -- [in] A pointer to the frame that is being transmitted.

void ezb_plat_radio_transmit_done(ezb_radio_frame_t *frame, ezb_radio_frame_t *ack, ezb_err_t error)

Signal that the radio platform has done the transmission.

Parameters:

  • frame -- [in] A pointer to the frame that was transmitted.

  • ack -- [in] A pointer to the ACK frame, NULL if no ACK was received.

  • error -- [in] EZB_ERR_NONE if the frame was transmitted. EZB_ERR_MAC_NO_ACK if the frame was transmitted but no ACK was received. EZB_ERR_MAC_CHANNEL_ACCESS_FAILURE tx could not be done due to activity on the channel. EZB_ERR_ABORT if transmission was aborted for other reasons.

int8_t ezb_plat_radio_get_rssi(void)

Get the most recent RSSI measurement.

Returns:

The RSSI in dBm when it is valid. 127 when RSSI is invalid.

ezb_err_t ezb_plat_radio_energy_detect(uint8_t channel, uint32_t duration)

Start the energy detection sequence on the radio.

Parameters:

  • channel -- [in] The channel to perform the energy detection on.

  • duration -- [in] The duration in milliseconds, for the channel to be scanned.

Returns:

EZB_ERR_NONE Successfully started scanning the channel. EZB_ERR_BUSY The radio is performing energy scanning.

void ezb_plat_radio_energy_detect_done(int8_t max_rssi)

Signal that the radio platform has done the energy detection.

Parameters:

max_rssi -- [in] The maximum RSSI encountered on the scanned channel.

void ezb_plat_radio_set_src_match(bool enable)

Set the state of source address match feature.

Parameters:

enable -- [in] True/False to enable/disable source address match feature.

ezb_err_t ezb_plat_radio_add_src_match_entry(uint8_t *addr, bool is_short)

Add a address to the source address match table.

Parameters:

  • addr -- [in] The address to be added.

  • is_short -- [in] True/False flag indicating is the address is short/extended address.

Returns:

EZB_ERR_NONE Successfully added address to the source match table. EZB_ERR_NO_MEM No available entry in the source match table.

ezb_err_t ezb_plat_radio_clear_src_match_entry(uint8_t *addr, bool is_short)

Remove a address from the source address match table.

Parameters:

  • addr -- [in] The address to be removed.

  • is_short -- [in] True/False flag indicating is the address is short/extended address.

Returns:

EZB_ERR_NONE Successfully removed address to the source match table. EZB_ERR_NOT_FOUND The address is not in source address match table.

void ezb_plat_radio_clear_src_match_entries(bool is_short)

Clear the the short/extended source address match table.

Parameters:

is_short -- [in] True/False flag indicating short/extended address match table to be cleared.

5.2.2.6.3. Structures

struct ezb_radio_frame_s

Represents an IEEE 802.15.4 radio frame.

Public Members

uint8_t *psdu

The PSDU

uint8_t length

Length of the PSDU.

uint8_t channel

Channel used to transmit/receive the frame.

uint64_t timestamp

The timestamp in microseconds when the frame's SFD field was received.

struct ezb_radio_frame_s tx

Structure representing radio frame transmit information.

int8_t rssi

Received signal strength indicator in dBm for received frame.

uint8_t lqi

Link quality indicator for received frame.

bool acked_with_pending

The frame was acked with frame pending set.

struct ezb_radio_frame_s rx

Structure representing radio frame receive information.

union ezb_radio_frame_s info

The union of transmit/receive information of radio frame.

5.2.2.6.4. Macros

ESP_ZIGBEE_PLATFORM_RADIO_H
EZB_ERR_MAC_CHANNEL_ACCESS_FAILURE

Unable to transmit due to channel being busy

EZB_ERR_MAC_NO_ACK

ACK not received after tx with ack_req flag set

5.2.2.6.5. Type Definitions

typedef struct ezb_radio_frame_s ezb_radio_frame_t

Represents an IEEE 802.15.4 radio frame.

5.2.2.7. Toolchain

5.2.2.7.1. Header File

5.2.2.7.2. Macros

ESP_ZIGBEE_PLATFORM_TOOLCHAIN_H
EZB_HAS_BUILTIN(builtin)

Check whether the compiler supports a given builtin.

Parameters:

  • builtin -- [in] The builtin name to check.

EZB_HAS_GNU_ATTRIBUTE(attribute)

Check whether the compiler supports a given GNU attribute.

Parameters:

  • attribute -- [in] The attribute name to check.

EZB_CRITICAL_RESULT

Compiler-specific indication that the function result must be used.

EZB_PACKED_BEGIN

Compiler-specific indication that a class or struct must be byte packed.

EZB_PACKED_FIELD

Indicate to the compiler a nested struct or union to be packed within byte packed class or struct.

EZB_PACKED_END

Compiler-specific indication at the end of a byte packed class or struct.

EZB_WEAK

Compiler-specific weak symbol modifier.

EZB_EXPERIMENTAL

Compiler-specific experimental symbol modifier.

EZB_DEPRECATED

Compiler-specific deprecated symbol modifier.

EZB_DEPRECATED_MSG(msg)
EZB_UNAVAILABLE

Compiler-specific deprecated symbol modifier.

EZB_UNAVAILABLE_MSG(msg)
EZB_PRINTF(fmt_index, va_index)

Compiler-specific indication that printf style arguments check must be done.

Specifies that a function or method takes printf style arguments and should be type-checked against a format string.

Parameters:

  • fmt_index -- [in] The argument index of the format string, start from 1.

  • va_index -- [in] The argument index of the first variadic argument, start from 1.

EZB_CONSTRUCTOR

Compiler-specific indication that function is a constructor.

EZB_FALLTHROUGH
EZB_MAYBE_UNUSED