Skip to main content Link Menu Expand (external link) Copy Copied

Northbound Interface (NBI) Developer Guide

There are 2 top-level concepts in Spacetime: Platforms and Network Nodes.

  • A Platform describes something physical that has a position, which can be fixed or moving in either the Earth’s or the Moon’s frame of reference.
  • A NetworkNode represents a logical network device.

Some entities, such as aircraft, satellites, and ground stations, will have a Platform and an associated NetworkNode, but there is not always a 1-to-1 relationship. Some entities must be included in the network topology for their routing tables to be updated, but their physical location is irrelevant, so only their logical relationships in the network need to be modeled. These entities can be defined as a NetworkNode without a Platform, such as for a point of presence to the Internet, routers and switches on the ground, or enterprise cloud resources in the ground segment that will be routed to. For other entities, it’s useful to model a physical location, but Spacetime does not orchestrate the network across these entities. These entities can be defined as a Platform without a NetworkNode, such as for a third-party satellite, a victim of interference, or a jammer.

Platform

Platforms are defined in PlatformDefinition. This message contains fields to define the position of the platform and the collection of communications assets onboard.

Motion

The coordinates field (of type Motion) defines the position and/or motion of the platform. Spacetime supports Geodetic coordinates relative to mean sea level or the WGS84 reference ellipsoid; Earth-centered, Earth-fixed coordinates; timestamped interpolations of Earth-centered, Earth-fixed coordinates; cartographic waypoints; two-line elements (TLE); Keplerian elements; state vectors; and selenographic coordinates (coordinates in the Moon’s reference frame). The interval field of the Motion message allows any type of motion to be defined over a specified time interval or continuously propagated.

Another way to define motion is to have Spacetime fetch a platform’s coordinates from a public web service, such as TLEs from Norad or FlightRadar24 trajectories, through the motion_source field.

Transceivers

TransceiverModels define the communications assets on the platform. Each TransceiverModel contains a transmitter (of type TransmitterDefinition), a receiver (of type ReceiverDefinition), an antenna (of type AntennaDefinition), and a list of supported MACs (of type WirelessMac). If there are other parameters you would like to define on each MAC, you can define a Protocol Buffer extension in your code to add new fields to this message.

Transmitters and Receivers
Spacetime groups channels that can be considered as having the same propagation loss effects into BandProfiles for performance optimization. Then, the same propagation loss modeling is applied to all channels in the BandProfile. For example, consider the 2.4GHz and 5GHz bands in WiFi. There are many channels in the 2.4GHz band, such as channels 1 - 11, and there are many channels in the 5GHz band, such as U-NII-1, U-NII-2A, etc. In many cases, the channels in the 2.4GHz band can be considered to have the same propagation loss, and the channels in the 5GHz band can be considered to have the same propagation loss. But, we cannot treat channels in the 2.4GHz band the same as channels in the 5GHz band. So, we could model the 2.4GHz channels and the 5GHz channels as 2 BandProfiles, and the propagation loss will be computed for each BandProfile. In this way, BandProfiles allow users to tell Spacetime which ranges of channels to compute a different propagation loss modeling for. Each BandProfile has an AdaptiveRateTable, which stores levels of carrier-to-noise-and-interference (C/(N + I), in dB) with the effective data rate that each level can maintain.

The TransmitterDefinition and ReceiverDefinition have a channel_set field that defines which channels belong to each BandProfile. For the transmitter, users can define the maximum transmit power on each channel to model onboard power limitations or regulatory limitations. Both the TransmitterDefinition and ReceiverDefinition also have a list of signal_processing_steps. On the transmitter, users can configure a chain of amplifiers or constant gains and losses. On the receiver, users can configure a chain of filters, amplifiers for RF communications, photodetectors for Optical communications, or miscellaneous gains and losses.

Antennas
Antennas are defined in AntennaDefinition.

The fixed_coordinates_offsets allow each antenna to have its own positional and rotational offset from the platform’s center. The targeting field defines whether an antenna is fixed or steerable, and if it is steerable, this field specifies the motion of the target. The antenna_pattern_id field defines a reference to the antenna’s gain pattern, which is defined in AntennaPattern. Spacetime supports Gaussian, Helical, Isotropic, Parabolic, Square Horn, Gaussian Optical, and custom gain patterns specified through phi (radians), theta (radians), and gain (dB). Separate near- and far- field antenna patterns can be specified as well.

Network Node

A NetworkNode is a collection of network interfaces (of type NetworkInterface) and defines the networking parameters of a single device or a subnet.

The NetworkInterface has an IP address (IPv4 or IPv6) and a field to indicate whether the interface can receive traffic in promiscuous mode. This interface can model a WiredDevice or a WirelessDevice, which connect this logical networking entity to Spacetime’s physical model. WirelessDevices specify the ID of the TransceiverModel used for its communications. WiredDevices specify the ID of an associated platform and their data rate.

The storage field allows you to express that a node has a certain amount of onboard storage. This is useful for science missions that intermittently downlink data or for disruption tolerant network flows (DTN), where nodes can store-and-forward traffic either at the source or at an intermediate node.

The agent field configures whether Spacetime can orchestrate the routing on this node. This allows Spacetime to model nodes that have their own routing protocols and should be present in the network, but whose routing tables will not be updated by Spacetime. Within this message, the maximum_control_plane_latency field allows you to model multiple ways of reaching this node through the control plane.

The power_budget defines a limit on the aggregate amount of power on the node that is available across all network interfaces.

Service Request

A ServiceRequest defines a request to Spacetime to move data from a source node (or set of nodes) to a destination node (or set of nodes).

The FlowRequirements describe a set of time-dynamic requirements for the network flow. In the requirements, you can define a committed information rate (defined as bandwidth_bps_minimum) and an excess information rate (defined as bandwidth_bps_requested). The latency_maximum can also be set to constrain Spacetime to find routes within a given end-to-end propagation delay for this service request’s path. Each requirement has an associated time_interval, which can be bounded or unbounded. If unbounded, the request for connectivity will exist from now into the future, until an end time on this service request is defined.

To support delay tolerant network flows (DTN), setting the is_disruption_tolerant field causes this request to be solved across time intervals of disconnectedness. Spacetime will compute a schedule of intermittent downlinks, which may be continuous or disconnected, so that the onboard memory of any node does not overflow. For example, if a delay tolerant service request specifies a capacity request of 5 Mbps, Spacetime will ensure that 5Mbps generated at the source node can reach the destination node without oversaturating any links or exceeding the storage capacity of any node.

The priority field is a hard prioritization metric, so Spacetime will assign resources to service requests strictly according to this metric. Since it is a simple double, this value can represent any metric of relevance that describes the relative importance of service requests, such as estimated revenue, number of customers served, or priority tiers.