ARES Software Design Document

ARES operates as a decentralized network of nodes on computers. Normally there is a single node on any given machine but a machine can support multiple nodes as needed.

Key security-related ARES concepts:

ARES relies on physical computer and operating system security. Computers with nodes that include command capability (see Network/Message Security) or nodes with sensitive data should be operated in a secure facility. What "secure facility" means depends on the sensitivity of the node data and operations.

Access to ARES should be managed by the operating system, specifically the account permissions system. To launch ARES nodes, only read permission on the $ARES directory is needed, but the launching account will need read/write permission on the data directory.

Secure facility logs (if available) and OS account usage logs can be used to track ARES usage.

Normally, a node runs on a single computer. This node is launched from a single user account that has been configured as per the installation instructions. This includes having AWS keys in ~/.aws and appropriate AES keys in the ARES key file that supports the node operations (for example the DATA key for data nodes and the DATA/COMMAND/PAYLOAD/SENSITIVE keys for a full remote node such as a CubeSat). The same account is used to attach to the node, accessing data files, and sending commands. However, it can useful to use separate individual accounts for using this node. Individual user accounts access a common $ARES root but have their own copies of AWS keys and, more importantly, specific AES keys their their command role in their own ARES key file (for example only CubeSat controllers would have the COMMAND key on a ground station node). Under these conditions, a single ARES owner account is created, set with the AES keys needed to launch the node, and used to launch the node. A group is created to provide access to the $ARES directory (g=rwx,o-rwx) Then individual user accounts with different roles are added to the group. Use of separate accounts can be useful in monitoring (via OS log files) who are running the user-interface, launching nodes, and/or accessing the data.

As messaging is a key component of ARES, providing the method for passing data between nodes, ARES includes a set of encryption capabilities to:

By creating different encryption keys and limiting which nodes have which keys, one can control which nodes can do what. A prime example of this is using one of the keys to control which nodes can command a remote platform (for example which ground nodes can command a satellite). Image Network/Message Security Example shows an example of using encryption keys to control node capabilities.

To handle different message encryption and ensure valid messages are used, ARES supports a "Message Security Class". Each message created is tagged with a security class.

Message security classes:

Each security class has a corresponding AES encryption key stored in ARES key file (~/.ares/data.bin) and managed by the ARESMgrUI.py script. Overall encryption can be turned on/off via the MESSAGE_ENCRYPTION keywork in ARESconfig.toml. If MESSAGE_ENCRYPTION is set to True:

Message encryption/decryption:

The basic process for sending a message:

The basic process for receiving a message:

Most checks for message security class is normally done in the handle_incoming_app_messages method of apps. It’s at this point, incoming messages that do not meet the correct message security class are rejected. For example, ACSApp rejects command messages such as reboot if the message is not a COMMAND security class. Additional checks can be done in various message handlers. Message handlers are the methods that actually do something with the message.

AES keys are managed and stored via the ARESMgrUI.py script. The script allows on to generate AES keys and to store AES keys:

The next step is to install ARES from the ARES Gitlab repository. Before proceeding, please review the Using ARES section to setup overall mission requirements.

Once the mission has been set up, mission users can install ARES from the GitLab repository.

Cloning the ARES project handles most of the file setup requirements but there are few additional steps needed:

The ARESUI provides several functions - most of which are clear from the interface. There are several specific concepts/functions that are worth highlighting:

DASH-Based Webpages - In addition to the command line interface, one can create specialized scripts for accessing/viewing data. AMScUI.py offers an example of DASH-based webpage interfaces. These interfaces launch from the command-line interface but display data in a local webpage (i.e. one only accessable on the local platform) AMScUI provides an 'xl' command that launches a log file webpage and an 'xt' command that launches a telemetry webpage.

To help in managing nodes interfaces, nodes are given "node types". Each node may have one or more node types although it is not required. Node Types are used by the various user interface tools to filter and present appropriate options for the node. For example, a base station node may have various commands that it can send to other nodes/apps. An APS-based node may include commands related to accessing synced memory data. A node’s node type is defined in the <_node_type_field, Node Type>> field of the node’s MCP app in ARESAddresses.csv.

In addition, some apps may also have an app_type that allows the user interfaces to limit options to only sending commands to specific app types. A app’s node app_type is defined in the Node Type field of the app in ARESAddresses.csv. The Node Type Field for a given app may have multiple node/app types. Multiple node/app types are seperated by a bar (|). For example a node field might be 'BS|ME'.

ACSPlatforms.py includes a set of pre-defined node types along with a text description:

In addition, ARES supports several pre-defined app_types: * 'RZC' - Remote node MCP app (ZC) * 'RRU' - Remote node UHF Radio Link App * 'GRU' - Ground node UHF Radio Link App * 'RIR' - Remote node Iridium Radio Link App * 'RCM' - Remote node commercial radio network link app * 'RAD' - Remote node ADCS App * 'PYL' - Remote node payload App * 'PRF' - Remote node payload RF sensor App * 'PRO' - Remote node payload Omni-Directional RF sensor App * 'PRD' - Remote node payload Directional RF sensor App * 'PCM' - Remote node payload camera sensor App

Missions may find ARESUI.py sufficient but they may require additional data access, visualization, and command capabilities. There are three ways missions can extend UI capabilities:

To view a KML file:

You can control the time range viewed by using the time widget in the upper left corner of the earth display.

Since APS memory CSV files have location, they can be viewed and manipulated in GIS tools such as QGIS.

For example, to load into QGIS, follow https://www.qgistutorials.com/en/docs/importing_spreadsheets_csv.html.

A mission’s node/app configuration is found in an address table found in $ARES/config/ARESAddresses.csv. This CSV file is a comma separated key-value structure with most of the lines defined apps.

This is a CSV file listing a set of app configuration data. The address tables contains either key-value sets, a comment (starts with #), or an app description. The app description line contains a set of fields that corresponds to ACSApp arguments.

The ARESConfig.toml file holds ARES configuration data. Configuration data is a dictionary with keywords and values stored in TOML format (https://github.com/toml-lang/toml) - basically a key=value text format with the addition of tables.

Keys are a simple text string. Values can be string (in quotes), integer, float, or arrays (must be of the same type).

In addition to key-value sets, the ARES config file can contain tables. Tables (headed by [TableName] consists of a set of key-value pairs (or nested subtables). ARES Config uses tables for defining sets of values.

The configuration data is built from several possible files:

where app key, values are used in reverse order, i.e mission_name values take precedence over default values, node_address values take precedence over both default and mission values, and app_address values take precedence over all others.

If SIMULATE_ADCS is set to true, the location/orientation is simulated.

An example of simulating ADCS is found in AMScAppSCAD. AMScAppSCAD simulates using a TLE id found in the ARESAddresses path field. It simulations location using a this TLE and a simple spacecraft roll model. To simulate the spacecraft, several values are taken from the AppData field of the ADCS app entry in $ARES/config/ARESAddresses.csv. The field should contain a bar separated list of:

Example AppData field: 52118|0.0|0.0|5.0

Iridium and UHF radios can be simulated using an ACS Message Hub channel. Link operation is defined by the SIMULATE keyword:

Simulated links can be limited to a contact range. The contact range is defined in the $ARES/resources/sim/sim_uhf.csv or $ARES/resources/sim/sim_iridium.csv files. The files contain a list of:

The simulated link is considered open when the platform is within the given range from the receiver.

RF sources can be simulated to be used by the APS RF sensor. The simulated sources are stored in $ARES/resources/sim/sim_rf_sources.csv. The files contain a list of:

ARES testing assume (really requires) the use of:

ARES provides the following unit test scripts:

These call the following python "unittest" modules. You can directly execute these via the command:

To run unit testing:

The distributed nature of ARES makes higher level automated testing complicated. It is often far easier to run various networks and manually monitor the results and/or analyze the base station log, telemetry, and memory results.

One of the app arguments is "reset". This clears various app data including:

If the app is an MCP, it also:

Apps are created and managed by the MCP app. Below is a typical setup in an MCP app:

ACS operations is handled by a combination of the ACSApp base case, specific apps, ACSInterface class and an ACS communications manager (ACSAppZM). In addition, some nodes also include special link apps that handle communciations across non-internet based links such as a radio. ACS is handled with two apps on each node - an ACS Management App (ACSAppZM) and some form of node link app (typically a radio link). In the diagram below, it shows a ground station management app and a remote node ACS management app. Other apps interface to the ACS via an instantiation of the ACSInterface class.

Apps can run independently or dependently. Independent apps are started from a command line or IDE and run until halted. Dependent apps are child processes of independent apps. The are started, controlled, and halted by the parent app. Node MCP apps are an example of an independent app. Other node apps are usually dependent apps and are controlled by the MCP.

Dependent apps can be controlled in several ways:

Parent apps can control the operations of a child app using a couple of patterns:

Dependent apps support the following states:

Dependent apps can be commanded to:

Apps are commanded using shared pool flags:

Apps are share their state with the shared data pool value:

The base class for ACS Apps is ACSApp.py. The basic idea is that a specific mission would create a child app from this ACSApp base app. The basic flow is show below (Italicized methods are overridden methods for child apps):

Run

ACSLORI provides a general set of classes for handling location and orientation data in:

ACSLORI includes:

ARES also includes NASA’s NAIF SPICE Library (https://naif.jpl.nasa.gov/naif/) accessed via Andrew Annex’s SpiceyPy python interface (https://spiceypy.readthedocs.io/en/main/). This powerful library provides methods for computing a wide range of data about astrodynamics and spacecraft. Examples include using SPICE to compute the location of a spacecraft in orbit or the location of the sun relative to a location on the earth. SPICE is based on a set of "Kernels" which define spacecraft, space objects (such as planets), and time information. SPICE kernels necessary for ARES is found in $ARES/resources/spice_kernels. ARES wraps many of the SPICE library function in ACSSpice.py which includes management of the SPICE kernels necessary for computing spacecraft data. An instantiation of ACSSpice (and NASA NAIF SPICE) is found in ACSInterface allowing users to access SPICE without worrying about managing kernels.

See the message table.

Most messages involved some form of "acknowledgement" to let the sender know that the message was received and understood.

The are two major exceptions. First is that logd messages do not expect an acknowledgement. Second, if a message is received at a node and then routed (broadcast) to other nodes via the routing table in ARESAddresses, the original node receiver acknowledges the message but the nodes subsequently receiving the messages do not. This generally works as routing nodes usually involved a special link like a radio link while the subsequent nodes are linked to the original node are over the internet which increases the reliability.

Finally, most messages have a way for the sender to know there was a failure to receive a message - normally a timeout of not receiving the acknowledgement message. This usually results in a retransmission of the message.

Messages can have one 4 priorities. Higher priorities messages should generally arrive sooner than lower priority messages.

Note, acknowledgement messages typically have the same priority as the original message.

Data on board a remote platform is often critical to remote platform operations and may be subject to environment or other errors (for example, radiation errors on a spacecraft).Although the probabilities are low, messages and shared data values can experience errors. To prevent bad data from being passed around, the ACS uses checksums on all data files, messages, and shared data values. ACS also uses a "double-buffered" system that stores and passes two copies of all data files, messages, and shared data. This significantly reduces the chance of bad data being passed between apps. But it does raise the question of how to handle cases of bad data being detected. Therefore, ACS cannot guarantee message delivery. If both copies of a message or shared data value are determined to be corrupted, the message or shared data value is not delivered. In addition, messages passed between nodes (i.e. between a remote node and a ground node) are subjected to even more errors due to transmission errors. These errors are address through a combination of send/acknowledgement, checksums, and, in the case of file transfers, MD5 checksums.

In summary, ACS takes many steps to improve both delivery and integrity:

Each message may contain a specific "app-command". The command is used by apps to interpret what to do with a message. The app command consists of 2 upper-case alphanumeric characters (A-Z, 0-9).

Files may be sent from one app to another app by calling the appropriate SCSInterface method. Once the file has been received on the target apps node, a message will be sent to the target app that the file is available. Note:

Every app has places ways to "log" message strings:

Logging support three types of log messages:

Inter-node messages may be encrypted to improve message security. (See Network/Message Security for a discussion of ARES security and the use of encryption keys.

The effective message length:

Messages are defined in ACSMessage.py. The message consists of a block of bytes as defined in ACSOnlyBase.py. Most message fields are fixed but a few are variable length. In such cases, the variable length field is a '|' separated string.

Figure 9 - Internal Messenger Communications

ARES is primarily programmed in python and consists of a single unified code-base. Although python has several advantages (particularly for work with engineering-oriented student projects) it is an interpreted language. As such, access to the ARES platforms allows a person to get complete access to the code. Additionally, account and key data is stored on the platform. Althougth the account and key data is scambled to prevent easy reading of the keys, access to the code provides the tools to descamble the key data. All of these elements means that ARES security is dependent on controlling access to the platforms.

Ground Control Nodes (i.e. nodes that send commands to remote platforms such as spacecraft) can have: a 'Command Confirmation Code'. This code is then required to be entered when sending a command. The code is stored in the ARES Keychain and set/updated via ARESMgrUI.py.

The network topography is the layout of nodes/apps and how they connect. The network topography is normally defined by the ARESAddresses file (see ARES Addresses). This file defines all the apps in each node in the network along with the app address and app parameters.

In general, ARES is designed with a standard network topography. All nodes are assumed to have the same topography defined in the ARESAddresses file (specifically the node addresses, modules, node types, and various apps-specific forwarding and control data for link apps).

There are some points that mission should consider:

The ACS Message Hub provides an easy way to pass messages between nodes connected to the internet

The message hub consists of a set of 'queues', one for each node in the network. Normally, the ACS manager app on a node takes messages addressed to apps on another node from the local queue and places them in the appropriate queue. For example, a message addressed to GRZC would be placed in the GR queue. On the GR node, the GR ACS manager app would take the message from the GR queue and place it into the local queue to be read by the addressed GR app.

In most cases, the only app on a node that sends messages via the ACS Message Hub is the ACS Manager App. However, ACSInterface will sometimes bypass the ACS Manager App and directly send a message to improve efficiency. Apps using the ACS Message Hub should have a 't' in MessageHub field in $ARES/config/ARESAddresses.csv.

The ACS Message Hub is built on-top of Amazon Web Services (AWS) Simple Queue Service (SQS). One can either work with the ARES team and use the ARES servers or setup one’s own servers/services. To use AWS, you will need an AWS account. Best practices have:

Each platform must have the AWS SDK keys installed on the platform in the ~/.aws directory.

The ACS communication manager app (ACSAppZM) implements many of the ACS communication concepts described above, specifically handling:

AMS has several examples of Link Apps.

ACS is designed to transfer messages between nodes using various types of links (see Networks). In most cases, ground systems will transfer messages using the ARES Message Hub. But links are not limited to Internet-based connections (ACS Message Hub). Specialized communication links allow the same message-based communications as Internet-based communications. Specialized communication links can range from serial ports between processors on the same platform to radio links (UHF, etc.) to non-internet global networks such as Iridium or Globalstar. Such specialized communication links are handled by Link Apps.

ACS Nodes can "route" messages to other nodes. This allows a message to be sent to one node and have it automatically duplicated and sent on to other nodes. Another way of thinking of this is that ACS nodes can "broadcast" messages. This can be useful for minimizing messages across special links or modifying the network topography without sending an updated ARESAddresses.csv file to every node in the system. Messages can be sent to a known node, that node can route those messages to other nodes based on it’s own ARESAddresses.csv file. These additional nodes need not be in the original senders ARESAddresses.csv file.

To route messages, one needs a dedicated routing node with a set of routing apps:

Messages are routed by sending a message to the routing app address. For example one can route messages from XXApp to YYApp and ZZApp by sending the message to the routing node’s RRApp where the app has YYApp and ZZApp in it’s routing table.

To illustrate the use of links and routing, imagine a scenerio with multiple spacecraft (nodes S1 through S8), a single ground radio node (GR), and a set of ground control/analysis stations (GS, GP, and BA). The spacecraft communicate with each other (via the ground radio node) and with all the ground nodes. All ground nodes receive all log and telemetry data from the spacecraft. All communication with the spacecraft go through a commercial radio network (such as ViaSat). The network provides interfaces with the spacecraft via an APS/Special Hardware and with external ground systems via an API.

This scenario involves both links with link forward settings in ARESAddresses.csv and forwarding with a forwarding table in ARESAddresses.csv. Example from ARESAddresses.csv:

With this ARESAddresses.csv file, messages are routed via the link forward list and the route table. The link forward list handles uplink and downlink messages to/from the spacecraft. The route table allows the GR node to take single messages from spacecraft or ground nodes and broadcast them to the nodes in the route table. This allows a single message to be send from a spacecraft but arrive at multiple ground stations, thus saving precious radio bandwidth. In addition, additional ground nodes may be added by just updating the ARESAddresses.csv file on the ground radio node and spacecraft downlink messages will be routed to these additional ground nodes without having to update the spacecraft with new ARESAddresses.csv tables.

APS provides the following base classes:

APS provides the following self-contained support modules:

*

In addition, ACS provides the following pre-defined reasoners:

*

Finally, APS provides some examples:

All APS packages named APSv…​ are for internal APS and ARESUI use only.

The APS App is the main APS software component. It consists of a set of Python files including the primary file - APSApp.py. The APS App can be started via:

The APS can be terminated by the mission through a command file or a termination message (details of the termination message is host/mission dependent). The APS App can also be used to run a single instance of APS on a local computer.

APS Session Manager (part of APS App) is the primary control manager for running the APS framework and reasoners. It is called by all instances of the APS app.

Basically, the APS Session Manager consists of a single loop that runs from the start of a session until termination. Each loop is called a step. During each step, it checks for updates from the APS ground station, reads sensor data either directory or through a mission-specific data frame file, executes selected reasoners, evaluates the results, triggers any mission-specific actions, generates reasoner state files (for use in the next session), and generates a file to be sent to the GS at the end of an ARES session.

The core of the APS Session Manager is a set of “Reasoners” or “experiments”. Each Reasoner can be thought of as an experiment or thought process and has specific input, action, learning, and output controls. Each Reasoner is identified by a type name and a configuration id. The Reasoner uses a host platform-specific sensor suite and consists of a sensor data handler that maps inputs from the sensor suit, a reasoning core or engine that takes the inputs and reasons on them, and an action handler that takes the reasoning core results and performs any needed actions.

Key notes:

The APS framework provides a high-level memory subsystem. APS Memory is based on a SQL relational database. This subsystem can be used to store information between:

The core of the APS Memory Subsystem is an entity-relation model. Entities are basic items such as:

Relations tie these entity record together in a web of connections. Relations can link entity records of different types.

The key modules include:

In addition to the normal ACS clocks, APS supports the following clocks:

APSSensors supports platform location/orientation data obtained from a variety of sources including simualted locations and LORI data posted by the "flight software" via ACSPlatformState.py record.

Some sensors can be fired via the Task Scheduling component. Setting the sensor’s AUTOCAPTURE_RATE ARESConfig key value to 0 will mean that the sensor will only fire via the task scheduling component.

The APS Sensors configuration table defines the available sensors, their source, and their basic configuration. The configuration is from a table in the ARESConfig.toml file, referenced in the ARESAddresses entry for the APS Instance

ARESConfig.toml file contains a set of sensor tables. Each table is names APS_SENSORS_name where name is the ARESSensorSuite field of ARESAddresses for a given app.

The ARESConfig.toml file can contain multiple sensor configurations. Each configuration is a table named 'APS_SENSORS_ sensor_configuration_name'. For example, the sensor suite name is DESKTOP and the config file table is named APS_SENSORS_DESKTOP:

AEON uses the standard APS RF sensor component.

The RF sensors (Software Defined Radios) are used to measure the power (dB) of radio signals. See the AEON SDD for more information about radio signals.

The baseline APS RF Sensor is an standard Software Defined Radio accessible via the PYRTLSDR library.

The general process for reading power at a given frequency:

RF sensors are either:

[2] RF - ARES supports up to two RF sensors. The RF keyword can be 'RF_0', or 'RF_1' to support multiple RF sensors

The RF sensor module (AEONSensorRF) generates two types of data:

Action Field (THE ACTION FIELD MUST BE LESS THAN 80 CHARACTERS):

AEON includes a camera sensor via AEONSensorTypeCamera.py. The camera sensor supports a variety of input sources including movies, directory of images, Open-CV camera, and Pi camera (as of V4.0 - ARES support the Libcamera-based V2 camera - older legacy camera support defaults to Open-CV). Most desktop cameras are supported via Open-CV. Additional, specialized camera may require a subclass of AEONSensorTypeCamera.py.

The Camera Sensor can generate: