Skip to content
These scripts will generate an SD-Card image for the Raspberry-Pi based "Oktopus" sensor computer. The OS image is set up to enable a Bluetooth network access point and reroute network traffic to its local web server.
JavaScript Makefile C CSS Shell
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
files try waiting for hci interface before setting up bluetooth Apr 30, 2019
files_ws5inch/usr/share/X11/xorg.conf.d merge modularization from rpi_small fork Mar 14, 2019
gummikraken Add 'gummikraken/' from commit '0bedab200a6c2b0018bae205cf7678060008f… Apr 30, 2019
oktopus_frontend Add 'oktopus_frontend/' from commit '05151bd923ff2cacdbb4098c91d3dd78… Apr 30, 2019
sensors support for one-wire termal sensor Dec 29, 2018
teesock Add 'teesock/' from commit '7f2916d1960ad00d156f1d354f9402def32c0848' Apr 30, 2019
.gitignore include teesock, update test program Dec 18, 2018
.gitmodules transition to remove gummikraken submodule Apr 30, 2019
LICENSE.TXT include license text Nov 8, 2018
Makefile set up trusted.gpg directory before installing keys May 6, 2019 updated formatting Jan 9, 2019
config.example fall back to static salt for shells without $RANDOM Apr 30, 2019
debian-archive-stretch-stable.gpg integration of debian repos, switch to packaged raspberry pi kernel Mar 14, 2019 merge modularization from rpi_small fork Mar 14, 2019 merge modularization from rpi_small fork Mar 14, 2019
raspberrypi-archive-keyring.gpg debootstrap raspbian and build image file from it Oct 28, 2018
raspbian-archive-keyring.gpg debootstrap raspbian and build image file from it Oct 28, 2018 copy teesock.arm to file name teesock Apr 30, 2019
wifi.tmpl introduce config file tree Oct 31, 2018 merge modularization from rpi_small fork Mar 14, 2019

Oktopus Boot

Generator for Oktopus boot media.


The Oktopus sensor computer displays data on devices connected via Bluetooth. To enable this it opens a Bluetooth network access point. This AP allows connections by any device. To enable IP connectivity a DHCP server will be started on Oktopus. Oktopus identifies itself as an internet gateway to connecting devices. All attempts by those clients to connect to any websites will be directed to the local sensor display. This is enabled by a "fake" DNS server running on Oktopus, which resolves all domain names to the sensor computer itself.

In order to provide the necessary combination of Bluetooth, DHCP, and DNS settings, we provide a custom operating system image. This git repository contains the scripts and configuration files to assemble this image.

Requirements and Compatibility:

The build system must support Linux style loopback devices. The script as it is will only run on Linux OSes, and it strictly requires the losetup utility from the GNU userland package. In addition the main script is a GNU style makefile. This software will not work on BSD or Mac OS X, without modification. It will also not work on busybox based Linux OSes.

The Raspberry environment is configured via ARM CPU emulation using qemu. A static qemu binary for ARM emulation must be provided, as well as the accompanying binfmt support in the kernel.

Required Programs are:

  • a Linux Kernel with loop support (almost always available)
  • make (GNU flavour)
  • losetup (GNU flavour)
  • qemu-arm-static (e.g. from the qemu-user-static Debian package)
  • a C compiler for the ARM platform (i.e. gcc-arm-linux-gnueabi, see submodule teesock)
  • mkfs.ext4
  • mkfs.fat
  • sfdisk
  • debootstrap
  • ssh-keygen (optional)

debootstrap is available in all Debian derivatives, including Ubuntu. It can be installed in some Non-Debian distributions as well.


The script must be run as root. The target is raspi.img. I.e. you should run (as root):

make raspi.img

The resulting raspi.img file can be written to an SD-Card using dd. And a Raspberry Pi can be booted from this SD-Card.

Some configuration options can be set in See config.example as a template, but do not edit config.exampledirectly, as it is tracked by git. is particularly useful to set up an APT-Proxy, and to set up Wifi credentials. If Wifi credentials are set up, the Oktopus computer will attempt to connect to the specified wireless network to provide SSH access. Network configuration on the Wifi network is derived via DHCP, the Oktopus DHCP server will not interfere with the wifi network.

Log in on the Sensor Computer

Oktopus provides only a root login using SSH key authentication. There is no user account, no sudo, and no password login. You can provide an SSH public key before staring the build, which can later be used for the root login. In order to do this you just need to copy your public key to in the root folder of this repository. Note that even EC, or DSA keys should be named If you do not provide your own SSH key, the build script will conveniently generate one. You can then later login to Oktopus, by typing:

ssh -i id_rsa root@oktopus

Function outline

OS Image

The Makefile uses debootstrap to set up a Raspbian environment. Package signatures will be verified. Operations within the Raspbian environment are performed using qemu. Thus building on a x86 host platform is possible. The environment is then copied to an image file using loopback mounting. The files directory contains an overlay of Raspbian config files, which are copied into the image file at this stage. Since this happens at image creation, the debootstrapped root directory is modified as little as possible.

The list of raspbian packages which are installed in the chroot environmant can be extended in

Bluetooth and Wifi Networking

DHCP and DNS services on Oktopus are provided by dnsmasq. Bluetooth networking is provided by the regular Linux Bluetooth stack using hci, bridge, and ip/ifup utilities. All attempts to connect to the Bluetooth network ap are trusted automatically, this is facilitated by a shell loop in (files/)etc/rc.local (autotrust is not otherwise provided by the Bluetooth stack). As a matter of convenience during testing and debugging the sensor computer can also join an existing Wifi network. Wifi credentials can be provided in Because Oktopus will not provide DHCP and DNS on Wifi, the name resolution for Oktopus services will not work on Wifi and the sensor webapp may not be usable. Only Bluetooth networking is intended for this kind of operation.

Sensor readout and Webapp

The sensor application is currently under development. The gummikraken submodule provides virtual sensors with simulation data. Gummikraken will be gradually replaced by working sensor drivers.

The display application (oktopus_frontend) is developed as a separate project. See its respective repository for a detailed documentation.

Also see git submodules:

  • gummikraken (to be removed)
  • teesock
  • gummikraken/oktopus_frontend (submodule to be moved to the main repo)

The sensor application resides under /srv/ in the generated system image. Each sensor is read periodically by a distinct program. Each sensor program provides sensor readout on stdout in a short time interval of its own choosing. All sensor programs are launched in parallel by The sensor data is accumulated and provided on a Unix socket (/tmp/oktopus.sock) by the program teesock. Each connection to this socket will yield a copy of the current sensor stream.

The display application is served over HTTP by the busybox httpd, which is launched from inetd. The display reads the sensor data as an HTTP Event Stream from port 8200 (Okt-Two-pus ;-). The Event Stream is generated from the sensor stream on the aforementioned Unix socket. Conversion of the seonsor readout to the HTTP Event Stream format is done by, which is also launched via inetd.


  • include the sensor driver and utilities (so far: temperature, ...)
  • include the display application (done)
  • provide the display application via web server (done)
  • possibly counter DNS rebind protection by identifying as gateway and redirect via iptables (may not be necessary)


This program was originally developed on behalf of the Hochschule für Technik und Wirtschaft Berlin. The program is licensed under the GNU Affero General Public License. See LICENSE.TXT for details.

You can’t perform that action at this time.