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
TransceiverModel
s 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 BandProfile
s 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 BandProfile
s, and the propagation loss will be computed for each BandProfile
. In this way, BandProfile
s 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_offset
s 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. WirelessDevice
s specify the ID of the TransceiverModel
used for its communications. WiredDevice
s 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.