Skill: pi-config

# Skill: pi-config

Patterns for Raspberry Pi boot partition configuration injection.

## Boot partition layout

After `dd` writes the image, the first partition on the SD card is the boot partition (FAT32, label `bootfs` or `boot`).
This partition contains files read by the Pi firmware and the first-boot service (`pi-init`).

| File | Purpose |
|------|---------|
| `ssh` | Empty file - enables SSH daemon on first boot |
| `wpa_supplicant.conf` | Wi-Fi config (WPA2-Personal) - read on first boot and removed |
| `userconf` | `username:sha512crypt_hash` - creates initial user on first boot |
| `config.txt` | Hardware config: dtoverlay, GPU memory, HDMI settings |
| `cmdline.txt` | Kernel command line (do not overwrite; append only) |

## Mounting the boot partition

### Linux

```ts
import { execa } from 'execa';
import path from 'path';
import fs from 'fs/promises';
import os from 'os';

export async function mountBootPartition(device: string): Promise<string> {
  // e.g. /dev/sdb -> /dev/sdb1
  const partition = `${device}1`;
  const mountPoint = await fs.mkdtemp(path.join(os.tmpdir(), 'pi-boot-'));

  await execa('mount', [partition, mountPoint]);
  return mountPoint;
}

export async function unmount(mountPoint: string): Promise<void> {
  await execa('umount', [mountPoint]);
  await fs.rm(mountPoint, { recursive: true, force: true });
}
```

### macOS

On macOS, after `dd` the boot partition is auto-mounted at `/Volumes/bootfs`. No manual mount needed.
Detect the mount point by checking `/Volumes`:

```ts
export async function findMacOsBootMount(device: string): Promise<string> {
  // disk2 -> disk2s1
  const partition = device.replace('/dev/', '') + 's1';
  const { stdout } = await execa('diskutil', ['info', '-plist', partition]);
  const plist = parsePlist(stdout);  // use 'plist' npm package
  return plist.MountPoint as string;
}
```

## wpa_supplicant.conf

```ts
export function buildWpaSupplicant(ssid: string, password: string, country: string): string {
  return [
    'ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev',
    'update_config=1',
    `country=${country.toUpperCase()}`,
    '',
    'network={',
    `\tssid="${ssid}"`,
    `\tpsk="${password}"`,
    '\tkey_mgmt=WPA-PSK',
    '}',
  ].join('\n') + '\n';
}
```

Write to `<mountPoint>/wpa_supplicant.conf`.

Note: As of Raspberry Pi OS Bookworm (2023-10), the OS no longer reads `wpa_supplicant.conf` from the boot partition during cloud-init. Instead use `custom.toml` (see below). For compatibility with older images, write both.

## cloud-init (Pi OS Bookworm and later)

Newer Pi OS images use cloud-init. Write `user-data` and `network-config` to the boot partition.

```ts
export function buildUserData(hostname: string, username: string, passwordHash: string, enableSsh: boolean): string {
  const lines = [
    '#cloud-config',
    '',
    `hostname: ${hostname}`,
    'manage_etc_hosts: true',
    '',
    'users:',
    `  - name: ${username}`,
    `    password: ${passwordHash}`,
    '    chpasswd:',
    '      expire: false',
    '    shell: /bin/bash',
    '    sudo: ALL=(ALL) NOPASSWD:ALL',
    '    lock_passwd: false',
  ];

  if (enableSsh) {
    lines.push('', 'ssh_pwauth: true');
  }

  return lines.join('\n') + '\n';
}

export function buildNetworkConfig(ssid: string, password: string): string {
  return [
    'version: 2',
    'wifis:',
    '  wlan0:',
    '    dhcp4: true',
    '    optional: true',
    '    access-points:',
    `      "${ssid}":`,
    `        password: "${password}"`,
  ].join('\n') + '\n';
}
```

## Full config injection

```ts
// packages/server/src/provision/config-injector.ts
import path from 'path';
import fs from 'fs/promises';
import { buildWpaSupplicant, buildUserData, buildNetworkConfig } from './templates';
import { hashPassword } from './crypto';

export async function injectConfig(mountPoint: string, config: ProvisionConfig): Promise<void> {
  const write = (filename: string, content: string) =>
    fs.writeFile(path.join(mountPoint, filename), content, 'utf8');

  // Legacy SSH enable (Pi OS Buster/Bullseye)
  if (config.enable_ssh) {
    await write('ssh', '');
  }

  // Legacy user (Pi OS Bullseye and earlier)
  if (config.username && config.password_hash) {
    await write('userconf', `${config.username}:${config.password_hash}`);
  }

  // Legacy Wi-Fi (Pi OS Bullseye and earlier)
  if (config.wifi_ssid && config.wifi_password) {
    await write(
      'wpa_supplicant.conf',
      buildWpaSupplicant(config.wifi_ssid, config.wifi_password, config.wifi_country ?? 'GB')
    );
  }

  // Cloud-init (Pi OS Bookworm)
  if (config.username && config.password_hash) {
    await write(
      'user-data',
      buildUserData(config.hostname, config.username, config.password_hash, config.enable_ssh)
    );
  }

  if (config.wifi_ssid && config.wifi_password) {
    await write(
      'network-config',
      buildNetworkConfig(config.wifi_ssid, config.wifi_password)
    );
  }

  // Ensure writes are flushed to disk before unmounting
  await execa('sync');
}
```

## config.txt modifications

Append only - never replace the entire config.txt:

```ts
export async function appendConfigTxt(mountPoint: string, lines: string[]): Promise<void> {
  const configPath = path.join(mountPoint, 'config.txt');
  const existing = await fs.readFile(configPath, 'utf8').catch(() => '');
  const toAppend = lines.filter((l) => !existing.includes(l));
  if (toAppend.length > 0) {
    await fs.appendFile(configPath, '\n# pi-provisioner additions\n' + toAppend.join('\n') + '\n');
  }
}
```

Common config.txt additions:
- `dtparam=audio=on` - enable audio
- `gpu_mem=16` - minimal GPU memory for headless
- `dtoverlay=disable-wifi` - disable Wi-Fi

## Simulate mode boot partition

When `ALLOW_SIMULATED_WRITE=1`, write config files to a temporary directory instead of a real mount:

```ts
export async function getSimulatedBootMount(): Promise<string> {
  const dir = path.join(os.tmpdir(), 'pi-provisioner-sim-boot');
  await fs.mkdir(dir, { recursive: true });
  return dir;
}
```

The config files written to this temp dir can be logged for debugging.

## cmdline.txt - hostname approach (older images)

Some older images set the hostname via cmdline.txt. Avoid this - use `userconf` or cloud-init `hostname:` instead. Never modify `cmdline.txt` hostname unless you are certain the image reads it.

## Sync before unmount

Always run `sync` before unmounting to ensure filesystem buffers are flushed:

```ts
await execa('sync');
await execa('umount', [mountPoint]);
```

On macOS use `diskutil eject`:

```ts
await execa('diskutil', ['eject', partition]);
```

## Pi OS version detection heuristic

Check for `user-data` in the boot partition to determine if it is a Bookworm+ image:

```ts
async function isBookwormOrLater(mountPoint: string): Promise<boolean> {
  try {
    await fs.access(path.join(mountPoint, 'user-data'));
    return true;
  } catch {
    return false;
  }
}
```

Use this to decide whether to write cloud-init files vs legacy `userconf`/`wpa_supplicant.conf`.

## Wi-Fi password storage rule

The Wi-Fi password must never be stored in SQLite. Pass it through in memory from the wizard form body directly to `injectConfig`, then discard. The `provisions` table schema does not have a `wifi_password` column.