User Manual: GenerationOne FSDK

The interface to a component takes the form of actions and parameters. Unusual conditions arising when attempting to use an action or parameter give rise to exceptions; to indicate unusual conditions which occur asynchronously to these operations, components may also issue events.

During the development of the software, a high-level description of the interface to each software component is held in a simple model. When an software image is built this information is used by the tooling to generate a spacecraft database (SCDB) describing all of the actions, parameters, exceptions and events for the spacecraft, including their numeric IDs. The spacecraft database can be exported in a number of forms including a spreadsheet and HTML documentation.

To permit the storage of data, such as telemetry, received telecommands or onboard events, the onboard mass memory of the spacecraft is organised in to a number of storage channels. Each channel has a unique channel number and a fixed capacity which is configured when the software is built.

Each channel stores data in rows of uniform length. The length of each row in a channel can be set at any time by formatting the channel. For example, when a data channel is assigned to hold the event log, it will be formatted to store rows of data that are 12 bytes in length (this is the size of a single event plus a time stamp).

Each data channel can be configured to be circular or linear. When a linear channel is full, further attempts to add data to it will fail; when a circular channel is full, the oldest row will be deleted to make way for each new row added. The decision to make a channel linear or circular can be made when the channel is formatted.

Perhaps the most important function of onboard software is the gathering, logging, reporting and monitoring of telemetry. The GenerationOne FSDK provides a number of components, each carrying out one part of the data handling system. These components can be added to a software image and connected together in different ways to suit different missions.

A number of components are provided to allow autonomous operation of many aspects of the software and spacecraft hardware.

The main functions of a system built from our onboard software, including most of those described in the previous section, are provided by application components. These components rely on three further elements:

These three elements form what we refer to as the framework.

Finally, the system components and libraries of the framework rely on a Platform Support Package (PSP). This is either supplied by us, as part of the FSDK, or by the vendor of the target platform, and contains the basic software routines necessary to access the hardware. In some cases we may provide modifications or patches to vendor-supplied libraries to help integrate the library with our onboard software architecture.

A high-level depiction of the architecture, showing the relationship between the various elements, is presented in Figure 1.

This architecture is perhaps best illustrated with some examples. Typical application layer components would include:

In order to send telemetry, a TM/TC component would place the necessary data in a buffer and request that it be transferred using, for example, the Packet Service (PS). The service handler for PS will map this request onto, again for example, a system component acting as a protocol handler. This protocol handler will typically package the data into a valid packet and then send this new packet to the communications subsystem component, again using PS. The communications subsystem component will then transfer the data to the actual hardware using PS or the Memory Access Service (MAS). The service handler will map this request onto a system component providing access to the hardware interface to the device, such an onboard communications bus. The actual interface to the bus is typically provided by functions in the PSP. This sequence of interactions forms a communications stack where the interaction between each element of the stack is via a communications service such as PS or MAS. This is shown in Figure 2.

The communications services, PS and MAS, provide a regular interface to the functional services of other components without requiring knowledge of those components. The use of services in this way means that any component in the stack can be replaced without affecting any other component. This allows you to move your software between platforms easily.

A component is simply a collection of functions which are centred around two things:

Our components follow the principles of Object-Oriented Programming (OOP), so parameters are mostly the same as fields or attributes, and actions are mostly the same as methods or routines. Each action is implemented in a single C function. Each parameter is implemented through a number of C functions, called accessors, which provide access to the underlying data. The parameters and actions of a component may be accessed directly, by calling these functions, but they may also be access generically by using an identifier. These identifiers provide a mechanism through which component functionality can be accessed from ground via telecommand.

Every parameter and action in the system is assigned a unique ID, these IDs are mapped onto the action and parameter accessor functions of a component by a simple set of wrapper functions known as the component action source and parameter source respectively. The action and parameter sources translate between ID-based requests and the specific functions of a component. As such, these functions wrap-up access to the component and form part of a component’s container.

A container may also permit access to a component’s functions via a service provider interface, such as a Packet Service provider. This allows the component to be registered with, for example, PS. A request to send a packet using PS, on a specific channel, will then be routed by the PS service handler to a standard interface provided by a component container. This will then invoke an underlying action on the component itself.

As well as providing regular access to a component’s actions and parameters, a container helps manage the life-cycle of a component: component start-up, or initialisation, and component shut-down, or finalisation. A component may also wish to store part of its internal configuration data persistently, to permit the system to return to a previous configuration after a restart. The component’s container will provide functions to ease the handling of his configuration data.

Application and system components are identical, except for the fact that system components do not provide access to actions and parameters via sources.

For example, consider a subsystem component which provides a temperature parameter. As this parameter is read-only (in the absence of, for example, heaters, it makes no sense to be able to modify a subsystem temperature) the component needs to provide a single accessor function called getTemperature. If temperature is accessed directly, getTemperature can be used. If temperature is accessed by ID, the container functions of the parameter source are used to translate the ID-based access into a call to getTemperature. This is shown in Figure 3.

Similarly, an action function, such as send, may be accessed directly, or it may be accessed using an ID, via the action source in the container. The component may also permit access to send using the packet service, in which case another component would invoke a packet service function which accesses the component container which then invokes the component send function. These three cases are shown in Figure 4.

A component which simply responds to requests from other components is known as a passive component. A component may also provide one or more task functions. These are functions which may be attached to, or called called from, a dedicated task. This gives the component its own thread of execution, in which case the component is known as an active component.

When writing the code for a component you are actually creating a component type. This is much like a class in OOP. It provides the template for one or more component instances, in a similar way that a class is the template for one or more objects. To create some executing software it is necessary to instantiate a number of components and connect them together. This is called a deployment.

A deployment specifies:

Deployments are specific to a given platform and contain the initialisation code necessary to get the underlying platform up and running. Once the platform is running, the deployment initialises the component manager which is responsible for managing the life cycle of all components (initialisation, configuration and finalisation) and their attached tasks. The deployment then initialises the various services. The component manager then continues by initialising all components. The initialisation process is broken down into three phases:

Once the components are initialised, the component manager initialises component tasks. Finally, the deployment permits the task library to begin executing tasks and the component-based system springs into life!

The development of any onboard software using the GenerationOne FSDK is likely to follow the same general pattern. Rapid onboard software development, particularly for nano and small satellites, is likely to be collaborative and iterative. We have therefore tried to design the GenerationOne FSDK to support the iterative refinement of onboard software as much as possible.

This process can be repeated as often, and rapidly, as desired for your mission development process.

This section gives an overview of what the different elements are that make up a component. Some of these elements appear in all components, others will appear depending on the design of a specific component.

The following tools are required for building GenerationOne onboard software:

A core part of the FSDK is the code generation tool, codegen, which is used in many different tasks in the FSDK workflow.

codegen is run from the command line, and Java 11 is required to run it.

Java 11 is required to run TMTC Lab. Specifically Java SE 11.0.13 or later is recommended. There are no other requirements for TMTC Lab.

The Python API requires Python version >=3.7. See the HTML Python documentation (GNDSW/python/doc/html/index.html) for installation and usage details.

Our unit testing framework is based the tools Unity and CMock from throwtheswitch.org. We distribute patched versions of these tools under the OBSW/Tools directory.

To extract and install the tools, run the following commands from this location:

GenerationOne now supports source code that is not part of the FSDK directory structure by making use of environment variables referenced in a project’s config file.

This is described in Section 7.1.1.

Open up the Oracle VM VirtualBox Manager and click 'File' → 'Import Appliance…​'. Find and open the .ova file that came with your release. Now click 'Import' and the GenerationOne FSDK VM should appear on your list of virtual machines. Note that you can import the .ova file directly into VirtualBox. The machine is set up as dual-core, for better compatibility, we advise that you adjust the VM’s settings to maximise the resources that it will use.

With the 'GenerationOne' appliance selected, click 'Start' to start the VM. Note that another copy of this manual can be found on the VM’s desktop. Holding the host key (default is right-ctrl) and pressing 'F' will bring the virtual machine full screen, which we find to be easier to work with, especially where the virtual machine is used on a single desktop of multi-desktop host environment. Other functions for use with VirtualBox can be found in it’s documentation.

The login details for the VM are:

User name: gen1-user

Password: BrightAscension

When you start the VM, you should be presented with a basic desktop which contains:

The FSDK is used from the command-line terminal, and is available in the `gen1-user’s home directory.

When building a project for the first time, you need to call make from that project’s directory. For example, to build the app project:

If this is the first time building, make will build all the dependencies. If the dependencies have already been built, it will only build the app project itself.

If changes have been made to a dependency, the following command will force the build system to check for changes to `app’s dependencies to check whether it needs to rebuild them:

Depending on the speed of your workstation these builds can take several minutes.

For further information on the build system it’s possible to bring up help:

This will list the valid build configurations for the library. These specify which OS and board the build will target, and can be used on the command-line like so:

The build system can build and run unit tests as well. The make command will build all unit tests for the library, and these can be run after the command completes.

For example, to run the test for the CSLEPS component, run the following binary:

The test should execute and the last line of the test output should say 'OK'. The line before that gives a summary of the test results. Binary executable files for all unit tests are in the bin subdirectory.

Note that tests include checks that components fail correctly, so there may also be error logs, but this is normal. Look for the Unity output in the console, which should look similar to this:

The build system can also specifically build and run unit tests. To build all tests:

To build and run all tests:

To build a single test, in this case for the CSLEPS component:

To build and run a single test, in this case for the CSLEPS component:

The FSDK source code is commented with extra tags to permit the generation of cross-referenced documentation using Doxygen. You will need to make sure you have Doxygen installed and on your PATH to generate this documentation.

The build system will invoke Doxygen for the application component source tree. HTML documentation will be produced; you can find the output in the doc subdirectory. Doxygen generates a great deal of output; start with the file called index.html.

Equivalent documentation can be generated for any library in the FSDK.

The spacecraft database is used by the TMTCLab ground software to communicate with the deployment we are going to run.

Generating an SCDB requires the use of the codegen tool on the command-line.

Section 5 describes the FSDK’s command line tooling in more detail.

Having built the supporting libraries, you can now build the sample Linux deployment. This is in the demo_linux directory and can be built just as with the libraries:

Note that this command will not build dependencies. To check all the dependencies of a deployment, and build them if needed, run:

In either case, the build script follows the same pattern as before, but this time an executable is generated: bin/linux/demo_linux. This is the deployment, and is ready to be executed.

TMTC Lab is included as part of the FSDK as an executable JAR file. In some environments you may be able to double-click the JAR file to start the software. Otherwise, you may need to start it from the command line:

This should launch the TMTC Lab software and display the main window. The TMTC Lab main window with open Packet Monitor and Transfer is shown in Figure 5. Adding the option -help will provide information on other options that can be used with the software.

When you have finished using TMTC Lab, it’s best if you close it (or at least disconnect) after you stop the deployment from running. If you don’t do it this way round, various resources to do with the connection between the onboard software and TMTC Lab are not properly freed. You would then not be able to start another deployment immediately, rather you would have to wait for a period of time (usually 5-10 minutes) for Linux to detect a time out and free the resources for you.

The TMTC Lab main window contains smaller windows with different functionalities. In a example on the Figure 5 clockwise from top left these are:

Details about TMTCLab functionalities are presented in Section 9.

Before running the demo_linux deployment, make sure that TMTCLab TCP server is running as described in Section 6.3.5.

To run the deployment from the command line simply execute the binary file we built earlier:

The deployment will show various messages showing that it is starting up and configuring various aspects of the system. It will not return so runs indefinitely. You can stop the execution of the deployment using CTRL-C on the command line.

demo_linux uses a TCP client and the initialisation data matches the defaults of TMTC Lab and as such, it should connect successfully.

The TMTC Lab main window can be used to communicate with the deployment. There is an in-depth chapter on TMTC Lab in Section 9. For now, we will cover basic connection and telecommanding.

In order to communicate with the deployment we need to open the SCDB. This is done as follows:

You should be greeted with a window that looks like Figure 6. From here, you can explore the deployment as demonstrated in the image. There are dummy components included in the demo_linux deployment that you can use to get familiar with the interface. If you open the DummySubsys1 tab you will see there’s an action called 'reset' and 3 parameters that hold 8, 16 and 32 bit numbers. If you select the dummyparam8 parameter, you will see it’s signature, ID and a description. There are also Get and Set buttons available. If you click Get, you should see '08' appear in the 'Data' section and also the text 'Parameter accessed successfully' near the bottom. If you change the value to a different number and hit set, you should see the same output text. If you clear the data field and click Get again, it should return the value that you set.

If you now select the 'reset' Action you will see that the interface has changed slightly. Again, you are presented with the signature, ID and a description of the action. You are now able to 'Invoke' an action. Note that there is a disabled argument field; It is here that you would pass in arguments to be used during an invoke. If you click Invoke, the values of the dummySubsys1 component should be reset. You can check this by returning to dummyparam8 and clicking Get, it should return the value '08' again.

TMTC Lab is still running behind the SCDB window, you can minimise it by clicking the icon in the top-right corner. Doing this should reveal that there are now packet logs in the Packet Monitor window. These should mimic the actions that you just under-took while interacting with the deployment. As mentioned in Section 4.2.6, you should only disconnect from the packet service after stopping the deployment when you wish to stop using the TMTC Lab.

For each parameter you can get its value or downlink it. If the parameter is not read only, you can also uplink a value from the file. Progess might be followed in window 'Transfers' opened by clicking one of the buttons on the top. Example of Transacation Window after downlink and uplink is presented in the Figure 7.

The following table lists all available optional arguments along with a brief description of what they do, for more detailed information you can look at the manual provided with GenerationOne by typing man codegen.

The following command will generate a new Component Type xml in a library project:

There are multiple ways of generating existing Component Types. Platform independent Component Types can be generated by specifying the path to the componentType.xml or specifying the project and the fully qualified name of the Component Type.

This example uses the Dummy Component Type present in the app project.

It is also possible to specify that a new Component Type should be platform specific by providing a build configuration along with whether the Component Type is board or operating system specific. The codegen tool will then look up the correct build configuration and extract the architecture information needed to generate. The following example shows how to generate the board specific RTC Component Type.

Services are generated in a similar way to Component Types and are generally platform independent. Similar to Component Types, you can either specify the path to the service.xml or specify the project and the fully qualified name of the Service.

A new library project can also be created using the codegen tooling. New projects should be created in the root of the OBSW/Source directory. The following command will create a new library project called 'my_library'.

Existing library projects can be generated as follows:

A new deployment can also be created using the codegen tooling. New deployments should be created in the root of the OBSW/Source directory. The following command will create a new deployment called 'my_deployment'.

To generate code and documentation, including the Spacecraft Database for an existing deployment:

It is also possible to simply regenerate the Spacecraft Database and documentation for a given deployment by specifying the generate-docs operation.

If a deployment should be generated with a different build configuration to the default specified in the project.mk then you may pass in a different build configuration.

To generate the deployment navigate to the OBSW/Source directory using the terminal, and execute the following codegen command, replacing <name-of-deployment> with your project name:

This should have generated various new files and directories within the inc and src directories. Both directories now contain a deploy directory and an init directory. These are where deployment and initialisation data are handled respectively. There is also a deployment directory generated in src, this file provides the entry point for the deployment stage of the build system. The inc directory and src/deploy directory contain deployment generated code and should not be edited directly as they may accidentally be overwritten if the deployment is regenerated.

As with component generation (discussed in Section 8), there are files that are generated initially which can then be filled out by you. For deployments, these files are the initialisation source files located in src/init. If you change the group that a component instance is in, be sure to remove the old files (as they won’t be deleted) and to move/update the init file.

The next step after generating the deployment is to set up the initialisation data.

There are quite a number of components to initialise, most of which would require a more in depth understanding of the GenerationOne FSDK. To keep things simple for now, we will replace the generated initialisation source with the one from demo_linux. Simply copy and replace from demo_linux/src/init to your deployment project’s equivalent directory.

This should overwrite the duplicate files and leave just the additional dummy component to initialise. Using 'DummySubsys1' as a guide, fill out the initialisation data for 'DummySubsys2'.

With the initialisation data set, you can build and run your deployment.

Before attempting to build the deployment we first need to make sure the project.mk file is configured properly. Since we are building this deployment to run on a linux machine we need to specify this using the VALID_CONFIGS parameter. Assign VALID_CONFIGS the value linux, then save your changes. In addition, you will also want to make sure that the list of dependencies specified by DEPEND_DIRS is correct, according to the components you are including in your deployment. Since our deployment only contains components from the app and framework libraries, we can leave this as is. Once the project.mk file has been updated, we can build the deployment using similar steps to those for building a library (in Section 4.2.1). It should build without any errors. If there are errors, retrace the previous steps.

The Spacecraft Database is used to interact with a deployment using TMTC Lab, as seen in Section 4.2.8. The Spacecraft Database is generated as part of a deployment generation step above, however it is possible to generate only the Spacecraft Database without generating deployment code. This is achieved using the codegen tool. To generate the database standalone navigate to the OBSW/Source directory using the terminal, and execute the following command:

This generates a deployment.scdb file which it places within a directory named doc. This file will be used by TMTCLab to enable interaction with the spacecraft.

The deployment should be using a TCP client and so you’ll need to set the TCP server to connect to, which TMTC Lab can be used for. TMTC Lab can be run by executing the runLab.cmd script in the GNDSW/Source/TMTCLab/ directory. You should be greeted with a pop-up saying 'Connect to onboard software' followed by a TCP port. This is explained further in Section 9.2.3. The default settings should be valid so just click 'Connect'.

Now that the TCP server is running, you can run your deployment and interact with it. Since our deployment is built to run on linux we can simply run it directly from the terminal. To run the deployment navigate to OBSW/Source/<name-of-deployment>/bin/linux and execute the following command:

You should see output in the console similar to below.

In the Debug console window in TMTC Lab (Section 9.1.3.3) you should see that the deployment initialisation was also successful. Additionally, there may be some debug output regarding the deployment overwriting data, this is just the deployment setting up storage channels used by the loggers.

As mentioned previously, we’ll be interacting with the deployment using the generated spacecraft database. There is a section later on (Section 9.1.1) which goes into a more in depth view of using the Mission Explorer and TMTC Lab in general. For now, we’ll look at what we need to interact with the deployment.

When you have finished using TMTC Lab, first disconnect the deployment (by stopping it from running) before disconnecting the packet server ('Connection' → 'Disconnect') to free up the TCP port.

A common requirement of onboard software is to cache parameter data in a data pool. The GenerationOne FSDK provides the DataPool component to do this. A Sampler component is then used to periodically update particular parameters in the data pool. This is discussed in detail in Section 2.1.4.1 and Section 2.1.4.2.

Going back to the deployment.xml file, you should find that the DataPool component already has DummySubsys1 added to it. Add the DummySubsys2 component instance underneath the first one and give it a name to access it with (usually the same name as the instance).

Accessor defines will be generated for each parameter in the data pool. The individual parameters that we want to store in the datapool are specified here. It is possible to omit the parameter field, which will cause the datapool to generate parameters for each corresponding parameter for a component. We don’t want this for the Dummy component, because it’s dummyBuffer parameter has 65535 rows, which is a lot of data to cache, and unnecessary for this demonstration. As well as avoiding particularly large parameters, there may only be a few parameters which need to be pooled.

Another common data handling requirement is to periodically log parameters, through the use of a data logger and also to monitor parameter values, to check that they’re in range. This next tutorial section will take you through how to add a parameter to the base aggregator so that it is logged along with other aggregated data and also how to set up a monitor on a parameter.

We’ll now add to the frame that’s transmitted by the TMBeacon component. The beacon transmits frames with individual periods which are relative to the beacon’s task period. The frame transmitted is the parameter from a separate instance of an aggregator; the BeaconAggregator. As with the BaseAggregator, add in some more parameters from DummySubsys2 that you can use to check.

Taking a look at src/init/cdh/tmtc/TMBeacon_Init.c, you can see that there’s a single frame set up to be sent each period and the parameter transmitted is the BeaconAggregator packed data. With the new parameters added to the BeaconAggregator, you should be able to build and run the deployment.

There is a demonstration deployment for using the Aardvark – demo_aardvark.

The first steps you need to take is to include the aardvark/inc directory into the deployment project. After that, you need to make some additions to the dependencies section of the project.mk file. As well as adding '../aardvark' to the dependencies directories, you need to add 'dl' to the external libraries. This is because the main Aardvark library, Aardvark.so, is loaded dynamically and 'dl' is necessary to support this.

Adding the EPS is similar to how other components are added, you just need to specify that the subsys.csl.CSLEPS component is being used in the Import section and then add an instance to the Deploy section.

After that, you need to specify the service that the EPS will use, which is where the Aardvark comes in.

Note that in the deployment xml, the EPS uses channel 0 of the service that it’s using. The default channel is 0, so this could have been omitted. However, if there were more subsystems on the I²C bus, those could then be linked to incrementing channels.

The channels correlate to the index in the rt_Channels variable in the Aardvark’s init data. Therefore, any future subsystems which are added can be set up with their respective slave address.

If the EPS was deployed on a different platform, for example the Clyde Space Ltd. OBC, the Aardvark I²C Master component can be swapped out for an I²C driver component which is specific to that platform. The channel value for the required service remains the same, making it easier to deploy platform independent components.

One of the uses of the PeriodicAction component is using it’s functionality to service one or more system-wide watchdogs. We’ll demonstrate this by adding the CSLEPS watchdog reset action to the list of actions for the PeriodicAction component instance. This should be simple enough using the other element in the grt_PeriodicActionInitEntries array as a template to get the set up below:

To use the CSLEPS actions, you need to include the relevant header:

Now, once the PeriodicAction instance is enabled, the 3G EPS watchdog will be reset approximately every minute.

There are various configuration store components available in the GenerationOne FSDK, some of which are platform dependent. For this demonstration, the FileConfigStore component can be used to store a persistent configuration. The FileConfigStore component creates files to store component’s configuration, using a provided file system component’s file service which in this demonstration is provided via the POSIX OS. In the initialisation data for the component, it is possible to set the limit for how many different system configurations there can be.

Other configuration store components are available:

The number of system configuration stores available is on a per component instance and so multiple instances of configuration store components is possible, however the ability to do this may be limited by the underlying platform. In addition to multiple instances of the same component type, it’s also possible to mix different types of configuration store components.

The ConfigManager component makes some of the underlying configuration features of the GenerationOne FSDK available to adjust. Through the initialisation data, it’s possible to have configuration initially disabled. This stops individual components from storing their own configuration when their configuration changes. There are also actions that can be used to load and store configurations for either a list of components, or all of the components and these actions are not disabled when configuration is disabled as they’re invoked by the user. These actions use the configuration ID that is specified for each individual component instance.

The default ID is 0, which is equivalent to the default configuration for a component. Configuration 0 cannot be written to (as it is the default configuration) and so does not require a configuration store component. Storing a component’s configuration to configuration 0 will discard the configuration data and succeed, this is equivalent to disabling the configuration storage for that component.

Other IDs can be assigned, assuming that the deployment’s configuration store components can support them. For example, if you have a configuration store component that supports 2 system configurations, then ID 0, ID 1 and ID 2 are all valid, with the latter two being stored.

There is also an action to reset all the components to their default configuration. Invoking this action will not change the current configuration ID for each component.

Additionally, there is an action to erase a specific system configuration. Through the ConfigManager component, it is also possible to query the configuration sizes for each of the components. Those without a configuration will return a size of 0.

Periodic execution lists run periodically, and have their own periodic task which manages the execution list operation. Each time the periodic execution list’s task runs, the execution list code checks the properties of all of the tasks on the list to see if any of them should be executed. The tasks on the execution list do not generate real OS tasks and their associated resources. Instead the task functions are called from the periodic execution list’s own periodic task. This leads to substantial savings in memory footprint.

The priority of the periodic execution list’s task is set to the maximum of all the priorities of the tasks on the list.

The period of the periodic execution list’s task is automatically set to the greatest common divisor of the periods of all periodic tasks which belong to the list. For example a periodic execution list with one task of period 10 seconds and one task of period 8 seconds on it will run every 2 seconds.

Both of these tasks will be run on the first iteration of the periodic execution list’s task. There will then be 3 iterations where neither of the contained tasks are run. On the 4th iteration the 8 second period task will be run, and on the 5th iteration the 10 second period task will be run.

Note that although the periodic execution list’s task may run more frequently than any one task on the list, the tasks on the list are still run with the period specified in the deployment.xml.

Periodic execution lists also support running sporadic tasks in a periodic manner. This is a feature which should be used carefully, but can be very powerful in practice.

When a sporadic task is on a periodic execution list, its task queue is checked EVERY TIME the periodic execution list’s task runs. Returning to the above example, if a sporadic task were placed on the periodic execution list, it would be checked every 2 seconds. If there is an item on the sporadic task’s queue, the sporadic task will be executed.

Periodic execution lists therefore provide a way to convert sporadic behaviour to periodic behaviour. Some key things to note:

Sporadic execution lists run sporadically. Like periodic execution lists, they have their own task which manages the execution of the list, but it is sporadic instead of periodic. The priority of the sporadic execution list’s underlying sporadic task is the maximum of all the priorities of the tasks on the list.

The sporadic execution list’s task is triggered by the task queue of a specific task on the sporadic execution list. By default, the trigger task is the first task on the sporadic execution list, but it may also be explicitly identified using the trigger attribute of the sporadic execution list.

When an item is inserted into the task queue of the trigger task, the sporadic execution list task is executed. This task checks, in order, the task queues of each task on the sporadic execution list. Each task is executed up to N times, where N is the size of that task’s task queue, before moving on to the next task. This allows a task on the list to place multiple items on the next task’s queue, and for the list to behave as expected, while also preventing the possibility of an unterminated task execution.

Care must be taken over the order of the tasks on the sporadic execution list. It is the expectation that each task may trigger execution of the next task on the list (the canonical example being a set of sporadic tasks for managing the data passing up or down a comms stack).

GenerationOne FSDK includes a number of library projects. Some of these are component libraries which are used to bring required components into a deployment. The most prevelant are the framework and app component libraries. These contain a range of components which can be used to build up a basic satellite platform as well as some components for specific hardware.

When creating your own mission, you may need to make components specific to your mission. It’s usually easiest to keep these components separate in their own unique component library.

To create a component library project, navigate to the OBSW/Source directory using the terminal, and execute the following codegen command:

Note that you can also create component libraries (or deployments, for that matter) elsewhere in the filesystem.

To do this, you must first set the GEN1_ROOT environment variable to contain the path to the FSDK’s root before issuing codegen commands. This allows the tooling to use core resource (like build configurations) which are found within the FSDK, even when working outside the FSDK’s directory.

Once you have successfully created a component library, you can then use the codegen tool to create new components to store within it. To create a new component navigate to the OBSW/Source directory using the terminal, and execute the following codegen command:

If you wish for your new component to reside within a particular subdirectory, you can prefix <name-of-component> with a dot separated path indicating where to place it. For example, to place your new component within inc/path/to/component/<name-of-component>, you would execute the following codegen command:

If the component you wish to create is platform dependant, you must specify this within the codegen command using the board specific flag, -b, and you must also specify which platform it is for using the configuration flag, -c, and providing the name of the build configuration for that platform. For example, to create a platform specific component for the <name-of-build-configuration> build configuration, you would execute the following codegen command:

Once you have successfully created your component using the approach described above, you will notice that a componentType.xml file will have been generated and placed within the <name-of-library> project directory. The exact location of it within this directory will depend on whether you specified a particular path, or if you specified for it to be platform specific.

The next step is to define an XML model for your new component using the generated componentType.xml file. XML tags in the component type file specify each of the different parts of the component type. It’s not necessary for any of these to be present, but if they are present the order they appear in is important. In the following outline, comments indicate the required order of tags.

After defining the XML model for your new component, the next step is to generate it. Generating the component creates what we call a component container, which enables the component to be used within a deployment. To generate your new component, navigate to OBSW/Source using the terminal, and execute the following codegen command:

If your component is located at a particular path within the library, remember to prefix <name-of-component> with the appropriate dot notation path. Also if it is platform specific, remember to include the relevant board configuration flags and arguments (see Section 7.1.2).

Some components are more complicated and their instantiations will include setting up connections, services and tasks. The tutorial in Section 8.5.2 goes through an example of a component with a required service and task being deployed.

The demo deployments (such as demo_linux) contain multiple examples of more complex components being deployed such as the communications stack, which involves multiple components which provide the functionality of communication to the flight image.

For simple actions which require no additional information, you only need a name and documentation.

Single value parameters can be:

For example, the following shows a single 10-bit unsigned integer parameter.

Values which can be arranged into multiple rows are contained within a Vector tag and can have the same value type as Scalar Parameters. The maxRows attribute will define the maximum number of rows that the parameter can have, up to 65535. For parameters which have a fixed number of rows, the minRows attribute should match maxRows.

A variable raw parameter is a single value which can change in size. The maxBytes attribute marks the maximum number of bytes the value can be.

It is not possible to create a vector of varaw rows as a parameter can only be variable-length in one dimension.

The defaultBaseId for the exceptions should be a unique value. This is the base from which each exception will receive an incremental value from and should be globally unique and with enough space to account for the number of exceptions that the component provides.

There is a text file included with the software release, gen1/Documentation/exception_base.txt, which lists all current component type exception base IDs. This can be used for guidance in assigning additional base IDs.

The following example shows adding an exception including specifying a base ID.

The defaultBaseId for the events should be a unique value. This is the base from which each event will receive an incremental value from and should be globally unique and with enough space to account for the number of events that the component provides.

There is a text file included with the software release, gen1/Documentation/event_base.txt, which lists all current component type event base IDs. This can be used for guidance in assigning additional base IDs.

The following example shows adding an exception including specifying a base ID.

To allow a component type to emit events it needs an event source. It is possible to have multiple event sources, for example to relate events to functionally independent parts of a component type, but it is more common to have a single event source per-component type.

Component EventSinks allow a component type to listen for raised events from anywhere in the system. It’s possible to have more than one EventSink, but as every raised event is sent to all sinks, normally only one is required.

Periodic tasks will be called periodically. The defaultPeriod specifies how often (in seconds) the task function is called unless a deployment sets a different period.

Sporadic tasks are tasks with a queue associated with it. When that queue has data on it, it will be pulled off the queue and the sporadic task function will be called, passing it the data from the queue. This allows sporadic actions to take place. For example handling data received over a serial bus.

A common example which is used with asynchronous services, such the Packet Service (PS). In these cases a transaction is supplied to a PS function, such as receive, and the function returns immediately. When data is received by the PS provider, the received data is placed into the transaction and the transaction is placed onto the sporadic task queue. This causes the sporadic task to be executed, with the transaction passed to it.

The defaultQueueSize is the size of the transaction queue (in items) associated with the sporadic task. As with the period on periodic tasks, this default value is used unless a new size is specified in the deployment.

An interrupt task is an interrupt service routine which will be called when an interrupt is raised. The component type implementation is responsible for registering the interrupt task with the platform.

Interrupt tasks are normally used by driver components which are typically architecture-specific.

When deploying a component instance whose component type has tasks, those tasks will also need to be deployed.

Some components require specific other components. These are added inside the Required section. Inside that section is the Components tag, where each component that is required can be declared.

Each required component has:

When creating a component instance in a deployment, connections are made for components required by the type.

Using a service synchronously is the simplest approach: each call to the service provider, via the container, will block and only return once the operation has been completed. This is suitable for use with most services, except for when data must be handled asynchronously.

The service requirement should be given a name and then should be specified in the XML as follows.

Here, a requirement to use the io.MAS service is specified, giving it the name bus. Multiple service requirements can be specified within the Required tag.

When the container is generated, a header file of the form ComponentTypeName_ServiceName_package.h will be created containing the prototypes of the service functions which can be called from the component implementation. For example, in the above case, for a component type Example, the file Example_MAS_package.h would be created. The implementation C file, Example.c, can include this header file and call the service functions appropriately.

When using a service asynchronously, calls to the service provider will return immediately, before the operation is complete. Once the operation does, eventually, complete, a sporadic task will be triggered to indicate the completion. This works like a completion callback.

To keep track of the operation a structure known as a transaction is used. The transaction also specifies which sporadic task should be triggered on operation completion by storing a pointer to the relevant task queue (the queue associated with the sporadic task).

Requesting use of a service asynchronously requires the use of the implementation tag, which allows its use to be specified. In most cases where the service shouldn’t default to synchronous, it will instead default to asynchronous. In this case, only the defaultAccess attribute of the Service tag needs to be specified. It is possible however to specify the access for specific provided service operations. Not only can you specify whether those operations are synchronous or asynchronous, but also whether they’re not implemented or used by the component. This will affect what functions are generated for the component and component container.

Services have binding types which determine how they are required or provided as well as how channels are mapped to the service:

By default, services are fixed with a single channel.

For required services, the bindings determine how provided services are connected to the requirement. A single service requirement may have multiple channels which link to services provided by different components. Fixed and variable service requirements must have connections, but optional may not and an open binding should not have any connections. When a service requirement has an open binding, it will call a service provider and channel directly, and so it is not valid to try to connect a service directly to the requirement.

For provided services, the bindings determine how other services can be connected to it. A service provider does not know how many connections have been made and to which channels, but validation will verify that valid channels are connected based on the binding and channel count information.

For component types which have a service requirement, that requirement will need to be connected when deploying instances.

Connected services are enclosed within a Connections tag and then a Services tag.

Each service has:

The channel attribute defaults to 0 and may be omitted if there is only one channel or the first channel is being used.

When creating a component for hardware which interfaces via a bus such as I²C or SPI, that component can be implemented with the details of sending data over the bus being abstracted to writing and reading data via a MAS connection.

There are multiple components, for different platforms, which will provide that MAS service, allowing the component to remain platform independent. For example, most platforms provide an io.bus.i2c.I2CMaster component type which can be instantiated in a deployment to provide a MAS interface to an I²C bus as a bus master.

When creating a component for hardware which interfaces via a bus such as serial or TCP/UDP, that component can be implemented with the details of sending data over the bus being abstracted to sending and receiving packets via a PS connection. As data to be received can arrive at any time, it usually preferable to use PS asynchronously.

For receiving data over PS, a common pattern is used:

Using multiple transactions helps to ensure that no data is lost whilst the component processes data already received.

There are multiple components, for different platforms, which will provide a PS service, allowing the component using PS to remain platform independent. For example, most platforms provide an io.bus.Serial component type which can be instantiated in a deployment to provide a PS interface to a serial port.

To allow a component to persist data:

For configuration to persist, there must be at least one ConfigStore component. When a deployment is generated, the ConfigStore component(s) will be mapped to configuration indices, starting from 1 (0 is the default configuration). A deployment should also have the ConfigurationManager component, which provides control over the loading and storing of configuration. Examples of this are provided in the demonstration deployment for Linux (demo_linux) as well as the fully-featured examples for the Clyde Space platform (e.g. csl_primary).

The table below briefly describes each of the parameters we need.

Expressed as an XML fragment, it looks like this:

An important difference between Raw parameters and the other parameter types is that no adjustment for endianness is made for raw data whereas as other types will be translated to and from network-byte order when sent over the space-ground interface.

The table below briefly describes each of the actions we need.

and in XML:

The table below briefly describes the events that we need. When logged by a deployment, these events will give a basic overview of what the StoreAndForward component has been doing.

In XML:

Note the defaultBaseId. This is used to make sure that each event in a deployed system has a unique identifier. Each component type should have a unique base ID and the actual identifier of an event is found by adding on the base ID. The base IDs need to be spaced far enough apart to ensure that there are no overlaps between the different components. We look at the base IDs documented in the file event_base.txt (in gen1/Documentation) and pick an unused block. You may need to keep track of how your own components use these IDs to make sure there are not clashes. You can check for clashes in a deployment when you export the spacecraft database to HTML as you did for the sample Linux deployment in Section 6.3.4.

We will have three exceptions:

In XML:

In common with events, exceptions too have a defaultBaseId. We check for current allocations in the exception_base.txt file.

We require a single task which will periodically send the next message. This is an example of a periodic task. The other permitted type is a sporadic task. An overview of tasking in the GenerationOne FSDK is provided in Section 2.2.5.3.

The XML is quite straightforward:

We require the use of the packet service (PS) which allows us to send and receive chunks of data (packets) in a peer-to-peer way. For the StoreAndForward component, we will use PS for sending our messages. In the legacy_tutorial2 component library, there is another example component called SerialDemo which also receives over PS.

In XML:

We will call the new component type StoreAndForward and place it within a 'mission' directory in the saf_lib library that we should have created earlier (gen1/OBSW/Source/saf_lib). The component type can be easily created using the Codegen tool (refer back to Section 7 for a reminder on how this can be done). Since we want this component type to reside within a 'mission' directory, ensure to include mission within the component type’s dot notation path in the Codegen command. You also don’t need to worry about including any board configuration arguments since this component is platform independent. Once created, complete the componentType.xml file according to the component’s requirements.

The completed XML file should look like this:

Each component instance can have variables associated with it which are accessible to all of the functions that make up the component. This is achieved by having a C structure, the component type, which is instantiated for each instance of the component. A pointer to this instance is then passed to all of the component functions. Effectively, the instance of the component type is the component instance.

The component type for the StoreAndForward component is defined in the StoreAndForward_types.h header file. The automatically-generated type for StoreAndForward is as follows:

To add variables to the component we add them in place of the comment (“TODO: Add component variables here”). The code generator will also pick up that there is a variable-length vector (the messages parameter) and generate a variable that can be used in the source to track the current length of the corresponding vector. This is optional and can be replaced.

Our StoreAndForward component needs component variables to store the data we have decided will be available as parameters:

These variables can be added as follows:

As well as the data storage for the parameters, the component needs to keep track of its current transmission state. We will add some more variables to do this when we start to implement the transmission algorithm.

For now, we should make sure that the component variables we have just added are properly initialised. The correct place to do this is in the StoreAndForward_localInit function, which is responsible for initialising the internal component state. For now we just initialise the component variables to constant values:

The value of each parameter which we described can be obtained from the component using an accessor function. The accessor for reading the parameter value is always called getXXX where the 'XXX' is replaced with the parameter name. So, for example, the messagePeriod parameter has the accessor function getMessagePeriod. Most of the accessors are quite easy to implement: all they need to do is pass the parameter value back to the caller. To make sure that the state of the component variables are always consistent, we protect the component variables using a protection lock (just like a mutex, or binary semaphore). We enclose the code which accesses the component variables in special start and end statements which acquire and then release the protection lock. It is possible to specify a timeout to the protection lock handling statements. This makes sure that, even if the lock is being held for a really long time, the function will only wait for a predictable length of time. You can ask for an infinite wait (by specifying NULL) but we don’t recommend this as, in general, it is less safe. The status of the protection lock handling is reported in the specified status variable.

A complete parameter get accessor for the messagePeriod parameter is as follows:

Parameters which are not read-only also have set accessors. These are equivalent to the get accessors we’ve just discussed. For example, the set accessor for the messagePeriod parameter is as follows:

The accessors for the other simple, scalar, parameters (messageRepeats, messageCount, nextMessage and started) are all very simple, just like these ones.

Accessors become slightly more complicated when handling vector (multi-row) parameters, especially when those parameters can have a variable number of rows. In this case there are get and set accessors (unless the parameter is read-only, in which case there will be no set) but there is also a length accessor. This is called getXXXLength, where 'XXX' is the name of the parameter. So, for example, the messages parameter has three accessors: getMessages, setMessages and getMessagesLength:

Accessors for multi-row parameters have additional arguments which specify the first and last row for the get or set. It is important that the accessor check these arguments to make sure they are valid. When the parameter has a variable number of rows, like the messages parameter, there is a Boolean argument specifying whether or not a resize has been requested. For a get, resize means that if the caller has specified a last row which is beyond the actual last row of the parameter, the accessor should change the request to place the last row within range. For a set, resize means that the caller wants to change the number of rows the parameter has so that the last valid row of the parameter after the set is the last row that was specified as an argument. This might make the parameter bigger, or it might make it smaller. It is also possible to append the list by setting the first row to be the row immediately following the current last row of the parameter.

The get accessor for the messages parameter is shown below. As you can see, the actual parameter access is very simple, most of the code is there to check the accessor arguments. Note that although the basis of the validation code is generated for you, the code can be altered to suit the requirements of the mission.

This code uses the memcpy function; to make this available, add an include for string.h to the top of the file:

As with the get accessor, most of the set accessor code is responsible for checking arguments.

On the other hand, the accessor to get the parameter length is very simple. Note that this is automatically generated for you using the default length. If you changed this variable then you will need to update the corresponding function.

If you’ve been following along, and either writing or copying accessor code, you should now have code in all of the parameter accessor stubs. This means that all of the parameter handling for your component is done. The next sections will go on and fill out the rest of the component functionality, but it’s important to note that what you have now is a perfectly valid component, it just doesn’t do a lot. If you want, you could skip ahead to <<sec:sDeployingTheComponent} and add your current StoreAndForward component to a deployment and try it out. In fact, you could do that at the end of each of the following sections. Then come back and continue adding to your component. At this stage, you should find you can get, and set where appropriate, the values of your component parameters. You can try invoking the component actions, but these will return an error.

When you create a deployment with your component in it, you are effectively creating one (or more) instance(s) of your component. When you instantiate them you may want to be able to specify data which will configure that particular instance. In the GenerationOne FSDK we call this initialisation data. This is just like the information you would pass to an object constructor in Java or C++.

Initialisation data has a structure of its own. In a deployment you fill out this structure and the deployment gives it to the component manager, along with the component, so that the component manager knows how to initialise the instance. When you are writing a component, you can choose what initialisation you need by adding member variables to the initialisation data structure. The initialisation data structure type definition for the StoreAndForward component is in the StoreAndForward_types.h file and is called StoreAndForward_Init_t.

In our case, we want to allow the user to specify initial values for the messagePeriod and messageRepeat parameters. To do this we add two new member variables like this:

Then we change the component variable initialisation code we wrote to use these two values:

You can see, in the line above where we use this new initialisation data, we actually keep a pointer to the initialisation data structure in the component itself. This means that we can get access to these initialisation values at any time.

It’s important to note that, by convention, the members of the initialisation data structure are treated as constant. This is enforced by the use of the const modifier. This allows the compiler to put this initialisation data into read-only memory, if it can, which is often a more efficient use of resources on embedded systems. Also by convention, initialisation data is expected to persist after component initialisation. This means that a component can just keep a pointer to the initialisation data and refer to it again later if it needs to; there is no need for a component to take a copy of the initialisation data.

The StoreAndForward component has four actions: appendMessage, clearMessages, startSend and stopSend. You may have noticed, in the StoreAndForward.c file, that the code generator has generated function stubs for handlers for each of these four actions. For example, the startSend action handler is called StoreAndForward_startSend. Implementing the actions is a simple case of adding code to these handler stubs. The actions for clear messages and starting and stopping the sending of messages do not take any arguments, this makes them quite simple, so we’ll start with those. The clearMessages action is the simplest: all we need to do is set the number of messages (the message length variable) to zero. As usual, we protect our access to the component variables with the protection lock:

Starting and stopping the sending of messages is pretty simple too. The main thing we need to do is to change the value of the Boolean started parameter appropriately:

The statement UTIL_LOG_INFO("Started forwarding messages") is just like a printf (the valid arguments and format specifiers are identical, except that it goes via the framework). There are three types of debug logging:

The reason for using these statements, rather than a printf, is three-fold.

The logging statement is contained within the logging system, which is part of the framework. The header is automatically included when the source is generated.

The code for the stopSend action handler is equivalent to the start handler, with the values for the started parameter modified and the logging text changed.

The action handler for the appendMessage action is a little different because it takes an argument: the message to append to the list of messages. We need to copy the message data into our component variable containing all of the messages, into the next free message slot. Before we do this, we must make sure that there is a free slot available, and that the message is a valid length.

When we copy the message in, we first make sure to zero out the message slot. This is so that, if the message is short, unused characters are guaranteed to be zero. When we send the message, we stop sending characters when we reach the first zero-valued byte. Note that basic error checking is automatically generated, however we replace the STATUS_INVALID_PARAM status that’s set with the component specific exceptions to make it more meaningful.

The StoreAndForward component is progressing well: we have completed all of the parameter accessors and all of the action handlers. However, the component still doesn’t do very much. To get the component to send messages, we need to implement the periodic task. That will be the final step. Before we do that, we’ll add one other bit of functionality. We wanted the StoreAndForward component to raise events when it is started and stopped. That’s what we’ll do in the next section.

Events are system-wide notifications of significant things. Typically, events are logged, so that you can trace what has been happening, and they may also be forwarded to ground in real time. A lot of events are to signal that something has gone wrong, but in some cases we just want to log confirmation that an expected onboard operation has completed successfully.

In the case of the StoreAndForward component, we want to raise events to indicate when we start and stop sending messages. These are not errors, just a significant change in state. To do this we need to raise an event using the function that is generated in StoreAndForward_Container_package.h.

To use the function, we simply specify the event we want to raise and the information we want to associate with the event, if any. For our start and stop action handlers, we just want to raise the appropriate start or stop event. For the information field, it might be useful to specify the index of the next message we are (or were, for stop) going to send.

Raising the event is just one extra statement, like this:

The addition to the stopSend handler, to raise the STOREANDFORWARD_EVENT_SEND_STOP event, is equivalent.

Most of the work that the StoreAndForward component does takes place in a separate task. The code written for the task defines what that task will do when run. However the task itself isn’t created by the component; this is done by a deployment that instantiates the component.

A periodic task function is called periodically, in the context of a task. The code is expected to execute, and then return. The next time the period expires, the function will be called again. A periodic task function does not contain a loop which waits for the period to expire, that is handled by the task itself. The StoreAndForward task needs to:

To do this we need to keep track of our state in between calls to the periodic task function. This means that we need some more component variables. We need to keep track of:

We add these component variables as follows:

We also need to initialise them in the component local initialisation function:

Now we are ready to use these variables to control the sending of messages. As we need to make sure that the state of the component variables is consistent, we protect the body of the task function with the protection lock.

Here is the task function code so far. We’ve added quite a lot of comments to try and describe what is going on:

This code does everything the component needs to do, except actually send the message! We’ll come back to that in a moment.

When this code first executes, the count down variables are zero, so the function will try and send a message. If there isn’t one, the current message pointer gets set to NULL and nothing gets sent. If there is one, we record the current message and the next message. We always set up the period count down so that we only actually do anything the right number of iterations.

If anything goes wrong during the task function, we will set t_Status to a value other than STATUS_SUCCESS and an event will get raised indicating the error.

Now to add the code that actually sends the message. To do this we are going to use the Packet Service, which is part of the framework, but is accessed via the container. The Packet Service allows us to send and receive chunks of data (packets) in a peer-to-peer way. The actual device or protocol used for packet sending and receiving is handled by the way that component is connected in the deployment. The code generator will create package-accessible functions based on the required services as defined in the component XML. For this component, a PS_package.h file has been generated containing function prototypes and a macro to help use the PS service in simple cases.

We will use the Packet Service function PS_send to send the message. We need to specify:

The timeout for the PS send is configurable, but this can be configured at component type build time, rather than component instance deployment time. To permit this we add another define to the StoreAndForward_config.h file:

We then create a global constant variable at the top of the StoreAndForward.c file to hold the timeout value:

Now we are ready to add some code to the task function for actually sending the message. We need to calculate the size of the message (we’ll use strnlen for that) and then we can do the send. Rather than show the code for the whole function again, we’ve just shown the most relevant bits.

Now the task function will actually send the message, and the code for the StoreAndForward component is complete.

The generated unit test will automatically include the headers that ask CMock to produce a mock of various files. This is done by specifying the file, but with “Mock” in front of it. The build system will pick this up and request that CMock generate a mock.

For this test, we’ll also include string.h to allow us to compare strings in the test.

After the included headers, you should find that some global variables have been generated for you. These set up a container and get a global pointer to the component from this container. As you can see below, a TODO is set up to remind you to set up your component with the initialisation data that you want to test with. The global variable gpt_StoreAndForward will be what is used throughout the tests.

The global variables are followed by another section titled “Helper functions” that is currently empty. It’s in this section that a helper function for testing the configuration would be generated, additionally it’s this section that we’d advise placing non-test functions in for readability.

Following on from the helper function section is the set up / tear down section. We initialise the component in the setUp function, which is called by Unity at the start of every test. The component is relatively simple so all we need to do is initialise the component and test that it passes.

Similarly, at the end of each test, Unity calls the tearDown function. Here we finalise the component.

The final section generated is the section for the actual tests. You will see that some tests have been generated for the component’s actions. Tests should make sure that not only do the component’s functions execute successfully, but also that they catch error cases. The generated unit tests will test that invalid invocations are caught. They also generated “success” tests, which include TODO comments for changes that should be made to complete the test.

Setting these tests out in separate test functions helps make the Unity output easier to follow and see which particular tests passed and where the failures are.

If a generated component has a configuration, then 5 additional tests can be generated that will provide the types of tests that should be done for the configuration with TODOs added in to help inform you of what needs to be filled in and/or replaced.

The generated tests should compile but not all the tests will currently pass. We’ll address these tests as we implement tests.

The unit tests should be built when you do a build on the library with the StoreAndForward component and test code in. You can try the unit tests we’ve written simply by building saf_lib for Linux and executing the testStoreAndForward binary that is produced in the saf_lib/bin directory. This should produce the following output from Unity:

Additionally, some debug output can be produced from the component itself when it is started and stopped by the tests (from the UTIL_LOG_INFO statements).

The first step to creating a new deployment is to generate the basic file structure it requires using the Codegen tool (refer back to Section 6 for a reminder on how this can be done). Use the Codegen tool to create a new deployment named saf_test.

The next step is to update the deployment.xml file to describe the component instances and connections you wish to have in your deployment. The quickest and easiest way to do this is to copy an existing deployment which already has a similar structure to what you want, then modify it to suit your needs. In this case we suggest you base your new deployment off of the existing demo_linux deployment. Don’t worry about adding any new component instances to it yet, we will do that in the following section.

The same approach can then be used to update the config and make files, ensuring that TARGET, VALID_CONFIGS, and DEPEND_DIRS are set appropriately for your new deployment:

Notice we have set TARGET := saf_test, and added saf_lib to DEPEND_DIRS because we are going to add an instance of StoreAndForward from the saf_lib library to the deployment.

Now generate the deployment, referring to Section 6.3 if you’re not sure how to do this. After that, copy across the src/init directory from demo_linux so that the init data is filled out. You can actually check that your deployment builds at this point. You should get an executable called saf_test in the bin directory which you can execute and use exactly as you did the demo_linux deployment (see Section 4).

The first thing we need to do is to create an instance of our StoreAndForward component in our deployment. More specifically, what we actually do is create an instance of the StoreAndForward container, the container then creates and manages the component instance.

A component instance is a set of data declarations, some of which are initialised with data. There is no actual code. Because of this, these component instantiation files are quite repetitive. It is usually a good idea to copy files from a similar component instance and modify them.

As with tutorial 1, to add the component instance, you first need to import the mission.StoreAndForward component type in the deployment.xml <Import> section.

The component can then be instantiated by adding a <Component> element at the bottom of the deployment.xml <Deploy> section.

As can be found by checking the library documentation, StoreAndForward uses a service and also contains a periodic task. These will need to be set up within the <Component> element you have just created. First to set up are the connections so create a connection → service block and add the component and service to use for sending.

The Packet Utilisation Standard specifies a standard TM/TC protocol, together with a standard set of TM/TC services. The GenerationOne FSDK has an implementation for the PUS protocol and some of the key services. The demonstration deployments, and TMTC Lab, all use PUS. In addition to the specified services, PUS permits the implementer to add additional services of their own. We have done this to transfer parameter data when you carry out a 'Get'. The TMTC Lab software understands one more custom service, which is very simple telemetry packets which contain debug messages. These telemetry packets are identified by service ID 129 and sub-service ID 1. We will use these to transfer our messages from StoreAndForward. The main PUS protocol handler is called PUSCore. In the demo_linux deployment, which we will use as a base, it specifies channels for event forwarding, function management ('Get', 'Set' and 'Invoke' requests) and a special channel for return data from functions. We will need to add one more channel for debug messages.

The service name for StoreAndForward is 'message' and we want to use the 'dataPacket' service provided by PUSCore. Checking PUSCore in the framework library documentation shows that the component’s container can support up to 8 channels. In this deployment, channels 0 – 6 are being used by the other component connections just described and so we’ll use the next one along.

Next set up the task. The name is 'main' and we want the task to get called every second. We’ll also place it at a higher priority.

Now regenerate the deployment using the same approach as before.

We now need to update some of the init data related to our new component instance.

First we will update the initialisation data for PUSCore by adding in the new channel. Open src/init/comms/pus/PUSCore_Init.c and add the section below to the end of the grt_PUSCoreChannelInit[] array.

The additional channel specification specifies that we would like a new channel which transfers service ID 129, and only sub-service ID 1. The AckMask, SingleAck and AckStatusSize are related to the acknowledgement of telecommands on the channel. As there are no telecommands on this channel, they are not relevant. The IncludeSubservice parameter specifies whether the data that is passed on the channel (both for receive and send) should have the sub-service ID as the first byte. As our subservice ID is fixed, and we want to be able to send our messages without adding a sub-service ID at the start, we specify FALSE here.

Next, let’s set the initialisation data for our StoreAndForward component to use this new channel. Open src/init/mission/StoreAndForward_Init.c and replace the TODO comment with the following code:

This is all that is needed to initialise the StoreAndForward component.

Execute the deployment, and run TMTC Lab, it should connect to your deployment. As with tutorial 1, the Spacecraft Database should be generated and then open that in TMTC Lab.

As a simple test, try appending a new message by invoking the appendMessage``StoreAndForward action specifying the message. We need to specify the message in hexadecimal, for example: 48656c6c6f2c20576f726c6421. Now you can start sending by invoking the startSend action.

In the packet monitor window, you should see (after the action invocation telecommands and their acknowledgements) an event, indicating that sending has started and, possibly after a delay, a debug message. Additionally, you should be able to see the debug message in the debug console. This is shown in Figure 10. You should now be able to try out the other features of StoreAndForward.

One of the most intuitive methods of interacting with the spacecraft is through the Mission Explorer which will display a representation of a spacecraft database (SCDB), shown in Figure 12.

On first opening Lab, the Mission Explorer displays Sessions, Layouts, and Housekeeping. However, to view component groups and component instances present in a deployment, a deployment (SCDB) must be opened. This is explained in more detail in Section 9.2.2, however, for the moment an SCDB can be opened by clicking File → Manage deployments. Either add or select an existing target and click Select Deployment to choose an SCDB for the currently selected target.

Once an SCDB is open, the Mission Explorer tree view provides a list of all the component groups and component instances present in the deployment. Component groups allow components with similar functions to be grouped into easier to access and view areas. The groups are defined by the deployment. Components with parameters and/or actions can be expanded to reveal their list. Parameters and actions can be interacted with, e.g. fetching a parameter value, by first double-clicking on the component in the tree (this is explored more in Section 9.1.2).

At the top of the Mission Explorer there are 4 buttons:

To the right of these buttons is a search field that applies a fuzzy search to quickly lookup and jump to a particular node. This allows searching using the name of a component, for example, typing in 'dummy' brings up results for dummyParam8, dummyParam16, and dummyParam32, among others. Components can also be looked-up using their decimal or hexadecimal flight-ID. For example, typing the decimal ID of dummyParam32 prefixed with a hash, '#917504', will bring up dummyParam32 as a result. Alternatively, its ID in hex can be used by prefixing the number with '0x', for example, typing '0x000E0000' also brings up dummyParam32.

At the bottom of the Mission Explorer, interactive deployment documentation is displayed to allow you to view documentation without having to change between TMTC Lab and the HTML deployment documentation.

Interactions with parameters and actions are done via dialog windows representing different parameters/actions. For example, Figure 13 shows the dialog used to interact with dummyParam32, and Figure 14 shows the dialog used to invoke the OBT.reset action. To open a dialog, select the parameter/action of interest from the Mission Explorer.

Some options may also be disabled depending on what is available to that parameter. For example, some parameters only have a single row and so the ability to select a row range is disabled. Similarly, if the parameter is read-only, then the ability to uplink to set the parameter is disabled.

The system/debug/event console provides three tabbed windows. The system tab gives an overview of the actions being taken by TMTCLab. The Debug tab displays debug log messages sent from a connected spacecraft. The event tab allows a more human-readable form (i.e. not packets) to view raised events.

Layouts allow arrangements of windows, such as parameter dialogs, to be persisted and easily switched between. Existing layouts can be found under the Layouts section of the Mission Explorer. Right-clicking on the top-level layouts icon allows new layouts to be created.

Windows can be arranged in a layout by clicking and dragging. When a window is being moved, icons are displayed showing the locations the window can be docked to, as shown in Figure 18. The blue area shows the location the window will be docked when the mouse is released. In this way, layouts of windows can be built up.

Once you are happy with a layout, it can be saved by right-clicking on the layout in the Mission Explorer and choosing Save (Figure 19), making sure that layout is currently selected. Switching to another layout or closing TMTCLab also has the effect of saving the current layout. To prevent a layout from being modified, it can be locked using the option in the context menu (Figure 19). This will keep the layout in the state it was when it was locked, regardless of whether windows are added, moved, or removed.

Sessions allow the global configuration of TMTCLab to be changed. By switching sessions, the connection method, current layout, open deployments, as well as every other configurable part of TMTCLab can be switched between. An example use case is having a different session for the different deployments being developed for a specific spacecraft, loading in the different SCDBs for the deployments and using different layouts for each one.

TMTCLab initially starts in a default session, but new sessions can be created by right-clicking on the top-level Session item in the Mission Explorer (Figure 20). Existing sessions can be switched between by double-clicking on their icon in the Mission Explorer (Figure 21). Session layouts can also be modified and duplicated via the context menu available on each session.

The deployment management window allows you to add/remove targets and to set the deployments (SCDBs) for each of the configured targets (Figure 22). To add a new target, press the New target button. Selecting the target in the table then allows its deployment to be set using the Set deployment button, and choosing the corresponding SCDB.

The connection window allows you to configure and establish a connection to your deployment. To access this window click the 'Connect' button in the main window or go to File → Connect. It is possible to use a serial connection, a TCP client - where TMTC Lab acts as the client, a TCP server - where TMTC Lab acts as a server to be connected to, a UDP connection, an EGSE client, a Cortex TCP connection, or a qRadio TCP connection (Figure 23).

For certain connection types, the protocol framing in use can be specified as either Packet stream, KISS (TNC), or None.

This section discusses the different options available in the Protocol Properties window and is organised according to the different sections in the window.

The packet monitor (Figure 24) provides a log of packets exchanged between the ground and the on-board software. The different columns described in Packet monitor log columns contain decoded information relating to the packet.

Below the log of exchanged packets is further detail describing the selected packet, the left section presents some of the information given by the table in a different format as well as providing additional information such as the calculated CRC of the packet and also what the packet contained. The right section provides a human-readable description of the contents of the space packet.

The contents of the Packet Monitor can be exported to CSV using the right-click menu anywhere inside the log.

The Parameter Table displays the latest values of parameters, as shown in Figure 25. To add parameters to the table, drag and drop parameters from the Mission Explorer. Alternatively, double-clicking on an aggregation or beacon in the Mission Explorer (under Housekeeping) will open the Parameter Table populated with parameters in the aggregation.

When a parameter value is received (via a parameter get, beacon, or via the CLI) the corresponding parameter in the Parameter Table will also be updated. Using a beacon to retrieve parameter values allows for live values to be displayed in the Parameter Table as they are received.

The activity window (Figure 26) can be opened using the button in the bottom left of TMTCLab, or by going to Monitors → Activities.

The window displays a tree of activities, e.g. get, set, downlink, uplink, invoke, which are currently running or have completed. The nesting of activities indicates a parent-child relationship. For example, the top-most activity in Figure 26 was triggered by getting the value of a parameter. This activity then started a PUS get-request to perform the task of asking the on-board software for the value of the parameter.

Each entry in the list details the current state of the activity. These states are:

By default, completed activities will be removed from the list once they are completed. To prevent this behaviour, check the Hold checkbox.

The transfer window (Figure 27) displays a subset of the activities in the Activity monitor and can be opened using the Transfers button on the toolbar, or by going to Monitor → Transfers. When a parameter is downlinked/uplinked the transfer will be added to the transfer list, detailing the current state of the transfer.

If any errors are encountered with a transfer, then it will remain in the list. It’s possible to suspend a transfer, which will be picked up again upon resumption unless the transfer has timed out. Clicking abort on a transfer will perform an abort request to stop further packets being sent.

The Command-line interface (CLI), shown in Figure 28, allows interaction with onboard software via scripts. A script is composed of a simple set of instructions for getting, setting, downlinking, and uplinking parameters; querying the dimensions of a parameter; and invoking an action.

Commands can be run from this window and the output displayed to the CLI window. This information first prints out a readable echo for the telecommand that has been sent and then prints what telemetry was returned for the command. This could be either an ACK, a NACK, values requested or a response.

The history of commands run via entry into the CLI can be obtained using the arrow keys on the keyboard while the CLI text-field is focused. The up arrow moves backwards in the history one command, and the down arrow moves forward in the history. To aid the discovery of commands, when a command is performed via the GUI, such as a parameter-get via the parameter dialog (Section 9.1.2.1), the command to run this activity is also placed into the history.

Aggregations pack together multiple parameters into a single parameter, which can later be decoded into separate parameters.

Using New aggregation from file or Multiple new aggregations from files will create new aggregations from YAML files created using the Aggregation Builder (see Section 9.5.3). Aggregations created will be available under Aggregations in the Mission Explorer, and under the drop-down menus in the Decode Data Log and Decode Event Log tools.

Beacons broadcast aggregations regularly, after a given period. Using New beacon mapping creates a new mapping from an aggregation to a beacon.

Going to Tools → Decode event log will bring up the window to decode an EventLogger’s contents, as displayed in Figure 34. The tool can decode either the data from a recent parameter get or downlink. Once decoded the output can then be exported as a Comma Separated Value (CSV) file to be loaded into a spreadsheet. Section 9.6.2.4 provides a demonstration of how to use this tool.

Similar to Event Log Decoding, it’s possible to decode the output from a DataLogger. As with the Event Log Decoding, you can use either the values from a recent parameter get or from a downlinked binary file.

DataLoggers typically use the output from aggregators. Therefore, to decode a DataLogger, the corresponding aggregation is required. This can be supplied either by selecting an aggregation from the drop-down menu. Alternatively, an aggregation definition YAML file can be supplied which can be generated using the aggregation builder (Section 9.5.3).

Once you have set a source and definition, you can decode the source and you will get output similar to Figure 29. Section 9.6.3 provides a demonstration of how to use this tool.

The Aggregation Builder tool (Figure 30) displays the parameters being packed together in an aggregation, as well as allowing aggregations definitions to be edited.

To retrieve an aggregation definition, select the aggregation of interest from the drop-down menu and press the Load from aggregator icon, which will get the definition from the on-board software.

To add new parameters to the aggregation, drag and drop parameters from the Mission Explorer onto the aggregation viewer. To delete parameters from the aggregation, select the appropriate row in the table and press the delete icon. Once you are done editing, the updated aggregation is sent to the OBSW using the Send to aggregator icon.

A YAML data definition file can also be created using the Save to portable format icon, which can then be used decode a DataLoggers (Section 9.5.2) and for live housekeeping (Section 9.4).

The Time Action Schedule Builder (Figure 31) allows schedules dependent on time to be constructed and can be opened by going to Tools → Time action schedule builder.

Schedule entries (rows in the table) uploaded to the target can be executed at an absolute time; the onboard time (OBT) at which the entry will be executed. Alternatively, the entry can be run at a relative time; the time at which the entry will be executed is given as an offset to the OBT.

Once a schedule entry’s relative or absolute time is reached, a parameter or action associated with the entry can be set or invoked, respectively. The schedule can later be downlinked to check whether it has been executed.

The Periodic Action Schedule Builder(Figure 32) allows the construction of schedules that run at regular intervals and can be opened by going to Tools → Periodic action schedule builder. Once uploaded, an entry in the schedule is executed every period seconds, and are run a total of multiplier times, each time either invoking an action or setting a parameter. The schedule can later be downlinked to check whether it was executed.

The Event Action Schedule Builder (Figure 33) allows the construction of schedules that run according to whether certain events occur, and can be opened by going to Tools → Event action schedule builder. Each entry in the schedule contains an event that, when occurs, causes an action to be invoked or parameter set. The schedule can later be downlinked to see whether it was executed.

In this section, we will set up a Monitor for a dummy parameter to check whether it goes out of range. When the parameter goes out of range, an event will be raised. This event will be listened to and will trigger an action to reset the monitored parameter.

As explained in Downlink (Section 9.3.5.3), 'Get' telecommands can only retrieve up to the maximum amount of data that can be stored in a telemetry packet. Typical deployments include loggers that use storage channels to store information such as raised events and telecommands. The parameters these loggers store their data into are typically too large for a single packet. To provide an example of how to get the data in the storage channel, we’ll look at how to get the data saved by the EventLogger.

This section explains how aggregated data can be decoded using the Decode Data Log tool.

Eventually, your storage channels will fill up. You can check whether a storage channel is full through the isFull parameter in the Storage component, with a flag for each storage channel. Note, however, that channel 0 is a NULL channel and so should not be accessed.

While testing with TMTCLab, TCLogger component’s channel is likely to fill up. You can find out the ID of the channel used by this component through it’s channelId parameter. If the channel does fill up, then TCLogger will raise an event informing you of such.

If there are a lot of events being issued, it’s also possible that the EventLogger component’s storage channel will fill up, and you can similarly find out the channelId. To avoid a flood of events, if the `EventLogger’s channel is full then an event won’t be raised. Therefore, under normal operation, it is worth periodically checking whether the storage channel is full.

When you have the ID of the channel that you wish to wipe, you simply invoke the Storage.wipe action, passing in the channel ID as the argument (as two bytes in network byte-order).

It is possible to view live parameter values in TMTCLab. Live values are shown in the Parameter table window, as mentioned in Section 9.3.2.

For demo_linux, there is only one TMBeacon entry, which uses the BeaconAggregator. Before you can add the housekeeping definition for the beacon, you need a new aggregator definition to match the BeaconAggregator. To do this, use the Aggregation Builder to retrieve the aggregation definition for the BeaconAggregator. Next, save this definition as a YAML file (these are similar steps to [p:lab_GeneratingAnAggregationDefinition]). Finally, use Housekeeping → New aggregation from file to add a new aggregation using the created YAML file.

Now a new beacon mapping can be created. To do this, go to Housekeeping → New beacon mapping. Give the beacon an ID and select the aggregation just created. The mapping should now appear in the Mission Explorer under Housekeeping/Beacon map.

Before you can see live housekeeping, the TMBeacon component will need to be enabled using the cdh.tmtc.TMBeacon.enable parameter. Once enabled, you should see housekeeping packets start appearing in the Packet Monitor window. Opening the Parameter Table by double-clicking on the created aggregation or beacon mapping in the Mission Explorer, you should see the reported value of each parameter being updated, like in Figure 25.

The launcher should be copied to the onboard computer unmodified. It can found at 'gen1/OBSW/Source/linux/system/gen1/gen1-flightcontrol'.

Configuration of the launcher is done via a sourced shell script. It expects the configuration to be named 'gen1-launcher.conf' and be placed in the same directory as the script.

An example of a configuration file can be found at gen1/OBSW/Source/linux/system/ gen1-launcher.conf. In the file you’ll find several shell variables being set. All of these variables apart from the optional 'KERNEL_MODULES' needs to be configured.

Systemd is used to launch and monitor the gen1-flightcontrol launcher script. Users are free to use their own init system choice. However, these instructions will only provide a guide on systemd usage.

An example of a systemd service used to control the launcher can be found at 'gen1/OBSW/Source/linux/system/gen1-flightcontrol.service'. You should only need to modify two lines of this file. The 'ExecStart' line should be modified to point to the correct location of the gen1-flightcontrol launcher script. 'WorkingDirectory' should be modified to point to a modifiable folder. All relative paths specified in gen1 init.c files will be based off this given workspace root.

The gen1-flightcontrol.service file should be placed at '/etc/systemd/system/ gen1-flightcontrol.service'. To enable the service to run when the board is booted, execute the following as root.

The failsfe image should be placed at the location specified by the FAILSAFE_IMAGE_PATH variable in the launcher configuration script. Primary images should be placed under PRIMARY_IMAGE_DIR_PREFIX/x/ where the prefix is the value specified in the launcher configuration and x is a number between 1 and 9. This provides 9 primary image slots.

Each primary image should also have an accompanying md5 checksum file. The checksum file name should match the one specified in BINARY_MD5_NAME when writing the launcher config. MD5 checksum files can be gererated using the following command.

Note - The file listed in the output of md5sum should not have any path prefixing the file name.

Eg 'd41d8cd98f00b204e9800998ecf8427e gen1-binary' is fine while 'd41d8cd98f00b204e9800998ecf8427e workspace/gen1-binary' is invalid. As mentioned earlier, kernel modules can also be loaded by the gen1 launcher. A safe version of each kernel module should be placed under FAILSAFE_IMAGE_DIR. Any newer versions of the module should be placed into the same folders as the primary images. Kernel modules in the primary images folders are also expected to contain a checksum file. When a primary slot is booted, this version of the kernel module is loaded. If the checksum mismatches, the failsafe version of the module will be loaded instead. In the checksum mismatch case the primary gen1 image will continue to be booted. This allows for multiple gen1 primary binaries to be uploaded while only having one source of the kernel modules kept in the failsafe dir.

The BootControl component provides image management and reboot support. You’ll need to set up its init data with the same values that were used to configure the gen1 launcher config file.

Before the gen1 launcher launches a binary, it first deletes NEXT_IMAGE_FILE. This is done to prevent boot looping over an unstable primary image. When NEXT_IMAGE_FILE doesn’t exist, the failsafe is booted. To boot back into the same primary image upon the next restart, the NEXT_IMAGE_FILE must be written to again by the BootControl component. A time action component should be set up to instruct the BootControl to mark the current image as the next image after a safe timeout has passed. Below is an example configuration of a TimeAction component doing this four minutes after start up.

For the Kryten platform, it’s possible to place OBSW images into either flash or MRAM. A failsafe image is stored in embedded flash memory on the SmartFusion2 device and two primary images can be stored in EDAC-protected MRAM. The failsafe’s memory is more limited than MRAM, so for missions these tend to be cut down versions of the primary images.

Failsafe images shouldn’t be used for nominal operations during a mission. For nominal operations the satellite will operate from one of the primary images. The failsafe should only be used as a means to recover the satellite if the primary images become corrupted or unstable. Failsafe images should therefore be kept simple, to ensure correct operation.

By default, the OBSW will boot into the failsafe image. It is possible to then use the OBC component to change which image to boot into. When booting, image configuration records stored in MRAM are used to determine which image to boot. The boot process is as follows:

The OBC component provides access to core functions of the Kryten: * Powering on and off the onboard Q20 GPS (if fitted) * Powering on and off the onboard telemetry ADCs * Powering on and off the onboard rate sensors and magnetometers * Querying the OBC firmware part number and revision information * Control of the running OBSW image

To be able to boot into a primary image, an OBC component must be present in the failsafe deployment. Through this component it’s possible to check what the current image is. By altering image priorities it is also possible to change what the next boot image will be. The image numbers are as follows:

To prevent a boot loop occurring, primary images are marked as unstable before being booted into. The loaded primary image can mark itself as stable after successfully booting, or the operator can carry this out manually when contact with the OBC is made. There is an example of this in the kryten_failsafe cdh.scheduling.TimeAction component instance. If the primary image fails to mark itself as stable before an unplanned reset occurs, then the image will not be considered in the next boot image selection arbitration.

The Watchdog component manages the Kryten’s onboard 555 timer-based watchdog circuit. Its restore task should run at the lowest task priority in the deployment, while the kick task should run at the highest task priority in the deployment. This ensures the watchdog is kicked as long as there is enough "credit".

kryten_failsafe contains a configured platform.obc.Watchdog instance, and the io.driver.Watchdog component type is extensively documented.

The Kryten’s IO pins on the CSK can be configured for many different functions. The Gen1 OBSW sets all pins to inputs at boot up. A pin’s function is determined by the various driver components which can be deployed. All of these components claim pins using their initialisation data during local initialisation.

Note that pins are claimed by components unconditionally - if component B is instantiated after component A, then B’s local initialisation will happen after A’s. This will mean any pins which B claims which A has already claimed will have B’s settings applied. The OBC debug output can be used to check for collisions in pin allocation.

Pins are referenced by their position on the CSK. ACS’s somewhat inconsistent numbering and naming is not used by Gen1. For example H1.1 is referred to using the pin identifier BOARD_PINMUX_PINID_H1_1 rather than GPIO_0. Similarly H1.17 is referred to as BOARD_PINMUX_PINID_H1_17 rather than GPIO_10.

The available pin configuration options are determined by the Kryten firmware. This must be set correctly using the BOARD_CONFIG_FIRMWARE_ID symbol in kryten/inc/board/Board_config.h.

The GenerationOne FSDK builds using GCC; to build for the Kryten the arm-none-eabi toolchain is used. This toolchain is already set up in the Gen1 virtual machine.

To manually set up this toolchain, run download.sh from the /OBSW/Toolchains/arm-none-eabi directory. This will retrieve the archive containing the necessary toolchain from the internet. This should then be extracted into a suitable location, such as /opt, and then PATH should be adjusted to include the binary folder of this toolchain.

OpenOCD is used for programming failsafe and primary images onto the Kryten. To use OpenOCD and the BAL wrapper script, either an Olimex ARM-USB-TINY-H or a SEGGER JLink.

To install OpenOCD on Ubuntu the package openocd should be installed. Version 0.9.0 (or later) is required. If this package gives an earlier version, we recommend downloading and building version 0.10.0 as this is confirmed to work with this guide. If OpenOCD needs to be built from source, the following instructions should be followed. You may receive warnings that your system is missing some key dependencies for OpenOCD. You should remedy these warnings by installing the appropriate packages.

You may find that OpenOCD cannot communicate with your programmer. If so, there may be a problem with the device permissions which should be corrected by specifying device-management rules for Linux. For the ARM-USB-TINY-H on Ubuntu we created a file in /etc/udev/rules.d called 46-jtag-arm.rules with the following contents:

This rules file should work for any programmer, but you will need to set the vendor and product IDs to match your device. These can be found using the lsusb utility; the vendor and product IDs are listed for each device as a pair with a colon in the middle (vendor ID on the left, product ID on the right).

The umbilical TM/TC connection transfers TM/TC packets over serial. As asynchronous serial is a byte-wise stream, we utilise a custom framing protocol to locate the beginning and end of packets (this protocol is referred to as PacketStream in the component library and deployment). The TMTCLab software should be configured to connect to a serial device to work with the umbilical connection.

The debug console is a straightforward serial character stream and can be viewed in any suitable terminal emulator such as minicom. The console output uses linux line endings, so you may need to enable implicit carriage returns in your terminal emulator. The demonstration deployment for the Kryten uses the following serial settings:

There must always be a failsafe image programmed on the Kryten platform. To use a primary image, a failsafe is required as the starting point and a fall-back.

To avoid boot problems which can be caused by corrupt failsafe images, it is important that the power to the Kryten is not disrupted during programming. For example, the Clyde Space EPS has a watchdog which, if not serviced, will cycle the power every 4 minutes. This power-cycling could cause a corrupt failsafe image to be programmed. We therefore suggest that the Kryten is not powered by the EPS during failsafe programming, or the EPS watchdog time is increased to ensure that a power-cycle will not occur.

To program the failsafe image using a JTAG programmer supported by OpenOCD, you will need to run the following command:

Alternatively, to program using the SEGGER JLink, you can program the failsafe image as follows:

It is usually a good idea to carry out a hard reboot (a power cycle) of the OBC after programming the failsafe image.

If you have a terminal emulator running connected to the debug serial connection, you should see messages from the onboard software appearing very similar to those you saw when running the example Linux deployment.

Once programmed, you can connect TMTCLab to the running Kryten deployment. As described above, this uses a serial connection, as shown in [fig:lab_tcpClientConnection]. The baud rate should be changed to 57600 - the baudrate specified in all our Kryten example deployments.

Finally, the SCDB generated in Section 12.4 should be loaded into TMTCLab, and you should be able to interact with the deployment in exactly the same way as for the example Linux deployment in 6.5. The components which are available, and the parameter and action IDs to use, will be different.

ACS run factory tests on each Kryten before it is shipped out. These tests can sometimes leave the MRAM corrupted. Corrupted MRAM will cause the memory controller to raise an exception within the CPU. This will result in the board boot looping. It’s possible to tell that this is the cause of boot looping by observing the debug output. In this case the debug output will show the EDAC MRAM error count to be non-zero. For example:

To fix this issue you will need to erase the board’s MRAM. This can be done by running:

Once a failsafe image is up and running, the OBC component can be used to uplink a primary image, as mentioned in Section 12.1.2. A primary image should be built with the correct linker script setting in the .mk file as explained towards the end of Section 12.4. In this example, we assume demo_kryten has been build as a primary image.

Before uplinking, the binary image may need to be aligned. To uplink the image via TMTCLab the size of the image in 16-byte rows and its CRC are required. The image_crc.py script can align images and return the required information. Run:

This should show something similar to:

To uplink this primary image, connect to the failsafe image using TMTCLab. Find the OBC.image1 parameter. In this example, there are 12429 rows of 16 bytes, and this is what is uploaded via TMTCLab. Set the first row to 0 and the last row to 12428 (one less than the total number of rows), and tick Resize. Now click uplink and select the binary. The packet monitor should show packets being uplinked. Additionally the transfer window should show the progress of the uplink.

Once the uplink is complete, you should be able to confirm all the rows were uplinked by querying the length of the OBC.image1 parameter and checking its value against the image_crc.py output (e.g. 12429 in the example above). The next thing to do is update the CRC for the newly uplinked image by invoking OBC.updateImageCrc with 01 as the argument. Having invoked this action, OBC.imageCrc[1] should match the CRC given by image_crc.py (0x955BCA9E in this example).

This method allows new primary images to be uplinked during flight. New primary images should always be uplinked from the failsafe image.

It is possible to use the program.py script to replace the primary image on a Kryten. This is much faster than using the on-orbit uplink mechanism described above.

To do this, a tag file for the primary image needs to be created. The tag file contains metadata corresponding to the image such as its CRC and length. To create the tag file for the demo_kryten binary, run the following command:

The image and its corresponding tag can then be programmed as follows:

To use a SEGGER JLink, add --debugger=jlink as for the commands in Section 12.6.1.

These programming commands assume the the image was built with primary1.lds. For an image built with primary2.lds, change the primary1 option to primary2.

Both scripts will automatically update the CRC so after the script runs, it’s possible to just check the CRC for the image matches.

Once a primary image has been uplinked/programmed, it can then be booted into. To do this, the boot priority for the OBC must be set as well as the new image being marked as stable.

Note that if an image’s CRC does not match its contents, booting will fail. This can be checked by examining the imageValid parameter from the failsafe image.

The failsafe image is an image which is stored on the AVR32UC3C internal flash storage. It is not intended to be modified in flight. Due to storage sizing restrictions these images cannot be larger than 512KiB. It is recommended that all payload and mission code is placed in the primary image. Failsafe images should only be run when primary images are unstable.

The failsafe image is programmed into the internal flash of the AV32UC3C part. To program the board you are required to have the AVR Dragon programmer plugged into your machine (and available in your VM). The appropriate JTAG harness should also be connected to the A3200. To begin programming of the latest built failsafe image run

Primary images are stored in external flash. If selected during the boot process they are then loaded into RAM and executed. It’s possible to store two primary images in the external flash. Each image can be up to 1MiB big. When a primary image is stored in external flash it also stored along with its length and a CRC of the data.

The example deployment provides access to a GSW600 as well as subsystems contained in the A3200 itself. Documentation for each of the components provided in the deployment can be found by reading the generated documentation for the deployment. To generate the documentation follow the same steps as in Section 6.3.4. When prompted for the settings used to create the deployment, select

The umbilical TM/TC connection transfers TM/TC packets over serial. As asynchronous serial is a byte-wise stream, we utilise a custom framing protocol to locate the beginning and end of packets (this protocol is referred to as PacketStream in the component library and deployment). The TMTC Lab software can connect either to a TCP/IP server to transfer TM/TC packets or a serial connection; we want to connect to the latter.

The debug console is a straightforward serial character stream and can be viewed in any suitable terminal emulator, we use minicom. The console output uses linux line endings, so you may need to enable implicit carriage returns in your terminal emulator. The demonstration deployment for the A3200 uses the following serial settings:

Note that it is not necessary to use minicom with demo_gs_a3200, as the TMDebug component redirects stdout to TMTCLab, as explained in Section 9.1.3.3.

The bootloader deployment is required for bootloading images on the PC1.5 platform. On startup, this deployment will initialise the platform and run the bootloader. The bootloader will then either select a valid software image to jump to, or jump to the failsafe image instead. The configuration store uses a specific 32 kilobyte area in memory mapped FRAM.

The watchdog on board the PC1.5’s STM32 CPU resets the board after a maximum of approximately 16 seconds. Each time the kick task runs it uses 1 unit of "credit". Once the credit reaches 0, the kick task no longer kicks the watchdog. The credit is restored to its chosen maximum value from the restore task. The kick tasks runs at the highest priority and the restore task is at the lowest.

The GenerationOne FSDK builds using GCC; to build for the PC1.5 the arm-none-eabi toolchain is used. This toolchain is already set up in the Gen1 virtual machine.

To manually set up this toolchain, run download.sh from the /OBSW/Toolchains/arm-none-eabi directory. This will retrieve the archive containing the necessary toolchain from the internet. THis should then be extracted into a suitable location, such as /opt, and then PATH should be adjusted to include the binary folder of this toolchain.

Programming uses the STM32_Programmer_CLI supplied by STM as a download on their website. The BAL wrapper script parses arguments to make the STM32_Programmer_CLI easier to use. The wrapper script should be transferred to the computer connected to the hardware and placed into a suitable location, and then the PATH variable should be adjusted to include the folder of the location of the script. Usage of the script is covered later.

The umbilical TM/TC connection transfers TM/TC packets over serial. As asynchronous serial is a byte-wise stream, we utilise a custom framing protocol to locate the beginning and end of packets (this protocol is referred to as PacketStream in the component library and deployment). The TMTCLab software should be configured to connect to a serial device to work with the umbilical connection.

The debug console is a straightforward serial character stream and can be viewed in any suitable terminal emulator such as minicom. The console output uses linux line endings, so you may need to enable implicit carriage returns in your terminal emulator. The demonstration deployment for the PC1.5 uses the following serial settings:

Before the example deloyment can be programmed the bootloader image must be programmed, which when built is located in na_pc15_bootloader/na_pc15_boot.

To program the bootloader, assuming there is only one board connected to the computer, run the following command from the same directory as the deployment:

If there is a terminal emulator running connected to the serial output, you should see the messages from the onboard software logging the system startup.

There must always be a failsafe image programmed onto the PC1.5 platform; if you intend to use a primary1 or primary2 image, a failsafe is required as the starting point and a fall-back.

After the bootloader image programming is complete, assuming there is only one board connected to the computer, to program the example deployment in the failsafe image run the following command from that same directory:

It should be noted once the bootloader image is programmed, it need not be programmed again. That is to say, if you change the failsafe deployment for example and wish to re-program the PC1.5 with that new deployment, then only the failsafe image need be programmed. This is because as the system starts back up after a reboot, the bootloader will still be programmed and will jump to the memory offset of the newly programmed image.

If there is a terminal emulator running connected to the serial output, you should see the messages from the onboard software logging the system startup and successful programming of the failsafe image.

Once programmed, you can connect TMTCLab to the running PC1.5 deployment. As described above, this uses a serial connection as shown in [fig:lab_serialConnection].

Finally, the SCDB generated in Section 14.3 should be loaded into TMTCLab, and you should be able to interact with the deployment in exactly the same way as for the example Linux deployment in Section 4.2.8. The components which are available will be different.

An example of a Q8 FSDK project is demo_q8_system. The project will produce a rootfs packaged into a xdi file. xdi files can be installed to a Q8 using tools provided by Xiphos.

To use this example, a release provided by Xiphos needs placed in the directory. After the release has been added to folder the project SDK can be installed and project xdi built by running the following scripts.

demo_q8_depl is an example Gen1 deployment with components set up to monitor and manage Q8 specific functionality.

It has a simple SpacePacket communication stack which can be accessed via a TCP server running on port 51423. You will need IP network connectivity to the Q8 in order for the MCS to connect.

The FSDK software is capable of producing system images (xdi files) which can be programmed to a Q8 and its J/S variants. Producing system images for Xilinx dev boards is currently not supported.

External software can be compiled for the Q8 after sourcing the shell enviroment for the installed SDK.

Autoconf projects will need configured with the correct host and target before running make.

A systemd service, can1.service, is configured to bring up the CAN bus at 1MBit.

The device tree is included with the Xiphos release. It can be decompiled for modification and then recompiled using the following steps.

Install dtc if not already installed

Strip the mkimage header from devicetree.img

Decompile the devicetree binary

After editing, compile the source file

Add the mkimage header used by uboot

The demo_nanoobcv2 is configured to communicate with TMTCLab via a serial port as follows:

The GPIO0 pins are found on the NANOobc’s "User Connector" P1.

We recommend using a serial to USB adapter as elsewhere. TMTCLab can then be configured to connect to the serial adapter to communicate with the board (similar to that shown in [fig:lab_serialConnection]).

The debug console is available on the NANOobc’s "PicoSkyLINK Port" P3. We recommend using SkyLabs' provided PicoSkyLINK EGSE to receive characters from the debug console.

The PicoSkyLINK EGSE also provides the essential ability to program software onto the board.