Getting Started

• Prerequisites
• Preparing Your Repo
• Synchronizing thingOS Changes
• Customization
• Building
• Installing
• Committing
• First Boot

---

Prerequisites

Before hitting the road, make sure that:

• you have significant experience with Linux
• you're familiar with building software from source
• you have a computer running a recent Linux distro
• you have a supported single board computer with an SD card at your disposal
• you know what BuildRoot is about and you have read (at least briefly) their user manual
• your Linux system meets BuildRoot's requirements

Preparing Your Repo

With thingOS the workflow is a bit different than what you're probably expecting. In order to develop your OS, you're supposed to fork the thingOS repo and do your work on your own repo, unless, of course, you want to contribute directly to the thingOS project.

Either fork thingOS on GitHub or start by creating your own empty git repo, called mythingos:

mkdir mythingos && cd mythingos && git init

Then add thingOS as a git remote and fetch it:

git remote add thingos https://github.com/ccrisan/thingos.git
git fetch thingos

Now create a branch called thingos to track the thingOS main branch:

git branch --track thingos thingos/main

Finally, switch to your main branch, which is up to date with thingos/main, for now:

git checkout main

Synchronizing thingOS Changes

Everytime you want to pull in changes from thingOS, you'll need to update the thingOS branch:

git checkout thingos
git pull

Then you need to merge the changes into your main (or whatever branch you use):

git checkout main
git merge thingos

Alternatively, you can do a merge directly from the thingos remote (on your main branch):

git fetch thingos
git merge thingos/main

Customization

Packages

The default configurations that come with thingOS aren't too useful as they are; you need to include some packages into your build to make it useful. BuildRoot allows selecting from a variety of packages using a user-friendly tool that you can start with (replace <board_name> with your actual board name, e.g. raspberrypi3):

./build.sh <board_name> xconfig

If your system can't display graphical interfaces, you can use the console (ncurses) interface:

./build.sh <board_name> menuconfig

If you want to find out more on configuring your build, see BuildRoot's configuration documentation.

In theory you can tweak whatever the too allows you, but it is recommended that you only add/remove target packages, as thingOS relies on various settings. See Internals to get an idea on what you should and what you should not tweak.

Init Scripts

If you include packages that need to be started at boot, they most likely come with a default init script. However, it may not work with the thingOS setup and you may not be satisfied with the order given to the script. You can get rid of it by adding it to cleanups.sh and you can design your own, following the guidelines from Init Scripts.

Build Wrapper

As you probably have figured out already, thingOS provides a wrapper around the make commands used by BuildRoot, called build.sh. Its purpose is to make your like a bit easier when it comes to managing multiple boards at once. You can run build.sh all <target> instead of one build.sh <board_name> <target> for each available board and the command will be sequentially executed for all supported boards.

To summarize, build.sh <board_name> <target> is practically equivalent to make O=output/<board_name> <target>, except for targets such as mkimage or mkrelease.

Version

You'll probably want to update the version of your operating system, as well as its name. You can do that by editing the version file.

Alternatively, you could set the THINGOS_VERSION environment variable to your version when using the build.sh script.

Building

To build the OS image for your board, run:

./build.sh <board_name>

Go and fix yourself a coffee, because this is going to take a while (1-2 hours, depending on your machine).

If your build succeeded, after tons of mesmerizing text, you should see a line saying build successful. It's now time to build the final OS image (compressed as .xz):

./build.sh <board_name> mkrelease

If the image has been put together successfully, you'll get the following lines:

your xz image is ready at /path/to/mythingos-<board_name>-<version>.img.xz

Installing

Now that you have your /path/to/mythingos-<board_name>-<version>.img.xz file, it's time to "burn" it to an SD card. You can do that using whatever means you have (including the good old dd command), but the recommended way is to use the writeimage.sh script (replacing /dev/mmcblk0 with your card reader's device, e.g. /dev/sdc):

./writeimage.sh -i /path/to/mythingos-<board_name>-<version>.img.xz -d /dev/mmcblk0

You can also preconfigure your image as it is written to the SD. You can, for example, tell it to connect to a wireless network or set a static IP. For more details, run:

./writeimage.sh

Committing

Until this point, almost everything happened in the folder output/<board_name>, which is systematically omitted by .gitignore.

If you're satisfied with the OS image you have, you'll probably want to commit your changes and push them to your git server. Saving the BuildRoot configuration to git involves updating your configs/<board_name>_defconfig file:

./build.sh <board_name> savedefconfig

You probably have changed stuff in the board directory as well. In any case, you can safely add all changes to git and commit them:

git add .
git commit -am '<your_commit_message>'

Don't forget to push your changes at some point:

git push

First Boot

It is recommended that you do your first boot with a monitor attached, if your board can display output to a framebuffer, or otherwise you could use a serial terminal to watch the boot process.

The first boot involves a few initialization steps and therefore it takes a bit more (1 - 2 minutes, depending on the board and SD card). It is important that you do not disconnect or reboot your board during these first two minutes!

The initialization steps include:

• allocating & formatting the data partition
• creating the required directory structure on the data partition
• initializing SSH keys
• other service-specific initializations