Using a Radio

This document covers the general API for interacting with a supported radio. The underlying structure for radios varies quite dramatically, so please refer to the appropriate specific radio document in conjunction with this one.

The specific radio documents will cover things like configuration options, available telemetry types, and system requirements.

Project Configuration

The specific radio being used in a Kubos project should be specified in the radio parameter of the project’s config.json file. This tells the Kubos SDK to include the correct radio files when building the project. The radio’s subparameters may then be specified within the specific radio’s structure.

For example:

{
  "radio": {
    "trxvu": {
      "i2c_bus": K_I2C1
    }
  }
}

Radio Initialization and Termination

In order for a Kubos project to communicate with a radio, the k_radio_init function should be called. This opens the correct underlying Kubos Linux device file. The function should return RADIO_OK if it completed successfully.

Similarly, before the project finishes executing, the k_radio_terminate function should be called to perform the appropriate system cleanup.

For example:

#include "radio-api/radio.h"

if (k_radio_init() != RADIO_OK)
{
    return;
}

// Project logic

k_radio_terminate();

Run-Time Radio Configuration

Some radios may support or require that the radio be configured during run-time. This can be done by passing a pointer to a radio_config structure to the k_radio_configure function.

Unneeded configuration parameters may be left with zero values to indicate that they should not be changed.

For example:

#include "radio-api/radio.h"

radio_config config;
config.data_rate = RADIO_RATE_1200;
strncpy(config.to.ascii, "MAJORT", sizeof(config.to.ascii);
strncpy(config.from.ascii, "HMLTN1", sizeof(config.from.ascii);

k_radio_configure(&config);

Sending a Message

In order to write a message to the radio’s transmit buffer, call the k_radio_send function.

The function takes three parameters:

  • A pointer to the message to be sent
  • The length of the message
  • A pointer to a response byte (varies by radio. For example, returning the number of bytes written)

The function will return one of two values:

  • RADIO_OK - Indicating a message was successfully received
  • RADIO_ERROR - Indicating that something went wrong during the send process

For example:

#include "radio-api/radio.h"

KRadioStatus status;
uint8_t message[] = "Radio Test Message";
uint8_t len = sizeof(message);
uint8_t response;

status = k_radio_send(message, len, &response);

Receiving a Message

In order to read a message from a radio’s receive buffer, call the k_radio_recv function.

The function takes two parameters:

  • A pointer to a radio_rx_message structure where the message will be put
  • A pointer to a variable which will be updated to contain the length of the message received.

The function will return one of three values:

  • RADIO_OK - Indicating a message was successfully received
  • RADIO_RX_EMPTY - Indicating there are no messages to receive
  • RADIO_ERROR - Indicating that something went wrong during the receive process

For example:

#include "radio-api/radio.h"

KRadioStatus status;
radio_rx_message buffer;
uint8_t len;

status = k_radio_recv(&buffer, &len);