Getting Started

Getting Started

1. Build safely

From the repository root, build without opening or programming hardware:

build.cmd --all --clean --no-upx

On Bash-capable systems:

./build.sh --all --clean --no-upx

Focused builds are available with --host-only, --firmware-only, and --dry-run. The ordinary root build is hardware-free; explicit programming commands are separate.

2. Try the Virtual Board first

cd Tools\VirtualBoard
cmake --preset release
cmake --build --preset release --parallel
ctest --preset release

Then connect the host to the development transport:

Tools\Controller\bin\controller.exe tui --port tcp://127.0.0.1:8765
Tools\Controller\bin\controller.exe exec --port tcp://127.0.0.1:8765 hello

TCP targets are development transports and are not discovered as serial devices.

3. Choose a surface

Tools\Controller\bin\controller.exe web --port COM18
Tools\Controller\bin\controller.exe tui --port COM18
Tools\Controller\bin\controller.exe shell --port COM18

The WebUI normally listens at http://127.0.0.1:8787/. Host-only settings, diagnostics, and reconnect remain available while the board is offline; device controls become live only after native HELLO authentication succeeds.

Use the TUI for keyboard-first operation, the WebUI for visual control and diagnostics, and exec/shell for automation and support work. All surfaces use the same validation and dispatcher paths.

4. Identify the intended board

Tools\Controller\bin\controller.exe ports
Tools\Controller\bin\controller.exe exec --port COM18 hello

A candidate is accepted only after the firmware identifies itself as PCController. Selectors may use a COM name, friendly name, VID/PID, USB serial, or Windows device instance.

5. Keep settings in the right place

• MCU settings live in EEPROM and travel with the board.
• Host settings live in the platform user configuration/data directories.
• Build manifests and programming backups are deployment evidence; do not replace them with an older file that merely has the same name.

Configuration paths and precedence are documented in Host Configuration and Integrations. Credentials belong in the supported secret store or environment reference, never in committed configuration or a WebSocket URL.

6. Troubleshoot from evidence

• A page that says the host is ready is not proof that a board is connected.
• If a COM port is busy, find the primary instance and use its IPC path rather than opening the same port twice.
• Repeated reconnects require checking UART power, baud, reset behavior, and native HELLO logs.
• Missing INA219, PCA9685, DS18B20, or LCD modules are capability warnings on a reduced board, not a reason to abandon initialization of working hardware.

See the full operations guide for commands and acceptance checks.