High Data Rate PHY User Guide#

The HDR PHY (High Data Rate PHY) allows the exchange of proprietary messages over alternate PHYs which allow increased transmission rates of either 1 Mbit, with Forward Error Correction (FEC), or 2 Mbit, without FEC. On some platforms, it supports a payload size of up to 2047 bytes.

The HDR PHY is tied to the Zigbee MAC and shares the same radio channel, using an internal offset of 16 channels. However, there is currently no effort to use the HDR PHY as an alternate PHY for standardized Zigbee or OpenThread messaging.

HDR PHY Operation: Mode switch packet with corresponding HDR PHY packet followed by a regular IEEE802.15.4 packet for reference.

Initially, a mode switch packet is sent which uses the same modulation and data rate as a base rate 802.15.4 packet. It uses the same preamble, but a special syncword (SFD). On detection of this dedicated SFD, any compatible receiver will change to the alternate PHY for the duration of the following HDR PHY packet, or a timeout.

The HDR PHY uses the following packet structure after the mode-switch packet—a regular 802.15.4 preamble with a dedicated sync word—is sent:

802.15.4 2Byte PHR (PHY Header)

Note: The packet bytes and 4 byte CRC together cannot exceed 255 bytes.

Supported Devices#

Support for the HDR PHY is present in GSDK-4.5, which represents the LTS branch for legacy Series1 devices, and in SiSDK-2024.12 and later.

Note: The HDR PHY feature, although publicly accessible, is not fully disclosed and therefore not detailed in the release notes of EmberZnet, GSDK, or SiSDK.

Devices that support the HDR PHY in GSDK-4.5

• EFR32MG13

• EFR32MG21

Note: GSDK-4.5 is not recommended for MG21. Use SiSDK instead.

Devices that support the HDR PHY in SiSDK-2024.12.0 (and later)

• EFR32MG21

• EFR32MG26

• SiMG301

Buffer Handling#

In both Zigbee-only and concurrent Zigbee-Matter or Zigbee-OpenThread use cases, the HDR PHY utilizes the upper MAC of the Zigbee stack. HDR PHY messages are not currently available to the OpenThread or Matter stacks. Regardless of this, HDR PHY messages don't traverse through MAC in the exact same way as regular IEEE802.15.4 messages due to their stricter real-time requirements.

Incoming HDR PHY Messages#

Incoming HDR PHY messages will be added to the PHY-to-MAC queue and will be de-queued and placed in a dedicated callback on a MAC tick event to decouple from interrupt context.

In theory, the PHY-to-MAC queue can contain multiple messages which are handled in a first in, first out fashion. However, in practice, this queue typically only contains a single message because the incoming radio throughput is slower than the speed at which messages are handled by the Upper MAC.

Outgoing HDR PHY Messages#

Outgoing HDR PHY messages are placed in the MAC-to-PHY queue. Due to the comparatively slow radio throughput—CSMA backoffs, higher priority messages from other protocols, and so on—this queue will sometimes contain multiple messages which are scheduled for transmission. The MAC-to-PHY queue is also serviced in a first-in, first-out fashion but HDR PHY messages are automatically placed at the front of the queue to allow for timely delivery.

How to Include the HDR PHY in a Project#

To enable the HDR PHY, replace the project’s default Zigbee Stack with one that supports it. The new stack will include the HDR PHY APIs which are located in the Zigbee MAC.

The following figure details the choice of components:

Currently, there is no HDR PHY support for end devices, devices utilizing the Alt MAC, and devices using the non-Default MAC, leading to the following matrix:

In addition to the appropriate Zigbee stack library, the zigbee_high_datarate_phy component needs to be added to the project. It provides the following files:

The zigbee_high_datarate_phy component will utilize template contribution to enable the auto-initialization of the HDR PHY feature and register CLI commands which are available to the user; in case the CLI component is also included in the project.

Note: Currently, the HDR PHY does not support RCP or NCP modes of operation.

API Description#

The API consists of function calls and macros to configure the HDR PHY, function calls for the transmission of HDR PHY messages, and callbacks for the reception of HDR PHY messages.

The HDR PHY API traverses through the IPC component in non-bare-metal projects to ensure thread safety.

HDR PHY Configuration#

• The rail_util_ieee802154_high_datarate component can be used to enable/disable FEC.

  • Define SL_RAIL_UTIL_IEEE802154_2P4_1MBPS_FEC_PHY_ENABLED to use 1 Mbps FEC or undefine SL_RAIL_UTIL_IEEE802154_2P4_1MBPS_FEC_PHY_ENABLED to use 2 Mbps without FEC.

  • Forward error correction is disabled by default.

  • This is a compile-time configuration. At the time of building the application, decide which mode of operation to use.

• The sl_high_datarate_phy_config_rx_callback(void (*rx_callback)(…)) API can be used to override the default receive callback function that fires when an HDR PHY packet is received.

  • The default callback is sl_high_datarate_phy_rx_cb() which is implemented in high_datarate_phy.c.

• The sl_high_datarate_phy_config_csma_params(RAIL_CsmaConfig_t *csmap) API can be used to configure CSMA parameters used in the high-datarate transmission. The CSMA parameters of the HDR PHY can be independent of the ones used for Zigbee or OpenThread. The following are the default parameters:

  • csmap.csmaMinBoExp = 3

  • csmap.csmaMaxBoExp = 5

  • csmap.csmaTries = 5

  • csmap.ccaThreshold = typically -75 (platform dependent)

  • csmap.ccaBackoff = 320µs (20 x symbol_duration)

  • csmap.ccaDuration = 128 (8 x symbol_duration)

  • csmap.csmaTimeout = 0

• The sl_high_datarate_phy_config_radio_priorities(sl_802154_radio_priorities_t *prio) API can be used to change the radio scheduler priority for the high data rate transmission. By default, these transmissions utilize the same priority as regular Zigbee packets. These are, unless modified by the radio_priority_configurator component, known as the DMP Tuning and Testing components:

  • prio.background_rx = 255

  • prio.min_tx_priority = 100

  • prio.tx_step = 2

  • prio.max_tx_priority = 80

  • prio.active_rx = 255

• The sl_high_datarate_phy_set_reception_enable(bool enable) API can be used to permanently enable or disable reception of the high datarate packets.

  • By default, the reception of HDR PHY packets is enabled in case the HDR PHY is included in a project.

• The sl_high_datarate_phy_config_tx_complete_callback(void (*tx_complete_callback)(...)) API can be used to provide a transmit complete callback that fires after the high data rate packet is successfully transmitted or fails to be transmitted. A sample implementation on how the previously sent packet contents can be read is provided in sl_high_datarate_phy_tx_cb function which serves as the default. The tag field is unused and does not carry any useful information for an HDR packet.

  • SL_STATUS_OK : Configuration was successful

  • SL_STATUS_TRANSMIT_INCOMPLETE: catch all transmit failure (TX_BLOCKED, TX_ABORTED)

  • SL_STATUS_ALLOCATION_FAILED: No more buffers available; should be resolved with waiting some time before attempting another transmission

• The sl_high_datarate_phy_force_tx_after_failed_hdr_phy_cca(uint8_t hdr_csma_attempts, uint32_t min_bo_period_us, uint32_t max_bo_period_us) API defines the number of retries which are triggered specifically for HDR PHY messages in case there is a CSMA failure. The HDR PHY doesn’t utilize MAC ACKs therefore, failure to trigger a transmission as utilized by this API is limited to a CSMA failure. Input parameters are as follows:

  • hdr_csma_attempts: The number of retries after CCA failure, default is 0, maximum is 5

  • min_bo_period_us: The minimum backoff period in µs ahead of a retry, default is 0

  • max_bo_period_us: The maximum backoff period in µs ahead of a retry, default is 1000

Unless limited by min_bo_period_us and max_bo_period_us, the backoff applied ahead of a retry will keep increasing with the number of retries; similar to how CSMA backoffs increase with an exponent between 3 and 5. In case the computed backoff time is larger than max_bo_period_us, a backoff of max_bo_period_us will be performed. If the computed backoff time is smaller than min_bo_period_us, then the value of min_bo_period_us will be used instead.

sl_high_datarate_phy_force_tx_after_failed_hdr_phy_cca(uint8_t hdr_csma_attempts, uint32_t min_bo_period_us, uint32_t max_bo_period_us) will return the following statuses:

• SL_STATUS_OK: Configuration was successful

• SL_STATUS_INVALID_PARAMETER: hdr_csma_attempts is out of bounds, or min_bo_period_us is larger than max_bo_period_us

HDR PHY Message Reception#

Reception of packets: Any receiver with HDR PHY enabled on the same Zigbee channel as the HDR PHY transmitter will receive the packet. There is no address filtering or other kind of checks taking place on received HDR PHY packets, besides the CRC verification. The function signature for the void (*rx_callback) (uint8_t *packet, uint8_t linkQuality, int8_t rssi, uint32_t pkt_rx_timestamp) API's receive callback is as follows:

• The zigbee_high_datarate_phy component provides a default implementation for this callback in the shape of sl_high_datarate_phy_rx_cb() that the user can override using the sl_high_datarate_phy_config_rx_callback() function.

• The default function prints the packet payload, link quality, RSSI and timestamp of the received packet.

The first 2 bytes of the packet are used to indicate the length of the payload using the following formula:

length = (packet[1] << 8) + packet[0]

Payload starts from packet[2] and continues until packet[length+1].

Note: Only payload lengths of up to 251 (or 2043) bytes are currently supported on the hardware due to a 4-byte CRC being added to the packet.

HDR PHY Message Transmission#

There are two APIs for transmitting HDR PHY packets.

sl_high_datarate_phy_transmit(uint8_t *payload)

This API takes a pointer to the payload whose first 2 bytes must be used to indicate the length.

length = (packet[1] << 8) + packet[0] Where packet[2] ... packet[length+1] is the payload.

The remainder of the bytes contain “length” bytes of the actual payload. The maximum payload length is 251 (or 2043) bytes to account for a 4 byte CRC. This results in the transmission of a fully custom payload packet.

sl_high_datarate_phy_transmit_scheduled(uint8_t *payload, RAIL_Time_t timestamp)

Next to a pointer to the payload, this API takes a timestamp at which the packet is to be transmitted.

In order to achieve transmission, say, with a specified offset to the reception of a HDR PHY message, the following formula can be used to calculate the timestamp:

timestamp = RAIL_GetTime() + us_offset

Note: With this formula, it is recommended to not use an offset significantly smaller than 1000µs to allow for delays.

Both APIs return one of the following status values:

• SL_STATUS_INVALID_PARAMETER: Returned when length argument falls outside the supported ranges

• SL_STATUS_INVALID_MODE: Returned when node is not part of a Zigbee network

• SL_STATUS_ALLOCATION_FAILED: Returned when there are no buffers left to queue packets. Given enough time, this error will resolve automatically when the queued packets are eventually transmitted.

CLI Description#

The zigbee_high_datarate_phy component also contributes a set of commands to the command line interface to assist with testing the sl_high_datarate_phy_transmit (uint8_t *payload) and sl_high_datarate_phy_transmit_scheduled(uint8_t *payload, RAIL_Time_t timestamp) APIs.

• high_datarate_phy transmit [len]: This command will send a packet of (len-1) pre-assigned bytes over the air. Len is an unsigned 16-bit parameter.

• high_datarate_phy txsched [len, timestamp]: This command will send a packet of (len-1) pre-assigned bytes over the air in timestamp microseconds. Len is an unsigned 16-bit parameter, timestamp is an unsigned 32-bit parameter

• high_datarate_phy clr_stats: This command will clear the number of received and transmitted HDR PHY packets tracked by this component

• high_datarate_phy print_stats: This command will print the number of transmitted and received high datarate phy packets tracked by this component

• high_datarate_phy set_rx_enable [bool]: If the argument is 1, this command will enable reception of high datarate phy packets (note that this is enabled by default). If the argument is 0, reception of high datarate phy packets is disabled.

To use this component and the associated CLI, find and add the zigbee_high_datarate_phy component to, say, a Z3Light sample application or a DynamicMultiprotocolLight sample application. Remove the zigbee_pro_stack and add zigbee_pro_stack_with_high_datarate_phy component instead.

Using and Testing the HDR PHY via CLI#

To set up testing for the HDR PHY via CLI, follow these steps:

1. Form distributed network on the first HDR PHY enabled node - plugin network-creator start 0

2. Open network for joining on this first node - plugin network-creator-security open-network

3. Join second HDR PHY enabled node to the same network - plugin network-steering start 1

4. Wait for EMBER_NETWORK_UP on the second node

   • Transmit packet from the first node - high_datarate_phy transmit 20

   • Packet received on the second node is printed as follows:

Received Packet : 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 10 11 12 13

LQI : 255

RSSI : -14 timestamp: 0x12345678

Note: Prior to testing, clear high_datarate_phy clr_stats.

Technical Data#

RX Sensitivity

The following table lists device information for RX Sensitivity with 1% PER and packet length of 20 octets.

HDR PHY Release Notes#

New in SiSDK-2025.12.0 and GSDK-4.5

New in SiSDK-2024.6.0 and GSDK-4.4.2

New in SiSDK-2024.12.0 and GSDK-4.4.5

Note: This list includes items which have been introduced in earlier IFC releases of SiSDK-2024.12.

HDR PHY Known Issues#