Skip to content

Commit

Permalink
Merge pull request #2668 from reubenmiller/docs-update-rugpi-instruct…
Browse files Browse the repository at this point in the history
…ions

docs: update rugpi instructions to align with rugpi v0.6
  • Loading branch information
reubenmiller authored Feb 5, 2024
2 parents 144a3af + 7270cdc commit b688538
Showing 1 changed file with 73 additions and 50 deletions.
123 changes: 73 additions & 50 deletions docs/src/extend/firmware-management/building-image/rugpi/tutorial.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,8 @@ The instructions on this page can be used to build images for the following devi
* Raspberry Pi 1 (32 bit)
* Raspberry Pi 2 (64 bit)
* Raspberry Pi 3 (64 bit)
* Raspberry Pi 4 (64 bit)
* Raspberry Pi 4 / 400 (64 bit)
* Raspberry Pi Compute Module 4 (64 bit)
* Raspberry Pi 5 (64 bit)
* Raspberry Pi Zero W (32 bit)
* Raspberry Pi Zero 2W (64 bit)
Expand All @@ -36,8 +37,29 @@ Images can be built using Rugpi using a CI Workflow. An example for a Github Wor

The [tedge-rugpi-images](https://github.com/thin-edge/tedge-rugpi-image) project includes out of the box configurations to perform robust Over-the-Air Operating System updates.

The [tedge-rugpi-core](https://github.com/thin-edge/tedge-rugpi-core) project contains the %%te%% specific recipes which are used to build the image.

Feel free to clone the project if you want to make your own customizations, however please always refer back to the project if you run into any problems (as it may have changed in the meantime).

### Pre-requisites

To run the project tasks, you will need to install a command line tool called [just](https://just.systems/man/en/chapter_5.html).

You can install just using on of the following commands:

```sh tab={"label":"homebrew"}
brew install just
```

```sh tab={"label":"cargo"}
cargo install just
```

```sh tab={"label":"script"}
curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | sudo bash -s -- --to /usr/bin
```

For other installation possibilities check out the [just documentation](https://just.systems/man/en/chapter_4.html).

### Cloning the project

Expand All @@ -48,92 +70,101 @@ Feel free to clone the project if you want to make your own customizations, howe
cd tedge-rugpi-image
```

2. Install [just](https://just.systems/man/en/chapter_5.html) which is used to run different tasks provided by the project
2. Create a custom `.env` file which will be used to store secrets

```sh
curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | sudo bash -s -- --to /usr/bin
cp env.template .env
```

Check out the [justfile website](https://just.systems/man/en/chapter_5.html) for more installation options.
The `.env` file will not be committed to the repo

### Customizing your own image
3. Add your public ssh key to the `.env` file

1. Fork the project
Adding public SSH keys to the project will allow you to access after the image is flashed to the device (which is critical for the onboarding process). The SSH keys are provided in the form of environment variables where the variable names start with `SSH_KEY_<description>` and are added to the authorized keys for the root user, e.g. `/root/.ssh/authorized_keys`.

2. Edit the authorized ssh keys for each profile
For example:

Edit the `root_authorized_keys` under each toml file in the `profiles/` directory, and add the public ssh keys whom you want to grant ssh access to for the device. Below shows one example.
```
SSH_KEYS_bootstrap="ssh-rsa xxxxxxx"
```

:::tip
This step is critical as it will enable you to connect via SSH to your device to perform tasks such as onboarding! If you don't set your ssh public key in the authorized keys, you then need to connect your device to a monitor/display and keyboard in order to perform the onboarding.
:::
4. Optional: Add Wifi ssid/password
```toml title="file: profiles/default.toml"
#...
If your device does not have an ethernet adapter, or if you want to connect the device to a Wifi network for onboarding, then you will have to add the Wifi credentials to the `.env` file.
[parameters.ssh]
root_authorized_keys = """
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDfhQGWWw73ponAokdNSRZ5cQc9/CIX1TLQgYlr+BtObKoO4UNFP1YSbgK03GjhjeUid+QPmV+UURqxQTqLQoYWqUFP2CYkILFccVPmTvx9HLwupI+6QQKWfMDx9Djfph9GzInymaA5fT7hKppqittFrC/l3lkKgKTX5ohEOGshIbRgtgOYIaW3ByTx3urnaBbYCIgOyOZzSIyS0dUkwsiLu3XjPspgmn3Fs/+vofT/yhBe1carW0UM3ivV0JFfJzrxbCl/F7I2qwfjZXsypjkwlpNupUMuo3xPMi8YvNvyEu4d+IEAqO1dCcdGcxlkiHxrdITIpVLt5mjJ2LauHE/H bootstrap
"""
Below shows the environment variables that should be added to the `.env` file.
# ...
```sh
SECRETS_WIFI_SSID=example
SECRETS_WIFI_PASSWORD=yoursecurepassword
```
:::tip
This step is critical as it will enable you to connect via SSH to your device to perform tasks such as onboarding! If you don't set your ssh public key in the authorized keys, you then need to connect your device to a monitor/display and keyboard in order to perform the onboarding.
:::
The Wifi credentials only need to be included in the image that is flashed to the SD card. Subsequent images don't need to included the Wifi credentials, as the network connection configuration files are persisted across images.

3. Commit the changes
If an image has Wifi credentials baked in, then you should not make this image public, as it would expose your credentials!
:::

4. You can now add any custom recipes to your project if you want to include additional packages in your image, or configure items.

See the [Rugpi System Customization](https://oss.silitics.com/rugpi/docs/guide/system-customization) docs for details on how to do this or follow clues from some of the existing recipes included in the [tedge-rugpi-images](https://github.com/thin-edge/tedge-rugpi-image) project.

### Building an image

:::info
Currently building is only supported on a Linux environment. It is strongly encouraged to use the Github workflow to build the image.
:::
Building an image will produce a `.xz` file which can either by flashed to an SD card (or device). Afterwards your device will be enable to apply the same type of image via OTA updates.

Images can be built in MacOS or Linux environments (including WSL 2), however if you have problems building the image, then you can build the images using the Github workflow after forking the project.


1. Build an image for your device (machine)

```sh tab={"label":"Pi\tZero"}
just IMAGE_ARCH=armhf PROFILE=armhf VARIANT=pi01 build-all
just build-pizero
```

```sh tab={"label":"Pi\t1"}
just IMAGE_ARCH=armhf PROFILE=armhf VARIANT=pi01 build-all
just build-pi1
```

```sh tab={"label":"Pi\t2"}
just IMAGE_ARCH=arm64 PROFILE=default VARIANT=pi023 build-all
just build-pi2
```
```sh tab={"label":"Pi\t3"}
just IMAGE_ARCH=arm64 PROFILE=default VARIANT=pi023 build-all
just build-pi3
```
```sh tab={"label":"Pi\tZero2W"}
just IMAGE_ARCH=arm64 PROFILE=default VARIANT=pi023 build-all
just build-pizero2w
```

```sh tab={"label":"Pi\t4\t(With\tFirmware)"}
just IMAGE_ARCH=arm64 PROFILE=default VARIANT=pi4 build-all
just build-pi4-include-firmware
```

```sh tab={"label":"Pi\t4\t(Without\tFirmware)"}
just IMAGE_ARCH=arm64 PROFILE=default VARIANT=pi45 build-all
just build-pi4
```

```sh tab={"label":"Pi\t5"}
just IMAGE_ARCH=arm64 PROFILE=default VARIANT=pi45 build-all
just build-pi5
```

:::info
:::note
See the [tips](#raspberry-pi-4-image-selection) for helping you select which Raspberry Pi 4 image is suitable for you (e.g. with or without the EEPROM firmware update)
:::

2. Inspect the built image
2. Flash the base image using the instructions on the [Flashing an image](../../flashing-an-image.md) page

```sh
ls -ltr build/*.img
```

3. Flash the base image using the instructions on the [Flashing an image](../../flashing-an-image.md) page
:::info
The above tasks are actually just user-friendly helpers to make it easier to select the right image for your device, so some build-xxx tasks actually build the same output image (e.g. `build-pi4` and `build-pi5` produce the same image).

If you want more control over the process you can use the command, and select one of the images as defined in the [rugpi-bakery.toml](https://github.com/thin-edge/tedge-rugpi-image/blob/main/rugpi-bakery.toml)

For more information about Rugpi repositories, layers and overall concepts please read the [official Rugpi documentation](https://oss.silitics.com/rugpi/docs/guide/system-customization/).
:::


## Tips
Expand Down Expand Up @@ -181,29 +212,21 @@ INFO[0000] mountType: virtiofs
INFO[0000] socket: unix:///Users/johnsmith/.colima/default/docker.sock
```

### Permission denied error caused by xz
Try running the command with sudo. On some systems sudo is required to properly create the compressed xz file.
For exampke, the `build-all` task can be called with sudo:
```sh
sudo just IMAGE_ARCH=arm64 PROFILE=default VARIANT=pi45 build-all
```
### Raspberry Pi 4 image selection

Raspberry Pi 4 devices need to have their (EEPROM) firmware updated before the OTA updates can be issued. This is because the initial Raspberry Pi 4's were released without the [tryboot feature](https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#fail-safe-os-updates-tryboot). The tryboot feature is used by Rugpi to provide the reliable partition switching between the A/B partitions. Raspberry Pi 5's have support for tryboot out of the box, so they do not require a EEPROM upgrade.

You can build an image which includes the required EEPROM firmware to enable the tryboot feature, however this image can only be used to deploy to Raspberry Pi 4 devices (not Raspberry Pi 5!)

```sh
just IMAGE_ARCH=arm64 PROFILE=default VARIANT=pi4 build-all
just build-pi4-include-firmware
```

After the above image has been flashed to the device once, you can switch back to the image without the EEPROM firmware so that the same image can be used for both Raspberry Pi 4 and 5.

```sh
just IMAGE_ARCH=arm64 PROFILE=default VARIANT=pi45 build-all
just build-pi4
# or
just build-pi5
```

1 comment on commit b688538

@github-actions
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Robot Results

✅ Passed ❌ Failed ⏭️ Skipped Total Pass % ⏱️ Duration
390 0 3 390 100 52m51.794999999s

Please sign in to comment.