Add Linux build support for headless deployment (issue #48)

[chriskinal]

Summary

Draft PR to validate the cross-platform refactor on CI before proposing for merge. Addresses #48 — enables building and running AOG-TaskController as a headless Linux service on x86_64 and aarch64 (Raspberry Pi 3/4/5/Zero 2 W, generic Linux SBCs), and documents the UDP protocol for AgIO / AgValonia / third-party clients.

The Windows codepath is preserved bit-for-bit:

• WinMain, AttachConsole, hidden tool window, message pump, and lifecycle ordering are unchanged.
• SHGetFolderPathA(CSIDL_APPDATA) is the same call the original build linked against — no new ole32 dependency.
• localtime_s, WIN32_EXECUTABLE, AppIcon.rc, and all DLL copy/install commands still execute on Windows.
• Existing windows_build and windows_release workflow jobs are untouched; the new Linux jobs run in parallel.

What changed

Cross-platform code

• src/main.cpp — split entry point: WinMain (Windows) and main(argc,argv) (POSIX) with SIGINT/SIGTERM handlers and a new --can_adapter=socketcan option.
• src/settings.cpp — portable config dir via std::filesystem. Windows: %APPDATA%\AOG-TaskController; Linux: $XDG_CONFIG_HOME/~/.config/AOG-TaskController; macOS: ~/Library/Application Support/AOG-TaskController.
• src/logging.cpp / include/logging_utils.hpp — localtime_r on POSIX, localtime_s on Windows.
• src/udp_connections.cpp — SO_REUSEADDR on both UDP sockets (needed on Linux when binding 0.0.0.0 alongside a specific-IP socket) and getifaddrs(3) interface enumeration on POSIX (the hostname resolver returns 127.0.1.1 on stock Ubuntu and never matches a LAN subnet).
• src/app.cpp / include/settings.hpp — explicit <iostream>/<cstdint> that were arriving transitively through windows.h.

CMake

• WIN32_EXECUTABLE, AppIcon.rc, and all four Windows DLL copy/install blocks gated behind if(WIN32).
• CAN_DRIVER defaults per platform — Windows: PCAN+InnoMaker+TouCAN+SYS_TEC; Linux: SocketCAN; macOS: MacCANPCAN. Still overridable via -DCAN_DRIVER=.

CI / packaging

• .github/workflows/build.yml — new linux_build job with a matrix producing both linux-x86_64 (ubuntu-latest) and linux-aarch64 (ubuntu-24.04-arm) tarballs. The aarch64 tarball is what runs on Raspberry Pi under 64-bit Raspberry Pi OS.
• .github/workflows/release.yml — linux_release mirrors the Windows release with the same matrix; both tarballs attach to the same GitHub Release via softprops/action-gh-release@v2 (idempotent on tag_name).
• resources/linux/ — sample settings.json and a systemd unit shipped inside the tarball.

Documentation

• docs/LINUX_DAEMON.md — deployment guide for running the TC as a headless Linux service. Covers hardware targets, resource footprint (CPU/RAM/network), MCP2515 HAT and USB-CAN setup, the systemd unit, settings.json, and troubleshooting. Pi Zero 2 W is called out specifically.
• docs/PROTOCOL.md — UDP wire-protocol reference for client authors. Frame format (0x8081 start + checksum), ports 8888/9999, every PGN the TC sends/receives byte-by-byte (0xC9, 0xE5, 0xF0, 0xF1, 0xF2), settings + CLI reference, ISOBUS/CAN overview, and Python + C# example clients (the latter targeting AgValonia on .NET 8+).
• readme.md — links both new docs at the top.

Test plan

Already verified on Ubuntu 24.04 aarch64 against vcan0:

• Build with cmake/ninja
• --help / --version work
• SocketCAN attach to vcan0
• TC + TECU address claim with J1939-81 250ms post-claim delay
• UDP bind on real LAN interface via getifaddrs
• Synthetic AgIO subnet-detection → rebind
• Synthetic section-control enable received
• Synthetic 64-section state update received
• SIGTERM triggers graceful shutdown

CI status (latest run):

• Windows Build — pass
• Linux Build (x86_64) — pass
• Linux Build (aarch64) — pass
• clang-format style — pass
• cmake-format style — pass

Not testable from this branch alone:

• macOS build path — code paths exist (SHGetFolderPath replaced by ~/Library/Application Support on __APPLE__; CAN_DRIVER=MacCANPCAN default), but no CI runner added and no host to compile on. Can be added later if/when needed.

🤖 Generated with Claude Code