2023 November Release

This release is for version 1.0.0-gamma of the KOS platform.

Kry10 Servers

Orbit has been removed for this release and has been replaced with the Kry10 Servers. These are two new web server applications, the Studio Server and Fleet Server. Each server is designed to aid the different stages of a device’s life cycle, from early development steps through to managing a fleet of devices in the real world.

Studio Server

The Studio Server is intended to help with the very first steps of a device’s development life cycle, such as creating new systems, tracing apps and remote debugging, so that developers only need to focus on the unique problems they are solving and not the intricacies of deploying production KOS systems.

The Studio Server is bundled into the KOS SDK package (installed through kos-tool install), making it easily accessible to start up and use in a development environment. Assuming the SDK is installed, the Studio Server can be launched by running kos-tool server.start.

Fleet Server

The Fleet Server is designed for the professional deployment manager and provides tools to manage part, or all, of a fleet of devices running KOS. This includes support for updating device’s software, collecting data and monitoring device health. This version can either be self-hosted (e.g in an air-gapped environment) or deployed into a cloud environment.

The cloud hosted Fleet Server (beta version) is available at https://fs-beta.dev.kry10.com/.

Board Support

Portenta X8

KOS now supports the Arduino Portenta X8, an industrial-grade SOM that features the NXP® i.MX 8M Mini Cortex®-A53 quad core and the STMicroelectronics STM32H747 dual core. KOS currently only runs on the i.MX 8M Mini Cortex.

There is intermediate device support for this board and includes:

• Timer
• Serial
• Ethernet
• MMC controller interfacing with the on-board eMMC

It is possible to connect to a Kry10 server (both the Studio and the Fleet Server) with the board and also enable persistent booting.

Application Environments

MicroVMs

KOS now provides a virtualisation platform that is geared towards letting users deploy lightweight micro virtual machines or microVMs. microVMs are lightweight with respect to the hardware resource requirements needed by the VM (e.g. memory footprint) and the minimal machine interface it presents to the guest (e.g. limited guest devices and functionality).

A KOS microVM consists of:

• A single-core CPU and a configurable amount of RAM.
• Support for booting a Linux kernel guest (only), along with an initrd image.
• 1 virtio-net device for outbound network access, facilitated by the KOS tunnel.
• 1 virtio-console device for guest console access, facilitated by the KOS core serial component.
• Up to 5 virtio-blk devices for mounting file-backed images into the guest.

MicroVMs are only supported on a subset of KOS’s platforms. Platform specs that currently support microVMs include:

• imx8mm-evk,arch=aarch64,hyp=on
• qemu-arm-virt,arch=aarch64,hyp=on
• rpi4,arch=aarch64,hyp=on

Manifests

Manifest Assurance Checks

Introduced a new system manifest package, ManifestAssurance . The provides an Elixir library for inspecting KOS manifests and checking if they comply with security best-practices

Poukai

Added a new base system manifest layer package, Poukai, that bundles and instantiates common KOS core & standard packages into a single module. This abstracts away the set of common apps and configurations most standard KOS system will use, simplifying manifests specifications and enabling re-use.

Poukai bundles:

• a single message server - Poukai.msg0
• an RNG server - Poukai.rng_server
• a log server - Poukai.log_server
• an ethernet server - Poukai.ethernet
• a key store - Poukai.key_store
• a tunnel, for encrypted internet communication - Poukai.tunnel
• an admin component for connecting to a Kry10 Server (Studio or Fleet) - Poukai.admin
• basic tests to ensure the system works at start up - Poukai.self_test

Users can incorporate the Poukai layer into their Elixir manifest project, which they can then augment with their own applications e.g.

defmodule MyManifest do
 alias KosManifest.Context
 alias KosManifestSystems.Poukai
 import Context

 @behaviour KosManifest.System

 def kos_base_system(), do: Poukai

 def setup(context) do
   ...
   context
   |> put_app!(my_app)
   |> connect_protocol!(my_app, "kos_log_protocol", Poukai.msg_server())
   ...
 end
end

Packages

Kos.MicroVM: A new KOS Standard package for defining virtual machines that are specifically geared towards the MicroVM use case. This provides helper abstractions that when given a general VM definition, performs the required kos_manifest operations to ensure the VM is instantiated in the system.

Kos.I2CServer: A new KOS Standard I2C package implements I2C driver support for KOS’s various supported platforms. The server provides an interface for other applications to operate over a given I2C bus on the platform.

KOS SDK

kos-tool

Added a new command line tool, kos-tool. kos-tool provides a client command line interface to interact with and manage the KOS SDK on a developers host system. The command line tool provides utilities such as installing a new KOS SDK version, launching a development shell, starting a Studio server and bootstrapping a device with a KOS system. Running kos-tool --help will list all supported sub-commands.

GCC Toolchain Per-Architecture

The KOS SDK now declares and builds only one runtime per architecture. Needing a different compiler for each platform spec configuration is inconvenient and uses a lot of resources. As part of moving towards a single KOS toolchain that can build for all platforms, we first allow a toolchain for each architecture that can build multiple platforms.

Device Provisioning

Device provisioning tools have been added to the KOS SDK to simplify the process of flashing a device with a KOS installation, removing a cumbersome process that would otherwise involve a lot of manual steps.

kos-tool bootstrap

This SDK features a kos-tool bootstrap sub-command to automate the device provisioning process by installing a copy of a KOS system onto a device. The boostrap sub-command supports flashing a KOS manifest.zip image to the following platforms:

• am335x : Support for flashing to an SD card.
• imx8mm-evk: Support for flashing to on-device eMMC.
• portenta-x8: Support for flashing to on-device eMMC.

As part of the flashing command, the bootstrap command writes out a KOS bootfs image (generated from the manifest.zip system image), along with a uboot image and environment configuration that automatically loads KOS when the device powers on.

Key Generation

Each KOS device is now provisioned with set of private/public key pairs during the flashing process. Keys are currently generated for Tunnel and Kry10 Server access. Keys are no longer compiled into the KeyStore server or manifest configuration.

The keys can be generated at the time of flashing or users can opt to generate them before hand, using mix kos.keys.generate and passing them through as a parameter to the kos-tool bootstrap sub-command.

Similarly for development workflows using mix kos.run (simulated or fastboot-based methods), keys are generated at the time of running the system or can be passed through as a parameter.

KOS Mix

The following Mix tasks have been added:

• kos.watch - Runs a system project on hardware or in a simulator, watching and relaunching it when the system project sources changes.
• kos.manifest.check - Checks a KOS manifest for configuration issues.
• kos.network.enable_forwarding, kos.network.disable_forwarding : Enables/Disables connections between the device and the external internet by managing network traffic rules on the host. Allows locally connected KOS devices to communicate with a publicly hosted Fleet Server.

KOS Core

Persistent Boot: imx8mm-evk & Portenta X8

Persistent boot support has been added to the imx8mm-evk and portenta-x8 platforms. As part of the feature, this release vendors NetBSD’s SDMMC driver stack as well as its IMX8 board support, enabling access to each platform’s eMMC storage device. Only the eMMC storage device is available for persistent boot.

Console: Structured Output & Per-App Buffering

Added per-app buffering in the serial app so that output only happens when new-line characters are encountered. Additionally, each line is pre-pended with a timestamp and an app name. It should be possible to parse the output stream offline and provide per-app logging views by filtering the lines.

Examples

vmm_example

Introduces a new KOS testbed example system, vmm_example. The system demonstrates how to define and configure a simple Linux MicroVM. The example boots a VM with a generated Alpine Linux initrd.

protobuf_example

Introduces a new KOS testbed example system, protobuf_example. The system demonstrates passing protobuf messages between C and Elixir applications over a Message Server protocol. Additionally the system showcases the new protobuf CMake helpers in KOS.

Docs

Quickstart

Updated to align to SDK release. This revises content to reflect:

• Installing the SDK through kos-tool.
• Creating and modifying a new system using the Poukai manifest layer.
• Installing and running the Studio Server.
• Connecting a device to the Studio Server.
• Connecting a device to the Fleet Server.

Developers Guide

The following developers guide pages have been updated to align to SDK release:

• KOS Overview: The KOS SDK
  • Installation using the kos-tool tool.
• Building and running a KOS system: Building KOS
  • Updated to reflect SDK toolchain changes.
• Building and running a KOS system: Running KOS
  • Added per-platform pages for running KOS on the given system.
• Developing a KOS system: Develop a KOS system manifest
  • Added section on using Manifest Assurance package.
• Developing a KOS system: Develop an Elixir app.
  • Updated to reflect SDK toolchain changes
• Developing a KOS system: Develop a C app.
  • Updated to reflect SDK toolchain changes
• Developing a KOS system: Persistent Boot.
  • Updated to reflect SDK toolchain changes
  • Updated to describe flashing bootfs using kos-tool bootstrap.
• Developing a KOS system: Networking
  • Updated to describe configuring tunnel through Poukai package.
• Developing a KOS system: Virtual Machines
  • Added new page describing how to set up and use KOS MicroVMs.
• Developing a KOS system: Sending Device Data to MQTT
  • Added new page describing how to send MQTT data from device to Fleet Server.

KOS Packages

New documentation section added, describing the various core and standard KOS packages. The ‘KOS Packages’ section contains overviews of each package, its various interfaces and how to include it into a system project.

Kry10 Management Servers

New documentation section added, describing the Kry10 servers. The Kry10 Servers Guide provides support for connecting devices to either Kry10 Server (Studio or Fleet), remotely upgrading one or more devices and configuring user access controls. It is intended to assist with troubleshooting issues.

Breaking Changes

KOS Mix

The following Mix tasks have been removed:

• kos.install - Replaced by kos-tool install

The following Mix tasks have been renamed:

• kos.debug.remote_iex → kos.toolbox.remote_iex
• kos.orbit.active_overlay → kos.server.active_overlay
• kos.orbit.upgrade_device → kos.server.upgrade_device
• kos.orbit.upload_overlay→ kos.server.upload_overlay
• kos.orbit.upload_release → kos.server.upload_release
• kos.orbit.devices.* → kos.server.devices.*

The following Mix tasks have been deprecated (likely to be removed in the next release candidate):

• kos.build - In favour of using kos.manifest
• kos.local.scenic_driver_remote - Package is now importable via the KOS_BUILTINS path of the development shell.

Board Support

x86_64: x86_64 support has been disabled. The platform is unsupported for this release.

Third-party software dependency updates#

• OTP 25.1.2 → 26.1.1
• Elixir 1.14 → 1.15
• nixpkgs current (4d2b37a84fad) → unstable (7131f3c223a2d)

‍