Reconfigure Raspberry Pi images with an easy, Docker-like configuration file. For detailed information read our paper.
pimod overtakes a given Raspberry Pi image by mounting a copy and modifying this copy through QEMU chroot. Therefore one can execute Pi's ARM-code easily on its x86_64 host.
$ sudo apt-get install binfmt-support fdisk file kpartx lsof parted qemu qemu-user-static unzip p7zip-full wget xz-utils
$ sudo ./pimod.sh Pifile# build the docker container
$ docker build -t pimod .
# run the container privileged to allow loop device usage
$ docker run --rm --privileged -v $PWD:/pimod pimod pimod.sh examples/RPi-OpenWRT.Pifile
# alternatively use docker-compose
$ docker-compose run pimod pimod.sh examples/RPi-OpenWRT.Pifile name: tests
on: push
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v1
with:
submodules: recursive
- name: Run pimod OpenWRT example
uses: Natur40/pimod@v0.2.1
with:
pifile: examples/RPi-OpenWRT.PifileThe Pifile contains commands to modify the image. However, the Pifile itself is just a Bash script and the commands are functions, which are loaded in different stages.
$ cat Upgrade.Pifile
FROM 2018-11-13-raspbian-stretch-lite.img
PUMP 100M
RUN raspi-config nonint do_serial 0
RUN apt-get update
RUN bash -c 'DEBIAN_FRONTEND=noninteractive apt-get -y dist-upgrade'
RUN apt-get install -y sl
# The Upgrade.Pifile will create, called by the following command, a new
# Upgrade.img image based on the given Raspbian image. This image's size is
# increased about 100MB, has an enabled UART/serial output, the latest software
# and sl installed.
$ sudo ./pimod.sh Upgrade.Pifile
# Write the new image to a SD card present at /dev/sdc.
$ dd if=Upgrade.img of=/dev/sdc bs=4M status=progressMore examples are available in the Sensorboxes repository.
FROM sets the SOURCE_IMG variable to a target. This might be a local file or
a remote URL, which will be downloaded. This file will become the base for
the new image.
TO sets the DEST_IMG variable to the given file. This file will contain
the new image. Existing files will be overridden.
Instead of calling TO, the Pifile's filename can also indicate the output
file, if the Pifile ends with ".Pifile". The part before this suffix will be
the new DEST_IMG.
If neither TO is called nor the Pifile indicates the output, DEST_IMG will
default to rpi.img in the source file's directory.
INPLACE does not create a copy of the image, but performs all further
operations on the given image. This is an alternative to FROM and TO.
PUMP increases the image's size about the given amount (suffixes K, M, G are allowed).
INSTALL installs a given file or directory into the destination in the
image. The optionally permission mode (chmod) can be set as the first
parameter.
PATH adds the given path to an overlaying PATH variable, used within the RUN
command.
RUN executes a command in the chrooted image based on QEMU user emulation.
Caveat: because the Pifile is just a Bash script, pipes do not work as one
might suspect. A possible workaround could be the usage of bash -c:
RUN bash -c 'hexdump /dev/urandom | head'HOST executed a command on the local host and can be used to prepare files, cross-compile software, etc.
Because the Pifile is just a Bash script, some dirty brilliant hacks and extensions are possible.
Another Pifile can be extended by sourcing it in the first line.
source Parent.PifileHere documents can be used with the RUN command.
RUN <<EOF
apt-get update
DEBIAN_FRONTEND=noninteractive apt-get -y dist-upgrade
apt-get install -y sl
EOFHere documents can also be used to create files inside of the guest system, e.g., by using tee or dd.
RUN tee /bin/example.sh <<EOF
#!/bin/sh
echo "Example output."
EOFIf you happen to use pimod in a scientific project, we would very much appreciate if you cited our scientific paper:
@inproceedings{hoechst2020pimod,
author = {{Höchst}, Jonas and Penning, Alvar and Lampe, Patrick and Freisleben, Bernd},
title = {{PIMOD: A Tool for Configuring Single-Board Computer Operating System Images}},
booktitle = {{2020 IEEE Global Humanitarian Technology Conference (GHTC 2020)}},
address = {Seattle, USA},
days = {29},
month = oct,
year = {2020},
keywords = {Single-Board Computer; Operating System Image; System Provisioning},
}