{"id":19772202,"url":"https://github.com/recordevolution/reswarmos","last_synced_at":"2025-04-30T18:30:29.999Z","repository":{"id":122437556,"uuid":"288976279","full_name":"RecordEvolution/ReswarmOS","owner":"RecordEvolution","description":"A small, customized host operating system for IoT devices meeting the needs of Reswarm","archived":false,"fork":false,"pushed_at":"2024-04-15T10:21:33.000Z","size":33886,"stargazers_count":5,"open_issues_count":10,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-04-16T00:41:56.990Z","etag":null,"topics":["container","embedded-devices","embedded-linux","iot","minimal-linux","raspberry-pi","reswarm"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RecordEvolution.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"license.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-08-20T10:28:42.000Z","updated_at":"2024-06-18T16:05:47.350Z","dependencies_parsed_at":"2024-04-15T11:54:04.690Z","dependency_job_id":null,"html_url":"https://github.com/RecordEvolution/ReswarmOS","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RecordEvolution%2FReswarmOS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RecordEvolution%2FReswarmOS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RecordEvolution%2FReswarmOS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RecordEvolution%2FReswarmOS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RecordEvolution","download_url":"https://codeload.github.com/RecordEvolution/ReswarmOS/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224219688,"owners_count":17275477,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["container","embedded-devices","embedded-linux","iot","minimal-linux","raspberry-pi","reswarm"],"created_at":"2024-11-12T05:05:44.150Z","updated_at":"2024-11-12T05:05:44.851Z","avatar_url":"https://github.com/RecordEvolution.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.ironflock.com\"\u003e\n    \u003cimg\n      alt=\"IronFlock\"\n      src=\"https://res.cloudinary.com/dotw7ar1m/image/upload/v1708079370/vli89gsgy2siqcrmvzfm.png\"\n      width=\"400\"\n    /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n# ReswarmOS by Record Evolution\n\n_ReswarmOS_ represents a lightweight, customizable and efficient host operating\nsystem for embedded devices in the IoT context and is specifically designed to\nmeet the requirements of the IoT Development Studio\n_[IronFlock](https://www.ironflock.com/)_. It was designed with the \nfollowing objectives in mind: _minimal footprint/size_ of the root-filesystem\nto ensure quick flashing and easy setup for a myriad of devices, _container support_\nfor having a robust solution to dynamically run a huge variety of apps on the \ndevice and _security standards_ matching the latest industry requirements\nregarding data safety and network security.\n\n## Overview\n\n* [Usage](#Usage)\n* [Build](#Build)\n* [Buildsystem](#Buildsystem)\n* [References](#References)\n\n## Usage\n\n_ReswarmOS_ may be used in two different ways:\n\n1. as an independent alternative to i.a.\n  [Raspberry Pi OS](https://www.raspberrypi.org/downloads/raspberry-pi-os/),\n  [HypriotOS](https://blog.hypriot.com),\n  [balenaOS](https://www.balena.io/os/),\n  or [Tiny Core Linux](http://tinycorelinux.net)\n\n1. as the _default_ operating system empowering the embedded devices connected\n   to the IoT Development Studio _Reswarm_\n\n### Independent OS\n\nJust download the latest release, grab the SD card for your device and flash it\nusing the [Reflasher](https://github.com/RecordEvolution/Reflasher). After the\nflash process is successfully finished, open up the _boot partition (vfat)_\nlabeled _RESWARMOS_ containing the file _/device-config.ini_. Here, you may enter\nall configuration parameters for your device like i.a. your prefered _username_ and\ncorresponding login _password_ to be set up on the device. To be able to immediately\nconnect to the device via WIFI you have to enter the _SSID_ and _password_ of your\nlocal wireless network. However, I you choose to not enter your WIFI credentials you\nmay still connect via LAN at any time. After booting up the device, it will show up\nwith its _hostname_ (the one you provided in _device-config.ini)_ on the local network.\nHence, you can connect to it via _ssh_ and your credentials entered in _device-config.ini_\nby\n\n```\nssh \u003cyour-username\u003e@\u003cdevice-hostname/local-ip\u003e\n```\n\n### IoT devices\n\nAny devices created within the framework of the IoT Development Studio\n_Reswarm_ are by default equipped with the latest version of _ReswarmOS_\nand automatically configured to securely connect and communicate with\nthe IronFlock server cloud instance. Since this setup is coupled to your\nindividual IronFlock user account the _ssh login_ is more customized and\nsecure. During the initial boot process ReswarmOS will set up a personalized\nuser account on the device using the fields `swarm_owner_name` and `secret`\nof the _.reswarm_ configuration file as username and associated password.\nNote, that this username may be modified in order to comply to the\n`NAME_REGEX` rule `^[a-z][-a-z0-9]*$`. The device will show up in the local\nnetwork with its _hostname_ according to the IronFlock device name. To ensure\nmaximal security, by default, this user is the only one able to access the\ndevice directly using public key authentication. The required identity is\nconsequently provided by the _.reswarm_ file of the device and may,\nfor example, be prepared by\n\n```\necho -e $(cat /path/to/mydevice/config.reswarm | jq .authentication.key) | tr -d '\"' | grep -v \"^ *$\" \u003e id_rsa\nchmod 600 id_rsa\n```\n\nHenceforth, performing an _ssh login_ on the IronFlock device looks like this:\n\n```\nssh -i id_rsa \u003cswarm_owner_name\u003e@\u003cdevice-name/corresponding local ip\u003e\n```\n\n## Build\n\nThe development of _ReswarmOS_ relies on [Buildroot](https://buildroot.org)\nas its build system. To build _ReswarmOS_ yourself, all you need is a\n_docker-able_ host machine (with at least 4 threads and 4GB of RAM and\n20GB free disk space).\n\nFirst of all, clone the repository by doing\n\n```Shell\ngit clone https://github.com/RecordEvolution/ReswarmOS.git\ncd ReswarmOS\n```\n\nOpen up the main configuration file `setup.yaml` and choose i.a. the \ndesired target hardware the resulting operating system image is supposed\nto run on, e.g. for a Raspberry Pi 4\n\n```\n---\n  # OS name and version\n  osname: ReswarmOS\n  osvariant: light\n  version: 0.5.2\n  # general board description\n  board: raspberrypi\n  boardname: Raspberry Pi\n  # specific model\n  model: raspberrypi3\n  modelname: Raspberry Pi 3\n  # custom (buildroot) configuration file (default: \"config/\u003cboard\u003e/\u003cmodel\u003e/config\")\n  #config: config/raspberrypi/raspberrypi3/config\n  # custom linux configuration (default is already specified by (buildroot) config)\n  #linuxconfig: config/raspberrypi/raspberrypi3/linux-config-full\n  # name of image configuration file (default: \"config/\u003cboard\u003e/\u003cmodel\u003e/genimage.cfg\")\n  image:\n...\n```\n\nNote, that `board` refers to the family (type) of boards while `model` provides\nthe specifics of a particular member of this board family. While the corresponding\nfields `boardname` and `modelname` are merely arbitrary but meaningful labels, the\n`board` and `model` fields have to exactly match the directory structure in the\n`config/` folder. Please be aware, that the names, labels and versions provided\nhere are propagated to the release file and will eventually show up in the\n[Reflasher](https://github.com/RecordEvolution/Reflasher) as a hardware board/\nimage selection option. The fields `config` and `linuxconfig` are optional and may be\nused to employ any other custom configurations for buildroot (`config`) and the\nLinux kernel (`linuxconfig`). If these fields are undefined or empty the build\nsystem will automatically choose the default configurations determined by the\n`config/` directory structure and the given `board` and `model` definitions.\nAfter making the required adjustments save and close the file and proceed with\nsetting up the build environment and launching the actual build process:\n\n```Shell\nmake setup\nmake build\n```\n\nwhere the last step may take about up to one to two hours to finish\ndepending on your machine. Here are some random (non-averaged, single)\nrun stats:\n\n| CPU                                      | OS                  | ENV             | buildtime (min) | HD usage (kB) |\n|------------------------------------------|---------------------|-----------------|-----------------|---------------|\n| Intel(R) Core(TM) i7-8700T CPU @ 2.40GHz | Ubuntu 20.04.1 LTS  | Container       | 49:35           | 13288264      |\n| Intel(R) Core(TM) i7-8700T CPU @ 2.40GHz | Ubuntu 20.04.1 LTS  | Host            | 31:02           | 12830624      |\n| Intel(R) Core(TM) i5-7500T CPU @ 2.70GHz | Ubuntu 20.10        | Container       | 69:48           | 12855272      |\n\n\nIn order to roll out the image and release the corresponding\nRAUC update bundle to our google-cloud storage `gs://reswarmos` do\n\n```Shell\nmake release\n```\n\nThis requires `gsutil` to be set up and configured on your localhost.\nThe `release` target will compress the image, generate a RAUC bundle\nand update/extend the release file `config/supportedBoards.json` and push\neverything to the google-cloud bucket.\n\n## Buildsystem\n\nThe build mechanism is basically a wrapper and an extension to _Buildroot_,\nwhich takes care of setting up the tool-chains, cross-compiling, constructing\nthe root filesystem and generating the final system image. Buildroot's\nconfiguration concept bears strong similarities with the one of the\n[Linux Kernel](https://www.kernel.org). In particular, both use an `.ini` like\nconfiguration file `.config` located in the respositories root directory, i.e.\n`buildroot/.config` and `linux/.config`. Furthermore, they both use an\nan [ncurses](https://en.wikipedia.org/wiki/Ncurses) based configuration tool,\nwhich is used by `make menuconfig` in the parent directory of the corresponding\nrepository.\n\nThe ReswarmOS build mechanism will use `output-build` as its default output directory\ncontaining the final system image and update bundles:\n\n```\nmario@tuxedo:~/ReswarmOS$ ls -lh output-build/\ntotal 615M\ndrwxr-xr-x 16 mario mario 4,0K Jan 17 11:30 buildroot\n-rwxr-xr-x  1 root  root  2,1K Okt 29 12:35 cert.pem\n-rwxr-xr-x  1 root  root  3,2K Okt 29 12:35 key.pem\ndrwxrwxr-x  2 mario mario 4,0K Jan 17 11:53 rauc-bundle\n-rw-r--r--  1 mario mario 118M Jan 17 11:53 ReswarmOS-0.5.2-raspberrypi3.raucb\n-rw-r--r--  1 mario mario 433M Jan 17 11:09 ReswarmOS-light-0.5.2-raspberrypi3.img\n-rw-r--r--  1 mario mario 131M Jan 17 11:52 ReswarmOS-light-0.5.2-raspberrypi3.img.gz\n```\n\nHenceforth, to reconfigure any board/hardware specific Buildroot configuration  (`.config`)\nthe simplest way is to enter the buildroot directory (`cd output-build/buildroot`) which\nis generated by the `make build` step and use the text-based user interface via `make menuconfig`.\nAfter updating and saving the configuration you may want to store it and keep it as a\nboard's (default/custom) configuration by copying it to `config/\u003cboard\u003e/\u003cmodel\u003e/\u003cconfig-name\u003e`.\nNote, that you have to remove any dirty marks (indicating uncommited changes in the buildroot\ndirectory) and evtl. the relative path to the root filesystem overlay (which is auto-injected\nwhen starting up the build process). For instance, we may get\n\n```\n$ diff config/raspberrypi/raspberrypi3/config output-build/buildroot/.config\n\n3c3\n\u003c # Buildroot 2021.08-646-gd0298f4052 Configuration\n---\n\u003e # Buildroot -gb8485dc-dirty Configuration\n514c514\n\u003c BR2_ROOTFS_OVERLAY=\"\"\n---\n\u003e BR2_ROOTFS_OVERLAY=\"../../rootfs\"\n```\n\n### TODO Preliminary PKI for RAUC\n\nThe _preliminary_ (without using a IronFlock Platform Root CA) setup requires the `cert.pem` and\n`key.pem` for validating RAUC update bundles. Currently, the validity of the certificate is\nextended to one year (see make targets `$(OUT)key.pem $(OUT)cert.pem`). The current certificate\nand key are located in a restricted access google-cloud bucket, i.e.\n\n```\ngsutil ls -lh gs://reswarmos-certs\n  2.03 KiB  2022-01-18T11:46:58Z  gs://reswarmos-certs/cert.pem\n  3.19 KiB  2022-01-18T11:47:03Z  gs://reswarmos-certs/key.pem\nTOTAL: 2 objects, 5350 bytes (5.22 KiB)\n```\n\nMake sure to place these in the `output-build/` directory before trying to create\na RAUC update bundle.\n\n## References\n\n### Buildroot\n\n- https://github.com/buildroot/buildroot\n- https://buildroot.org/downloads/manual/manual.html\n- https://elinux.org/images/2/2a/Using-buildroot-real-project.pdf\n- https://firedome.io/wp-content/uploads/2021/02/How-to-build-your-own-tailor-made-IoT-Linux-OS_1.pdf\n\n### Image\n\n- https://github.com/pengutronix/genimage\n- https://books.google.de/books/about/Instant_Buildroot.html?id=dZL9AAAAQBAJ\u0026redir_esc=y\n- http://lists.busybox.net/pipermail/buildroot/2016-April/160030.html\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frecordevolution%2Freswarmos","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frecordevolution%2Freswarmos","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frecordevolution%2Freswarmos/lists"}