DuetScreen Buildroot
====================

This repository is a Buildroot-based firmware tree for the Duet3D DuetScreen.
It contains the board configuration, Linux configuration, root filesystem
overlay, image generation scripts, and the custom Buildroot package used to
build and install the DuetScreen application.

Unlike upstream Buildroot, this tree is focused on a single target and includes
shortcuts for two common workflows:

- building a complete SD card image for the device
- rebuilding only the DuetScreen application for faster development iterations

Key outputs from this repository include:

- `output/images/sdcard.img` for flashing an SD card
- `output/images/update.tar.gz` for NAND/rootfs update workflows
- `output/target/usr/bin/DuetScreen` for pushing only the application binary

Repository layout
-----------------

The DuetScreen-specific parts of the tree are primarily in these locations:

- `configs/duet3d_duetscreen_defconfig` - main Buildroot defconfig
- `board/duet3d/duetscreen/` - board files, DTS, overlays, image scripts
- `package/duetscreen/` - Buildroot package definition for the DuetScreen app
- `.vscode/tasks.json` - common build, flash, and deploy tasks
- `BOOT.md` - first-boot configuration options for WiFi, SSH, ADB, UART, and
	password setup

Prerequisites
-------------

This repo includes a helper script for Debian/Ubuntu-based hosts:

```sh
./scripts/install_prerequisites.sh
```

That script installs the toolchain and host utilities commonly needed to run
Buildroot in this tree, including `build-essential`, `cmake`, `u-boot-tools`,
`dosfstools`, `mkbootimg`, and related packages.

You do not need root privileges to build, but you do need them for dependency
installation and for writing images to an SD card.

Configuration
-------------

Load the DuetScreen Buildroot configuration with:

```sh
make duet3d_duetscreen_defconfig
```

The active defconfig currently targets:

- ARM Cortex-A7
- Allwinner T113-based hardware
- custom Linux DTS at `board/duet3d/duetscreen/dts/sun8i-duet3d-duetscreen-linux.dts`
- rootfs overlay at `board/duet3d/duetscreen/rootfs_overlay`

Full image build
----------------

To build the full firmware image:

```sh
make duet3d_duetscreen_defconfig
make
```

Important build artifacts:

- `output/images/sdcard.img` - bootable SD card image
- `output/images/update.tar.gz` - update bundle generated by the post-image
	script
- `output/images/zImage`, `rootfs.ubi`, `optee.bin`, and related low-level
	image components

The NAND update bundle is assembled by:

- `board/duet3d/duetscreen/scripts/genimage.sh`

Flash an SD card manually with:

```sh
sudo dd if=output/images/sdcard.img of=/dev/sdX bs=4M status=progress conv=fsync
```

Replace `/dev/sdX` with the correct removable device.

DuetScreen-only rebuilds
------------------------

For application development, the custom package in `package/duetscreen/` allows
you to rebuild only the DuetScreen component instead of the entire image.

Default behavior:

- If `DUETSCREEN_SRC` is not set, Buildroot fetches `git@github.com:Duet3D/duetscreen.git`
- If `DUETSCREEN_SRC` is set, Buildroot uses a local checkout
- The default CMake preset is `T113-Release`

Example using a local DuetScreen checkout:

```sh
export DUETSCREEN_SRC=/absolute/path/to/duetscreen
make duetscreen-reconfigure
```

The rebuilt application is installed into:

```text
output/target/usr/bin/DuetScreen
```

You can also pass extra CMake options through Buildroot when debugging:

```sh
make DUETSCREEN_EXTRA_CONF_OPTS="-DLOG_LEVEL=DEBUG" duetscreen-reconfigure
```

Development environment variables
---------------------------------

The VS Code tasks expect `.vscode/.env` for local overrides. The template file
is:

```text
.vscode/.env_template
```

It currently defines:

```sh
export DUETSCREEN_SRC="path_to_DuetScreen_repo"
export REMOTE_HOST="ip_addres_of_screen"
```

Typical setup:

```sh
cp .vscode/.env_template .vscode/.env
```

Then update the values to match your local DuetScreen checkout and target
device.

VS Code tasks
-------------

This repository includes a useful set of tasks in `.vscode/tasks.json`:

- `Configure Buildroot` - load `duet3d_duetscreen_defconfig`
- `Build Project` - full image build
- `Build Project - WSL` - full image build using `.vscode/.env`
- `Build DuetScreen - Github` - rebuild only the app from the remote repo
- `Build DuetScreen - Local` - rebuild only the app from `DUETSCREEN_SRC`
- `Push DuetScreen - ADB` - stop the app, push a rebuilt binary, restart it
- `Flash SD Card` - write `output/images/sdcard.img` to a selected block device
- `Reconfigure Linux` - run `make linux-reconfigure`
- `Save Buildroot Config` - run `make savedefconfig`

The `Push DuetScreen - ADB` task uses `adb` and expects the device to be in USB
device mode with ADB enabled.

The `Push DuetScreen - SSH` task referenced in the workspace expects a local
`push_duetscreen.sh` helper, which is not currently tracked in this repository.

First boot behavior
-------------------

The image supports several first-boot options through files dropped onto the
FAT boot partition. These are handled by the auto-setup script in:

- `board/duet3d/duetscreen/rootfs_overlay/etc/init.d/S02setup`

Supported first-boot options include:

- WiFi provisioning with `wpa_supplicant.conf`
- static networking with `dhcpcd.conf`
- root password setup with `password` or `password.txt`
- SSH enablement with `ssh`
- ADB enablement with `adb`
- UART console enablement with `getty`
- DuetScreen configuration injection with `duetscreen.json`

See `BOOT.md` for the end-user details.

Runtime services
----------------

The runtime image includes init scripts for both direct app control and crash
recovery monitoring:

- `board/duet3d/duetscreen/rootfs_overlay/etc/init.d/20DuetScreen`
- `board/duet3d/duetscreen/rootfs_overlay/etc/init.d/S21DuetScreenMonitor`

Normal operation uses the monitor script to keep `/usr/bin/DuetScreen` running
and to capture recent application logs before restart.

Useful commands
---------------

Common commands when working in this repo:

```sh
make duet3d_duetscreen_defconfig
make
make linux-reconfigure
make savedefconfig
make duetscreen-reconfigure
```

Notes
-----

This tree still contains the standard upstream Buildroot source layout, but the
intended entry points for day-to-day DuetScreen work are the defconfig, board
directory, custom package, and VS Code tasks described above.