Getting Started

Getting Started

Prerequisites

• PlatformIO (CLI or the VS Code extension).
• Git (with Git LFS installed, per the project's contribution docs).

Project layout at a glance

• src/ — the firmware library (Duck classes, radio, routing, security, payload encoding).
• examples/ — Arduino sketches (.ino) that build against src/ for specific boards/roles.
• boards/ and src/include/boards/ — board-specific pin/peripheral definitions.
• test/ — Unity-based unit tests (bloom filter, payload encode/decode).
• platformio.ini — all supported build environments (see Supported Boards).

Building

This is a PlatformIO library, so a board environment ([env:...] in platformio.ini) builds whichever example sketch is currently selected — not a fixed "main" sketch.

pio run -e <env-name>

Selecting which example sketch gets built: EXAMPLE_DIR

tools/example_select.py is wired into every environment as a pre: script. It reads the EXAMPLE_DIR environment variable to decide which sketch under examples/ to point PROJECT_SRC_DIR at. If EXAMPLE_DIR is not set, it defaults to Basic-Ducks/MamaDuck — a minimal, board-agnostic MamaDuck sketch.

To build a specific board's real sketch (with BLE, battery reporting, encryption toggles, etc.), set EXAMPLE_DIR relative to examples/, without the examples/ prefix:

EXAMPLE_DIR=Basic-Ducks/Heltec pio run -e local_heltec_wifi_lora_32_V3
EXAMPLE_DIR=Basic-Ducks/Seeed/WioTrackerL1 pio run -e local_wio_tracker_l1
EXAMPLE_DIR=Basic-Ducks/PapaDuck pio run -e local_heltec_wifi_lora_32_V4

Without EXAMPLE_DIR, a build only verifies changes made to src/ against the generic MamaDuck example — it does not exercise a specific board's own .ino sketch.

Environment naming convention

• local_* — local development builds (library referenced via symlink://./, so src/ changes are picked up immediately).
• prod_* — production builds (library fetched from the PlatformIO registry / a pinned release).
• release_* — base/shared configuration for release builds.
• test_* — Unity-based unit test environments.
• *_encrypted — otherwise-identical environment with -DDUCK_CRYPTO_DEFAULT_ENABLED=1, so uplink/session encryption defaults to on instead of off.

See Supported Boards for the full environment list grouped by hardware family.

Running tests

Unit tests live under test/ (test_BloomFilter, test_DuckPayloads) and run via PlatformIO's test runner against a test_* environment, e.g.:

pio test -e test_heltec_wifi_lora_32_V3

Generating documentation

docs/Doxyfile configures Doxygen output for the C++ API reference (separate from this wiki).