Skip to content

Home

Jump to bottom
gfo974 edited this page Jul 6, 2026 · 13 revisions

LinKit v4 Core — Firmware Documentation

LinKit v4 Core is a multi-sensor wildlife tracker firmware running on nRF52840 (Nordic Semiconductor). It supports Argos satellite communication (KIM/SMD modules) and LoRaWAN (RAK3172-SiP) for tracking birds and marine animals with configurable sensors, underwater detection, geofencing zones, and low-battery management.

GUI configuration tool: this firmware is compatible with the Linkit Device Config Tool, a graphical interface available at https://devices.arribada.org. Use it to provision credentials, push parameter templates, run DFU updates over BLE, and pull field logs.

Features

  • GNSS — u-blox M10Q GPS with AssistNow Online/Offline, configurable dynamic models, HDOP/HACC filtering, deep-idle mode (GNP52) for ~10 µA continuous backup
  • Optional communication:
    • Argos Satellite TX/RX — pass prediction, legacy, duty cycle, Doppler, SURFACING_BURST modes. KIM2 (CLS) and SMD (Arribada, A+ protocol) modules. Optional BLIND MAC profile (ARP44-46): module-owned retransmission bursts
    • LoRaWAN — RAK3172-SiP (Semtech SX1262), OTAA/ABP, EU868 (+ other bands), Class A/B/C
  • Optional sensors: pressure (LPS28DFW), accelerometer (BMA400), thermistor (NTC), ambient light (LTR-303), pH (OEM), sea-temp (RTD/TSYS01), CDT, camera trigger
  • Underwater Detection — Saltwater switch (SWS analog with auto-calibration, 5-level surface detection, 12 safety mechanisms)
  • HAULED-Mode auto-detection — comm-override when animal is hauled out / inactive
  • Rolling rate limiter — opt-in TX budget cap (RLP01–RLP03)
  • Geofencing Zones — circular zone with out-of-zone detection and alternate Argos config
  • Low Battery Management — alternate GNSS/Argos params + critical shutdown
  • Dive Mode — reed-switch pause/resume
  • Bird Mortality Detection (RSPB) — automatic confidence from activity + temperature + GPS stationarity
  • Sealed-device hardening — boot-fail counter + factory-reset cascade + 5 exception barriers + cooldown gates + virtual RTC
  • Configurable Parameters — read/write via DTE over USB/BLE/UART
  • Sensor data logging — per-sensor CSV flash logs (DUMPD retrieval)
  • Sensor data in TX — configurable aggregation (oneshot/mean/median) in Argos/LoRa packets

Supported Boards

Board Communication Description
LinkIt V4 KIM Argos (KIM2, UART) Default Argos tracker with CLS module
LinkIt V4 SMD Argos (SMD, SPI or UART) Arribada SMD with A+ protocol and security
LinkIt V4 LoRa LoRaWAN (RAK3172) Terrestrial LPWAN
RSPB Tracker Argos (SMD, SPI) Bird tracker with TPL5111 duty-cycle wakeup + mortality

See Board Variants for hardware specs, parameters, and per-board configuration.

Hardware

  • MCU: nRF52840 (ARM Cortex-M4F, 1 MB Flash, 256 KB RAM)
  • SoftDevice: S140 v7.2.0 (BLE 5.0)
  • GPS: u-blox M10Q (UART)
  • Build: CMake + ARM GCC 10.3
  • Test: CppUTest (host x86)

Wiki structure

Getting started

# Page
01 User Guide — activate, configure, deploy
02 Developer quick start — build from source
03 Building — CMake options, all compile-time flags, per-board scripts, CI workflows
04 Programming — flashing, debugging, DFU

Hardware & architecture

# Page
05 Boards — board hardware comparison + power-down
06 DTE commands — protocol reference
07 Architecture — code structure + design patterns + sealed-device hardening
08 Development Guide — adding params, services, sensors

Configuration & behavior

# Page
09 Parameters — all configurable parameters
10 GPS Guide — aggressive config + AssistNow + deep-idle (GNP52) + RTC strategy
11 Satellite Communication — KIM / SMD SPI / SMD UART specifics + all 6 Argos TX modes + first-TX optims + SMD timing autofallback + complete Argos message formats + decision guide
12 LoRa Communication — RAK3172, ABP vs OTAA, EU868/DCS, DR trade-offs, ChirpStack/TTN, LoRa packet formats, differences vs Satellite
13 Underwater & Behavioral Modes — SWS algorithm + cooldown + HAULED-mode
14 RSPB Mortality Tracker — TPL5111 duty cycling, battery modes, mortality detection

Time-based defenses & sealed-deploy debug — the page-18 content was distributed in 2026-05 across its primary owners: RTC strategy lives in 10 — GPS Guide § Part E; cooldown gates in 13 — Underwater § Part D; rolling rate limiter + spacing-guard in 11 — Satellite Communication § E.4–E.5; boot-fail counter, exception barriers, POF, defense-layers summary, WDT in 07 — Architecture § Sealed-device hardening.

SMD timing details

The SMD FAST/SAFE timing tables, cold-reboot gotcha and autofallback design live inside 11 — Satellite Communication § Part D.

Off-tree references (under .claude/, kept outside the wiki)

  • .claude/SMD-Timing-Optimizations-and-Autofallback.md — extended SMD timing reference (state machine diagrams, full debug cheatsheet)
  • .claude/sws_robustness_analysis.md — full SWS failure-scenario catalogue
  • .claude/sws_adaptive_water_down.md — deferred adaptive-water-DOWN feature
  • .claude/time-based-defenses-architecture.md — RTC architecture deep-dive
  • .claude/review-robustesse-deploy.md — pre-deploy robustness audit

Recent reorganization (2026-05)

The wiki was consolidated to reduce page count:

  • New ordering: GPS (10) → Satellite (11) → LoRa (12) → Underwater (13) → RSPB (14)
  • Pages 10 + 14 → merged into Satellite Communication (KIM / SMD SPI / SMD UART)
  • Pages 11 + 13 + 21 → merged into Underwater & Behavioral Modes
  • Pages 16 + 22 → merged into GPS Guide
  • Page 18 (Time-based Defenses) — distributed across owners: RTC → GPS Guide; cooldown → Underwater; rate limiter + spacing-guard → Satellite; boot-fail counter + exception barriers + POF + defense layers summary → Architecture
  • Page 20 (Rate Limiter) → folded into Satellite Communication
  • Page 17 (CI Workflows) → condensed into page 03 (Building)
  • Page 15 (Test Checklist) → removed
  • Page 19 (SMD Timing) → moved to .claude/ (off-tree, summary in Satellite page)
  • LoRa Tracker Configuration → renamed to LoRa Communication and moved to slot 12

Clone this wiki locally