Board Initialization

Board Initialization

This page covers first commissioning of a blank ATmega328P board. Start with loads disconnected and identify the target board, USBasp, and UART adapter before writing anything.

Preferred end-to-end command

With USBasp connected and a UART adapter available for first-boot checks:

Tools\Controller\bin\controller.exe board initialize --portable-cli --uart COM4

The Programming page in the TUI exposes the same initialization workflow. If UART is absent, the bootloader and application can still be installed; serial HELLO, first-boot diagnostics, naming, and peripheral checks are skipped and reported clearly.

What the workflow must do

1. Resolve or install the firmware CLI, MiniCore/core, programmer support, and required libraries from the managed dependency profile.
2. Detect the exact USBasp and MCU signature.
3. Back up flash, EEPROM, signature, fuses, lock bits, and programmer metadata before destructive writes whenever the target is readable.
4. Try normal USBasp speed first. If communication fails, retry at slow SCK only to repair the fuse/clock policy, then probe again at normal speed. Keep slow mode for later writes only when normal speed still fails or the operator explicitly requested it.
5. Install the bootloader selected by the board's configured core/FQBN, write and verify the application and EEPROM policy, and preserve exact hashes and logs.
6. If UART is present, reconnect to the application, complete native HELLO/ping, query firmware identity and build information, apply the board name (maximum eight characters), discover capabilities, and diagnose every available peripheral.
7. Treat absent optional modules as unavailable capabilities. Continue checking all peripherals that are present.

The application protocol record is authoritative for the board name. Bootloader user metadata may mirror it for provisioning audit, but is not the live source of truth.

Portable and installed toolchains

PCController can use an installed firmware CLI or its verified portable tool directory. --portable-cli deliberately chooses the portable copy. Internet downloads honor standard proxy environment variables. The tool preserves caller NO_PROXY entries and appends loopback, .local, and private/link-local networks so local IPC, WebSocket, discovery, and bridge traffic bypasses Internet proxies.

On Windows, controller driver usbasp status diagnoses USBasp driver state. The guarded Zadig path downloads and verifies the official executable, checks the exact connected VID/PID, and launches it only when a suitable driver is missing. Native libwdi/driver installation without GUI remains backlog work and must not be claimed complete prematurely.

Ordinary firmware updates

After commissioning, prefer UART bootloader programming:

Tools\Controller\bin\controller.exe program flash .build\firmware\PCController.ino.hex COM18

The guarded lifecycle validates the image, authenticates the board, backs up flash/EEPROM/settings, forces safe outputs, shows Prog, writes and verifies, reconnects, restores exact compatible settings, and retains a recovery marker if interrupted. USBasp is an explicit recovery path, not the everyday updater.

Alpha EEPROM policy

During alpha, a new version build may intentionally replace unpublished wire, flash, or EEPROM layouts. Do not add migrations, dual readers, aliases, or preservation code merely to support an earlier alpha version. Compatibility and preservation belong to explicitly selected feature/profile builds that coexist by design.

Before an intentional incompatible alpha reinitialization, retain the raw EEPROM backup. Never reinterpret incompatible bytes as semantic settings.

For exact details, read Toolchain Bootstrap and Safe Programming.