# Project Drogheda (GPS RTK)

Helgen Technologies' **HBOX** RTK GPS tracker fleet for **Hutchison Ports** heavy
equipment (ICAVE / TIMSA / EIT / LCT) — centimetre-class position over 4G, streamed to the
Helgen backend (`retranslator` → Wialon/Traccar → VERONICA), built to survive a hot, salty,
high-vibration port environment.

> **New here? Read [`00-Project-Management/Engineering-Handover.md`](00-Project-Management/Engineering-Handover.md) first.**
> It is the deep context: product, failure analysis, fixes, repo map, open items, glossary.
> This README is the 2-minute orientation; [`CLAUDE.md`](CLAUDE.md) is the terse machine index.

---

## Where we are (2026-06-20 · updated 2026-07-02)

> **2026-07-02:** backend deployed + stable; thermal chamber run done; 3-board protoboard
> campaign in flight (units to ICAVE 7-jul). **Watchdog v3 PROD schematic is complete (ERC 0)**
> — LTC4040 battery-backup sized to the 12 Ah pack, fail-safe Modo-B relay bypass — and the
> **PCB is now a 120×100 carrier board**: Blackpill + simpleRTK2B Pro (UNO-shield sockets) +
> 4G NTRIP Master (on-board XBee socket) all on female headers. Layout in placement review;
> fab gate = proto bench validation. Canonical: `03-Architecture-Hardware/watchdog-electrical-design-state.md`.

We deployed a first batch of HBOX trackers on ICAVE machines in **Veracruz**. They worked
"ish," then failed. We are **mid-crisis, hardening for scale** — target **30 units by
August**. The failure is **three independent fronts**, fixed in parallel:

1. **Backend** (confirmed in code) — `retranslator.py` head-of-line blocks the whole fleet
   on slow upstream, and an anti-jump filter can **permanently black-hole a healthy unit**.
2. **Thermal** — an **ASA** case (UV-stable, ~95–100 °C — adequate) sealed in a sealed **IP67**
   cabinet that also holds the heat-generating **Mean Well** PSU, in full sun → nested heat trap
   for the **battery / boost / modem** (not the case).
3. **Prototype hardware** — Dupont + hand-wiring + 18650/PowerBoost; fragile under vibration.

**Units:** all pulled — **4 in hand (3 dead, 1 working-ish)** in Veracruz; team in Querétaro
→ **remote debug**. Field firmware is **v1** (no thermal log).

> **Free triage:** a unit **ONLINE in htracker but OFFLINE in Wialon** is a **backend
> victim**, not dead hardware. Check that before condemning a radio.

---

## The product in one breath

**Rover (HBOX)** on the machine + **Base Station** (Ardusimple AS-PRO-CORS, 110/230 V)
publishing **RTCM3** corrections over **NTRIP**. The rover gets corrections **over the 4G
modem, not the GNSS** → recover a dead link by **power-cycling the 4G stack**, never a GNSS
reset. HBOX core: simpleRTK2B **Pro** (ZED-F9P) · 4G NTRIP Master · STM32F411 watchdog ·
Mean Well SD-15B-05 (24→5 V) · PowerBoost + 18650 · GX16-5 to the cabinet. **24 V is the
production variant.**

## Invariants (never violate)

1. Power-off is the safe state. 2. Never vanish, never loop. 3. Corrections ride the 4G
modem, not the GNSS. 4. No material that softens below ~80 °C (PLA-class) in the thermal path —
the ASA enclosure complies; design to *measured* cabinet temperature. 5. Backend forwards without head-of-line blocking; anti-jump never
locks out a healthy unit. 6. **No secrets in the repo** (the committed MSSQL password is a
live violation to rotate).

## Repo layout

`00-Project-Management` (plan, ethos, financials, **handover**, Drive tooling) ·
`01-Requirements` (SRS, product spec, tracker) · `02-Architecture-Software` (backend review) ·
`03-Architecture-Hardware` (cabinet/HBOX, BOM, PCB brief, watchdog, manual) ·
`04-Source-Code` (`firmware/` · `htracker/` · `notifications/`) ·
`05-Analytics-Reports` (SQL views — placeholder) · `06-Testing-Validation` (RCA, diagnostics) ·
`Marketing` (datasheet, brochure) · `_brand` (LaTeX style) · `99-Archive` (raw inputs).

## Quick start

```bash
# Branded docs (XeLaTeX; League Spartan + MADE Evolve Sans):
cd 01-Requirements/HBOX-Ficha-Tecnica && latexmk -xelatex main.tex

# Firmware (own repo 'hbox-firmware', at 04-Source-Code/firmware):
#   open blackpillrtkcode_v2/blackpillrtkcode_v2.ino in the STM32duino toolchain.
#   ⚠ Bench-test before any field flash — the sandbox cannot build STM32.

# Backend: 04-Source-Code/htracker  (ssh://git.helgen.dev:6611/htracker, feature/test500unidades)
```

## Storage model (one home per artifact)

**This repo** = working source of truth (editable `.md`/`.tex`, code). **Google Drive**
`Drogheda (GPS RTK)` = finalized exports (branded PDFs, native Docs/Sheets). **Second Brain
vault** = distilled decisions/lessons. Author in repo → export final to Drive → distill to
vault. Drive upload how-to + mapping: `00-Project-Management/Drive-Upload/README.md`. Never
change Drive sharing — that's Leo's call.

## Go deeper

- **Deep context / onboarding** → [`00-Project-Management/Engineering-Handover.md`](00-Project-Management/Engineering-Handover.md)
- Current priorities → [`00-Project-Management/PLAN.md`](00-Project-Management/PLAN.md)
- Machine index → [`CLAUDE.md`](CLAUDE.md)
- Failure analysis → [`06-Testing-Validation/RCA-2026-06-field-failures.md`](06-Testing-Validation/RCA-2026-06-field-failures.md)