Key Configuration Files
This document describes the configuration files that control WendyOS service behaviour, where they live on the device, and what they do.
Key Configuration Files
This document describes the configuration files that control WendyOS service behaviour, where they live on the device, and what they do.
Identity and device files
| Path | Persistence | Description |
|---|---|---|
/etc/wendyos/device-uuid | Persistent (/data/etc/wendyos/) | RFC 4122 UUID generated once on first boot by wendyos-uuid-generate.service. Survives OTA updates via bind mount. |
/etc/wendyos/device-name | Persistent (/data/etc/wendyos/) | Human-readable name in adjective-noun format (e.g. brave-dolphin), generated by wendyos-device-name-generate.service. Used as the mDNS hostname and USB gadget product string. |
/etc/wendyos/device-type | Persistent (/data/etc/wendyos/) | Board identifier string (e.g. raspberry-pi-5, raspberry-pi-4). Seeded from the rootfs on first boot and kept on /data thereafter. |
/etc/wendyos/version.txt | Symlink to /usr/lib/wendyos/version.txt, refreshed via bind mount | OS version string (e.g. WendyOS-RPi-0.13.2). Updated on every OTA. |
All files under /etc/wendyos/ are bind-mounted from /data/etc/wendyos/ by wendyos-etc-binds.service early in boot.
Agent configuration
| Path | Description |
|---|---|
/etc/default/wendy-agent | Shell-format environment file sourced by both wendyos-agent.service and wendyos-agent-updater.sh. Supports WENDYOS_AGENT_GITHUB_REPO, WENDYOS_AGENT_VERSION. Not created by default; create it to override release channel. |
/var/lib/wendy-agent/ | Runtime state directory for the agent (current-version file, working data). |
/usr/local/bin/wendy-agent | Agent binary. Installed at build time; overwritten in-place by wendyos-agent-updater.service. |
/opt/wendyos/bin/wendyos-agent-updater.sh | Updater logic: checks GitHub releases API, downloads, replaces binary, restarts service. |
/opt/wendyos/bin/download-wendyos-agent.sh | Low-level downloader used by the updater. Fetches wendy-agent-linux-arm64-*.tar.gz from the latest stable GitHub release. |
Network configuration
All files under /etc/NetworkManager/system-connections/ are bind-mounted from /data/etc/NetworkManager/system-connections/ by wendyos-etc-binds.service.
| Path | Description |
|---|---|
/usr/lib/NetworkManager/system-connections/usb-gadget.nmconnection | Distro-managed profile for the usb0 interface. Read-only on the rootfs; updated on OTA. IPv4 mode is set at build time by WENDYOS_USB_NET_MODE (link-local, dhcp-client, or dhcp-server). High route-metric (700) keeps WiFi/Ethernet preferred as the default route. |
/etc/NetworkManager/system-connections/ | User-added connections (WiFi, VPN). Persisted on /data. NM gives /etc priority over /usr/lib for same-named files. |
/etc/NetworkManager/NetworkManager.conf | Main NM config: keyfile plugin, DNS managed by NM (not systemd-resolved), random MAC scan disabled, INFO-level logging to journal. |
/etc/NetworkManager/conf.d/00-manage-usb0.conf | Ensures NM manages the usb0 interface. |
/etc/NetworkManager/conf.d/10-usb-gadget.conf | Additional per-interface settings for the USB gadget connection. |
/etc/NetworkManager/conf.d/99-interface-metrics.conf | Sets route metrics so wired/WiFi interfaces are preferred over USB gadget (usb0). |
systemd journal configuration
| Path | When present | Description |
|---|---|---|
/usr/lib/systemd/journald.conf.d/10-wendyos-persistent.conf | WENDYOS_PERSIST_JOURNAL_LOGS=1 | Sets Storage=persistent so journald writes to /var/log/journal instead of /run/log/journal. |
/etc/systemd/journald.conf.d/10-persistent.conf | RPi5, journal_persist-on feature | Same persistence setting, installed by the RPi-specific rpi-systemd.inc bbclass. |
See logging.md for the full journald configuration and how to access logs.
USB gadget configuration
gadget-setup.service runs /usr/sbin/gadget-setup.sh which uses Linux configfs to build the gadget. Environment variables that control it can be set system-wide (e.g. via /etc/default/wendy-agent or a drop-in for gadget-setup.service):
| Variable | Default | Description |
|---|---|---|
USB_VID | 0x1d6b | USB Vendor ID (Linux Foundation) |
USB_PID | 0x0104 | USB Product ID (Multifunction Composite Gadget) |
USB_MFR | Wendy Labs Inc | Manufacturer string |
USB_PROD | WendyOS Device <name> | Product string shown on host |
USB_SERIAL | device serial number | Serial number string |
GADGET_FUNC_ORDER | ncm ecm | Network function preference; ncm is tried first, ecm is the fallback |
The gadget always includes an ACM serial function (/dev/ttyGS0 on device, ttyACMx on host).
Boot configuration (RPi)
| Path | Description |
|---|---|
/boot/config.txt | RPi firmware configuration. WendyOS adds enable_uart=1 and either dtoverlay=uart0-pi5 (RPi 5) or dtoverlay=uart0 (RPi 4). Also adds dtoverlay=dwc2 when ENABLE_DWC2_PERIPHERAL=1. |
/boot/cmdline.txt | Kernel command line. WendyOS appends console=tty1 to keep a HDMI console alongside the serial console. |
fstab
/etc/fstab is populated from a board-specific template at build time:
- RPi 4/5 (
rpi-fstab): mounts partitions by PARTUUID. - RPi 3 (
rpi-mbr-fstab): mounts partitions by filesystem label. Under MBR the kernel exposes PARTUUIDs as<disk-signature>-<partno>rather than UUIDv4, so label-based references are used instead.
RPi 4/5 fstab mounts:
| Partition | Mount point | Options |
|---|---|---|
PARTUUID=<boot> | /boot | vfat, defaults |
PARTUUID=<root> | / | ext4, noatime |
LABEL=config | /config | vfat, nofail |
RPi 3 fstab mounts:
| Partition | Mount point | Options |
|---|---|---|
LABEL=boot | /boot | vfat, defaults |
LABEL=root | / | ext4, noatime |
LABEL=config | /config | vfat, nofail |
The nofail option on /config means a missing or unformatted config partition does not block boot. See Config Partition for details.
Disk layout
The partition table format depends on the board:
RPi 4/5 — GPT (rpi-partuuid.wks)
| Partition | Label | Size | Filesystem | Mount |
|---|---|---|---|---|
| 1 | boot | 128 MB | FAT32 | /boot |
| 2 | config | 64 MB (default) | FAT32 | /config |
| 3 | root | 8 GB | ext4 | / |
RPi 3 — MBR (rpi-mbr.wks)
The BCM2837 GPU bootrom on the Pi 3 can only read MBR-partitioned FAT32. The GPT layout used on Pi 4/5 leaves the board unable to find bootcode.bin and the system never boots.
| Partition | Label | Size | Filesystem | Mount |
|---|---|---|---|---|
| 1 | boot | 128 MB | FAT32 | /boot |
| 2 | config | 64 MB (default) | FAT32 | /config |
| 3 | root | 8 GB | ext4 | / |
The config partition size can be adjusted at build time with WENDYOS_CONFIG_PART_SIZE_MB in local.conf or the distro conf.
There is no pre-provisioned /data partition in the SD image. Machines that need persistent data (Tegra/Jetson) add a /data partition via their own WKS files.
WendyOS systemd Services
WendyOS is a Yocto-based Linux distribution managed entirely by systemd. This document covers what runs on a WendyOS device, the startup order, and how services depend on one anoth
EEPROM Support (Raspberry Pi 5)
The Raspberry Pi 5 stores its bootloader configuration in an SPI EEPROM on the board. WendyOS manages two EEPROM settings automatically on first boot via one-shot systemd services.