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

state: Idle state. Should be RADIO_IDLE_ON or RADIO_IDLE_OFF

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

buffer: Pointer to storage area. Should point to a trxvu_tx_telem_raw structure if RADIO_TX_TELEM_ALL or RADIO_TX_TELEM_LAST is being requested
type: Telemetry type to fetch. Should be RADIO_TX_TELEM_ALL, RADIO_TX_TELEM_LAST, RADIO_TX_UPTIME, or RADIO_TX_STATE

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

buffer: Pointer to storage area. Should point to a trxvu_rx_telem_raw structure if RADIO_RX_TELEM_ALL is being requested
type: Telemetry type to fetch. Should be RADIO_RX_TELEM_ALL or RADIO_RX_UPTIME

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.