F Prime Layout (FPL)

This repository contains tools for laying out and visualizing topologies in the F Prime flight software framework. It is designed to work as a preprocessor for the visualization tool being developed here.

Requirements

• A Unix environment, such as Linux, Mac OS, or the Windows Subsystem for Linux.

• The Simple Build Tool (sbt) for Scala.

Note: pre-built packages are available through PIP.

Installation

To install in the bin directory, run ./install. To install to a different directory, run ./install dir-name.

Once you have installed the FPL tools to a directory FPL_INSTALL_DIR, you can put FPL_INSTALL_DIR in your shell path. For example, in bash:

Note: most users will install via the published native PIP packages.

% export FPL_INSTALL_DIR=[path-to-fpl-install-dir]
% export PATH=$PATH:$FPL_INSTALL_DIR

That way you can run the tools from anywhere.

Tools

The following tools are available.

fpl-extract-xml

This tool extracts subtopologies from F Prime topology XML files. In general, laying out an entire F Prime topology as a single graph does not produce good results; the resulting layout is too complex to be useful. This tool lets you partition a complete topology into smaller subtopologies, so you can lay out each of those. For example, you can have one topology for registering commands, another for sending commands, another for emitting telemetry channels, etc. See examples/ref for an example based on the Ref topology from the F Prime distribution.

fpl-extract-xml reads one or files named as arguments; or, if there are no arguments, it reads from standard input. It writes to zero or more XML files.

When reading input, the tool looks for named blocks of connections delimited by XML comments @FPL START and @FPL END. Each block is written to a separate XML file, with the file name specified in the start delimiter. For example, suppose the file RefTopologyAppAi.xml is annotated like this, where the ellipses represent lines of XML:

... other XML ...
<!-- @FPL START CmdReg -->
... command registration connections ...
<!-- @FPL END -->
... other XML ...

Then you can run the tool like this:

% fpl-extract-xml RefTopologyAppAi.xml

All lines between the delimiters @FPL START CmdReg and @FPL END are wrapped in an XML node named fpl and written to a file CmdReg.xml. The output file will look like this:

<fpl>
... command registration connections ...
</fpl>

Output Directory

You can provide an output directory with the -d option, like this:

% mkdir dir
% fpl-extract-xml -d dir RefTopologyAppAi.xml

In this case all lines between @FPL START CmdReg and @FPL END are written to dir/CmdReg.xml.

Non-Contiguous Blocks

The named blocks need not be contiguous. For example, you can start and end a block named CmdReg and then start and end another block named CmdReg. All connections in blocks named CmdReg will be concatenated and written to the file CmdReg.xml.

For example, this input

... other XML ...
<!-- @FPL START CmdReg -->
... command registration connections ...
<!-- @FPL END -->
... other XML ...
<!-- @FPL START CmdReg -->
... more command registration connections ...
<!-- @FPL END -->
... other XML ...

produces this output:

<fpl>
... command registration connections ...
... more command registration connections ...
</fpl>

fpl-convert-xml

This tool converts XML subtopologies generated by fpl-extract-xml into the FPL topology format used by fpl-layout. It reads a single XML file named on the command line and writes standard output. For example:

fpl-convert-xml CmdReg.xml > CmdReg.txt

fpl-layout

This tool reads an FPL topology, constructs a layout, and writes the layout as a JSON file. It reads standard input and writes standard output. For example:

fpl-layout < CmdReg.txt > CmdReg.json

You can export the JSON file to the visualization tool available here.

fpl-write-pic

This tool reads an FPL topology, constructs a layout, and writes the layout as a file that can be rendered by the pic drawing utility. For example:

fpl-write-pic < CmdReg.txt > CmdReg.t

By convention pic files end in .t because they were originally troff files on Unix. To use pic, you must have GNU troff (Groff) installed on your system.

fpl-write-eps

This tool reads an FPL topology, constructs a layout, and renders it as an EPS (encapsulated PostScript) file. For example:

fpl-write-eps < CmdReg.txt > CmdReg.eps

fpl-write-eps is a wrapper script that calls fpl-write-pic, pic, groff, and ps2eps. To use this tool, you must have Groff and ps2eps installed on your system.

Examples

See the examples directory.

Data Formats and Implementation Notes

See the wiki.

Testing

Run ./test to run all integration tests. Do this after running ./install. If you update the build, rerun ./install before running ./test.

Development

1. Start up the sbt shell.

2. In the shell, run compile to compile everything and assembly to create jar files. The install script runs these commands automatically. It also moves the jar files to the install directory and puts executable shell scripts there.

Cleaning

To clean the repository, run ./clean in this directory. This will run sbt clean and delete generated build and test artifacts.