README.md

# Software-Defined Industrial System (SDIS)

## Project Overview

SDIS is a reference implementation that proves the viability of using cloud-native approaches and virtualization in resource-constrained embedded environments for industrial automation and energy management. The system supports concurrent execution of near real-time control and compute-intensive workloads like machine vision/AI, all while maintaining levels of deterministic performance.

## Key Features

- **Hardware-Independent Design**: Built for Arm SystemReady certified platforms, enabling easy portability across different hardware
- **Real-Time Performance**: Supports deterministic operation for critical workloads
- **Mixed-Criticality Support**: Successfully runs both real-time control and best-effort AI workloads concurrently
- **Virtualization**: Optionally uses XEN hypervisor for secure workload isolation and resource management
- **Flexible Deployment**: Supports dynamic workload combinations (1 real-time + up to 4 best-effort workloads)
- **Edge AI Capable**: Demonstrated with multi-camera machine vision processing using Arm NN

## Technical Stack

- **Hardware**: Arm SystemReady certified platforms (tested on Xilinx ZCU102 and Raspberry Pi 4)
- **Hypervisor**: XEN (bare-metal configuration)
- **Real-Time Support**: PREEMPT-RT Linux patch
- **AI/ML**: Arm NN inference engine with GPU acceleration
- **Containerization**: Optional container support for both workload types

## Benefits

- Reduced development time through hardware abstraction
- Lower latency for critical applications
- Enhanced security through workload isolation
- Decreased reliance on cloud resources
- Improved sustainability through efficient resource utilization

## System Diagram

![SDIS Architecture](/docs/softwarediagram.jpg)

## Getting Started

### Bluegreen machines

This project contains [kas](https://kas.readthedocs.io/en/latest/index.html) configuration to download meta-bluegreen and all required layers.
[EWAOL](https://gitlab.arm.com/ewaol/meta-ewaol) is the reference implementation of the [SOAFEE](http://soafee.io) project and is used as a baseline for bluegreen
project.

### 1. Tools

You must install essential host packages on your build host. The following command installs the host packages based on an Ubuntu distribution:

```shell
sudo apt install gawk wget git diffstat unzip texinfo gcc build-essential chrpath socat cpio python3 python3-pip python3-pexpect xz-utils debianutils iputils-ping python3-git python3-jinja2 libgl1 libglx-mesa0 pylint xterm python3-subunit zstd liblz4-tool
```

Install the kas tool, ensuring you have a version 3.0.2 or greater. The preferred method is installation using the package manager of your Linux distribuntion.


#### 1.a. Preferred: Install kas using package manager on Linux

On Ubuntu Linux:

```shell
sudo apt install kas
```

#### 1.b. Alternative: Install kas using pip

If you can't install kas as above, you can follow the instructions [here](https://kas.readthedocs.io/en/latest/userguide.html).

However, please note some issues where encountered when using kas installed from pip. See Known issues, below.

### 2. Build

To build bluegreen, use the helper script `build.sh` which gives a consistent way of building for the target platforms.

`build.sh` is located in the root of this project. It relies on kas to do the actual build.

```shell
# Building for the generic-arm64 target
./build.sh generic-arm64 baremetal
```

To view alternative build targets see [Generic arm64 Documentation](docs/generic-arm64.md)

Built image will be available at: `build/generic-arm64/tmp_*target*/deploy/images/*target*/bluegreen-*target*.wic`

### 3. Install

Installation instructions for each platform is outlined in the documentation for that platform. Check out the table in the status section below.

#### 3.1. Status

|   Machine     | Status | Documentation |
|---------------|--------|---------------|
| generic-arm64 | Ok     | [Generic arm64 Documentation](docs/generic-arm64.md) |

#### 3.2. Machine specific notes

##### 3.2.1. generic-arm64

Put UEFI firmware on the sdcard and the bluegreen image on a SD Card.

##### 3.2.2. Xillinx ZCU102

See [ZCU102 SD card boot documentation](docs/zcu102_sd_boot.md).

##### 3.2.3. Raspberry Pi 4

This has been tested on the RPi4 using [SystemReady compliant UEFI firmware](https://github.com/pftf/RPi4).

### 4. Known issues

* On Ubuntu 22.04, using `pip` to install `kas` in a Python virtual environement produced a tool that wasn't able to finish the build. Root cause is unknown, workaround is to get `kas` from with `apt install`:
```shell
sudo apt install kas
```

* On Ubuntu 22.04, it was necessary to manually install libtinfo5:
```shell
sudo apt install libtinfo5
```

## Project Status

This is a proof-of-concept implementation demonstrating the viability of cloud-native approaches in industrial edge computing.

## Licensing

This project combines multiple open-source components under various licenses:

MIT License: arm-compute-library, armnn, SOAFEE/EWAOL, kas, resize-tool
Apache-2.0: armnn tensorflow lite, containerd, docker, k3s, runc, flatbuffers, openvswitch
GPL-2.0-only: kvm, dpdk, xen, Yocto/Yocto Linux/Preempt-rt
Other: go (BSD-3-Clause), usbids (GPL-3.0-only), libosinfo (LGPL-2.1-only & GPL-2.0-only)

All newly created software files, including build system and documentation, are under MIT License.
Important Restrictions
This project explicitly prohibits:

Any code that emulates Arm or third-party instruction sets
Any code that emulates Arm or third-party hardware IP

See LICENSE for complete details.