TRAILNAV OLED — FIRST WORKING-LOOP SOURCE PACKAGE

I am starting a 1.3-inch OLED revision because the original large display is not
available. The CAD and firmware in this package were generated with Codex
assistance. They are new development sources, not evidence of a fabricated or
outdoor-tested device. The earlier SolidWorks construction photographs describe
the earlier enclosure, not this revision.

TARGET FOR THIS MILESTONE
Read a real GPS outdoors, save one waypoint, retain it through restart, and show
live distance and the geographic bearing back on a 128x64 OLED. Compass-relative
arrows, solar charging, measured runtime and final custom electronics follow
after this loop is verified. This firmware does not implement those later parts.

HARDWARE ASSUMPTIONS
- Seeed XIAO RP2040 with the Earle Philhower Arduino-Pico core 4.5.3.
- 1.3-inch 128x64 SH1106 I2C OLED, address 0x3C, compatible with 3.3 V supply and
  signals. SH1106 is the starting driver choice, not a verified part identity.
  Config.h also supports an SSD1306 module: set TRAILNAV_DISPLAY_SH1106 to 0.
  An SPI-only display needs different wiring/source; diagonal size alone does
  not identify the controller, interface, board dimensions or module pin order.
- A GPS breakout producing standard NMEA RMC/GGA sentences at 9600 baud.
  Identify the exact breakout, supply rating and TX signal voltage before wiring.
- A normally-open momentary switch. No compass is needed for this first loop.

BENCH CONNECTIONS (BOARD LABELS, NOT RAW GPIO NUMBERS)
XIAO D4 / GPIO6 -> OLED SDA
XIAO D5 / GPIO7 -> OLED SCL
XIAO 3V3 -> OLED VCC only if the exact module is rated for it
XIAO GND -> OLED GND, GPS GND, button return
GPS TX -> XIAO D7 / GPIO1 (3.3 V-compatible signal required)
XIAO D6 / GPIO0 -> not connected for this receive-only GPS test
XIAO D2 / GPIO28 -> button -> GND; internal pull-up enabled
GPS power -> supply allowed by its exact breakout; not inferred from chip name

I will power the initial board through USB. The XIAO RP2040 is not assumed to
include a lithium-cell charger. I will not connect the panel or a bare cell to
the 3V3 rail. Battery/solar operation requires a separately verified charging,
protection, regulation and power-path arrangement. Check module current and the
board regulator rating before powering peripherals from its output.

BUILD
Install these Library Manager versions:
  Adafruit SH110X 2.1.12 (default SH1106 build)
  Adafruit SSD1306 2.5.17 (only needed for the alternate SSD1306 build)
  Adafruit GFX Library 1.13.0
  Adafruit BusIO 1.17.4
  TinyGPSPlus 1.0.3
Use the RP2040 core 4.5.3 and board "Seeed XIAO RP2040".
Open firmware/TrailNAV_OLED/TrailNAV_OLED.ino and its TrailNAV.cpp tab. Review Config.h against the actual
module address and baud rate. CLI equivalent:
  arduino-cli compile --fqbn rp2040:rp2040:seeed_xiao_rp2040 firmware/TrailNAV_OLED
Do not select the ESP32-C3/C6 board definition for this source.

OPERATION
Wait outdoors for a fresh valid fix. The starting quality gates are at least four
satellites, HDOP <= 5, location age <= 3 seconds, and quality-field age <= 5
seconds. These are configuration choices, not a tested accuracy specification.
Press and release SAVE to store the first point. Once a point exists, hold SAVE
for two seconds and release to replace it. A short press preserves the old point.
Storage uses flash emulation with a version and CRC; writes happen only on save.
An interrupted write can still lose the single stored record. Retention across
real power cycles needs a bench test; CRC detection is not redundant storage.

BRG is the bearing to the waypoint relative to TRUE NORTH. It is not the direction
the enclosure is facing. No compass-relative arrow is drawn. "Near waypoint" is
a configurable distance indication and is not a guarantee of precise arrival.
If the GPS fix is lost, live distance/bearing are hidden and the saved point is
retained. An absent display produces a USB diagnostic, not a display test pass.

FUSION DESIGN
cad/TrailNAV_Fusion is a native Fusion Python script with parameters.json.
Run it from Fusion's Scripts and Add-Ins dialog. It creates a new design and
exports into cad/exports without changing an existing open design.
The native .f3d keeps a feature timeline, sketches and named parameters. STEP is
an exchange format and does not retain that original modelling history.
Change parameters.json and rerun to regenerate geometry and exports, or use
Fusion's Change Parameters dialog to adjust the dimensioned native model.
Re-export manufacturing files after changes; existing exports do not update
automatically when the native model is edited.

The starting assembly is 82 x 128 x 33 mm including a 3 mm faceplate. It includes
a hollow printed base, screw bosses, a removable electronics tray with a button
clearance notch, a separate
OLED backing frame, and a laser-cut faceplate. The print coupon compares three
pilot sizes. All module envelopes, OLED window/hole pitch, screw fits, button
geometry and material thickness need checking against actual parts. The model
does not establish water resistance, a finished PCB layout, solar-panel mounting
or a validated battery/charger fit. Leave the solar arrangement separate for the
first bench loop. Do not fabricate the full enclosure before a module fit check.

Print the coupon first. Nominal 0.2 mm layers, 3 perimeters and 20% infill are
starting slicer suggestions only; use material/printer settings validated in the
lab. No production G-code is supplied. The faceplate DXF is nominal geometry;
measure stock and apply the lab's actual laser kerf compensation in CAM.

SOURCES AND ATTRIBUTION
Seeed XIAO RP2040 pinout: https://wiki.seeedstudio.com/XIAO-RP2040/
Arduino-Pico UART: https://arduino-pico.readthedocs.io/en/latest/serial.html
Arduino-Pico EEPROM: https://arduino-pico.readthedocs.io/en/latest/eeprom.html
TinyGPSPlus: https://github.com/mikalhart/TinyGPSPlus (LGPL-2.1)
Adafruit SSD1306: https://github.com/adafruit/Adafruit_SSD1306 (BSD)
Adafruit SH110X: https://github.com/adafruit/Adafruit_SH110x (BSD)
Adafruit GFX: https://github.com/adafruit/Adafruit-GFX-Library (BSD)
Adafruit BusIO: https://github.com/adafruit/Adafruit_BusIO (MIT)
Fusion API: https://help.autodesk.com/cloudhelp/ENU/Fusion-360-API/
Third-party libraries are installed separately and retain their own licences.
I selected MIT for my original code and CC BY 4.0 for my original written documentation. See MIT.txt and LICENSING.txt for scope and third-party exclusions.

LOCAL 3D PREVIEW
The website embeds viewer/index.html. Its JavaScript and uncompressed GLB models
are included locally; the viewer does not need a CDN or an internet connection
after the package is downloaded. To view a downloaded copy, serve this folder
over local HTTP rather than opening the HTML as a file:
  python3 -m http.server 8765 --bind 127.0.0.1
Then open http://127.0.0.1:8765/viewer/ in a WebGL-capable browser.
Assembly, Interior and Exploded select mechanical views; Reset view restores
the camera. CAD captures and STEP files remain available if WebGL cannot run.
Google model-viewer 4.1.0 is included under Apache-2.0 in vendor/, with its licence.
The GLB previews are generated from the Fusion STL exports by cad/build_web_models.py
using trimesh 5.1.1 and numpy. They are previews, not fabrication source files.
