dotpi-install

Intro

This utility prepares a Raspberry Pi for running in a dotpi distributed system. It serves several purposes:

locally configure a project
run locally to prepare the SD card
run on Raspberry Pi to prepare the remote system
add utilities and services to the remote system

Getting started

In the project folder, select a project that is close to your needs: example-dev is quite complete.

Do not forget to install the pair SSH keys from projects/example-dev/secrets/ssh to local you ${HOME}/.ssh configuration.

Download and install the Raspberry Pi Imager.
Select OS (operating system)
- Choose Rapsberry Pi OS (other)
- Choose Rapsberry Pi OS Lite (64-bit)
- For Raspberry Pi 3, you may need to select No filtering or separately download a non-legacy OS, and choose Use custom.
Insert a new SD card in your computer
Select it as the storage
You may change somme settings. In particular, you can choose not to eject media when done, to avoid pulling the SD card out, then inserting it again.
Write the SD card
You you choose to apply the settings, these will be the defaults before applying the dotpi settings

In a terminal:

# change path to the dotpi-install folder
cd ~/src/dotpi-install

# prepare the SD car with the chosen project
./dotpi_root/bin/dotpi_prepare_sd_card --project ./projects/example-dev

Type the instance number, or accept the default. The first instance will be 1

Put the SD card into a Raspberry
Power it on
Connect it to the internet, and to you computer

You may then copy the last line to get info of the remote process.

Any SSH operation will wait until the network on the Raspberry Pi is ready.

# This will monitor the first instance of the `dev` project
ssh [email protected] 'tail -f /opt/dotpi/var/log/dotpi_prepare_system_*.log'

When done, you can connect.

ssh [email protected]

It should also appear in the dotpi-manager.

Settings

Raspberry Pi Imager

The installer will first apply the settings of the Raspberry Pi Imager.

In particular:

host-name
ssh access
- you can allow for password authentication (in case the authentication via key fails)
user and password
- user name: not recommended to change
- user password, when ssh is not available
the wifi settings will be over-ridden
you can avoid the eject the SD car when done

Environment defaults

Then, dotpi-install will apply the default settings of the dotpi environment.

dotpi_root/etc/dotpi_environment_default.bash

You should not change anything here. Instead, you can over-ride any value in your projects.

Project settings

Then, dotpi-install will apply the default settings of your project.

`configuration` folder

This folder is for "public" settings, that you would share on a repository.

In you project, there is a configuration file named configuration/dotpi_project.bash, where you can override any value.

Note that you can also extend settings, by appendind to bash arrays:

# this add `screen` to the list of packages to install
dotpi_apt_install+=(
  screen
)

In particular, you can change the name of your project. (The default is the folder name.)

dotpi_project_name='dev'

The remote machine hosnames will be on the form dotpi-dev-xxx with xxx as the instance numbers.

You can also choose your audio device.

dotpi_audio_device='HiFiBerry DAC+ ADC Pro'

`jackd` folder

You can add a jackd folder in you <project>/configuration folder, in order to over-ride jackd settings from dotpi-root/share/jackd.

Note that there is a symbolic link to configuration for known sound-cads. If it does not suit your needs, you can use a dotpi_jackd.bash configuration file.

# keep this
DOTPI_JACKD_ENVIRONMENT=(
  JACK_NO_AUDIO_RESERVATION=1
)

# warning: long option for -d (--driver) seems broken

DOTPI_JACKD_ARGUMENTS=(
  --realtime
  --realtime-priority 95
  -d alsa
  --device hw:0
  --playback
  --period 1024
  --nperiods 2
  --rate 48000
)

`secrets` folder

This folder is for "private" settings, that you would not share on a repository.

In you project, there is a configuration file named secrets/dotpi_secrets.bash, where you can chage the password.

dotpi_password='!rapsberry'

`network` folder

You can add any NetworkManager configuration file. Be sure not to quote values, including ssid and psk, as anything is part of the value, including quotes.

To keep the automatic configuration for the ethernet interface, do not add it here.

To keep NetworkManager functional, do not configure network in an other way (ie. no wpa_supplicant.conf file).

`ssh` folder

Be sure to install the pair of SSH keys in you ${HOME}/.ssh configuration.

Instance settings, `tmp` folder

The last step is to apply particular settings relative to the instance.

After sucessfully preparing an SD card, a copy of the last settings will be in your pject, in a tmp folder.

dotpi_prepare_sd_card_*.log is a copy of the screen messages
dotpi_tmp.bash contains the instance number (to increment for the next time)
file-system is a full copy of what will be installed on the Raspberry Pi.

On the Raspberry Pi

Any system-wide installation will link to the /opt/dotpi directory. Except the following.

The /boot/firmware folder (mounted as /bootfs as a local SD card) contains the config.txt file.

Commands

Use dotpi or sudo dotpi to run any dotpi_function function.

`/boot/firmware` `/bootfs`

config.txt is the hardware configuration file.
firstrun_*.log is the log the the first run
- Intentionnaly, the network does not start at this stage
the dotpi folder contains the initial version of the dotpi file-system, and a non-customised version of the firstrun.sh script from the imager.

`/opt/dotpi`

/opt/dotpi/bin/dotpi is the main executable, installed in /usr/bin

`/opt/dotpi/etc`

config.txt is an initial copy of the hardware configuration. It may diverge after any mofdification.
dotpi_environment_*.bash contain the customisation of the environment
network contains the network configuration, that where copied to /etc/NetworkManager/system-connections. It may diverge after any mofdification.
ssh contains the public SSH keys that were copied to ${HOME}/.ssh/authorized_keys

`/opt/dotpi/share`

dotpi-manager contains the client and the service. Use sudo dotpi manager_update to update the client.
jackd contains the configuration and the service.
limits contains the limits that were copied to /etc/security/limits.d.
n contains the node version manager. node.js itself, is in /home/pi/n/bin/node and linked in /usr/bin/node.

`/opt/dotpi/var/log`

Log files.

dotpi_prepare_system_*.log contains the log of the system preparation
dotpi_manager_update_*.log contain the logs of the dotpi-manager updates

`/usr/local/bin`

This is an alias to /usr/bin.

Other

Local machine

If you install wpa_passphrase, wifi passwords will be hashed.

You should install the version 3 of rsync to get quicker transfer times with dotpi-manager.

rsync --version | grep version

Remote Raspberry Pi

Network

Everything is managed via NetworkManager. You can use nmtui to use a user-interface.

You also directly use nmcli with a command-line interface.

nmcli device
# DEVICE         TYPE      STATE                   CONNECTION
# eth0           ethernet  connected               Wired connection 1
# lo             loopback  connected (externally)  lo
# wlan0          wifi      disconnected            --
# p2p-dev-wlan0  wifi-p2p  disconnected            --

nmcli radio
# WIFI-HW  WIFI     WWAN-HW  WWAN
# enabled  enabled  missing  enabled

`jackd`

In order to play soundfiles via jackd, you can install mpv

mpv --ao=jack 'sound.mp3'

You can monitor a jack connection in a terminal with. Warning, you need to install the jackmeter package but the command is jack_meter.

# list jack connections
jack_lsp
# system:capture_1
# system:capture_2
# system:playback_1
# system:playback_2
# cpal_client_out:out_0
# cpal_client_out:out_1
# cpal_client_out-01:out_0
# cpal_client_out-01:out_1

# monitor the system output
jack_meter system:playback_1

# monitor a particular connection
jack_meter mpv:out_0

Raspberry pi

You can get various information about the hardware and software.

cat /proc/device-tree/model
# Raspberry Pi 4 Model B Rev 1.4pi

# 64bit kernel (even for 32bit system)
uname -a
# Linux dotpi-dev-019 6.1.21-v8+ #1642 SMP PREEMPT Mon Apr  3 17:24:16 BST 2023 aarch64 GNU/Linux

# 64bit kernel (even for 32bit system)
arch
# aarch64

# 32bit system
file $(which file)
# /usr/bin/file: ELF 32-bit LSB executable, ARM, EABI5 version 1 (SYSV), dynamically linked, interpreter /lib/ld-linux-armhf.so.3, BuildID[sha1]=f5f7f7c84dbb609f53ae3b9ac6b4437d927bde7d, for GNU/Linux 3.2.0, stripped

Known bugs

Please do report them.

do not allow . character in project, it generates an invalid hostname.

Todo

dotpi-manager: dependency to audio should be soft
- allow client to run without audio
- client should continue to run if audio stops
@dotpi/audio-module
- generate
- soft limiter at audio output
  - pipewire filter-chain Cf. https://flaterco.com/kb/audio/pipewire/volume.html
  - easy effect Cf. https://github.com/wwmm/easyeffects/wiki/Command-Line-Options

Name		Name	Last commit message	Last commit date
Latest commit History 294 Commits
dotpi_root		dotpi_root
examples		examples
src		src
test		test
.gitignore		.gitignore
BACKUP-SANDO.command		BACKUP-SANDO.command
BACKUP-SISIDO.command		BACKUP-SISIDO.command
DEV.md		DEV.md
DOC.md		DOC.md
LICENSE		LICENSE
NOTES.md		NOTES.md
README.md		README.md
dotpi-tools.js		dotpi-tools.js
ismm-projects		ismm-projects
lerna.json		lerna.json
package-lock.json		package-lock.json
package.json		package.json

License

ircam-ismm/dotpi-tools

Folders and files

Latest commit

History

Repository files navigation

dotpi-install

Intro

Getting started

Settings

Raspberry Pi Imager

Environment defaults

Project settings

configuration folder

jackd folder

secrets folder

network folder

ssh folder

Instance settings, tmp folder

On the Raspberry Pi

Commands

/boot/firmware /bootfs

/opt/dotpi

/opt/dotpi/etc

/opt/dotpi/share

/opt/dotpi/var/log

/usr/local/bin

Other

Local machine

Remote Raspberry Pi

Network

jackd

Raspberry pi

Known bugs

Todo

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors 2

Uh oh!

Languages

`configuration` folder

`jackd` folder

`secrets` folder

`network` folder

`ssh` folder

Instance settings, `tmp` folder

`/boot/firmware` `/bootfs`

`/opt/dotpi`

`/opt/dotpi/etc`

`/opt/dotpi/share`

`/opt/dotpi/var/log`

`/usr/local/bin`

`jackd`

Packages