252 lines
16 KiB
Markdown
252 lines
16 KiB
Markdown
---
|
||
tags: [project-drogheda, master-index, gps-rtk, hbox]
|
||
project: Project Drogheda
|
||
author: Helgen CTO
|
||
date: 2026-06-20
|
||
status: Active
|
||
---
|
||
|
||
# Project Drogheda — Master Index (CLAUDE.md)
|
||
|
||
> **Source of truth for this workspace.** Read this first, then
|
||
> [[00-Project-Management/PLAN|PLAN]] for current priorities. **Human engineers
|
||
> onboarding** should start with [[00-Project-Management/Engineering-Handover|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|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|RCA]].
|
||
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|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)
|
||
|
||
```text
|
||
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|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\|PLAN]] · [[00-Project-Management/Engineering-Handover\|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: +1 fan, +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` · `watchdog-protoboard-bringup.md` (shop list) · `watchdog-connections.xlsx` (pin/net connection list, PCB+proto) · `watchdog-connections-rationale.md` (per-connection justification + firmware cross-check; flags Q10 Vgs, ignition level, 5V-sense tap) |
|
||
| `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), **observability** | `2026-06-22_Drogheda_Manual-Logs-Grafana_v1.0.pdf` (Grafana/Loki log-consultation manual) |
|
||
| `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`).
|
||
- **Observability (logs):** backend logs ship off-box to **Grafana Loki** (free tier, 50 GB/mo,
|
||
14-day) via **Vector** (default) or **Grafana Alloy** reading journald (capped 200 MB) —
|
||
`04-Source-Code/htracker/log-shipping/` (`README.md` runbook · `setup-logging.sh` · `vector.toml`).
|
||
Read in Grafana → Explore → Loki: `{job="htracker"}` (Vector) or `{unit="htracker.service"}`
|
||
(Alloy). Consultation manual (PDF): `05-Analytics-Reports/2026-06-22_Drogheda_Manual-Logs-Grafana_v1.0.pdf`.
|
||
Creds in `/etc/vector/htracker.env` (server) — never in the repo.
|
||
- **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.
|
||
|
||
<!-- OBJECTIVITY:START — managed by _framework/scripts/apply-objectivity.sh; edit there + re-run -->
|
||
## Objectivity — partner, not sycophant
|
||
|
||
I want an objective partner, not a sycophant. On every task:
|
||
|
||
- **Genuine take first.** Lead with your real assessment. Don't mirror my tone or sentiment, and don't open by validating me.
|
||
- **Disagree when you disagree.** Say so plainly and explain why — and pair the criticism with a concrete better option (direct *and* constructive).
|
||
- **Self-check.** If a reply is about to start with something semantically like "You're right" / "Good point" / "Great question," stop and first answer: *"Is this true?"*
|
||
<!-- OBJECTIVITY:END -->
|