EnduroSat OBC How-to Guide
A guide to running Flightkit software on the EnduroSat onboard computer.
1. Introduction
The EnduroSat onboard computer (OBC) is built around an STMicroelectronics STM32H7 device with a wide range of integrated peripherals. The board hosts additional peripherals, some of which are currently supported by Flightkit.
|
Flightkit support for the EnduroSat OBC is at an early stage and only limited OBC functionality is currently available. This will be expanded in forthcoming releases. Note also that support which currently is present may be subject to breaking changes in forthcoming releases! |
This guide provides an overview of:
-
How flight software images are stored on the EnduroSat OBC.
-
How images are run on the EnduroSat OBC.
-
How to build missions for the EnduroSat OBC.
-
How to program the EnduroSat OBC.
2. Technical Background
In this section we give an overview of the EnduroSat OBC support provided with
FlightkitFoundation. This includes details on how the EnduroSat OBC’s onboard
memory is used, how different software images are managed, and the different
component types we provide for interacting with the onboard peripherals.
2.1. The Memory Map
The memory map used by Flightkit flight software on the EnduroSat OBC makes use of the STM32H7 memory map used by ST Microelectronics.
|
The ST Microelectronics memory map is detailed in the reference manual for the relevant STM32H7 MCUs (RM0433 Rev8). Specifically refer to Table 7 ("Memory map and default device memory area attributes") in Section 2.3 ("Memory organization") on page 130. |
While the STM32H7 memory map provides for a wide range of different memories and peripherals, many of these memory-mapped regions are not relevant to the EnduroSat OBC support in Flightkit.
The EnduroSatObc board in Flightkit uses the memory map as follows:
-
All code (
.text) and readonly data (.rodata) is placed in the 2MiB flash region starting at0x08000000. This region is split into 4 areas - one for our bootloader, one for the failsafe flight software image, and two for flight software images which may be upgraded on orbit. -
The main stack, used during initialisation and interrupt handling, is maintained in the tightly coupled data RAM (DTCM) region starting at
0x20000000. -
All initialised (
.data) and zeroed (.bss) variables are placed in the 512KiB AXI SRAM region in the D1 power domain.
|
The SRAM1, 2, and 3 regions (which are in the D2 power domain) and the SRAM4 region (in the D3 power domain) may also be used. These regions are not contiguous, however, which makes supporting them difficult out-of-the-box. If you need to use more than the limited 512KiB RAM available the AXI SRAM region then please get in touch. Bear in mind that, as far as we are aware, the EnduroSat OBC has no memory-mapped external memory devices, so may not be suitable for high memory-usage applications. |
The following table shows the memory map used by Flightkit flight software on the EnduroSat OBC, including MPU attributes applied at runtime.
| Range | Size | Usage | MPU Attributes |
|---|---|---|---|
0x08000000 |
128 KiB |
Bootloader |
RO during Bootloader execution, otherwise RW XN |
0x08020000 |
640 KiB |
Failsafe image |
RO during failsafe execution, otherwise RW XN |
0x080C0000 |
640 KiB |
Programmable image 1 |
RO during image 1 execution, otherwise RW XN |
0x08160000 |
640 KiB |
Programmable image 2 |
RO during image 2 execution, otherwise RW XN |
0x20000000 |
8 KiB |
Main stack (used for initialisation and interrupt handling) |
RW XN |
0x24000000 |
512 KiB |
All |
RW XN |
2.2. Image Management
As can be seen in The Memory Map, we provide support for executing multiple flight software images from the EnduroSat OBC’s executable flash memory.
This section discusses the various deployments, components and data involved in managing these flight software images.
2.2.1. The Bootloader Image
The bootloader image is stored in the first sector of flash and is responsible
for carrying out user image verification and selection when the board starts up
or resets. BAL provide a deployment in the EnduroSatObcDemo mission to serve
as the bootloader. More information on using the BAL deployment is given
below.
|
It is not expected that users will write their own bootloader deployment, though it is possible in principle. If you require some special behaviour in the bootloader we recommend you get in touch with BAL support to discuss your needs. |
2.2.2. Boot Configuration
To store information about which of the 3 main images (failsafe, programmable image 1 and programmable image 2) should be executed, the BAL Bootloader deployment makes use of the EnduroSat OBC’s onboard FRAM. This is a small, persistent and robust RAM device accessed via SPI.
For each of the failsafe, image 1 and image 2 the following information is persisted in the FRAM:
-
Image priority. This gives an ordering over the 3 images. Images with numerically higher priority values are preferred over those with lower values. The failsafe image always has a priority of 1.
-
Image stability. This is a boolean flag which must be true in order to consider an image for booting. The failsafe image is always stable.
-
Image boot count. This is a counter useful for diagnosing reboots.
This structure is defined by the drivers.endurosat.boot.BootUtil module and
used by the drivers.endurosat.boot.Bootloader and
drivers.endurosat.boot.BootControl component types.
The drivers.endurosat.boot.BootControl component type has parameters which
can be used to affect image priority and image stability, and thereby control
the result of the boot procedure described below. This
is briefly described later in this guide. You
may also wish to refer to the BootControl component type documentation for
more detail.
2.2.3. The Boot Procedure
When the EnduroSat OBC starts, execution always begins at the start of flash. As shown above, this is where the BAL bootloader image is programmed.
As a deployment, the BAL bootloader carries out normal board and component
initialisation. Once this is complete the boot.Bootloader component
instance’s boot task will run.
The boot task carries out the following procedure:
-
The next image to boot is first determined. The logic for this is provided by the
drivers.endurosat.boot.BootUtilmodule’sBootUtil_getNextImage()function as follows:-
Each image is given an "effective priority".
-
The failsafe image is always given an effective priority of 1.
-
If the first programmable image is stable its effective priority is the same as its priority. If it is not stable it is given an effective priority of 0.
-
If the second programmable image is stable its effective priority is the same as its priority. If it is not stable it is given an effective priority of 0.
-
The images are then evaluated for validity in descending effective priority order. If images have equal effective priority then image 2 is preferred over image 1 and the failsafe, and image 1 is preferred over the failsafe. An image is valid if the 32-bit CRC value embedded in it matches the CRC value calculated over the image data.
-
As soon as a valid image is found, it is selected for boot.
-
As soon as the failsafe image is encountered it will be selected for boot, regardless of its validity. A warning will be printed if it is invalid.
-
-
The
boottask then increments the next image’s boot counter in the boot configuration structure. -
The next image’s stable flag is cleared in the boot configuration. In combination with the image selection given above, this prevents short period boot loops by removing the next image from consideration if it fails to boot successfully and be marked as stable (whether by onboard automation or operator interaction).
-
The updated boot configuration is stored in the FRAM. In the unlikely event this fails (due to some communication or hardware issue) the next image is still booted, but the updated boot configuration will not be stored.
-
The
boottask prepares to jump to the new image by flushing the console, disabling the MPU, disabling all interrupts in the ARM’s NVIC and ensuring the master stack is selected for use. -
Finally, the next image’s reset vector is jumped to, at which point the next image will begin execution.
3. Working With the EnduroSat OBC
This section outlines various procedures which you will need to use when working with the EnduroSat OBC
3.1. Installing the Toolchain
Flightkit support for the EnduroSat OBC requires the same toolchain as the ACS
Kryten: version 10.3-2021.10 of ARM’s arm-none-eabi toolchain.
|
This is the same version as required to use Flightkit’s ACS Kryten support, so if you have already installed it via the ACS Kryten How-to Guide then you can skip this section. |
|
A very similar version of this toolchain is available directly from the Ubuntu package repositories. However, it supplies a C standard library which is built without support for features which our EnduroSat OBC board support code uses. As a result you should not use the toolchain in the Ubuntu package repositories. |
Once downloaded:
-
Extract the archive. The
/optdirectory is a common location used for storing external toolchains. -
Add the extracted
…/gcc-arm-none-eabi-10.3-2021.10/bindirectory containing the toolchain executables to yourPATH. -
Verify that the toolchain was successfully added to the path by restarting your shell and running the following command:
arm-none-eabi-gcc --version
3.2. Building Missions
With the toolchain successfully installed, you can build flight software to run on the EnduroSat OBC.
3.2.1. Building the Demo Mission
Folow these steps to build the EnduroSatObcDemo mission from the
FlightkitFoundation bundle:
-
Create a new workspace for building the mission in.
-
Require the
FlightkitFoundationbundle so that the tooling can access its contents by running the following command:hfk workspace bundle require FlightkitFoundation -
Build the
EnduroSatObcDemomission from theFlightkitFoundationbundle by running the following command:hfk mission build EnduroSatObcDemo
This builds all the deployment instances in the mission, and generates a
mission database for interacting with them via HELIX Lab. The binaries and
database can be found in
output/bundles/FlightkitFoundation/X.Y.Z/missions/EnduroSatObcDemo/, where
X.Y.Z is the version of FlightkitFoundation you are using.
3.2.2. Building Your Own Missions
In order to build your own Flightkit missions to run on the EnduroSat OBC you must:
-
Provide the correct
<Architecture>element in your deployment type. -
Use one of the EnduroSat OBC build configurations in your mission.
-
Include various required component instances in your deployment type.
Once this is done, building the deployment binaries uses the same approach as
for the EnduroSatObcDemo mission above. The following instructions give more
details on the above points:
-
You must ensure your
deploymentType.xmlhas the following element before the<Implementation>:<Architecture> <Board name="EnduroSatObc"/> <OSAL name="Freertos"/> </Architecture>You may then add
EnduroSatObc-specific component types to your deployment type. -
You must use a matching
<Architecture>element whenever you instantiate your deployment type in amission.xml. -
Your deployment instance must also have a valid
<BuildConfiguration>element. You may provide your own, but we recommend using one of the following, all found inFlightkitFoundation:-
EnduroSatObcBootloaderif you need to build your own bootloader, instead of using the BALBootloaderdeployment inEnduroSatObcDemo. This is not recommended. -
EnduroSatObcFailsafefor building images for the failsafe slot. -
EnduroSatObcImage1for building images for the image 1 slot. -
EnduroSatObcImage2for building images for the image 2 slot.
-
-
Your deployment must instantiate the
drivers.endurosat.periph.Watchdogcomponent type. This is because the BALBootloaderdeployment switches on the MCU’s watchdog, and it cannot be switched off without an MCU reset. As a result, any booted deploment must periodically kick the watchdog. TheWatchdogcomponent type, when correctly configured, will take care of this for you.
You may then build your mission, as above, using hfk mission build. Your
built binaries will be installed to output/missions/YourMission/…
If you wish to use the drivers.endurosat.boot.BootControl component type to
control the boot procedure described above, you may
instantiate it in your deployment. In order for it to work correctly with the
BAL Bootloader deployment, the following additional components are required:
-
drivers.endurosat.io.bus.SPIControllermust be instantiated to give access to the SPI bus connected to the EnduroSat OBC’s onboard FRAM device. -
storage.SPIFrammust be instantiated to provide access to the data on the FRAM device. It must be connected to theSPIControllerinstance. -
storage.config.StaticConfigStoremust be instantiated and configured to store persistent configuration data on the FRAM device. It must be connected to theSPIFraminstance. A 1KiB region at the start of the FRAM device and associated with theBootControlcomponent ID is required. It must be configured with a CRC32 integrity check. -
drivers.endurosat.boot.BootControlmust be instantiated, and itsdefaultConfigattribute set to match the configuration store index of theStaticConfigStoreinstance (most likelydefaultConfig="1").
Examples of these instances and connections may be found within the
EnduroSatObcDemo mission.
3.3. Connecting to the EnduroSat OBC
There are three main connections that you will need to set up when working with the EnduroSat OBC: the telemetry and telecommand (TMTC) link, the debug link and the programmer.
The following sections will explain how to set up each one.
3.3.1. TMTC Link
The TMTC link is used to transport telemetry and telecommand (TMTC) packets between the EnduroSat OBC and the PC running HELIX Lab.
The deployment instances in the EnduroSatObcDemo mission are configured to
provide the TMTC link using USART1 via an onboard RS485 transceiver.
To set up the TMTC link for the these deployment instances connect a suitable USB to RS485 adapter to the EnduroSat OBC’s SYSTEM1 RS485 connector, shown in Figure 11 of the EnduroSat OBC User Manual (version 4.19).
The serial settings for the TMTC link are set as follows:
-
115200 baud
-
8 data bits
-
No parity bit
-
1 stop bit
-
No flow control
HELIX Lab is only capable of exchanging TMTC packets with a spacecraft via a
TCP server. For this reason, you will also need to configure your host PC to
forward packets destined for the TCP port that HELIX Lab transmits to to the
serial port that your TMTC link is connected to, and vice versa. There are many
ways this can be achieved, however we recommend you use a tool such as
ser2net or socat. If you are unfamiliar with how to use these tools, refer
to their documentation online.
3.3.2. Debug Link
The debug link is used for transporting debug information from the EnduroSat OBC to the PC where it can be displayed.
The EnduroSatObc board is configured to use UART8 with LVTLL voltage levels
for debug output by default.
To set up the debug link for deployment instances which use this default console configuration connect a suitable USB to serial adapter to the EnduroSat OBC’s CSK connector. Specifically, as shown in Figure 6 of the EnduroSat OBC User Manual (version 4.19), connect the adapter’s RX line to pin H1.33 - the OBC’s TX line.
There is no need to connect the adapter’s TX line to the OBC.
To view the debug produced by the board on the host PC run a terminal emulator,
such as minicom.
The serial settings for the debug link are set as follows:
-
115200 baud
-
8 data bits
-
No parity bit
-
1 stop bit
-
No flow control
You must apply these settings to your terminal emulator so that it interprets the incoming data correctly. The debug produced by the board uses Linux line endings, so you may also need to enable implicit carriage returns in your terminal emulator to view the data properly.
3.3.3. Programmer
To program the EnduroSat OBC you will need to use an ST-LINK/V2 programmer.
-
Connect the ST-LINK/V2 programmer to the EnduroSat OBC according to EnduroSat’s documentation.
-
Install the STM32CubeProg tool from STMicroelectronics on the host machine.
If the programmer is able to communicate with the EnduroSat OBC you should be able to run the following command:
STM32_Programmer_CLI -c port=JTAG
and see output similar to the following:
-------------------------------------------------------------------
STM32CubeProgrammer v2.18.0
-------------------------------------------------------------------
ST-LINK SN : 38FF6B06304E4B3008211443
ST-LINK FW : V2J37S7
Board : --
Voltage : 3.23V
JTAG freq : 9000 KHz
Connect mode: Normal
Reset mode : Software reset
Device ID : 0x450
Revision ID : Rev V
Device name : STM32H7xx
Flash size : 2 MBytes
Device type : MCU
Device CPU : Cortex-M7
BL Version : 0x90
3.4. Programming the EnduroSat OBC
As of Flightkit 2026.4.0, we provide a Python script to validate and program images onto the EnduroSat OBC. This script is installed with Flightkit.
|
At this stage it is important to emphasise that images built with the different build configurations we provide - bootloader, failsafe, image 1 and image 2 - are not interchangeable. A failsafe image binary cannot be programmed to the image 2 slot, for example. The In short: you must be sure of the image type you are programming when you program it! |
3.4.1. Programming the Bootloader
There must always be a valid binary at the base of the EnduroSat OBC flash, as
this address is always executed when the board is powered up. Our component
types and deployments expect the BAL Bootloader deployment to be programmed
into this first flash sector.
Follow these steps to ensure your OBC has the BAL Bootloader deployment
programmed correctly:
-
If you have not already built it, build the
Bootloaderdeployment from theEnduroSatObcDemomission. Within your workspace, which must requireFlightkitFoundation:hfk mission build EnduroSatObcDemo BootloaderThis will build the
Bootloaderdeployment binary and install it tooutput/bundles/FlightkitFoundation/X.Y.Z/missions/EnduroSatObcDemo/Bootloader/Bootloader/Bootloader.bin, whereX.Y.Zis the version ofFlightkitFoundationyou are using. -
Make sure the OBC is powered from a stable power supply with enough current to support flash programming. EnduroSat may be able to advise on appropriate power connections.
-
Program the
Bootloaderdeployment using the following command, withX.Y.Zreplaced with the version ofFlightkitFoundationyou are using:hfk-esobc-program \ bootloader \ output/bundles/FlightkitFoundation/X.Y.Z/missions/EnduroSatObcDemo/Bootloader/Bootloader/Bootloader.binhfk-esobc-programdoes not examine the image data to determine which image slot it is built for, so take care when tab-completing the path to ensure you really are selecting a bootloader binary!The backslash characters and extra whitespace are included here for readability and may be omitted.
-
Once the
Bootloaderdeployment is programmed you should see the following debug output:INF: Deployment.c:201: Running deployment: INF: Deployment.c:202: - Deployment instance: Bootloader INF: Deployment.c:203: - Deployment type: endurosat.Bootloader INF: Deployment.c:204: - Target: Bootloader INF: Deployment.c:205: - Mission: EnduroSatObcDemo INF: Deployment.c:331: Deployment initialisation successful INF: Bootloader.c:165: boot.Bootloader: Entering bootloaderIf you have not yet programmed other images then you should then see the following messages:
ERR: BootUtil.c:255: Failsafe image is invalid but there are no better candidate images! INF: Bootloader.c:199: boot.Bootloader: Booting image 0 from slot 1This will repeat approximately every 16 seconds as the internal watchdog resets the board.
To complete boot, there must also be a failsafe image programmed. Follow the instruction in the next section to supply a failsafe image.
3.4.2. Programming Failsafe Images
The same programming script can be used to program failsafe images.
The following procedure demonstrates how to program a failsafe image using the
EnduroSatObcDemo mission’s BasicCommsDemo.Default deployment instance. The
same approach can be used for programming any binary that has been built for
the failsafe image slot using the EnduroSatObcFailsafe build configuration.
-
First, you must program a valid deployment to the bootloader slot before any other images will boot. If you haven’t done so yet, program the BAL
Bootloaderdeployment now, as described above. -
As always, make sure the OBC is powered from a stable power supply with enough current to support flash programming. EnduroSat may be able to advise on appropriate power connections.
-
Program the
BasicCommsDemo.Defaultdeployment using the following command, withX.Y.Zreplaced with the version ofFlightkitFoundationyou are using:hfk-esobc-program \ failsafe \ output/bundles/FlightkitFoundation/X.Y.Z/missions/EnduroSatObcDemo/BasicCommsDemo/Default/Default.binhfk-esobc-programdoes not examine the image data to determine which image slot it is built for, so take care when tab-completing the path to ensure you really are selecting a failsafe binary!The backslash characters and extra whitespace are included here for readability and may be omitted.
-
Once both the
BootloaderandBasicCommsDemo.Defaultdeployments are programmed, you should see the following debug output:INF: Main.c:338: HSE oscillator initialisation: OK INF: Main.c:359: LSE oscillator initialisation: OK INF: Main.c:380: CPU and bus clock initialisation: OK INF: Main.c:381: SYSCLK at 216000000 Hz INF: Main.c:382: HCLK at 108000000 Hz INF: Main.c:383: PCLK1 at 54000000 Hz INF: Main.c:384: PCLK2 at 54000000 Hz INF: Deployment.c:201: Running deployment: INF: Deployment.c:202: - Deployment instance: Bootloader INF: Deployment.c:203: - Deployment type: endurosat.Bootloader INF: Deployment.c:204: - Target: Bootloader INF: Deployment.c:205: - Mission: EnduroSatObcDemo INF: Deployment.c:331: Deployment initialisation successful INF: Bootloader.c:165: boot.Bootloader: Entering bootloader INF: Bootloader.c:199: boot.Bootloader: Booting image 0 from slot 1 INF: Board_Boot.c:310: Slot 1 stored image size: 194272 bytes INF: Board_Boot.c:314: Slot 1 stored image CRC: 0x1D6302CF INF: Deployment.c:369: Running deployment: INF: Deployment.c:370: - Deployment instance: Default INF: Deployment.c:371: - Deployment type: endurosat.BasicCommsDemo INF: Deployment.c:372: - Target: BasicCommsDemo INF: Deployment.c:373: - Mission: EnduroSatObcDemo INF: Deployment.c:528: Deployment initialisation successfulThe reported image size and image CRC will likely be different.
Notice that because the bootloader is a true Flightkit deployment, the startup
code in Deployment.c correctly reports that 2 deployments have been
intialised - first Bootloader, then BasicCommsDemo.Default. This is
expected. When you use your own failsafe (or programmable images) this pattern
will be the same.
The failsafe image should now execute indefinitely and you should see no watchdog resets.
3.4.3. Programming Other Images
Programming images to the image 1 or image 2 slots follows the same procedure as that for failsafe images:
-
Images built with the
EnduroSatObcImage1build configuration for the image 1 slot must be programmed as follows:hfk-esobc-program \ image1 \ path/to/Image1.bin -
Images built with the
EnduroSatObcImage2build configuration for the image 2 slot must be programmed as follows:hfk-esobc-program \ image2 \ path/to/Image2.bin
|
|