Application APIs

group Satellite Network Function APIs

Hubble Sat Network Function APIs.

Warning

The satellite functionality is currently in pre-production and is not yet ready for production deployments. APIs and behavior may change in future releases.

Enums

enum hubble_sat_transmission_mode

Satellite transmission mode.

It tells what is the desired reliability when transmitting a packet. Higher reliability consumes higher power because it increases the number of retries.

The drift is estimated from the device’s Time Drift Rate (TDR), configured through CONFIG_HUBBLE_SAT_NETWORK_DEVICE_TDR and expressed in parts per million (PPM). The accumulated drift is computed as (time since last sync) * TDR, so a higher TDR yields more additional retries for the same elapsed time.

Note

The retry counts listed below are baselines. Extra retries are added to compensate for the device’s clock drift accumulated since the last time synchronization: one additional retry is added for every full retransmission interval worth of drift. The longer the device goes without synchronizing its clock, the more retries are performed. Modes with no retries (HUBBLE_SAT_RELIABILITY_NONE) are not affected.

Values:

enumerator HUBBLE_SAT_RELIABILITY_NONE: No retries. The packet is transmitted one time.

enumerator HUBBLE_SAT_RELIABILITY_NORMAL: Good balance between reliability and power consumption. The packet is transmitted 8 times with a 20 second interval between transmissions.

enumerator HUBBLE_SAT_RELIABILITY_HIGH: High reliability and higher power consumption. The packet is transmitted 16 times with a 10 second interval between transmissions.

Functions

int hubble_sat_packet_send(const struct hubble_sat_packet *packet, enum hubble_sat_transmission_mode mode)

Transmit a packet using the Hubble satellite communication system.

This function sends a packet over the satellite communication channel. The packet must be properly formatted and adhere to the Hubble protocol.

Note

This function is blocking: it does not return until the transmission period has completed.

Warning

This function checks if the packet is NULL but does not perform any validation on the packet structure. It is the caller’s responsibility to ensure the packet is correctly formatted.

Parameters:

packet – A pointer to the hubble_sat_packet structure containing the data to be transmitted.
mode – Desired reliability for the transmission.

Returns:

0 on successful transmission, or a negative error code on failure.

int hubble_sat_satellites_set(const struct hubble_sat_orbital_params *const satellites, size_t count)

Set orbital information for satellites.

This function stores orbital parameters for one or more satellites. The parameters are used by hubble_sat_next_pass_get() and hubble_sat_next_pass_region_get() to compute the next satellite pass across all configured satellites.

Note

The caller must ensure the satellites array remains valid for the lifetime of subsequent pass calculations, as the data is not copied internally.

Note

To clear the satellite list, call with satellites set to NULL and count set to 0.

Parameters:

satellites – Pointer to an array of satellite orbital parameters. May be NULL only if count is 0.
count – Number of entries in the array. Pass 0 to clear the satellite list.

Return values:

-EINVAL – if satellites is NULL and count is greater than 0.

Returns:

0 on success.

int hubble_sat_next_pass_get(uint64_t t, const struct hubble_sat_device_pos *pos, struct hubble_sat_pass_info *pass)

Get the next satellite pass.

This function calculates the next pass of a satellite over a given location, based on satellites orbital parameters and the device’s location.

Parameters:

t – Current time or the time to start the calculation (milliseconds since Unix epoch).
pos – Pointer to the device’s location.
pass – The next satellite pass in case of success.

Returns:

0 on success or a negative value in case of error.

int hubble_sat_next_pass_region_get(uint64_t t, const struct hubble_sat_device_region *region, struct hubble_sat_pass_info *pass)

Get the next satellite pass over a geographic region.

This function calculates the next pass of a satellite over a rectangular geographic region defined by latitude and longitude bounds, based on satellites orbital parameters.

Parameters:

t – Current time or the time to start the calculation (milliseconds since Unix epoch).
region – Pointer to the geographic region definition.
pass – The next satellite pass in case of success.

Returns:

0 on success or a negative value in case of error.

int hubble_sat_min_elevation_angle_set(uint8_t angle)

Set the minimum elevation angle for a satellite pass.

This function configures the minimum elevation angle above the horizon that a satellite must reach at culmination for a pass to be reported by hubble_sat_next_pass_get() and hubble_sat_next_pass_region_get(). Passes whose maximum elevation angle is below this threshold are ignored.

Raising the angle restricts results to higher, closer passes (typically better link quality) at the cost of fewer reported passes. The default minimum elevation angle is 45 degrees.

Parameters:: angle – Minimum elevation angle in degrees. Must be in the range [30, 90].
Return values:: -EINVAL – if angle is outside the range [30, 90].
Returns:: 0 on success.

struct hubble_sat_orbital_params

#include <pass_prediction.h>

Represents the orbital parameters of a satellite.

This structure contains the parameters required to describe the orbit of a satellite, including its position, motion, and orientation.

struct hubble_sat_device_pos

#include <pass_prediction.h>

Represents the location of a device.

This structure contains the latitude and longitude of a device on Earth.

struct hubble_sat_device_region

#include <pass_prediction.h>

Represents a rectangular geographic region.

This structure defines a rectangular region using a center point (latitude/longitude) and range values.

struct hubble_sat_pass_info

#include <pass_prediction.h>

Represents information about a satellite pass.

This structure contains details about a satellite’s pass over a specific location, including the time, longitude, and whether the satellite is ascending or descending.

group Satellite Network packet APIs

Hubble Sat Network Packet APIs.

Defines

HUBBLE_PACKET_MAX_SIZE

HUBBLE_SAT_PAYLOAD_MAX

HUBBLE_PACKET_FRAME_PAYLOAD_MAX_SIZE

HUBBLE_PACKET_FRAME_MAX_SIZE

Functions

int hubble_sat_packet_get(struct hubble_sat_packet *packet, const void *payload, size_t length)

Build a Hubble satellite packet from a payload.

This function constructs a Hubble satellite packet by encoding the provided payload data into the packet structure.

Parameters:

packet – Pointer to the packet structure to be populated.
payload – Pointer to the payload data to be included in the packet.
length – Length of the payload data in bytes. Must be one of the supported sizes: 0, 4, 9, or 13 bytes.

Return values:

0 – On success.
-EINVAL – If any of the input parameters are invalid.
-ENOMEM – If the payload length exceeds the maximum allowed size.

int hubble_sat_packet_frames_get(const struct hubble_sat_packet *packet, struct hubble_sat_packet_frames *frames)

Split a Hubble satellite packet into transmission frames.

This function divides the encoded data of a Hubble packet into one or more frames suitable for transmission. Each frame carries a portion of the packet payload along with its associated channel.

Parameters:

packet – Pointer to the source packet to split.
frames – Pointer to the frames structure to be populated.

Return values:

0 – On success.
-EINVAL – If any of the input parameters are invalid.

struct hubble_sat_packet

#include <packet.h>

Structure representing a Hubble packet.

This structure is used to represent a Hubble packet, the data is a set symbols that represents the frequency in a specific channel.

Since the preamble is a fixed pattern that is formed by the reference frequency and the complete absence of transmission for a certain period, it is NOT included in this structure.

Note

The preamble is NOT included in this struct.

struct hubble_sat_packet_frames

#include <packet.h>

Structure representing a set of Hubble packet frames.

A single Hubble packet may be split into multiple frames for transmission. Each frame carries a chunk of the encoded packet payload along with the channel on which it should be transmitted.

Note

The preamble is included in this struct.

Port APIs

group Hubble Network Satellite Radio Port APIs

Hubble Network Satellite Radio Port APIs.

Platform-specific functions that need to be implemented for satellite communication.

Defines

HUBBLE_WAIT_SYMBOL_US: Duration to wait for a symbol transmission in microseconds.

HUBBLE_WAIT_SYMBOL_OFF_US: Duration to wait for a symbol off period in microseconds.

HUBBLE_SAT_SYMBOLS_FRAME_MAX: The max number of symbols to transmit in single frame.

HUBBLE_SAT_NUM_CHANNELS: Number of available channels for transmissions.

HUBBLE_SAT_PREAMBLE_SEQUENCE

Preamble sequence pattern for satellite communication.

This array defines the frequency step pattern used for the preamble. Values represent frequency steps relative to the reference frequency:

0: reference frequency
-1: no transmission
31: center channel frequency

Functions

int hubble_sat_port_init(void)

Initialize the satellite radio port.

This function performs platform-specific initialization of the satellite radio hardware. It is called before any other satellite radio operations are performed.

Returns:: 0 on success, negative error code on failure.

int hubble_sat_port_packet_send(const struct hubble_sat_packet *packet, uint8_t retries, uint8_t interval_s)

Transmit a packet over the satellite radio.

This function transmits a packet using the satellite radio hardware. The packet is sent on the specified channel (frequency) using the platform-specific radio implementation. It handles re-transmissions internally.

Note

This function blocks the caller during the whole transmission.

Note

This API is thread safe.

Parameters:

packet – Pointer to the packet structure containing the data to transmit.
retries – The number of times this packet must be transmit.
interval_s – The time interval between transmissions.

Returns:

0 on successful transmission, negative error code on failure.

int hubble_sat_dtm_port_packet_send(const struct hubble_sat_packet *packet, int8_t channel)

Transmit a DTM test packet over the satellite radio.

Platform-specific implementation for sending a single DTM packet on the specified channel. When channel is -1, the transmission follows the standard channel-hopping scheme used by hubble_sat_port_packet_send.

Parameters:

packet – Pointer to the packet structure containing the data to transmit.
channel – RF channel to transmit on. -1 to hop between channels.

Return values:

0 – Success.
-EINVAL – Invalid channel.

int hubble_sat_dtm_port_power_set(int8_t power)

Set the transmit power level (port implementation).

Platform-specific implementation for configuring the output power used for subsequent DTM transmissions.

Parameters:

power – Desired TX power in dBm.

Return values:

0 – Success.
-EINVAL – Power level is out of the supported range.

int hubble_sat_dtm_port_cw_start(uint8_t channel)

Start continuous wave (CW) transmission (port implementation).

Platform-specific implementation that begins transmitting an unmodulated carrier on the specified channel. Call hubble_sat_dtm_port_cw_stop to end the transmission.

Parameters:

channel – RF channel index to transmit on.

Return values:

0 – Success.
-EINVAL – Invalid channel.

int hubble_sat_dtm_port_cw_stop(void)

Stop continuous wave (CW) transmission (port implementation).

Platform-specific implementation that halts the unmodulated carrier started by hubble_sat_dtm_port_cw_start.

Return values:: 0 – Success.