Wildlife satellite/LoRa tracker firmware for the nRF52840 platform. Next generation evolution of the CLS-Argos-Linkit-CORE platform.
Hardware repository: linkit-v4-hw
| Board | Communication | Interface | Use Case | Documentation |
|---|---|---|---|---|
| LinkIt V4 KIM | Argos (CLS KIM2) | UART | Open ocean, remote areas | Wiki: Boards |
| LinkIt V4 SMD | Argos (Arribada SMD) | SPI | Open ocean, remote areas | Wiki: Boards |
| LinkIt V4 LoRa | LoRaWAN (RAK3172-SiP) | UART | Coastal, urban, farm | Wiki: Boards |
| RSPB | Argos (SMD) | SPI | Bird tracking (TPL5111 duty cycle) | Wiki: Boards |
Recommended: Ubuntu/Debian or WSL2 (Windows). A Docker image is also provided with all tools pre-installed:
docker build -t linkit-v4-build .
docker run --rm -v $(pwd):/workspace linkit-v4-build ./scripts/build_linkitv4_kim.shWindows native is possible with adapted tools but not officially supported. Use WSL2 for the best experience.
The setup script installs all required tools (ARM GCC 10.3, nrfutil, nrfjprog, CMake, etc.):
./scripts/setup_environment.sh # interactive
./scripts/setup_environment.sh --auto # auto-install everythingThis generates build_config.sh with detected tool paths and configures VSCode tasks.
Use the build scripts (they source build_config.sh automatically):
| Script | Board | Output |
|---|---|---|
./scripts/build_linkitv4_kim.sh |
LinkIt V4 KIM | build/LINKIT/ |
./scripts/build_linkitv4_smd.sh |
LinkIt V4 SMD | build/LINKIT_SMD/ |
./scripts/build_linkitv4_lora.sh |
LinkIt V4 LoRa | build/LINKIT_LORA/ |
./scripts/build_rspb.sh |
RSPB | build/RSPB/ |
./scripts/build_with_bootloader.sh <target> |
Any | Merged hex (app+bootloader+SD) |
Build with bootloader for deployment:
./scripts/build_with_bootloader.sh rspb --clean --recover # RSPB
./scripts/build_with_bootloader.sh linkit-smd --clean --recover # LinkIt V4 SMDOr build manually with CMake:
source build_config.sh # load toolchain paths
mkdir -p ports/nrf52840/build/LINKIT && cd ports/nrf52840/build/LINKIT
cmake -DCMAKE_TOOLCHAIN_FILE=../../toolchain_arm_gcc_nrf52.cmake \
-DBOARD=LINKIT -DENABLE_AXL_SENSOR=ON \
-DCMAKE_BUILD_TYPE=Debug -DDEBUG_LEVEL=4 ../..
make -j$(nproc)See Building for all CMake options and per-board examples.
nrfjprog --recover
nrfjprog -f nrf52 --program ports/nrf52840/drivers/nRF5_SDK_17.0.2/components/softdevice/s140/hex/s140_nrf52_7.2.0_softdevice.hex --sectorerase
nrfjprog -f nrf52 --program ports/nrf52840/build/<BUILD_DIR>/<TARGET>.hex --sectorerase
nrfjprog -f nrf52 --resetcd docs && doxygen Doxyfile
# Open: docs/doxygen_output/html/index.htmlRequires Doxygen installed. The generated documentation includes all source code API reference and the wiki pages (boards, DTE commands, parameters, architecture).
cd tests && mkdir -p build && cd build
cmake .. && make -j$(nproc)
cd .. && ln -sf data build/ && ./build/TrackerTests -vTwo ready-to-use workflows live in .github/workflows/ — no local toolchain required, just a browser.
Build firmware on demand — build.yml
Manual trigger (workflow_dispatch only). Pick board, comm module, sensors and features from the Actions UI and download the resulting firmware.
- Go to Actions → Build Firmware → Run workflow
- Configure:
- Board:
LINKITorRSPB - Comm:
KIM/SMD_SPI/SMD_UART/LORA(LORA requires LINKIT) - Sensors (individual checkboxes):
AXL,PRESSURE,THERMISTOR(exclusive withSEA_TEMP),SEA_TEMP,ALS,CDT,PH,MORTALITY(auto-enables AXL+THERMISTOR),SWS_LOG,GNSS_BBR,CAM - Features:
BUZZER,BATTERY_MONITOR_TYPE,LORA_DCS,LORA_POWER_OFF_UNDERWATER,DEBUG_LEVEL
- Board:
- Run, then download the artifact zip from the run summary. It contains:
LinkIt_board-<TAG>.hex— applicationLinkIt_board_merged-<TAG>.hex— full image (app + bootloader + softdevice) fornrfjprog --program ... --chiperaseLinkIt_board_app_settings-<TAG>.hex— app + settings for--sectoreraseupdatesLinkIt_board_dfu-<TAG>.zip— DFU OTA packageLinkIt_board-<TAG>.elf— debug symbolsbuild_config.txt— manifest of every flag used
Required repository secret (otherwise only the unsigned *.hex / *.elf are produced): NRFUTIL_PKG_KEY_PEM = full PEM contents of ports/nrf52840/nrfutil_pkg_key.pem. Set it in Settings → Secrets and variables → Actions → New repository secret.
Tests on every push & PR — tests.yml
Runs the host (x86 Linux) test suite on push to main, on every pull request, or manually via workflow_dispatch. Three jobs run in parallel after a shared compile step:
| Job | Command | Purpose |
|---|---|---|
| Unit tests | TrackerTests -p -xg SWS |
Fast suite, all groups except SWS |
| SWS tests | TrackerTests -p -g SWSAnalog and -g SWSAnalogFlash |
Long-running underwater simulation |
| Turtle simulation | TurtleSimulation -v |
1-year tracker mission, produces an HTML report |
JUnit XML reports and the turtle HTML report are uploaded as artifacts.
See Wiki: CI Workflows for details on every input, secret, and report.
| Option | Values | Default | Description |
|---|---|---|---|
BOARD |
LINKIT, RSPB |
LINKIT |
Target board |
| Option | Description |
|---|---|
| (none) | KIM2 module (CLS, UART, legacy Argos) |
ARGOS_SMD=ON |
SMD module (Arribada, SPI, A+ protocol) |
LORA_RAK3172=ON |
RAK3172-SiP (LoRaWAN 1.0.3) |
| Flag | Default | Sensor |
|---|---|---|
ENABLE_AXL_SENSOR |
1 | BMA400 accelerometer |
ENABLE_PRESSURE_SENSOR |
0 | LPS28DFW pressure/temperature/altitude |
ENABLE_THERMISTOR_SENSOR |
0 (1 for RSPB) | NTC thermistor |
ENABLE_PH_SENSOR |
0 | OEM pH sensor |
ENABLE_SEA_TEMP_SENSOR |
0 | RTD / TSYS01 sea temperature |
ENABLE_ALS_SENSOR |
0 | LTR-303 ambient light |
ENABLE_CDT_SENSOR |
0 | Conductivity-Depth-Temperature |
CAM_ENABLE |
0 | RunCam camera trigger |
Note: ENABLE_THERMISTOR_SENSOR and ENABLE_SEA_TEMP_SENSOR are mutually exclusive (shared Argos TX slot).
| Option | Default | Description |
|---|---|---|
DEBUG_LEVEL |
3 | Debug verbosity (0=off, 4=trace) |
CMAKE_BUILD_TYPE |
Debug | Debug or Release |
BATTERY_MONITOR_TYPE |
ANALOG (STC3117 for RSPB) | ANALOG, FAKE, STC3117 |
GPS_FAKE_POSITION |
0 | Simulate GPS fix at Saint-Paul, Reunion |
WAKEUP_PERIOD |
3600 (RSPB) | TPL5111 wakeup interval (s) — must match the board resistor; runtime-writable via PWP04 |
RSPB_VSENSORS_FLOOR |
1 (RSPB) | Keep VSENSORS always on — I²C pull-ups live on it (0 = allow cut, test only) |
SMD_FLASH_HOLD |
OFF (RSPB) | Test only: park nRF + hold SMD powered to flash the STM32WL over SWD |
See Wiki: Building for the complete build-flag reference.
Parameters are read/written via the DTE protocol (USB, BLE, or UART) using PARMR/PARMW commands with 5-character keys.
| Group | Prefix | Examples |
|---|---|---|
| Argos TX | ARP |
ARP01 (mode), ARP05 (repetition), ARP16 (depth pile) |
| GNSS | GNP |
GNP01 (enable), GNP05 (timeout), GNP25 (trigger on surfaced) |
| Underwater | UNP |
UNP01 (enable), UNP10 (detect source), UNP20-23 (SWS analog) |
| Low Battery | LBP |
LBP01 (enable), LBP02 (threshold), LBP12 (critical) |
| Zone | ZOP |
ZOP01 (type), ZOP04 (out-of-zone mode) |
| LoRa | LRP |
LRP01-06 (credentials), LRP07-15 (radio config) |
| Power/Wakeup | PWP |
PWP01 (shutdown timer), PWP03 (boot modulo), PWP04 (wakeup period) |
| Identity | IDP/IDT |
IDP12 (Argos ID), IDP13 (SMD seckey) |
See Parameters for the complete parameter reference.
All documentation is on the GitHub Wiki:
| Document | Description |
|---|---|
| User Guide | Activate, configure, and deploy your tracker |
| Developer Quick Start | Build firmware from source |
| Building | CMake configuration and build options |
| Programming | Flashing, debugging, DFU |
| Boards | Hardware specs and configuration per board |
| DTE Commands | DTE protocol and commands reference |
| Architecture | Code structure and design patterns |
| Development Guide | Adding parameters, services, sensors |
| Parameters | All configurable parameters |
| Satellite Message Format | Argos & LoRa packet encoding, bit layouts, decoding |
| LinkIt UW Behavior | Underwater mode and SWS algorithm |
| RSPB Mortality Tracker | TPL5111 duty cycling, mortality detection |
| SWS Algorithm | SWS analog detection deep-dive |
| Argos TX Modes | All Argos modes and decision guide |
Compatible with:
- PyLinkit - Python configuration tool
- LinkIt App - Mobile app
- LinkIt V4 with KIM module (CLS) - HW: kim-only
- LinkIt V4 with SMD module (Arribada) - HW: smd-only
- LinkIt V4 with LoRa RAK3172-SiP
- RSPB Tracker
Legacy (use CLS-Argos-Linkit-CORE)
- Horizon Board (Artic R2)
- Linkit V3 CORE (Artic R2)
- Fix Bridge TX command
- Tests for remaining sensors (currently validated only with BMA400, LPS28, STC31, Thermistor)
- LoRa OTAA activation (ABP tested, OTAA still needs validation)
- Flash LoRa over SMD path not yet tested
- Add blind mode management for Satellite
- RCONF saved in RAM for KIM and required SAVE in flash command. SMD directly saved in flash, harmonize the pattern
- Warning problem with LPM mode with SPI, not tested with KIM and UART
If you'd like to contribute, start by searching through the issues and pull requests to see whether someone else has raised a similar idea or question.
- Change as little as possible. Break up into multiple PRs if necessary.
- If you've added a new feature, document it with a simple example.
- Please submit your PR using the release_candidate branch.
Collaboration with
