ReswarmOS represents a lightweight, customizable and efficient host operating system for embedded devices in the IoT context and is specifically designed to meet the requirements of the IoT Development Studio by Record Evolution. It was designed with the following objectives in mind: minimal footprint/size of the root-filesystem to ensure quick flashing and easy setup for a myriad of devices, container support for having a robust solution to dynamically run a huge variety of apps on the device and security standards matching the latest industry requirements regarding data safety and network security.
ReswarmOS may be used in two different ways:
-
as an independent alternative to i.a. Raspberry Pi OS, HypriotOS, balenaOS, or Tiny Core Linux
-
as the default operating system empowering the embedded devices connected to the IoT Development Studio Reswarm
Just download the latest release, grab the SD card for your device and flash it using the Reflasher. After the flash process is successfully finished, open up the boot partition (vfat) labeled RESWARMOS containing the file /device-config.ini. Here, you may enter all configuration parameters for your device like i.a. your prefered username and corresponding login password to be set up on the device. To be able to immediately connect to the device via WIFI you have to enter the SSID and password of your local wireless network. However, I you choose to not enter your WIFI credentials you may still connect via LAN at any time. After booting up the device, it will show up with its hostname (the one you provided in device-config.ini) on the local network. Hence, you can connect to it via ssh and your credentials entered in device-config.ini by
ssh <your-username>@<device-hostname/local-ip>
Any devices created within the framework of the IoT Development Studio
Reswarm are by default equipped with the latest version of ReswarmOS
and automatically configured to securely connect and communicate with
the Record Evolution server cloud instance. Since this setup is coupled to your
individual Record Evolution user account the ssh login is more customized and
secure. During the initial boot process ReswarmOS will set up a personalized
user account on the device using the fields swarm_owner_name and secret
of the .reswarm configuration file as username and associated password.
Note, that this username may be modified in order to comply to the
NAME_REGEX rule ^[a-z][-a-z0-9]*$. The device will show up in the local
network with its hostname according to the Record Evolution device name. To ensure
maximal security, by default, this user is the only one able to access the
device directly using public key authentication. The required identity is
consequently provided by the .reswarm file of the device and may,
for example, be prepared by
echo -e $(cat /path/to/mydevice/config.reswarm | jq .authentication.key) | tr -d '"' | grep -v "^ *$" > id_rsa
chmod 600 id_rsa
Henceforth, performing an ssh login on the Reswarm device looks like this:
ssh -i id_rsa <swarm_owner_name>@<device-name/corresponding local ip>
The development of ReswarmOS relies on Buildroot as its build system. To build ReswarmOS yourself, all you need is a docker-able host machine (with at least 4 threads and 4GB of RAM and 20GB free disk space).
First of all, clone the repository by doing
git clone https://github.com/RecordEvolution/ReswarmOS.git
cd ReswarmOSOpen up the main configuration file setup.yaml and choose i.a. the
desired target hardware the resulting operating system image is supposed
to run on, e.g. for a Raspberry Pi 4
---
# OS name and version
osname: ReswarmOS
osvariant: light
version: 0.5.2
# general board description
board: raspberrypi
boardname: Raspberry Pi
# specific model
model: raspberrypi3
modelname: Raspberry Pi 3
# custom (buildroot) configuration file (default: "config/<board>/<model>/config")
#config: config/raspberrypi/raspberrypi3/config
# custom linux configuration (default is already specified by (buildroot) config)
#linuxconfig: config/raspberrypi/raspberrypi3/linux-config-full
# name of image configuration file (default: "config/<board>/<model>/genimage.cfg")
image:
...
Note, that board refers to the family (type) of boards while model provides
the specifics of a particular member of this board family. While the corresponding
fields boardname and modelname are merely arbitrary but meaningful labels, the
board and model fields have to exactly match the directory structure in the
config/ folder. Please be aware, that the names, labels and versions provided
here are propagated to the release file and will eventually show up in the
Reflasher as a hardware board/
image selection option. The fields config and linuxconfig are optional and may be
used to employ any other custom configurations for buildroot (config) and the
Linux kernel (linuxconfig). If these fields are undefined or empty the build
system will automatically choose the default configurations determined by the
config/ directory structure and the given board and model definitions.
After making the required adjustments save and close the file and proceed with
setting up the build environment and launching the actual build process:
make setup
make buildwhere the last step may take about up to one to two hours to finish depending on your machine. Here are some random (non-averaged, single) run stats:
| CPU | OS | ENV | buildtime (min) | HD usage (kB) |
|---|---|---|---|---|
| Intel(R) Core(TM) i7-8700T CPU @ 2.40GHz | Ubuntu 20.04.1 LTS | Container | 49:35 | 13288264 |
| Intel(R) Core(TM) i7-8700T CPU @ 2.40GHz | Ubuntu 20.04.1 LTS | Host | 31:02 | 12830624 |
| Intel(R) Core(TM) i5-7500T CPU @ 2.70GHz | Ubuntu 20.10 | Container | 69:48 | 12855272 |
In order to roll out the image and release the corresponding
RAUC update bundle to our google-cloud storage gs://reswarmos do
make releaseThis requires gsutil to be set up and configured on your localhost.
The release target will compress the image, generate a RAUC bundle
and update/extend the release file config/supportedBoards.json and push
everything to the google-cloud bucket.
The build mechanism is basically a wrapper and an extension to Buildroot,
which takes care of setting up the tool-chains, cross-compiling, constructing
the root filesystem and generating the final system image. Buildroot's
configuration concept bears strong similarities with the one of the
Linux Kernel. In particular, both use an .ini like
configuration file .config located in the respositories root directory, i.e.
buildroot/.config and linux/.config. Furthermore, they both use an
an ncurses based configuration tool,
which is used by make menuconfig in the parent directory of the corresponding
repository.
The ReswarmOS build mechanism will use output-build as its default output directory
containing the final system image and update bundles:
mario@tuxedo:~/ReswarmOS$ ls -lh output-build/
total 615M
drwxr-xr-x 16 mario mario 4,0K Jan 17 11:30 buildroot
-rwxr-xr-x 1 root root 2,1K Okt 29 12:35 cert.pem
-rwxr-xr-x 1 root root 3,2K Okt 29 12:35 key.pem
drwxrwxr-x 2 mario mario 4,0K Jan 17 11:53 rauc-bundle
-rw-r--r-- 1 mario mario 118M Jan 17 11:53 ReswarmOS-0.5.2-raspberrypi3.raucb
-rw-r--r-- 1 mario mario 433M Jan 17 11:09 ReswarmOS-light-0.5.2-raspberrypi3.img
-rw-r--r-- 1 mario mario 131M Jan 17 11:52 ReswarmOS-light-0.5.2-raspberrypi3.img.gz
Henceforth, to reconfigure any board/hardware specific Buildroot configuration (.config)
the simplest way is to enter the buildroot directory (cd output-build/buildroot) which
is generated by the make build step and use the text-based user interface via make menuconfig.
After updating and saving the configuration you may want to store it and keep it as a
board's (default/custom) configuration by copying it to config/<board>/<model>/<config-name>.
Note, that you have to remove any dirty marks (indicating uncommited changes in the buildroot
directory) and evtl. the relative path to the root filesystem overlay (which is auto-injected
when starting up the build process). For instance, we may get
$ diff config/raspberrypi/raspberrypi3/config output-build/buildroot/.config
3c3
< # Buildroot 2021.08-646-gd0298f4052 Configuration
---
> # Buildroot -gb8485dc-dirty Configuration
514c514
< BR2_ROOTFS_OVERLAY=""
---
> BR2_ROOTFS_OVERLAY="../../rootfs"
The preliminary (without using a Reswarm Platform Root CA) setup requires the cert.pem and
key.pem for validating RAUC update bundles. Currently, the validity of the certificate is
extended to one year (see make targets $(OUT)key.pem $(OUT)cert.pem). The current certificate
and key are located in a restricted access google-cloud bucket, i.e.
gsutil ls -lh gs://reswarmos-certs
2.03 KiB 2022-01-18T11:46:58Z gs://reswarmos-certs/cert.pem
3.19 KiB 2022-01-18T11:47:03Z gs://reswarmos-certs/key.pem
TOTAL: 2 objects, 5350 bytes (5.22 KiB)
Make sure to place these in the output-build/ directory before trying to create
a RAUC update bundle.