ISIS TRXVU Radio API

Radio config.json configuration options and default values

TRXVU_I2C_BUS

I2C bus the TRXVU radio is connected to.

RADIO_TX_ADDR

Transmitter I2C address.

RADIO_RX_ADDR

Receiver I2C address.

TX_MAX_SIZE

Transmitter maximum message size.

RX_MAX_SIZE

Receiver maximum message size.

TX_MAX_FRAMES

Transmitter buffer slots.

RX_MAX_FRAMES

Receive buffer slots.

TRXVU_WD_TIMEOUT

Watchdog timeout (in seconds)

Telemetry Conversion Functions

Convert raw ADC values into human-readable units

float get_voltage(uint16_t raw)

Return
Voltage in volts
Parameters
  • raw: Raw ADC value

float get_current(uint16_t raw)

Return
Current in milliamps
Parameters
  • raw: Raw ADC value

float get_temperature(uint16_t raw)

Return
Temperature in degrees Celsius
Parameters
  • raw: Raw ADC value

float get_doppler_offset(uint16_t raw)

Return
Doppler shift in hertz
Parameters
  • raw: Raw ADC value

float get_signal_strength(uint16_t raw)

Return
Received signal strength power in decibel-milliwatts
Parameters
  • raw: Raw ADC value

float get_rf_power_dbm(uint16_t raw)

Return
RF reflected power in decibel-milliwatts
Parameters
  • raw: Raw ADC value

float get_rf_power_mw(uint16_t raw)

Return
RF reflected power in milliwatts
Parameters
  • raw: Raw ADC value

Typedefs

typedef uint32_t trxvu_uptime

Transmitter or receiver uptime value (in seconds)

Enums

enum KRadioStatus

Radio function return values.

Values:

RADIO_OK = 0

Function call completed successfully.

RADIO_RX_EMPTY

Radio receive buffer is empty.

RADIO_ERROR

Generic radio error.

RADIO_ERROR_CONFIG

Function input parameter is invalid.

enum KRadioReset

Radio reset types.

Values:

RADIO_HARD_RESET

Perform hardware-level radio reset.

RADIO_SOFT_RESET

Perform software radio reset.

enum RadioTXRate

Flags used to set radio transmission data rate.

Values:

RADIO_TX_RATE_1200 = 0x01

Transmitter data rate 1200bps.

RADIO_TX_RATE_2400 = 0x02

Transmitter data rate 2400bps.

RADIO_TX_RATE_4800 = 0x04

Transmitter data rate 4800bps.

RADIO_TX_RATE_9600 = 0x08

Transmitter data rate 9600bps.

enum RadioIdleState

Flags used to set transmitter’s idle state.

Values:

RADIO_IDLE_UNKNOWN = 0

Dummy value to indicate no change should be made.

RADIO_IDLE_OFF

Transmitter should turn off while idle.

RADIO_IDLE_ON

Transmitter should remain on while idle.

enum RadioTelemType

Telemetry request types.

Values:

RADIO_TX_TELEM_ALL

Returns the current measurements of all the transmitter’s telemetry channels.

RADIO_TX_TELEM_LAST

Returns the telemetry channels that were sampled during the last frame transmission.

RADIO_TX_UPTIME

Returns the amount of time, in seconds, that the transmitter portion of the radio has been active.

RADIO_TX_STATE

Returns the current state of the transmitter.

RADIO_RX_TELEM_ALL

Returns the current measurements of all the receiver’s telemetry channels.

RADIO_RX_UPTIME

Returns the amount of time, in seconds, that the receiver portion of the radio has been active.

enum RadioTXState

Radio TX state flags returned by RADIO_TX_STATE request.

Values:

RADIO_STATE_IDLE_OFF = 0x00

Transmitter will turn off when idle.

RADIO_STATE_IDLE_ON = 0x01

Transmitter will remain on when idle.

RADIO_STATE_BEACON_ACTIVE = 0x02

Transmitter’s beacon is enabled.

RADIO_STATE_RATE_1200 = 0x00

Transmitter sending at 1200bps.

RADIO_STATE_RATE_2400 = 0x01

Transmitter sending at 2400bps.

RADIO_STATE_RATE_4800 = 0x02

Transmitter sending at 4800bps.

RADIO_STATE_RATE_9600 = 0x03

Transmitter sending at 9600bps.

Functions

KRadioStatus k_radio_watchdog_kick(void)

Kick the radio’s watchdogs once.

Return
KRadioStatus RADIO_OK if OK, error otherwise

KRadioStatus k_radio_watchdog_start(void)

Start a thread to kick the radio’s watchdogs at an interval of (TRXVU_WD_TIMEOUT/3) seconds.

Return
KRadioStatus RADIO_OK if OK, error otherwise

KRadioStatus k_radio_watchdog_stop(void)

Stop the watchdog thread.

Return
KRadioStatus RADIO_OK if OK, error otherwise

KRadioStatus k_radio_send_override(ax25_callsign to, ax25_callsign from, char *buffer, int len, uint8_t *response)

Send a message to the transmit buffer, but use the specified call-signs instead of the defaults.

Return
KRadioStatus RADIO_OK on success, otherwise error
Parameters
  • to: AX.25 call-sign for message sender
  • from: AX.25 call-sign for message destination
  • buffer: Pointer to message to send
  • len: Length of message to send
  • response: Pointer to storage area for response byte

KRadioStatus k_radio_set_beacon_override(ax25_callsign to, ax25_callsign from, radio_tx_beacon beacon)

Set the automatic periodic beacon, but use the specified call-signs instead of the defaults.

Return
KRadioStatus RADIO_OK on success, otherwise error
Parameters
  • to: AX.25 call-sign for message sender
  • from: AX.25 call-sign for message destination
  • beacon: radio_tx_beacon to send

KRadioStatus k_radio_clear_beacon(void)

Clear/deactivate the automatic periodic beacon.

Return
KRadioStatus RADIO_OK on success, otherwise error

KRadioStatus k_radio_init(void)

Initialize the radio interface.

Return
KRadioStatus RADIO_OK if OK, error otherwise

void k_radio_terminate(void)

Terminate the radio interface.

KRadioStatus k_radio_configure(radio_config *config)

Configure the radio.

Note
This function might not be implemented for all radios. See specific radio API documentation for configuration availability and structure
Return
KRadioStatus RADIO_OK if OK, error otherwise
Parameters
  • config: Pointer to the radio configuration structure

KRadioStatus k_radio_reset(KRadioReset type)

Reset the radio.

Note
This function might not be implemented for all radios
Return
KRadioStatus RADIO_OK if OK, error otherwise
Parameters
  • type: Type of reset to perform (hard, soft, etc)

KRadioStatus k_radio_send(char *buffer, int len, uint8_t *response)

Send a message to the radio’s transmit buffer.

Return
KRadioStatus RADIO_OK if OK, error otherwise
Parameters
  • buffer: Pointer to the message to send
  • len: Length of the message to send
  • response: Response value from radio (if supported)

KRadioStatus k_radio_recv(radio_rx_message *buffer, uint8_t *len)

Receive a message from the radio’s receive buffer.

Return
KRadioStatus RADIO_OK if a message was received successfully, RADIO_RX_EMPTY if there are no messages to receive, error otherwise
Parameters
  • buffer: Pointer where the message should be copied to
  • len: Length of the received message

KRadioStatus k_radio_get_telemetry(radio_telem *buffer, RadioTelemType type)

Read radio telemetry values.

Note
See specific radio API documentation for available telemetry types
Return
KRadioStatus RADIO_OK if OK, error otherwise
Parameters
  • buffer: Pointer to structure which data should be copied to
  • type: Telemetry packet to read

void *kprv_radio_watchdog_thread(void *args)

Thread which kicks the radio’s watchdogs every (TRXVU_WD_TIMEOUT/3) seconds.

KRadioStatus kprv_radio_tx_set_beacon(uint16_t rate, char *buffer, int len)

Set the transmitter beacon’s interval and message.

Return
KRadioStatus RADIO_OK on success, otherwise error
Parameters
  • rate: Interval (in seconds) at which to send beacon message
  • buffer: Pointer to beacon payload message
  • len: Length of beacon payload message

KRadioStatus kprv_radio_tx_set_default_to(ax25_callsign to)

Set the transmitter’s default AX.25 sender call-sign.

Return
KRadioStatus RADIO_OK on success, otherwise error
Parameters
  • to: Pointer to AX.25 call-sign structure

KRadioStatus kprv_radio_tx_set_default_from(ax25_callsign from)

Set the transmitter’s default AX.25 destination call-sign.

Return
KRadioStatus RADIO_OK on success, otherwise error
Parameters
  • from: Pointer to AX.25 call-sign structure

KRadioStatus kprv_radio_tx_set_idle(RadioIdleState state)

Set the transmitter’s idle state.

Return
KRadioStatus RADIO_OK on success, otherwise error
Parameters

KRadioStatus kprv_radio_tx_set_rate(RadioTXRate rate)

Set the transmitter’s data rate.

Return
KRadioStatus RADIO_OK on success, otherwise error
Parameters
  • rate: Data rate. Should be RADIO_TX_RATE_1200, RADIO_TX_RATE_2400, RADIO_TX_RATE_4800, or RADIO_TX_RATE_9600

KRadioStatus kprv_radio_tx_get_telemetry(radio_telem *buffer, RadioTelemType type)

Get telemetry from transmitter.

Return
KRadioStatus RADIO_OK on success, otherwise error
Parameters

KRadioStatus kprv_radio_tx_watchdog_kick(void)

Kick the transmitter’s watchdog.

Return
KRadioStatus RADIO_OK if OK, error otherwise

KRadioStatus kprv_radio_tx_reset(KRadioReset type)

Reset the transmitter.

Return
KRadioStatus RADIO_OK if OK, error otherwise
Parameters
  • type: Type of reset to be performed. Should be RADIO_RESET_SOFT or RADIO_RESET_HARD

KRadioStatus kprv_radio_rx_get_count(uint8_t *count)

Get number of frames in receive buffer.

Return
KRadioStatus RADIO_OK if OK, error otherwise
Parameters
  • count: Pointer to storage area for count value

KRadioStatus kprv_radio_rx_remove_frame(void)

Delete oldest frame from receive buffer.

Return
KRadioStatus RADIO_OK if OK, error otherwise

KRadioStatus kprv_radio_rx_get_frame(radio_rx_message *buffer, uint8_t *len)

Retrieve oldest frame from receive buffer.

Return
KRadioStatus RADIO_OK if OK, error otherwise
Parameters
  • buffer: Pointer to storage area for frame
  • len: Pointer to storage are for length of frame payload

KRadioStatus kprv_radio_rx_get_telemetry(radio_telem *buffer, RadioTelemType type)

Get telemetry from receiver.

Return
KRadioStatus RADIO_OK on success, otherwise error
Parameters

KRadioStatus kprv_radio_rx_watchdog_kick(void)

Kick the receiver’s watchdog.

Return
KRadioStatus RADIO_OK if OK, error otherwise

KRadioStatus kprv_radio_rx_reset(KRadioReset type)

Reset the receiver.

Return
KRadioStatus RADIO_OK if OK, error otherwise
Parameters
  • type: Type of reset to be performed. Should be RADIO_RESET_SOFT or RADIO_RESET_HARD

struct trxvu_tx_telem_raw
#include <trxvu.h>

Transmitter raw telemetry fields returned from RADIO_TX_TELEM_ALL and RADIO_TX_TELEM_LAST requests.

Public Members

uint16_t inst_RF_reflected

Instantaneous RF reflected power at transmitter port.

uint16_t inst_RF_forward

Instantaneous RF forward power at transmitter port.

uint16_t supply_voltage

Power bus voltage.

uint16_t supply_current

Total supply current.

uint16_t temp_power_amp

Power amplifier temperature.

uint16_t temp_oscillator

Local oscillator temperature.

struct ax25_callsign
#include <trxvu.h>

AX.25 call-sign structure.

Public Members

uint8_t ascii[6]

Six character station call-sign.

uint8_t ssid

One byte station SSID value.

struct trxvu_rx_telem_raw
#include <trxvu.h>

Receiver raw telemetry fields returned from RADIO_RX_TELEM_ALL telemetry request.

Public Members

uint16_t inst_doppler_offset

Instantaneous Doppler offset of signal at receiver port.

uint16_t supply_current

Total supply current.

uint16_t supply_voltage

Power bus voltage.

uint16_t temp_oscillator

Local oscillator temperature.

uint16_t temp_power_amp

Power amplifier temperature.

uint16_t inst_signal_strength

Instantaneous signal strength of the signal at the receiver.

union radio_telem
#include <trxvu.h>

High-level Unifying Radio Telemetry Structure.

Public Members

uint8_t tx_state

Returned by RADIO_TX_STATE.

trxvu_uptime uptime

Returned by RADIO_TX_UPTIME and RADIO_RX_UPTIME.

trxvu_tx_telem_raw tx_telem

Returned by RADIO_TX_TELEM_ALL and RADIO_TX_TELEM_LAST.

trxvu_rx_telem_raw rx_telem

Returned by RADIO_RX_TELEM_ALL.

struct radio_tx_beacon
#include <trxvu.h>

Transmitter automatic periodic beacon configuration.

Public Members

uint16_t interval

Interval (in seconds) at which the beacon message should be sent.

char *msg

Pointer to beacon payload message to be sent.

uint8_t len

Length of beacon payload message.

struct radio_config
#include <trxvu.h>

Radio transmitter configuration options.

Public Members

RadioTXRate data_rate

Transmission data rate flag.

RadioIdleState idle

Transmitter’s state when idle.

radio_tx_beacon beacon

Transmitter beacon configuration.

ax25_callsign to

Transmitter AX.25 sender call-sign.

ax25_callsign from

Transmitter AX.25 destination call-sign.

struct radio_rx_message
#include <trxvu.h>

Radio receive frame structure.

Public Members

uint16_t msg_size

Size of the frame payload.

uint16_t doppler_offset

ADC value of doppler shift at receive time (convert with get_doppler_offset)

uint16_t signal_strength

ADC value of signal strength at receive time (convert with get_signal_strength)

uint8_t message[RX_MAX_SIZE]

Frame payload.