Skip to content

Latest commit

 

History

History
94 lines (64 loc) · 4.83 KB

RAKPiOS.md

File metadata and controls

94 lines (64 loc) · 4.83 KB
Raw

RAKPiOS

This document describes the differences of RAKPiOS with Raspberry Pi OS.

Introduction

This tool is used to create RAKPiOS images, a custom image based on Raspberry Pi OS, which was in turn derived from the Raspbian project.

The RAKPiOS image differs from the stock Raspberry Pi OS in:

  • Custom kernel with support for WiFi Next Gen AGN
  • Overlays for existing components in RAK7391
  • Docker installed by default
  • Brings up a WiFi Access Point if no other connection is active
  • Custom MOTD
  • SSH, I2C and SPI enabled by default
  • Set of utilities
    • OLED script to leverage a connected SSD1306 OLED screen to display system metrics
    • rakpios-cli to manage network and docker images
  • Default user (rak) and password (changeme), forces user to create new password on first login

RAKPiOS specific building stage

Changes to the default Raspberry Pi OS image are defined on the stage2-rak stage. This is used to build a customized image for RAK WisGate Developer products. The stage will make some changes to the systems, including pre-installing docker and other tools, adding new kernel modules, updating system information, and adding some new features tailored for RAK WisGate Developer products.

As mentioned in the original README.md (see https://github.com/RPI-Distro/pi-gen.git), users can define a variable called STAGE_LIST in the configuration file to change the order of building stages. In the config_rak file, variable STAGE_LIST is set to stage0 stage1 stage2 stage2-rak, then instead of working through the numeric stages in order, this list will be followed.

RAKPiOS is a lite system, thus the build will skip stage 3, stage 4, and stage 5 which are only for a desktop system with a graphical user interface.

We defined some original configuration tags and also introduced some custom configuration tags in the config_rak file.

NAME="RAKPiOS"
VERSION=0.8.1
ARCH=arm64
RELEASE=bookworm

IMG_NAME="${NAME,,}-${VERSION}-${ARCH}"
PI_GEN_RELEASE="${NAME,,}-${VERSION}-${RELEASE}"
TARGET_HOSTNAME="${NAME,,}"
IMG_DATE=$( date +%Y%m%d )
ARCHIVE_FILENAME="${IMG_DATE}-${IMG_NAME}"
FIRST_USER_NAME=rak
FIRST_USER_PASS=changeme
DISABLE_FIRST_BOOT_USER_RENAME=1
ENABLE_SSH=1
STAGE_LIST="stage0 stage1 stage2 stage2-rak"

PI_GEN_REPO=https://github.com/RAKWireless/rakpios
KERNEL_BUILD=0
KERNEL_CACHED=1
KERNEL_TAG=rpi-6.6.y

For more details about the original configurations, please check the original README.md . For custom configuration tags, now you can define whether you want to build the kernel (KERNEL_BUILD and KERNEL_TAG variables), use the cached image (KERNEL_CACHED variable) or just leave it to the official kernel. If KERNEL_BUILD is set to 1 but no KERNEL_TAG is defined then it defaults to the HEAD of the rpi-6.6.y branch. But please mind that some specific kernel patches (like GPIO Expander support) will not be applied since they are version-dependent. The final step is to launch the build.sh script：

apt-get install coreutils quilt parted qemu-user-static debootstrap zerofree zip \
dosfstools libarchive-tools libcap2-bin grep rsync xz-utils file git curl bc \
gpg pigz xxd arch-test
./build.sh -c config_rak

or, you can use docker to perform the build:

./build-docker.sh -c config_rak

Please check the original README.md to see how to skip stages and also how to continue the build after a failure.

How the stage2-rak stage works

There are a number of different directories in the stage2-rak directory:

  • 00-base - Updates and installs new packages, new config.txt, sets up custom firstboot script

  • 01-docker - Installs docker, docker compose plugin, and adds user rak to docker group.

  • 02-kernel - Cross-builds a kernel that is tailored to the RAK7391.

  • 03-utils - Installs several scripts and utilities: boot AP, OLED script, portainer, MOTD, and so on.

Notice

  • The default login credentials for the pre-built image are username: rak and password: changeme. Please note that it is important to change the default password upon first login to enhance security.

  • In the case of WiFi-enabled CM4 modules and Raspberry Pi, the image will automatically create an access point when the device boots and no other connectivity options are enabled. This feature is based on WiFi-connect developed by Balena.

    This access point, named RAK_XXXX (where XXXX represents the last four digits of the eth0 MAC address), enables users to configure an existing connection. The access point is secured with the password rakwireless. After connecting to the access point from a mobile phone or laptop, the captive portal will be detected and the web page will automatically open. In the event that the captive portal does not automatically redirect, please browse to 192.168.230.1 to access the captive portal.