Add New Board

• The Board Directory
• The Overlay Files
• Board Configuration File
• Initramfs Configuration File
• Kernel
• Non-standard Configurations

---

Adding support for a new board is done by creating the corresponding files and directories in the thingOS source tree.

The Board Directory

Each board has its own directory named board/<name>. The Raspberry PI board has a board/raspberrypi directory. It is usually a good idea to start by copying the board directory from an existing board. The board directory is a good place to add various files that are specific to the board (such as precompiled boot loaders or boot configuration files).

The postscript.sh Script

This script is responsible of making the last tweaks and adjustments for the boot and root filesystems. It often copies boot files over to the boot directory.

The cleanups.sh Script

In addition to the common cleanups performed by board/common/cleanups.sh, if a board/<name>/cleanups.sh script exists, it will be called to remove unnecessary files/directories that are specific to this board and that end up on the target filesystem. The $TARGET variable points to the root of the target filesystem.

The mkimage.sh Script

This script is responsible of creating the actual OS image for the board. It is usually just a simple wrapper around support/scripts/mkimage.sh, exporting variables $IMG_DIR and $BOARD.

The Initramfs File

Each board should have a special initramfs file, built separately using ./build.sh <board>_initramfs. The format of this file depends on the used bootloader. Common formats include gzipped cpio archive and U-Boot Initrd.

The Overlay Files

The contents board/<name>/overlay directory will be overlaid on the target root filesystem, just like board/common/overlay is. This board/<name>/overlay directory contains board-specific files that will overwrite or augment the common ones.

The following files should be present for each board.

The /etc/board File

This file lives in board/<name>/overlay/etc/board and should simply contain a word indicating the <name> of the board, such as odroidxu4.

The /etc/init.d/boardsn Script

This script lives in board/<name>/overlay/etc/init.d/boardsn. By convention, thingOS unit serial numbers are made of 8 hex digits. In the absence of such a script, thingOS will simply use 00000000.

If the board has a way to read its CPU serial number, it should use this script to do so (see board/raspberrypi/overlay/etc/init.d/boardsn for an example).

Otherwise, it is a good idea to use the mac address of the network adapter to build a unique serial number (see board/odroidxu4/overlay/etc/init.d/boardsn for an example).

The /usr/libexec/fw-prepare-boot Script

This script lives in board/<name>/overlay/usr/libexec/fw-prepare-boot. It is responsible of switching from normal boot mode to firmware update boot mode (aka initramfs). For more details, see Firmware Updates.

The remove_initramfs Script

This script lives in board/<name>/overlay-initramfs/remove_initramfs. It is responsible of switching from firmware update boot mode (aka initramfs) to normal boot mode. For more details, see Firmware Updates.

Board Configuration File

A separate BuildRoot defconfig configuration file must be provided for each board. These defconfig configuration files live in the config folder and are named <board>_defconfig. You should start by copying the defconfig file corresponding to the existing board that's the closest to your board and then make the changes either manually or using ./build.sh <board> xconfig, followed by ./build.sh <board> savedefconfig.

Initramfs Configuration File

The Initramfs is used while performing Firmware Updates. The contents of the Initramfs file are also built using BuildRoot and a separate configuration file named <board>_initrafms_defconfig. You should start by copying the defconfig file corresponding to the existing board that's the closest to your board and then make the changes either manually or using ./build.sh <board>_initramfs xconfig, followed by ./build.sh <board>_initramfs savedefconfig.

Kernel

Use ./build.sh <board> xconfig to choose how your kernel is provided.

Use ./build.sh <board> linux-xconfig to configure your kernel. After tweaking the configuration, run ./build.sh <board> linux-update-defconfig to copy the configuration over to the default, in-tree location.

Non-standard Configurations

Custom fstab.disk

thingOS uses /dev/mmcblk0p* as the "local disk" block device. In case your board uses a different block device, you can change this by providing a custom board/<board>/overlay/etc/fstab.disk, starting from the common board/common/overlay/etc/fstab.disk.

Custom os.conf

If, for some reason, your board requires a slightly different os.conf than the common one, you can create a file called board/<board>/os.conf and add only the lines that differ.

Additional Kernel Modules

If your board requires some kernel modules to be loaded manually at boot, you should add them to board/<board>/overlay/etc/modules.