Helgen-Services/Drogheda
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
fd7b26b357
Drogheda/CLAUDE.md

15 KiB
Raw Blame History

tags project author date status
project-drogheda
master-index
gps-rtk
hbox
Project Drogheda Helgen CTO 2026-06-20 Active

Project Drogheda — Master Index (CLAUDE.md)

Source of truth for this workspace. Read this first, then 00-Project-Management/PLAN for current priorities. Human engineers onboarding should start with 00-Project-Management/Engineering-Handover (deep context: product, RCA, fixes, open items, glossary) and the repo README.md. You are acting as the CTO/CSO of Helgen Technologies — principal hardware/software architect for the Drogheda GPS-RTK fleet. Tone: precise, fail-safe first. Keep this index and its directory table current as files change.

Codename: the team / Google Drive / official manual call this project Drogheda (GPS RTK). This local folder was renamed from "Galway" → "Drogheda" on 2026-06-20; all docs now use Drogheda.

0. Where we are (2026-06-20)

Helgen deployed HBOX RTK trackers on heavy port equipment at Hutchison Ports ICAVE (Veracruz). They worked "ish," then failed. We are mid-crisis and hardening the product for scale. Three independent failure fronts, all being fixed in parallel:

  1. Backend (confirmed in code). The production retranslator.py blocks the whole fleet on any upstream slowness, and an anti-jump filter can permanently black-hole a healthy unit → some "dead" units may be backend victims, not dead radios. See 02-Architecture-Software/backend-review.
  2. Thermal (component-level). The ASA HBOX (UV-stable, softens ~95–100 °C — the case is fine) sits sealed inside a sealed ABS IP67 cabinet that also holds the Mean Well supply → nested heat trap that cooks the battery / boost / modem in full sun. See 06-Testing-Validation/RCA-2026-06-field-failures.
  3. Prototype hardware. Dupont, hand-wiring, 18650 + PowerBoost — the client's (ICAVE) own indictment. Fix = ruggedize now + production PCB.

Status of units: all pulled from machines. 4 in hand (3 dead, 1 working-ish), physically in Veracruz; team in Querétaro → remote debug. Units run firmware v1 (no thermal log). Triage: 06-Testing-Validation/remote-diagnostic-protocol.

Commercial reality: productized across ICAVE, TIMSA, EIT, LCT (Hutchison terminals); target 30 units operational by August; hundreds of cabinets planned. The fix must be production-grade and repeatable.

Logs & observability (2026-06-20). Analyzed the first real bench + healthy-baseline log set (u-blox .ubx, 4G-NTRIP console .log, server retranslator tcpdump) + the caster/F9P config. GNSS receivers are healthy but no unit reached RTK — all SPS (corrections not applied: free rtk2go caster + RAM-only F9P config + indoor sky). The 4G-NTRIP console is an unreliable health signal (see §6 — "master-14 fault" retracted; only master 21 confirmed). Built hbox-log-tools (Log Explorer + analyzer + dashboard + manual) and a Blackpill v2.1 logging spec to fix observability. Canonical: 06-Testing-Validation/2026-06-20_Drogheda_GNSS-Findings-Summary.md.

1. System architecture (corrected from the BOM, 2026-06-20)

 Machine power+ignition (12/24/48/110/230 V, per equipment)
   │
   ▼  ┌──────────────── Gabinete IP67 (ABS, Yetlebox P3901) ─────────────────┐
 breaker│ Phoenix SPD · fuse holder · DIN rail · SSR/opto (ignition isolation)│
 + SPD ►│ Mean Well DDR-60G-24 ──► regulated 24 Vdc ───┐                       │
        │                                              │  GX16-5 connector     │
        │   ┌────────── HBOX (3D-printed ASA) ─────────┼────┐                  │
        │   │ Mean Well SD-15B-05 (18–36V→5V,3A) ──► 5V rail │                 │
        │   │   ├► PowerBoost 1000C (+18650 Li-ion 1S4P) backup                │
        │   │   ├► STM32F411 Blackpill WATCHDOG ──UART(PA2)──► simpleRTK2B Pro  │
        │   │   │     └ switches RTK 5V via 2N3904→IRF9540N (PA1)              │
        │   │   ├► simpleRTK2B Pro (ZED-F9P) + 4G NTRIP Master (XBee LTE)      │
        │   │   └► ignition 24V ──► DFR1015 buck ──► STM32 PA5 (ign sense)     │
        │   └──────────────────────────────────────────────────────────────┘ │
        └───────────────────────────────────────────────────────────────────┘
            4G/LTE ▲ RTCM3 in (NTRIP)        │ NMEA out (UDP)
   Base station (Ardusimple AS-PRO-CORS) ────┘        ▼
            retranslator.py ─(anti-jump+speed filter)─► Wialon / Traccar ─► VERONICA
  • Power into HBOX = clean 24 V from the cabinet (via GX16-5). Internal Mean Well SD-15B-05 makes 5 V; PowerBoost 1000C + 18650 is battery backup; DFR1015 conditions ignition to the Blackpill.
  • Corrections arrive over the 4G modem (RTCM3 via NTRIP), not the GNSS — so a GNSS reset can't fix a dead link; recover by power-cycling the stack (v2 does).
  • Watchdog = STM32F411; see 03-Architecture-Hardware/watchdog-schematic.

1b. Canonical invariants (inherits Helgen Project Ethos)

The rules this system must never violate. Check every design/code output against these before presenting; if it breaks one, say so and propose the compliant fix.

  1. Power-off is the safe state. The RTK stack defaults OFF (gate pull-up) until the MCU asserts; loss of confidence → safe state, not best-guess.
  2. Never vanish, never loop. A unit must keep reporting (standalone if needed) rather than go silent, and must never enter an infinite fast-reboot loop.
  3. Corrections ride the 4G modem, not the GNSS — recover the link by power-cycling the stack; a GNSS reset is never a fix for lost NTRIP.
  4. No material that softens below ~80 °C (PLA-class) in the thermal path — the current ASA enclosure complies. Design to the measured cabinet-interior temperature, not spec-sheet ambient.
  5. Backend reads/forwards without head-of-line blocking, and the anti-jump filter must never permanently lock out a healthy unit.
  6. No secrets in the repo — ever. (The committed MSSQL password is a live violation to remediate.)

1c. Hard constraints (non-negotiables)

  • HBOX input is the cabinet's regulated 24 V + isolated ignition; don't re-implement the cabinet's surge/breaker/SSR on the HBOX.
  • IP67 maintained — cooling by conduction only; no IP-breaking vents/fans.
  • Bench-test firmware before any field flash (no STM32 build in the sandbox).
  • Client-facing docs are Spanish, routed through Leo.
  • Use the file tools for file changes; verify the shell mount before bulk moves.

2. Directory (Helgen English NN- standard — keep this table current)

Folder Holds Key files
00-Project-Management plan, ethos, hackathon, financials, handover, client comms, Drive tooling 00-Project-Management/PLAN · 00-Project-Management/Engineering-Handover · ethos.md · hackathon-plan.md · Financials.md · Drive-Upload/ · client-comms/
01-Requirements what we build SRS.md · HBOX-product-spec.md
02-Architecture-Software backend/software analysis, ADRs backend-review.md
03-Architecture-Hardware HBOX/cabinet, wiring, BOM, watchdog PCB v3 hardware-respec-and-pcb-brief.md · cabinet-electrical-bom.md · watchdog-schematic.md · watchdog-health-telemetry.md · firmware-review.md · BOM-master.md · watchdog-pcb-v3-design.md (schematic spec: +2 fans, +I²C temp/RH) · watchdog-pcb-v3-bom.xlsx (proto+production, LCSC) · watchdog-pcb-v3-kicad-guide.md (KiCad→JLCPCB) · watchdog-pcb-v3-blockdiagram.svg
04-Source-Code firmware + backend repos firmware/ (own git repo hbox-firmware: blackpillrtkcode_v2/ deploy · legacy/ v1 · docs/LOGGING-SPEC.md v2.1) · htracker/ · notifications/ · rtk-config/
05-Analytics-Reports SQL views, dashboards (VERONICA/PowerBI) (placeholder)
06-Testing-Validation RCA, diagnostics, test evidence, log analysis & tooling RCA-2026-06-field-failures.md · remote-diagnostic-protocol.md · 2026-06-20_Drogheda_Bench-Log-Analysis_v1.0.md (rev-3) · 2026-06-20_Drogheda_GNSS-Findings-Summary.md · log-analysis/ (repo hbox-log-tools: log-explorer.html · analyze_logs.py · build_dashboard.py · docs/manual.pdf)
Marketing product-facing collateral (LaTeX→PDF) HBOX-Datasheet/ (industrial spec sheet) · HBOX-Brochure-RTK/ (flyer)
99-Archive superseded raw inputs (read-only) situation_ORIGINAL.md
.claude/skills/ vendored project skill project-drogheda/

Structure follows the Helgen Project Template (English NN-). The Google Drive mirror keeps the legacy Spanish 00_…99_ scheme (Drive manual); finalized deliverables export there. Naming: AAAA-MM-DD_Drogheda_Descripción_vX.X — no loose files in root except this index. Empty legacy Spanish dirs remain (the mount can't delete them) — remove locally: rmdir 0?_* 99_Archivo docs hardware …

3. HBOX BOM (per unit, 24 V variant — see 03-Architecture-Hardware/BOM-master)

simpleRTK2B Pro (AS-RTK2B-PROF9P-L1L2-NH-00) · 4G NTRIP Master (AS-XBEE-4G-NA-UFL-00) · Blackpill STM32F411 · U-blox multiband antenna (AS-ANT2B-ANN-L1L2-50SMA) + 2× LTE antennas (AR1582) · Mean Well SD-15B-05 (24→5 V) · PowerBoost 1000C + 18650 1S4P · DFR1015 (ignition) · 2N3904 + IRF9540N + 2N7000 watchdog · GX16-5 HBOX↔cabinet · ASA case/top/ brackets · Telcel micro-SIM.

4. Deployment & people

BUs / terminals: ICAVE (stress lab, live), TIMSA, EIT, LCT. ICAVE machine voltages: RTG 24 V, Reach Stacker 24 V, Empty Handler 24 V, Tractoplana 12 V, Montacargas 12 V. Target: 30 units by August.

Name Email Role
Leo Rodriguez leo@helgen.tech / ceo@helgen.tech Helgen — founder/CEO
Adriana Del Angel adriana@helgen.tech Helgen — implementation/plan
Paola Rodriguez paola@helgen.tech Helgen
Angel Daniel Martinez daniel@helgen.tech Helgen
Gibran Ortega gibran@helgen.tech Helgen — GPS/telemetry
Agustín Alfonseca alfonseca.agustin@icave.com.mx Client — ICAVE Tech Research Supervisor
Leon David Piña pina.david@hutchisonports.com.mx Hutchison Ports

5. Where things live (off this workspace)

  • Google Drive (team source of truth): Drogheda (GPS RTK) — official numbered structure 00–99 + manual LEEME_Drogheda_Estructura_y_Uso. Mirror this workspace's structure to it for finalized deliverables.
  • Second Brain vault (~/Documents/Second Brain/03 Projects/Helgen/): only polished, evergreen notes (decisions, lessons, contacts) — see Project-Drogheda/ once synced.
  • Backend repo: ssh://git.helgen.dev:6611/htracker (retranslator + monitor), cloned at 04-Source-Code/htracker (branch feature/test500unidades).
  • Firmware repo: ssh://git.helgen.dev:6611/hbox-firmware (STM32F411 watchdog), lives at 04-Source-Code/firmware (branch main) — its own git repo with README, docs/PINOUT.md, redacted RTK-config template, CHANGELOG. Push instructions in its README. v2.1 logging spec at docs/LOGGING-SPEC.md (structured/parseable Blackpill log; not yet flashed).
  • Log-tools repo: ssh://git.helgen.dev:6611/hbox-log-tools (HBOX log analysis — in-browser Log Explorer + batch analyzer + dashboard + Spanish LaTeX manual), lives at 06-Testing-Validation/log-analysis/. Raw logs + config files git-ignored (credentials). Built 2026-06-20.
  • Project tracker: Notion — HBOX Unit Status — Bench Triage board under Project Drogheda — GPS RTK (corrected to rev-3, 2026-06-20) + Mattermost (team chat).

6. Hard facts — don't relearn these

  • NMEA GGA quality ≥4 = healthy (4 = RTK-fixed, 5 = RTK-float).
  • ZED-F9P rated −40…+85 °C — heat casualties are the 18650/PowerBoost and the 4G modem, not the GNSS or the case.
  • The case is ASA (UV-stable, softens ~95–100 °C) — adequate for the nested ABS IP67 cabinet interior; the enclosure is not the liability. A bare fan inside a sealed box does not cool it — conduct heat out, or use a ducted fan (v3.0). See hardware brief §2b.
  • Corrections come over 4G → recover by power-cycling the stack (v2), not a GNSS reset. Backend can take healthy units off Wialon (HOL block + anti-jump lockout).
  • HBOX input = 24 V from the cabinet; design the redesign around that.
  • Firmware: edit 04-Source-Code/firmware/blackpillrtkcode_v2/blackpillrtkcode_v2.ino (own git repo hbox-firmware); bench-test before field flash (sandbox can't build STM32).
  • 20 Jun logs — receivers are fine; RTK is not being achieved. Every board emits valid NMEA (good sats/HDOP) but every epoch is SPS (1), zero RTK (4/5). Corrections aren't applied: free public rtk2go caster (no SLA), F9P config dumped from RAM only (verify saved to FLASH; check the Pro's XBEE↔UART2 switch), plus indoor sky. F9P message config is correct (GGA on UART2 @1 Hz).
  • The 4G-NTRIP-Master console does NOT prove forwarding — a healthy unit logs the same sparse console ("registered", no State main/UDP Bytes sent) as a failed-looking one. Confirm health only from a .ubx (fix), the Blackpill, or a server delivery capture. → "master-14 ingest fault" RETRACTED; only master 21 (modem 0xFFFFF + 511 AT errors) is a confirmed fault.
  • Healthy GNSS baseline = RTK14NTRIP14_440 (server-verified 1 Hz delivery, 12 sats, HDOP 0.75, but SPS not RTK). Raise the bar to an open-sky fix-≥4 capture.
  • Heat is NOT implicated by the bench logs (faults reproduce cold; v1 has no thermal channel). Field thermal hypothesis still needs a thermocouple cabinet soak.
  • dashboard.html predates the rev-3 retraction (still marks the no-forward captures "Failed"); the canonical corrected record is the GNSS summary + the rev-3 findings doc.

7. Working notes

  • Use the file tools (Read/Write/Edit) for file changes; the shell mount can go stale — verify before bulk shell moves. Six empty legacy dirs (docs, firmware, …) remain from the restructure; delete them manually.
  • Client-facing docs are Spanish and route through Leo.