System Integration

This page describes how to integrate a new system into the SUNRISE framework. The steps below represent a recommended approach to create a SysAPI-compliant, deployable system. Any approach that results in a SysAPI-compliant system is valid.

Step	Description
1 - Prerequisites	Review the integration requirements and assess whether the system to be integrated will be able to fulfill them
2 - Docker Image	Create a Linux-based Docker image that meets SysAPI requirements and contains a working runtime environment for the system
3 - System Definition	Collect the system metadata, parameters and result definitions; generate and validate a `sysdef.json` file
4 - SysAPI Implementation	Implement the SysAPI entry points (e.g. using the optional System Adapter template); test locally
5 - Git Repository	Ensure that the git repository contains all required files and fulfills the SysAPI requirements
6 - Integration Testbench	Configure and run the testbench; fix any reported failures
7 - Deployment	Hand off `sunrise_integration.json` and the access credentials to the SUNRISE Runtime Manager

System Adapter Template

To simplify SysAPI-compliant system development, a ready-to-use System Adapter Python template is provided. It handles all SysAPI boilerplate - argument parsing, SysDef/SysCfg loading, parameter merging, result file checking, and OS signal handling - so that the system developer only needs to implement the system-specific logic.

The following methods can be overridden in a derived class:

Method	Required	Description
`_build(parameters)`	Optional	Build/compile the simulation
`_run(parameters)`	Required	Execute the simulation
`_stop(signum, frame)`	Optional	Handle `SIGTERM`/`SIGINT` gracefully
`_delete(parameters)`	Optional	Clean up external resources

To use the template for a new system, copy system_adapter.py into the system git repository and implement the methods in the derived class. The adapter is then invoked directly by the build_command and run_command entries in the SysDef.

Using and Testing the System Adapter

For usage information run:

python system_adapter.py --help

Build the simulation:

# With default values from SysDef
python system_adapter.py build

# With custom SysCfg
python system_adapter.py build example_syscfg.json

Run an app on the simulator (requires the completion of the previous build step):

# With default values from SysDef
python system_adapter.py run

# With custom SysCfg
python system_adapter.py run example_syscfg.json

Stop a building or running simulator by sending SIGINT or SIGTERM - e.g. by pressing CTRL+C:

# Stop an ongoing build
python system_adapter.py build  # press CTRL+C to stop

# Stop an ongoing run
python system_adapter.py run    # press CTRL+C to stop

Delete simulation artifacts (optional - cleans up external or generated resources):

# With default values from SysDef
python system_adapter.py delete

# With custom SysCfg
python system_adapter.py delete example_syscfg.json

Testbench Usage

The SUNRISE Integration Testbench is an automated validation tool that verifies a system's SysAPI compliance before deployment. It exercises the full lifecycle - build, run, and delete - against the actual Docker image and system adapter, and checks that all declared results are produced correctly.

Setup and usage instructions are documented in the README of the testbench repository. In brief, the workflow is:

Clone the testbench repository.
Create a test_config.json pointing to the system's git repository and Docker image.
Run integration_tests.py and iterate on any reported failures until all tests pass.

Tip

The testbench repository provides an end-to-end example that exercises the full integration workflow using the Demo System as the system under test and then integrates it into the SUNRISE Demonstrator.