Annex swc_radio_hal_t Structure

This structure is part of the swc_hal_t structure. It contains Wireless Core function pointers required to interact with microcontroller peripherals. Every function present in this structure must be implemented except for the transceiver shutdown pin which is optional.

Refer to SR1010 and SR1020 datasheet for physical pin assignments.

typedef struct swc_radio_hal {
    void (*set_shutdown_pin)(void);   /*!< Set shutdown pin level high */
    void (*reset_shutdown_pin)(void); /*!< Set shutdown pin level low */
    void (*set_reset_pin)(void);      /*!< Set reset pin level high */
    void (*reset_reset_pin)(void);    /*!< Set reset pin level low */
    bool (*read_irq_pin)(void);       /*!< Return IRQ pin state */
    void (*set_cs)(void);             /*!< Set SPI chip select pin level high */
    void (*reset_cs)(void);           /*!< Set SPI chip select pin level low */
    void (*delay_ms)(uint32_t ms);    /*!< Block for a specified number of milliseconds */
    uint64_t (*get_tick)(void);       /*!< Get tick function pointer */
    uint32_t tick_frequency_hz;       /*!< Tick frequency in Hz for the get_tick function */
    void (*transfer_full_duplex_blocking)(uint8_t *tx_data, uint8_t *rx_data,
                                          uint16_t size); /*!< SPI Transfer full duplex in blocking mode */
    void (*transfer_full_duplex_non_blocking)(uint8_t *tx_data, uint8_t *rx_data,
                                              uint16_t size); /*!< SPI Transfer full duplex in non blocking mode using DMA */
    bool (*is_spi_busy)(void);           /*!< Check if the SPI controller is busy transferring bytes */
    void (*context_switch)(void);        /*!< Trigger the radio IRQ */
    void (*disable_radio_irq)(void);     /*!< Disable radio IRQ interrupt source */
    void (*enable_radio_irq)(void);      /*!< Enable radio IRQ interrupt source */
    void (*disable_radio_dma_irq)(void); /*!< Disable SPI DMA interrupt source */
    void (*enable_radio_dma_irq)(void);  /*!< Enable SPI DMA interrupt source */
} swc_radio_hal_t;

Tip

If the user does not intend to provide control over a GPIO for the shutdown pin, the user can simply create a void no_shutdown_pin(void) {} function and pass it to both set_shutdown_pin and reset_shutdown_pin pointers.

set_shutdown_pin

This function is used to set a high output level on the GPIO pin connected to the transceiver SHUTDOWN pin. The transceiver will be turned off when this function is called.

In the SDK, this is implemented by this EVK1.4 BSP function:

void evk_radio_set_shutdown_pin(void)

Set the on-board controller shutdown pin.

reset_shutdown_pin

This function is used to set a low output level on the GPIO pin connected to the transceiver SHUTDOWN pin. The transceiver will be turned on when this function is called.

In the SDK, this is implemented by this EVK1.4 BSP function:

void evk_radio_reset_shutdown_pin(void)

Reset the on-board controller shutdown pin.

set_reset_pin

This function is used to set a high output level on the GPIO pin connected to the transceiver RSTN pin. The transceiver will enter the active state when this function is called.

In the SDK, this is implemented by this EVK1.4 BSP function:

void evk_radio_set_reset_pin(void)

Set the on-board controller reset pin.

reset_reset_pin

This function is used to set a low output level on the GPIO pin connected to the transceiver RSTN pin. The transceiver will enter the reset state when this function is called.

In the SDK, this is implemented by this EVK1.4 BSP function:

void evk_radio_reset_reset_pin(void)

Reset the on-board controller reset pin.

read_irq_pin

This function is used to read the state of the GPIO pin connected to the transceiver IRQ pin.

In the SDK, this is implemented by this EVK1.4 BSP function:

bool evk_radio_read_irq_pin(void)

Read the status of the on-board controller IRQ pin.

Return values:
  • True – Pin is high.

  • False – Pin is low.

set_cs

This function is used to set a high output level on the GPIO pin connected to the transceiver CS pin. Chip select functionality (via CS) needs to be managed by the Wireless Core and not the SPI peripheral.

In the SDK, this is implemented by this EVK1.4 BSP function:

void evk_radio_spi_set_cs(void)

Set the on-board controller chip-select pin.

reset_cs

This function is used to set a low output level on the GPIO pin connected to the transceiver CS pin. Chip select functionality (via CS) needs to be managed by the Wireless Core and not the SPI peripheral.

In the SDK, this is implemented by this EVK1.4 BSP function:

void evk_radio_spi_reset_cs(void)

Reset the on-board controller chip-select pin.

delay_ms

Blocking delay function in milliseconds. Delays are usually implemented with a MCU timer peripheral. Blocking means the CPU is held until the delay expires.

In the SDK, this is implemented by this EVK1.4 BSP function:

void evk_timer_delay_ms(uint32_t delay_ms)

Blocking delay with a 1 millisecond resolution.

Parameters:

delay_ms[in] Delay in milliseconds to wait.

get_tick

This function returns a free running timer’s tick count. This is used by the Wireless Core to make sure the transceiver has been powered on long enough (1 second startup delay) to start its operation. The optional Stop and Wait feature can also use the timer tick count as a watchdog timer, telling the Wireless Core when it is time to move on and abort packet re-transmission efforts.

In the SDK, this is implemented by this EVK1.4 BSP function:

uint64_t evk_timer_free_running_ms_get_tick_count(void)

Get the free running timer tick count with a 1 millisecond resolution.

Returns:

Tick count.

Tip

If the user does not intend to use the Wireless Core Stop and Wait feature and has low power requirements, a stub function can be provided and assigned to the get_tick function pointer. This will avoid initializing an extra timer peripheral and save the power it would otherwise consume.

/* Stub function */
uint64_t no_tick(void)
{
     return UINT64_MAX;
}

Also, the tick_frequency_hz must be set to 0.

Warning

If a stub is provided, make sure to respect the transceiver’s startup delay of 1 second before calling swc_init.

tick_frequency_hz

This member indicates the tick frequency in Hertz that works in conjunction with the get_tick function.

The purpose of this member is to enable the application layer to inform the Wireless Core about the interpretation of results returned by the get_tick function.

Below are two scenarios demonstrating the proper initialization of tick_frequency_hz:

Scenario A: If the get_tick function returns 1 tick per millisecond (as is the case in the SDK through the use of the evk_timer_free_running_ms_get_tick_count function), then the timer is running at 1000 Hertz. In this case, tick_frequency_hz must be set to 1000.

Scenario B: If the get_tick function returns 1 tick per 250 microseconds (as is the case when using the evk_timer_free_running_quarter_ms_get_tick_count function), then the timer is running at 4000 Hertz. In this case, tick_frequency_hz must be set to 4000.

By initializing tick_frequency_hz as shown above, the Wireless Core can ensure that the transceiver has been powered on for a sufficient duration (1 second startup delay) before starting its operation.

Warning

If a stub is provided to the get_tick function, tick_frequency_hz must be set to 0.

transfer_full_duplex_blocking

This function is used to initiate an SPI transfer in full duplex blocking mode. The CPU is held until the transfer completes.

See the Serial peripheral Interface (SPI) section for more details on how to implement the SPI.

In the SDK, this is implemented by this EVK1.4 BSP function:

void evk_radio_spi_transfer_full_duplex_blocking(uint8_t *tx_data, uint8_t *rx_data, uint16_t size)

Read and Write data full duplex on the radio in blocking mode.

Parameters:
  • tx_data – Data buffer to write.

  • rx_data – Data received.

  • size – Size of the data.

transfer_full_duplex_non_blocking

This function is used to initiate an SPI transfer in full duplex non-blocking mode. The non-blocking mode means that the CPU is yielded and is free to execute other tasks while the DMA manages the SPI data transaction. The DMA peripheral needs to provide callback functions for “transmission complete” and “reception complete” status.

See the Serial peripheral Interface (SPI) section for more details on how to implement the SPI.

In the SDK, this is implemented by this EVK1.4 BSP function:

void evk_radio_spi_transfer_full_duplex_non_blocking(uint8_t *tx_data, uint8_t *rx_data, uint16_t size)

Read and Write data full duplex on the radio in non-blocking mode.

Parameters:
  • tx_data – Data buffer to write.

  • rx_data – Data received.

  • size – Size of the data.

is_spi_busy

This function is used to return the state of the busy flag in the SPI Status Register.

In the SDK, this is implemented by this EVK1.4 BSP function:

bool evk_radio_is_spi_busy(void)

Read the status of the radio’s SPI.

Return values:
  • true – SPI is busy.

  • false – SPI is not busy.

context_switch

This function is used to manually trigger the transceiver’s IRQ pin interrupt.

In the SDK, this is implemented by this EVK1.4 BSP functions:

void evk_radio_context_switch(void)

Software interrupt trigger to force the cpu to get into the interrupt handler.

disable_radio_irq

This function is used to disable the external interrupt (transceiver IRQ pin). Some tasks require to momentarily disable external interrupts. For example, this function must be called just prior to the Wireless Core initialization, which must occur without any interruption from the transceiver.

In the SDK, this is implemented by this EVK1.4 BSP function:

void evk_radio_disable_irq_it(void)

Disable the on-board controller IRQ external interrupt.

enable_radio_irq

This function is used to enable the external interrupt (transceiver IRQ pin).

For a priority list example, see the Annex EVK1.4 MCU Priority List section.

In the SDK, this is implemented by this EVK1.4 BSP function:

void evk_radio_enable_irq_it(void)

Enable the on-board controller IRQ external interrupt.

disable_radio_dma_irq

This function is used to disable the SPI DMA transfer complete interrupt. Some tasks require disabling this interrupt event momentarily.

In the SDK, this is implemented by this EVK1.4 BSP function:

void evk_radio_disable_dma_irq_it(void)

Disable the DMA SPI interrupt of the radio.

enable_radio_dma_irq

This function is used to enable the SPI DMA transfer complete interrupt.

For a priority list example, see the Annex EVK1.4 MCU Priority List section.

In the SDK, this is implemented by this EVK1.4 BSP function:

void evk_radio_enable_dma_irq_it(void)

Enable the DMA SPI interrupt of the radio.

Return to Wireless Core article