neon-image-recipe

Make a Pi image from scratch. - Core Configuration - Base configuration of ubuntu server - Network Manager - Configures networking to allow for wifi configuration via wifi-connect. - SJ201 Support - Installs and configures drivers and scripts to run the SJ-201 HAT. - OVOS Shell - Installs and configures the GUI shell - Neon Core - Installs Neon Core with dependencies. - Dashboard - Installs a web dashboard for device diagnostics - Camera - Installs system dependencies for CSI Camera Support - Splash Screen - Configures device splash screen on boot

Docker Automated Image Building

The included Dockerfile can be used to build a default image in a Docker environment.

The following dependencies must be installed on the build system before running the container:

• chroot
• qemu-user-static

First, create the Docker container:

docker build . -t neon-image-builder

Then, run the container to create a Neon Image. Set CORE_REF to the branch of neon-core that you want to build and RECIPE_REF to the branch of neon-image-recipe you want to use. Set MAKE_THREADS to the number of threads to use for make processes.

sudo mknod /dev/loop99 b 7 99
sudo losetup -P /dev/loop99 {image}
# TODO: Above is just creating p1/p2 files; can this be done via mknod or something?

docker run \
-v /home/${USER}/output:/output:rw \
-v /run/systemd/resolve:/run/systemd/resolve \
-v /dev/loop99:/dev/loop99 \
-v /dev/loop99p1:/dev/loop99p1 \
-v /dev/loop99p2:/dev/loop99p2 \
-e CORE_REF=${CORE_REF:-dev} \
-e RECIPE_REF=${RECIPE_REF:-master} \
-e BASE_IMAGE=${BASE_IMAGE:-debian-base-image-rpi4} \
-e MAKE_THREADS=${MAKE_THREADS:-4} \
--privileged \
--network=host \
--name=neon-image-builder \
neon-image-builder

Base Image Selection

The BASE_IMAGE environment variable selects which image is mounted and built on. Valid base images are uploaded to 2222.us and specified by their file basename (i.e. debian-base-image-rpi4_2022-11-08_18_50). The latest debian-base-image-rpi4 is generally a good choice and is the latest output from neon_debos.

The entire build process will generally take several hours; it takes 1-2 hours on a build server with 2x Xeon Gold 5118 CPUs (48T Total).

Build-Time Overlay Files

Files to be overlaid on the image file system can be placed in /output/overlay. These files will be moved to the build directory and applied as described in below.

Interactive Image Building

The scripts in the automation directory are available to help automate building a default image. For building an image interactively, specify paths for IMAGE_FILE and BUILD_DIR before running the below commands:

bash automation/prepare.sh "${IMAGE_FILE}" "${BUILD_DIR}"
bash /tmp/run_scripts.sh

Image Overlay Files

Extra files to be included in the image can be placed in ${BUILD_DIR}/overlay. This directory will be recursively copied to the image at the beginning of the build process. This may be useful for including key files or other files that do not belong in the image recipe repository.

The below documentation describes how to manually build an image using the individual scripts in this repository.

Getting Started

The scripts and overlay files in this repository are designed to be applied to Ubuntu Server 22.04 as the root user. It is recommended to apply these scripts to a clean image available here. Instructions are available at opensource.com.

Note: The GUI shell is not installable under Ubuntu 20.04 and earlier

For each step except boot_overlay, the directory corresponding to the step should be copied to the mounted image and the script run from a terminal chroot-ed to the image. If running scripts from a booted image, they should be run as root.

Preparation

From the host system where this repository is cloned, running prepare.sh <base_image> will copy boot overlay files, mount the image, mount DNS resolver config from the host system, copy all other image overlay files to /tmp, and chroot into the image. From here, you can run any/all of the following scripts to prepare the image before cleaning up

core_configuration

Configures user accounts and base functionality for RPi. neon user is created with proper permissions here.

At this stage, a booted image should resize its file system to fill the drive it is flashed to. Local login and ssh connections should use neon/neon to authenticate and be prompted to change password on login.

network_manager

Adds Balena wifi-connect to enable a portal for connecting the Pi device to a wifi network.

A booted image will now be ready to connect to a network via SSID Neon.

sj201

For SJ201 board support, the included script will build/install drivers, add required overlays, install required system packages, and add a systemd service to flash the SJ201 chip on boot. This will modify pulseaudio and potentially overwrite any previous settings.

Note: Running this scripts grants GPIO permissions to the gpio group. Any user that interfaces with the SJ201 board should be a member of the gpio group. Group permissions are not modified by this script

Audio devices should now show up with pactl list. Audio devices can be tested in the image by recording a short audio clip and playing it back.

parecord test.wav
paplay test.wav

embedded_shell

Installs ovos-shell and mycroft-gui-app. Adds and enables neon-gui.service to start the shell on system boot.

The image should now boot to the GUI shell.

neon_core

Installs neon-core and dependencies. Configures services for core modules.

At this stage, the image is complete and when booted should start Neon.

dashboard

Installs the OVOS Dashboard and service to start the dashboard from the GUI.

From the GUI Settings -> Developer Settings menu, Enable Dashboard will now start the dashboard for remote access to device diagnostics.

camera

Installs libcamera and other dependencies for using a CSI camera.

The default camera skill can be used to take a photo; libcamera-apps are also installed for testing via CLI.

splash_screen

Enables a custom splash screen and disables on-device TTY at boot.

On boot, a static image should be shown until the GUI Shell starts.

updater

Enables an updater service to update python packages.

systemctl start neon-updater will stop core services, create a code backup, install updated Python packages, validate the core modules load properly and optionally roll back changes, and then restart core services.

Clean Up

cleanup.sh removes any temporary files from the mounted image before unmounting it. After running cleanup.sh, the image is ready to burn to a drive and boot.

Patches

The patches directory contains scripts used to patch existing installations to add new features or make them compatible with updates Python modules. These files are intended to be referenced by updater scripts and should not be used during image creation.

Deprecated Scripts

base_ubuntu_server

For Ubuntu Server base images, the included scripts install the openbox DE, add a neon user with default neon password, and configure the system to auto-login and disable sleep. cleanup.sh removes the ubuntu user, expires the neon user password, and schedules a device restart.