ISIS TRXVU Radio API¶

Telemetry Conversion Functions

Convert raw ADC values into human-readable units

float get_voltage(uint16_t raw)¶

Parameters: raw – [in] Raw ADC value
Returns: Voltage in volts

float get_current(uint16_t raw)¶

Parameters: raw – [in] Raw ADC value
Returns: Current in milliamps

float get_temperature(uint16_t raw)¶

Parameters: raw – [in] Raw ADC value
Returns: Temperature in degrees Celsius

float get_doppler_offset(uint16_t raw)¶

Parameters: raw – [in] Raw ADC value
Returns: Doppler shift in hertz

float get_signal_strength(uint16_t raw)¶

Parameters: raw – [in] Raw ADC value
Returns: Received signal strength power in decibel-milliwatts

float get_rf_power_dbm(uint16_t raw)¶

Parameters: raw – [in] Raw ADC value
Returns: RF reflected power in decibel-milliwatts

float get_rf_power_mw(uint16_t raw)¶

Parameters: raw – [in] Raw ADC value
Returns: RF reflected power in milliwatts

Typedefs

typedef uint32_t trxvu_uptime¶: Transmitter or receiver uptime value (in seconds)

Enums

enum KRadioStatus¶

Radio function return values.

Values:

enumerator RADIO_OK¶: Function call completed successfully.

enumerator RADIO_RX_EMPTY¶: Radio receive buffer is empty.

enumerator RADIO_ERROR¶: Generic radio error.

enumerator RADIO_ERROR_CONFIG¶: Function input parameter is invalid.

enum KRadioReset¶

Radio reset types.

Values:

enumerator RADIO_HARD_RESET¶: Perform hardware-level radio reset.

enumerator RADIO_SOFT_RESET¶: Perform software radio reset.

enum RadioTXRate¶

Flags used to set radio transmission data rate.

Values:

enumerator RADIO_TX_RATE_1200¶: Transmitter data rate 1200bps.

enumerator RADIO_TX_RATE_2400¶: Transmitter data rate 2400bps.

enumerator RADIO_TX_RATE_4800¶: Transmitter data rate 4800bps.

enumerator RADIO_TX_RATE_9600¶: Transmitter data rate 9600bps.

enum RadioIdleState¶

Flags used to set transmitter’s idle state.

Values:

enumerator RADIO_IDLE_UNKNOWN¶: Dummy value to indicate no change should be made.

enumerator RADIO_IDLE_OFF¶: Transmitter should turn off while idle.

enumerator RADIO_IDLE_ON¶: Transmitter should remain on while idle.

enum RadioTelemType¶

Telemetry request types.

Values:

enumerator RADIO_TX_TELEM_ALL¶: Returns the current measurements of all the transmitter’s telemetry channels.

enumerator RADIO_TX_TELEM_LAST¶: Returns the telemetry channels that were sampled during the last frame transmission.

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

enumerator RADIO_TX_STATE¶: Returns the current state of the transmitter.

enumerator RADIO_RX_TELEM_ALL¶: Returns the current measurements of all the receiver’s telemetry channels.

enumerator 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:

enumerator RADIO_STATE_IDLE_OFF¶: Transmitter will turn off when idle.

enumerator RADIO_STATE_IDLE_ON¶: Transmitter will remain on when idle.

enumerator RADIO_STATE_BEACON_ACTIVE¶: Transmitter’s beacon is enabled.

enumerator RADIO_STATE_RATE_1200¶: Transmitter sending at 1200bps.

enumerator RADIO_STATE_RATE_2400¶: Transmitter sending at 2400bps.

enumerator RADIO_STATE_RATE_4800¶: Transmitter sending at 4800bps.

enumerator RADIO_STATE_RATE_9600¶: Transmitter sending at 9600bps.

Functions

KRadioStatus k_radio_watchdog_kick(void)¶

Kick the radio’s watchdogs once.

Returns: 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 (timeout/3) seconds.

Returns: KRadioStatus RADIO_OK if OK, error otherwise

KRadioStatus k_radio_watchdog_stop(void)¶

Stop the watchdog thread.

Returns: 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.

Parameters

to – [in] AX.25 call-sign for message sender
from – [in] AX.25 call-sign for message destination
buffer – [in] Pointer to message to send
len – [in] Length of message to send
response – [out] Pointer to storage area for response byte

Returns

KRadioStatus RADIO_OK on success, otherwise error

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.

Parameters

to – [in] AX.25 call-sign for message sender
from – [in] AX.25 call-sign for message destination
beacon – [in] radio_tx_beacon to send

Returns

KRadioStatus RADIO_OK on success, otherwise error

KRadioStatus k_radio_clear_beacon(void)¶

Clear/deactivate the automatic periodic beacon.

Returns: KRadioStatus RADIO_OK on success, otherwise error

KRadioStatus k_radio_init(char *bus, trx_prop tx, trx_prop rx, uint16_t timeout)¶

Initialize the radio interface.

Parameters

bus – [in] The I2C bus device the radio is connected to
tx – [in] The transmitter’s properties
rx – [in] The receiver’s properties
timeout – [in] The radio’s watchdog timeout (in seconds)

Returns

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

Parameters: config – [in] Pointer to the radio configuration structure
Returns: KRadioStatus RADIO_OK if OK, error otherwise

KRadioStatus k_radio_reset(KRadioReset type)¶

Reset the radio.

Note

This function might not be implemented for all radios

Parameters: type – [in] Type of reset to perform (hard, soft, etc)
Returns: KRadioStatus RADIO_OK if OK, error otherwise

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

Send a message to the radio’s transmit buffer.

Parameters

buffer – [in] Pointer to the message to send
len – [in] Length of the message to send
response – [out] Response value from radio (if supported)

Returns

KRadioStatus RADIO_OK if OK, error otherwise

KRadioStatus k_radio_recv(radio_rx_header *frame, uint8_t *message, uint8_t *len)¶

Receive a message from the radio’s receive buffer.

Parameters

frame – [out] Pointer where the header properties should be stored
message – [out] Pointer to where the message payload should be stored
len – [out] Length of the received message

Returns

KRadioStatus RADIO_OK if a message was received successfully, RADIO_RX_EMPTY if there are no messages to receive, error otherwise

KRadioStatus k_radio_get_telemetry(radio_telem *buffer, RadioTelemType type)¶

Read radio telemetry values.

Note

See specific radio API documentation for available telemetry types

Parameters

buffer – [in] Pointer to structure which data should be copied to
type – [in] Telemetry packet to read

Returns

KRadioStatus RADIO_OK if OK, error otherwise

void *kprv_radio_watchdog_thread(void *args)¶: Thread which kicks the radio’s watchdogs every (timeout/3) seconds.

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

Set the transmitter beacon’s interval and message.

Parameters

rate – Interval (in seconds) at which to send beacon message
buffer – Pointer to beacon payload message
len – Length of beacon payload message

Returns

KRadioStatus RADIO_OK on success, otherwise error

KRadioStatus kprv_radio_tx_set_default_to(ax25_callsign to)¶

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

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

KRadioStatus kprv_radio_tx_set_default_from(ax25_callsign from)¶

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

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

KRadioStatus kprv_radio_tx_set_idle(RadioIdleState state)¶

Set the transmitter’s idle state.

Parameters: state – Idle state. Should be RADIO_IDLE_ON or RADIO_IDLE_OFF
Returns: KRadioStatus RADIO_OK on success, otherwise error

KRadioStatus kprv_radio_tx_set_rate(RadioTXRate rate)¶

Set the transmitter’s data rate.

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

KRadioStatus kprv_radio_tx_get_telemetry(radio_telem *buffer, RadioTelemType type)¶

Get telemetry from transmitter.

Parameters

buffer – [out] 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 – [in] Telemetry type to fetch. Should be RADIO_TX_TELEM_ALL, RADIO_TX_TELEM_LAST, RADIO_TX_UPTIME, or RADIO_TX_STATE

Returns

KRadioStatus RADIO_OK on success, otherwise error

KRadioStatus kprv_radio_tx_watchdog_kick(void)¶

Kick the transmitter’s watchdog.

Returns: KRadioStatus RADIO_OK if OK, error otherwise

KRadioStatus kprv_radio_tx_reset(KRadioReset type)¶

Reset the transmitter.

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

KRadioStatus kprv_radio_rx_get_count(uint8_t *count)¶

Get number of frames in receive buffer.

Parameters: count – [out] Pointer to storage area for count value
Returns: KRadioStatus RADIO_OK if OK, error otherwise

KRadioStatus kprv_radio_rx_remove_frame(void)¶

Delete oldest frame from receive buffer.

Returns: KRadioStatus RADIO_OK if OK, error otherwise

KRadioStatus kprv_radio_rx_get_frame(radio_rx_header *frame, uint8_t *message, uint8_t *len)¶

Retrieve oldest frame from receive buffer.

Parameters

frame – [out] Pointer where the header properties should be stored
message – [out] Pointer to where the message payload should be stored
len – [out] Pointer to storage are for length of frame payload

Returns

KRadioStatus RADIO_OK if OK, error otherwise

KRadioStatus kprv_radio_rx_get_telemetry(radio_telem *buffer, RadioTelemType type)¶

Get telemetry from receiver.

Parameters

buffer – [out] Pointer to storage area. Should point to a trxvu_rx_telem_raw structure if RADIO_RX_TELEM_ALL is being requested
type – [in] Telemetry type to fetch. Should be RADIO_RX_TELEM_ALL or RADIO_RX_UPTIME

Returns

KRadioStatus RADIO_OK on success, otherwise error

KRadioStatus kprv_radio_rx_watchdog_kick(void)¶

Kick the receiver’s watchdog.

Returns: KRadioStatus RADIO_OK if OK, error otherwise

KRadioStatus kprv_radio_rx_reset(KRadioReset type)¶

Reset the receiver.

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

Variables

int radio_bus¶: File descriptor for the radio’s I2C bus.

trx_prop radio_tx¶: Radio transmitter properties.

trx_prop radio_rx¶: Radio receiver properties.

struct trx_prop¶

#include <trxvu.h>

TX/RX properties.

Public Members

uint8_t addr¶: I2C address of component.

uint16_t max_size¶: Maximum frame message size.

uint16_t max_frames¶: Maximum number of frames that can be in the buffer.

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_header¶

#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)