Modules

One of the main features in CustomPiOS is writing modules. A module is a structured piece of code that adds a function to a distro.

Setting Modules

To set what the distro does, you can add and remove modules. The modules are defined in the MODULES variable set in your distro <distro folder>/src/config file. Modules can be nested, this enables you to provide namespaces or run cleanup functions after other module have run. For example MODULES=base(network(octopi, picamera)), in this example base will start first, and end last, network will start second and end one before last, octopi will start third and end first.

Writing Modules

• Module are places in folders whose names are small letters and with hyphens.
• They can be placed either in CustomPiOS/src/modules or <distro folder>/src/modules.

See the example module in the example disro.

Modules are made from 4 parts:

• start_chroot_script / end_chroot_script
• filesystem folder
• config file
• meta (optional)

Variable names in the config file of a module

In the config file you can set bash variables that would change the configuration of the module. They are automatically exported to the build and you can use them, and also set them in the main config file of a distro. Only variables with the prefix of the module name are exported. So for example the base module variables should start with BASE_. If there is a Hyphen - symbol it would be converted to an underscore. So the module example-hello should be set as EXAMPLE_HELLO_VAR.

Module types

Standard library modules

These are modules that are part of the CustomPiOS. They are listed below.

Remote modules

You can have modules that are stored on other repositories, currently implemented only for git repositories, and have them downloaded and used at build time.

They are configured in this yaml file: https://github.com/guysoft/CustomPiOS/blob/devel/src/modules_remote.yml

In the future a local yaml that lets you add repositories is possible. If you want to override the current file you can either edit it or mount one on top of it in docker using:

    volumes:
      - ./modules_remote.yml:/CustomPiOS/modules_remote.yml:ro

Meta modules

Meta modules have meta file in the modules folder. It lets a module add in sub modules based on if they are needed based on the configuration variables (for example the BASE_BOARD, module config variable, etc). So for example:

base(octopi)

Could be turned by a meta file to

base(armbian(octopi))

The meta file is an executable script that can hold any logic you like it should print to stdout the required module to add. You can see an example for one here in the network module.

List of Standard library modules

admin-toolkit

admin-toolkit helps to harden your pi, install other packages easily, and add files out of the box. Some things require a user to be added and others dont. Some things are indended to be used with FullPageOS and the scripts that come with it, but there are uses outside of that, if you edit a bit of code. This has only been used with FullPageOS, and Raspbian Buster on a pi3/4

auto-hotspot

This is a module that makes your raspberrypi a wifi hotspot if wifi fails to connect to a network. If an ethernet cable is connected it will forward the connection. Originally based on this guide. Has to be inside a disable-services module block.

auto-mount-removable

Automatically mount removable devices to /media. The format is /media/usb0 /media/usb1 and so on.

auto-mount-removable

Sets that devices would be automatically mounted to /media

base

This is the base module you must have in your distro. It sets what image is selected and critical things in the distro. You can see all available settings here. In general you will find them in the config file of the module.

cockpit-install

Cockpit is a Red Hat sponsored free software project released under the LGPL v2.1+ https://cockpit-project.org/ this module installs it

disable-services

Disables systemd services to start up right after installing them. If your module is installing something, say lighttpd. You should wrap your module with this one. Eg disable-services(lighttpd).

docker

This module installs docker. And by default also installed docker-compose. It also by default creates a folder in /boot/docker-compose (or /boot/firmware/docker-compose in ubuntu base image), which lets you places folders with docker-compose.yml files that would pull and start on boot. For an example of usage look at PhotoprismPi.

ffmpeg

Module builds and installs latest ffmpeg from git

gui

Lets you add a gui that will start on boot, autologin and GPU out of the box.

install-linux-modules-extra

Installs linux-modules-extra with a hack that is needed for it to install correctly

kernel

Builds and installs a custom kernel. Warning: building a kernel can take as long as 6 hours. And with two it takes 12 hours. If you are building them a lot its recommended to create a base image and build on top of that. See RealtimePi for usage example.

mysql

Installs and configures an mysql mariadb database with default user 'pi' and password 'raspberry'

network

This module is enabled by default, it creates a file in /boot/${DIST_NAME}-network.txt and /boot/${DIST_NAME}-wpa-supplicant.txt that lets you set up the wifi configuration from a text file that is accessable even from a windows machine.

password-for-sudo

Revert Raspbian's "no password for sudo"

pkgupgrade

This Module allows you to upgrade your packages and preinstall needed packages to your Image.
By default it performs an 'apt full-upgrade'.
If you copy this module to your 'src/modules' folder, you can set it up to perform an upgrade by your choosen method and installs given packages.
Take a look into the config File for what you can setup with this Module.

raspicam

Enables the pi camera by default

readonly

Module makes raspbian readonly, bases off of: https://github.com/adafruit/Raspberry-Pi-Installer-Scripts/blob/master/read-only-fs.sh

can definitely be extended a little more... Has been tested and is working, including ntp time

usage-statistics

Module lets you send anonymous statistics to a webserver regarding usage of your distro. Does not store any private information. Currently only reports each time the device boots, using the pi ID with obfuscation.

usbconsole

Adds a console (getty) on the Raspberry's USB Port, useful for debugging headless setups without network Use minicom or Coolterm to access your PI (Note: This has only been tested on the RPI4)