2023 May release update

This release is a minor update to the version 1.0.0-beta of the KOS platform. This is intended as another pre-release before the first major release.

The goal for this release update is to address feedback around making it easy for a brand new developer to understand KOS and begin creating and running simple but realistic programs.

Orbit

• remote-iex - KOS simplifies the application development process by supporting remote iex shells on running elixir apps. However, this has not always been easy to use, since Elixir apps will normally only be able to access the internet via the KOS tunnel protocol, which meant developers would first have to set this up before connecting to the remote shell. This release updates Orbit so that developers can connect to their apps and run commands in the browser. As long as the device is connected to Orbit and remote shells are enabled (see below for more), commands can be run on the device’s operations page with no additional setup required. Orbit now also displays a prominent warning on manifests that have remote shells enabled so that it is harder to mistakenly push them to a production device.
• TCP traffic forwarding - Orbit now supports forwarding traffic from devices to external servers. This was introduced primarily to allow users to connect applications to an MQTT server without needing to bypass the secure tunnel or to set it up on their server. The feature is general-purpose however, and will support any TCP-based protocol.
• Serial data capture - KOS devices have been updated to buffer serial data and send it on-demand to Orbit. This data is now shown in Orbit when a user opens the device’s operation page, which should simplify development and debugging devices that do not have their own TTY.
  • Device-side, KOS has been updated to capture and forward all serial data via the KOS Core admin component.
• user event logs - to help with security and compliance, Orbit now stores a record whenever a user or admin user: logs in, logs out, changes their password, resets or requests a password reset, is created or is locked out. This data includes the IP address responsible and a timestamp to aid with incident detection. The records can be viewed by the user by navigating to the user’s settings page. Organisation owners can also view records of any users by navigating to the organisation and clicking on the user’s email address. Admin users can also view this data for any user in Orbit by navigating to any organisation the user belongs to and then clicking on the user’s email address.
• sign in with Microsoft - Orbit can be configured to support signing in with a Microsoft account rather than requiring a username and password. This requires configuring Orbit with the required Microsoft ID and secret so isn’t currently intended to be used locally, but can be set up if needed.
• device disconnects - Orbit now pops up an error message when a device disconnects from the operations page, rather than clearing the state. This is intended to reduce friction when interacting with the devices so that a user can continue where they left off when the device reconnects.
• deployment preview - users can now view what the merged manifest will look like for any given device on the deployment page before deploying a new release. This allows a user to visualise how any given release will interact with a device’s overlay before attempting to make the changes.
• overlay improvements - previously, changing a device’s overlay triggered a new release to be sent whereas now the device’s overlay is updated separately to being deployed. This means a new overlay can be uploaded in preparation for a deployment release update without affecting the current release. The overlay can still be updated without changing the underlying release by choosing to deploy it after upload.
• beta server - users can now try out Orbit without running a local instance by using our beta server. Note: this server should only be used for test purposes; organisations may not be sufficiently segregated yet to ensure the security of any connected device, and we currently provide no guarantees around the server’s uptime or reliability.
• clustering - Orbit can now be deployed in a clustered group to add redundancy and/or support higher loads.
• Upgrade progress update messages - Notify progress reports whenever a file is fully transferred during device upgrades.

Studio

• The commands have been simplified; kos.new.app no longer has to be run from a specific directory, the simulation scripts have been consolidated into kos.run.simulate which automatically uses the environment’s platform and the default build location unless otherwise specified
• Generating keys - a new command kos.keys.generate has been added to support generating unique key pairs for a device’s tunnel and Orbit client. This makes it easier for users to create a new private device rather than needing to use the default device.
• Manifest signing key generation - kos.manifest.sign updated to support the generation of an ed25519 private/public key pair for signing the manifest with. This makes it easier and more accessible to create private keys if the user doesn’t already have a preference to one. Available via the --gen-keys command line argument.
• kos.orbit commands have been improved to support identifying entities by name instead of id and to add new commands to upload overlays and clean up Orbit after the user has finished running it.
• Elixir apps no longer default to having an open empd port. Following the “secure by default” principle, the kos.new.* apps have been updated to default to keeping the empd port closed as this is how production devices should be configured. A —debug flag can be passed to the commands to open the port on creation, and the generated manifest/config files contain comments on how to open/close the port.
• kos.toolbox.remote_iex has been added to support connecting to an iex shell in Elixir apps running on a device. This requires Orbit to be running locally and the app to have an empd port open to accept connections.
• A new platform spec format for specifying a platform to target. The simple format starts with a specific platform name and then a comma separated list of key=value fields that are applied as platform configuration. For example, am335x,arch=aarch32,mcs=on selects the am335x platform for aarch32 architecture and with the Micro-kernel configured for mcs.
• Projects can now configure their default platform. In config.exs, :kos_mix. default_env_platform: can be set to one of kos.env’s supported platforms so that it doesn’t have to be specified each time an environment is opened.

KOS

• Beam ports for communicating with kos processes
  • am335x gpio and PWM modules
• ARMv8 AArch64 support: KOS can now be run on 64-bit Arm v8 platforms. However the kernel verification project for this architecture is still in-progress by Proofcraft for the seL4 foundation.
• KOS Channels Updates
  • kos_manifest library support for describing channels: KOS channels can now be described and associated with applications through the kos_manifest library.
  • New manifest properties introduced when defining channels:
    • identify_receiver : allows applications to identify which app, by its ID, is receiving on the channel i.e if wanting to perform additional validation. If the property is absent, the receivers badge id will not be recorded into the dev-resource book-keeping structure.
    • restricted_access : allows a channel to lock down each access right to itself for a given set of applications
  • Core application support: The KOS core application set (i.e. serial server), now support the ability to use KOS channels.
• Looback server and communicating BEAM instances
  • Added a loopback server app that allows local TCP/IP connections between components on a KOS system
  • Added an example of using the loopback server to enable inter-BEAM communication (using BEAM distribution mechanisms) on KOS
• We are in the progress of adding new experimental RPI4 platform support. Initial support for the Raspberry Pi 4 Model B has been added. Images for the rpi4 platform can be build from inside a mix kos.env -p rpi4 environment and examples like the weather_station example can be loaded onto the platform. Running the image on a Raspberry Pi 4 Model B requires installation of the U-Boot boot loader and we have not yet completed adding a mix command for creating a rpi4 sd card image for easier setup. Instructions for how this can be done can be found on this page maintained by the seL4 Foundation: https://docs.sel4.systems/Hardware/Rpi4.html. In future updates, we will have added platform setup documentation for the rpi4 to make this easier.

KOS Manifest

• kos options support in Elixir manifest - the Elixir manifest now supports kos_options (such as manifest signing rules and persistent boot options) making it closer to having feature parity with the native DTS manifest.

KOS Libs

• Added Elixir library “kos_msg” that is an elixir binding to the KOS msg_server api.

Documenation updates

• Add initial “Develop a C App” developer guide page.
• Update “Connecting to IEx on the device” developer guide page.
• Update “Develop an Elixir App” with section explaining how to write Scenic apps.
• Add “Interprocess communication” in-depth guide page

Quick start guide

• Connecting to public Orbit - the quick start guide now has a section describing how to connect to the public instance of Orbit (an instance of Orbit hosted in Azure, e.g. beta Orbit). It describes how to configure the build to use the public Orbit tunnel, how to add appropriate device configurations to Orbit, and how to configure the development machine to allow devices to connect to external services.

‍