Flightkit Communication Protocols Reference

A guide to Flightkit component types for use in communication protocol stacks.

1. Overview

Communications with computer systems are often described in layered terms. Each "layer" in the "stack" is responsible for a different part of the process of transforming physical signals on the wire to high-level software interactions.

Flightkit provides various component types which can be used to handle communications with (and between) your various flight software deployments.

Each component type typically implements a single communication protocol. Multiple types can be instantiated and connected together within your deployment type to produce the protocol stack you require.

This document describes some of these component types and demonstrates how they can be used within a deployment type to produce different communication protocol stacks.

2. Component Types

The FlightkitFoundation bundle provides a variety of different component types for implementing a protocol stack, some of which are shown below:

TCPServer
PacketStream
SpacePacket
PUSCore
PUSAMS
PASTarget
AASTarget

Let’s take a high level look at what each of these component types do, how they are configured to operate by default, and the different ways in which they can be initialised. For more detail, please refer to their documentation which can be generated using the tooling.

When inspecting the diagrams below, refer to the following key:

2.1. `TCPServer`

The TCPServer component type implements a basic TCP socket for network communication. The socket is hard coded to accept data from all IP addresses.

When data is received from a connected TCP client via the socket, the component type processes that data then transmits it as a stream of bytes to the data service provision’s consumer. Similarly, when stream data is received from the data service provision’s consumer, the component type processes that data then transmits it to the connected TCP client via the socket.

By default, the component type is configured as follows:

It can queue up to 10 client connection requests at one time (only one client can actually connect at a time).
It can process up to 10 receive transactions issued by the data service provision’s consumer at one time.
The maximum amount of data that each receive transaction can hold is limited to 1024 bytes, regardless of transaction size.
The timeout for accessing locked sections is set to 0.5 seconds.

These settings can be overridden at build time by redefining the relevant symbols from TCPServer_config.h in your deployment instance’s lib_config/meson.build file.

The following initialisation data must be specified by the user when the component type is instantiated.

The port number for the socket.
Whether or not to silently discard data to be transmitted when no client is connected.

2.2. `PacketStream`

The PacketStream component type implements a basic framing protocol developed by Bright Ascension Limited. It converts frames of stream data into packets, and vice versa.

When stream data is received from the stream service requirement’s provider, the component type validates whether the stream contains a packet, and if so, extracts the packet and transmits it to the packet service provision’s consumer.

When a packet is received from the packet service provision’s consumer, the component type adds framing data to the packet in the form of a start indicator, data length and CRC, then transmits the resultant frame as a stream of bytes to the stream service requirement’s provider.

By default, the component type is configured as follows:

The size of each framing field is set to 4 bytes.
It can process up to 15 receive transactions issued by the packet service provision’s consumer at one time.
It can only process packets received from the packet service provision’s consumer which are less than or equal to 4096 bytes in length.
It can issue up to 10 receive transactions to the stream service requirement’s provider at one time.
It can only process frames received from the stream service requirement’s provider which are less than or equal to 268 bytes in length.
The timeout for accessing locked sections is set to 0.1 seconds.

These settings can be overridden at build time by redefining the relevant symbols from PacketStream_config.h in your deployment instance’s lib_config/meson.build file.

This component type has no initialisation data.

2.3. `SpacePacket`

The SpacePacket component type implements the CCSDS Space Packet Protocol for TC and TM packets.

When a space packet is received from the spacePacket service requirement’s provider, the component type validates the packet, and if valid, extracts the payload and transmits it to the dataPacket service provision’s consumer that corresponds to the APID specified in the space packet’s header.

When a packet is received from the dataPacket service provision’s consumer, the component type encapsulates the packet within a space packet data structure, sets the field values accordingly, and transmits the resultant packet to the spacePacket service requirement’s provider.

By default, the component type is configured as follows:

It’s dataPacket service provision can be connected to a maximum of 12 different consumers, facilitating support for up to 12 different application processes.
It can process space packets with a payload size of up to 2078 bytes.
It can process up to 10 transmit transactions issued by a single dataPacket service provision’s consumer at one time.
It can issue up to 8 transmit transactions to the spacePacket service requirement’s provider at one time.
It can process up to 10 receive transactions issued by a single dataPacket service provision’s consumer at one time.
It can issue up to 8 receive transactions to the spacePacket service requirement’s consumer at one time.
The timeout for accessing locked sections is set to 0.1 seconds.

These settings can be overridden at build time by redefining the relevant symbols from SpacePacket_config.h in your deployment instance’s lib_config/meson.build file.

The following initialisation data must be specified by the user when the component type is instantiated.

A description of each application process that the dataPacket service provision supports.
The number of application processes that the dataPacket service provision supports.

2.4. `AMSTargetPS`

The AMSTargetPS component type handles AMS packets by issuing the operation contained within the packet to the relevant target, and returning response data if applicable.

When an AMS packet is received from the initiator service requirement’s provider, the component type validates the packet, and if valid, extracts the payload within it to determine the AMS operation that it contains and the target that it needs to be issued to. It then asynchronously issues the operation to the serviceTarget service requirement’s provider that corresponds to the required target.

On completion of AMS request operations, response data is serialised into a packet and transmitted back to the initiator service requirement’s provider.

By default, the component type is configured as follows:

The timeout for accessing locked sections is set to 0.5 seconds.
The timeout for asynchronous AMS operations is set to 0.5 seconds.
The timeout for asynchronous PS operations is set to 0.5 seconds.
It can issue up to 8 receive transactions to the initiator service requirement’s provider at one time.
It can issue up to 8 transmit transactions to the initiator service requirement’s provider at one time.
It can issue up to 8 AMS request operations at one time.
It can issue up to 8 AMS send operations at one time.
It will not attempt to reissue AMS request or send operations if no transactions are available during its first attempt.
If retries are enabled (they are disabled by default), it will use a default wait time of 2 milliseconds between attempting to reissue AMS request or send operations.

These settings can be overridden at build time by redefining the relevant symbols from AMSTargetPS_config.h in your deployment instance’s lib_config/meson.build file.

This component type has no initialisation data.

2.5. `PUSCore`

The PUSCore component type implements the CCSDS PUS Protocol for TC and TM packets. PUSCore and PUSAMS together provide a PUS-compatible alternative to the above AMSTargetPS component type.

When a PUS packet is received from the pusPacket service requirement’s provider, the component type validates the packet, and if valid, extracts the payload and transmits it to the dataPacket service provision’s consumer that corresponds to the service type specified in the PUS packet’s header. If the header specifies that acknowledgements must be provided, the component type also transmits a PUS acknowledgement packet to the pusPacket service requirement’s provider.

When a packet is received from the dataPacket service provision’s consumer, the component type encapsulates the packet within a PUS packet data structure, sets the field values accordingly, and transmits the resultant packet to the pusPacket service requirement’s provider.

By default, the component type is configured as follows:

It’s dataPacket service provision can be connected to a maximum of 8 different consumers, facilitating support for up to 8 different PUS services.
It can process PUS packets with a payload size of up to 512 bytes.
It can process up to 10 transmit transactions issued by the dataPacket service provision’s consumer at one time.
It can issue up to 8 transmit transactions to the pusPacket service requirement’s provider at one time.
It can process up to 10 receive transactions issued by the dataPacket service provision’s consumer at one time.
It can issue up to 8 receive transactions to the pusPacket service requirement’s provider at one time.
It can issue up to 4 acknowledgement transactions to the pusPacket service requirement’s provider at one time.
The size of acknowledgement status codes is set to 4 bytes.
The timeout for accessing locked sections is set to 0.1 seconds.

These settings can be overridden at build time by redefining the relevant symbols from PUSCore_config.h in your deployment instance’s lib_config/meson.build file.

The following initialisation data must be specified by the user when the component type is instantiated.

The PUS version the component instance must implement.
The APID corresponding to this process.
The destination ID to apply to TM packets (only required if implementing PUS-C).
The transaction timeout to use when sending PUS acknowledgement packets.
A description of each PUS service that the dataPacket service provision supports.
The number of PUS services that the dataPacket service provision supports.
The timestamp format to apply to TM packets.

2.6. `PUSAMS`

The PUSAMS component type is designed to be used in combination with the PUSCore component type. It is responsible for handling PUS requests made to sub-services used to transport AMS requests.

When a request is received from the pusReceive service requirement’s provider, the component type validates the request, and if valid, converts it into an equivalent AMS request. It then issues the AMS request in blocking fashion to the target service requirement’s provider.

When the request is complete, the component type transmits an acknowledgement packet to the pusReceive service requirement’s provider to indicate the status of the request. If the request contains response data, it also transmits a packet containing the response data to the pusSend service requirement’s provider.

By default, the component type is configured as follows:

It can process requests which are up to 246 bytes in length.
It can transmit responses which are up to 246 bytes in length.
It can process up to 4 requests at one time.
The timeout for accessing locked sections is set to 0.5 seconds.

These settings can be overridden at build time by redefining the relevant symbols from PUSAMS_config.h in your deployment instance’s lib_config/meson.build file.

The following initialisation data must be specified by the user when the component type is instantiated.

The timeout to use when initiating AMS requests.
The timeout to use when transmitting responses.

2.7. `PASTarget`

The PASTarget component type acts as a proxy target for interacting with component instances' parameters within a deployment instance.

When an AMS request is received from the remote service provision’s consumer, the component type deserialises the request, validates the contents, and if valid, issues the contained PAS request to the relevant proxy service requirement’s provider. This is done synchronously in the context of the AMS request handler.

By default, the component type is configured as follows:

The timeout for accessing locked sections is set to 0.5 seconds.

These settings can be overridden at build time by redefining the relevant symbols from PASTarget_config.h in your deployment instance’s lib_config/meson.build file.

The following initialisation data must be specified by the user when the component type is instantiated.

A boolean value indicating whether or not to omit parameter time fields (this is only included for compatibility with legacy systems, it is usually expected to be false).
A buffer for storing parameter values.
The size of the buffer for storing parameter values.

2.8. `AASTarget`

The AASTarget component type acts as a proxy target for interacting with component instances' actions within a deployment instance.

When an AMS request is received from the remote service provision’s consumer, the component type deserialises the request, validates the contents, and if valid, issues the contained AAS request to the relevant proxy service requirement’s provider. This is done synchronously in the context of the AMS request handler.

By default, the component type is configured as follows:

The timeout for accessing locked sections is set to 5 seoncds.

These settings can be overridden at build time by redefining the relevant symbols from AASTarget_config.h in your deployment instance’s lib_config/meson.build file.

This component type has no initialisation data.

2.9. `AMSInitiatorPS`

The AMSInitiatorPS component type serialises AMS operations into packets, transmits them to their designated target, then deserialises any data received in response. It fulfils an inverse role to the AMSTargetPS component type described earlier.

When an AMS operation is received from the target service provision’s consumer, it is serialised into a packet then transmitted asynchronously to the serviceInitiator service requirement’s provider. A state machine then handles whether to wait for a response packet or not.

When a packet is received from the serviceInitiator service requirement’s provider, the component type processes the packet and determines whether it is in response to an earlier request. If it is, the response is validated, and if valid, is used to complete the AMS operation that it corresponds to.

By default, the component type is configured as follows:

The timeout for accessing locked sections is set to 0.5 seconds.
It can issue up to 8 receive transactions to the serviceInitiator service requirement’s provider at one time.
It can issue up to 8 transmit transactions to the serviceInitiator service requirement’s provider at one time.

These settings can be overridden at build time by redefining the relevant symbols from AMSInitiatorPS.h in your deployment instance’s lib_config/meson.build file.

This component type has no initialisation data.

2.10. `EDSInitiator`

The EDSInitiator component type acts as a proxy initiator for sending EDS event messages to a remote system using AMS.

When an event message is received from its proxy service subscription, the component type serialises the message into an AMS send operation then issues it to the remote service requirement’s provider. This is done synchronously in the context of the message reception.

By default, the component type is configured as follows:

The timeout for accessing locked sections is set to 5 seconds.
The timeout for issuing AMS send operations is set to 1 second.

These settings can be overridden at build time by redefining the relevant symbols from ESDInitiator_config.h in your deployment instance’s lib_config/meson.build file.

The following initialisation data must be specified by the user when the component type is instantiated.

The timeout to use for AMS send operation timeouts, or zero for the component type’s default.

3. Helix Lab Compatibility

Helix Lab, the ground software included with Flightkit, is currently compatible with a single, non-configurable communications stack.

The diagram above shows how this protocol stack is constructed from some of the above component types. Each block represents an instance of the named component type. The connections between them illustrate how each component instances' service requirements are being fulfilled by other component instances' service provisions.

When a request is made from the ground, it is encapsulated using the same protocol layers as those running on the deployment instance prior to transmission over the communication link.

When the request is received by the deployment instance, each protocol layer performs their respective processing on the packet. At the top of the stack actions are invoked by AAS invoke operations, and parameters are accessed by various PAS operations.

Responses to these operations are then passed down each layer of the stack until one or more frames are formed for transmission back to the ground via the communication link.

As you can see, AAS, PAS and EDS service operations are routed by the SpacePacket component instance according to their application process IDs. In order for your deployment instance to be compatible with Helix Lab, you must configure your SpacePacket component instance to use the same APID values for each corresponding service operation, as those used by Helix Lab:

Channel usage	`SpacePacket` APID
PAS requests and responses	2
AAS requests and responses	3
EDS messages	7

4. PUS-based Configuration

The diagram above shows a similar protocol stack which makes use of the PUS component types described above - PUSCore and PUSAMS.

Note that PUS-based protocol stacks are currently not compatible with Helix Lab.

Flightkit Communication Protocols Reference

1. Overview

2. Component Types

2.1. TCPServer

2.2. PacketStream

2.3. SpacePacket

2.4. AMSTargetPS

2.5. PUSCore

2.6. PUSAMS

2.7. PASTarget

2.8. AASTarget

2.9. AMSInitiatorPS

2.10. EDSInitiator

3. Helix Lab Compatibility

4. PUS-based Configuration

2.1. `TCPServer`

2.2. `PacketStream`

2.3. `SpacePacket`

2.4. `AMSTargetPS`

2.5. `PUSCore`

2.6. `PUSAMS`

2.7. `PASTarget`

2.8. `AASTarget`

2.9. `AMSInitiatorPS`

2.10. `EDSInitiator`