|
| 1 | +# AGENTS.md |
| 2 | + |
| 3 | +Agent instructions for the **nRF Connect SDK Amazon Sidewalk** repository. |
| 4 | +Applies to Claude Code, GitHub Copilot, Cursor, Codex, and similar AI coding assistants. |
| 5 | + |
| 6 | +## Knowledge Sources |
| 7 | + |
| 8 | +Prefer up-to-date sources over built-in knowledge: |
| 9 | + |
| 10 | +- **nrflow MCP** (if available) — nRF Connect SDK, Zephyr, west (`nordicsemi_search_sources` / `nordicsemi_workflow_ncs`) |
| 11 | +- **context7 MCP** (if available) — external library and tool docs: CMake, Python libs, AWS, etc. (`resolve-library-id` + `query-docs`) |
| 12 | +- **nordic-semiconductor-docs MCP** (if available) — Nordic Semiconductor product documentation and datasheets |
| 13 | +- **Project documentation** — reStructuredText docs in `doc/` (see [Documentation](#documentation) section below) |
| 14 | + |
| 15 | +MCP servers may not be available in all environments; fall back to project docs and web search if needed. |
| 16 | + |
| 17 | +## Project Overview |
| 18 | + |
| 19 | +This is the **nRF Connect SDK Amazon Sidewalk** repository — a Platform Abstraction Layer (PAL) and sample application framework for Amazon Sidewalk on Nordic Semiconductor nRF hardware (nRF52840, nRF5340, nRF54L15). It targets Zephyr RTOS with support for BLE, LoRa, and FSK link types. The Sidewalk protocol core is shipped as prebuilt `.a` libraries. |
| 20 | + |
| 21 | +## Build System |
| 22 | + |
| 23 | +This repository is designed to live inside a west workspace. The workspace root is the **parent directory** of this repo, where `.west/` resides. All commands below assume the workspace root as the working directory; paths like `sidewalk/` refer to this repo from there. |
| 24 | + |
| 25 | +### Workspace initialization check |
| 26 | + |
| 27 | +Before running any build command, verify the workspace is initialized: |
| 28 | + |
| 29 | +```bash |
| 30 | +ls ../.west # must exist; if not, the workspace is not set up |
| 31 | +``` |
| 32 | + |
| 33 | +If `../.west/` is missing, the workspace has not been initialized. Report this to the user and direct them to the SDK setup guide: |
| 34 | +`doc/setting_up_sidewalk_environment/setting_up_sdk.rst` |
| 35 | + |
| 36 | +### Determining the toolchain version |
| 37 | + |
| 38 | +The required NCS version is declared in `west.yml` (this repo) under `projects[name=nrf].revision`: |
| 39 | + |
| 40 | +```bash |
| 41 | +grep revision west.yml # e.g. v3.0.0 |
| 42 | +``` |
| 43 | + |
| 44 | +`west` must be invoked through `nrfutil toolchain-manager` — it is not on PATH directly. Use `--ncs-version` with the version from `west.yml`. Before running any build command: |
| 45 | + |
| 46 | +1. **Check available toolchains:** |
| 47 | + ```bash |
| 48 | + nrfutil toolchain-manager list |
| 49 | + ``` |
| 50 | +2. **Exact match** — if the version from `west.yml` is listed, use it directly: |
| 51 | + ```bash |
| 52 | + nrfutil toolchain-manager launch --ncs-version v3.0.0 --chdir .. -- west ... |
| 53 | + ``` |
| 54 | +3. **No exact match** — pick the closest installed version using semver comparison (prefer same major.minor, nearest patch/pre-release). Inform the user which version is being used as a substitute. |
| 55 | + |
| 56 | +4. **No toolchain installed** — report to the user and ask them to install the required toolchain: |
| 57 | + ```bash |
| 58 | + nrfutil toolchain-manager install --ncs-version v3.0.0 |
| 59 | + ``` |
| 60 | + |
| 61 | +## Common Commands |
| 62 | + |
| 63 | +All commands run from the **workspace root** (parent directory of this repo). Replace `<ncs-version>` with the version resolved above. |
| 64 | + |
| 65 | +### Build a sample |
| 66 | + |
| 67 | +```bash |
| 68 | +# Default: hello app, BLE link, nrf54l15dk/nrf54l10/cpuapp |
| 69 | +nrfutil toolchain-manager launch --ncs-version <ncs-version> --chdir .. -- \ |
| 70 | + west build -b nrf54l15dk/nrf54l10/cpuapp sidewalk/samples/sid_end_device --sysbuild |
| 71 | +``` |
| 72 | + |
| 73 | +Artifacts: `build/zephyr/zephyr.elf`, `build/merged.hex`, `build/dfu_application.zip`. |
| 74 | + |
| 75 | +For LoRa/FSK, add `-DOVERLAY_CONFIG=overlay-hello.conf` and the appropriate shield: |
| 76 | +```bash |
| 77 | + -DSHIELD="simple_arduino_adapter;semtech_sx1262mb2cas" |
| 78 | +``` |
| 79 | + |
| 80 | +### Flash |
| 81 | + |
| 82 | +```bash |
| 83 | +nrfutil toolchain-manager launch --ncs-version <ncs-version> --chdir .. -- \ |
| 84 | + west flash |
| 85 | +``` |
| 86 | + |
| 87 | +## Documentation |
| 88 | + |
| 89 | +The project documentation is written in **reStructuredText** and lives in the `doc/` directory. Read it to understand how to build, configure, run, and test Sidewalk — do not duplicate it here (DRY). |
| 90 | + |
| 91 | +**How to navigate:** |
| 92 | + |
| 93 | +- Start at `doc/index.rst` — it contains the root `toctree` linking all top-level sections. |
| 94 | +- Each `.rst` file may contain a nested `toctree` pointing to further sub-pages; follow the tree recursively to find relevant content. |
| 95 | +- Key top-level sections and their entry points: |
| 96 | + - `doc/setting_up_sidewalk_environment/setting_up_environment.rst` — environment setup, hardware requirements, SDK installation, prototype setup, manufacturing environment |
| 97 | + - `doc/samples/samples_list.rst` — sample overview and board/variant matrix |
| 98 | + - `doc/testing.rst` — testing instructions |
| 99 | + - `doc/compatibility_matrix.rst` — supported hardware and NCS version compatibility |
| 100 | + - `doc/release_notes_and_migration.rst` — release notes and migration guides |
| 101 | + - `doc/known_issues.rst` — known issues |
| 102 | + - `doc/additional_resources.rst` — external links and references |
| 103 | + |
| 104 | +When asked about setup, building, flashing, or testing, read the relevant `.rst` file(s) before answering. |
| 105 | + |
| 106 | +## Architecture |
| 107 | + |
| 108 | +### Layer Stack |
| 109 | + |
| 110 | +``` |
| 111 | +Application (samples/sid_end_device/src/{hello,sensor_monitoring,cli,sbdt}) |
| 112 | + ↓ |
| 113 | +Sidewalk Thread + Message Queue (sidewalk.c / sidewalk_events.c) |
| 114 | + ↓ |
| 115 | +Sidewalk Protocol Core (prebuilt libs: lib/cortex-m4/ or lib/cortex-m33/) |
| 116 | + ↓ |
| 117 | +PAL — Platform Abstraction Layer (subsys/sal/sid_pal/) |
| 118 | + ↓ |
| 119 | +Zephyr drivers + Semtech radio drivers (subsys/semtech/) |
| 120 | + ↓ |
| 121 | +Hardware (nRF SoC) |
| 122 | +``` |
| 123 | + |
| 124 | +### Key Directories |
| 125 | + |
| 126 | +- **`lib/`** — Prebuilt Sidewalk protocol libraries. Two architecture variants (`cortex-m4`, `cortex-m33`), each with `ble_only` and `lora_fsk` sub-variants. |
| 127 | +- **`subsys/sal/`** — PAL implementations for BLE adapter, radio, crypto (PSA-based), storage, timers, serial bus. The `common/` subdirectory contains interface headers; `sid_pal/` contains Zephyr-specific implementations. |
| 128 | +- **`subsys/hal/`** — Minimal HAL for memory and reset. |
| 129 | +- **`subsys/ace/`** — AWS Cloud for Edge OSAL — OS abstraction for memory allocation used by the Sidewalk library. |
| 130 | +- **`subsys/semtech/`** — Third-party SX126x, LR1110, LR11xx radio drivers. |
| 131 | +- **`samples/sid_end_device/`** — The primary sample application. `main.c` → `app_start()` → dedicated Zephyr thread with a `K_MSGQ`-backed event queue. |
| 132 | +- **`utils/`** — Reusable utilities: TLV encoding, settings/NVS helpers, button handling, state notifier (LED/log backends), nanopb (protobuf), DFU support. |
| 133 | +- **`tests/unit_tests/`** — 20+ x86 unit test suites covering BLE callbacks, PAL (timer, temp, logging), TLV, manufacturing parsers, message queuing, etc. |
| 134 | + |
| 135 | +### Event-Driven Design |
| 136 | + |
| 137 | +The sample application uses a dedicated Zephyr thread (`sid_thread_entry`) with a kernel message queue. Sidewalk library callbacks post events to this queue; the thread dispatches them to handlers defined in `sidewalk_events.c`. Core event types: `process`, `platform_init`, `connect`, `autostart`, `send_msg`, `factory_reset`. |
| 138 | + |
| 139 | +### Configuration |
| 140 | + |
| 141 | +- **Kconfig** (`Kconfig`, `Kconfig.dependencies`) — compile-time feature selection: link type (BLE/LoRa/FSK), heap size, thread stack/priority, logging verbosity. |
| 142 | +- **Device tree overlays** (`dts/`) — board-specific hardware configuration. |
| 143 | +- **`test_config.yaml`** — Twister test levels: `samples`, `unit`, `integration`, `Github_tests`, `bugs`. |
| 144 | + |
| 145 | +### Manufacturing Data |
| 146 | + |
| 147 | +Manufacturing credentials are provisioned per-device using the tools in `tools/provision/`. The flow requires a Sidewalk account and device JSON files obtained from AWS IoT (either a combined `certificate.json` or separate `wireless_device.json` + `device_profile.json`). |
| 148 | + |
| 149 | +Provisioning is board-specific — the `--addr` argument and flash command differ per target: |
| 150 | + |
| 151 | +| Target | `--addr` | Flash command | |
| 152 | +|--------|----------|---------------| |
| 153 | +| nRF52840 / nRF5340 DKs | `0xFF000` | `nrfjprog --sectorerase --program <file>.hex --reset` | |
| 154 | +| nRF54L10 (emulated on nRF54L15 DK) | `0xFF000` | `nrfutil device program --x-family nrf54l ...` | |
| 155 | +| nRF54L15 DK | `0x17c000` | `nrfutil device program --x-family nrf54l ...` | |
| 156 | + |
| 157 | +Example for nRF54L15: |
| 158 | +```bash |
| 159 | +python3 tools/provision/provision.py nordic aws \ |
| 160 | + --output_bin mfg.bin \ |
| 161 | + --certificate_json certificate.json \ |
| 162 | + --addr 0x17c000 \ |
| 163 | + --output_hex nordic_aws_nrf54l15.hex |
| 164 | + |
| 165 | +nrfutil device program \ |
| 166 | + --x-family nrf54l \ |
| 167 | + --options chip_erase_mode=ERASE_RANGES_TOUCHED_BY_FIRMWARE,reset=RESET_PIN,verify=VERIFY_READ \ |
| 168 | + --traits jlink \ |
| 169 | + --firmware nordic_aws_nrf54l15.hex |
| 170 | +``` |
| 171 | + |
| 172 | +Full provisioning instructions (including onboarding and MQTT destination setup) are in: |
| 173 | +`doc/setting_up_sidewalk_environment/setting_up_sidewalk_prototype.rst` |
| 174 | + |
| 175 | +The TLV-based manufacturing hex format (v7 and v8) is handled by parsers in `utils/` and tested in `tests/unit_tests/mfg_parsers/`. |
| 176 | + |
| 177 | +## CI |
| 178 | + |
| 179 | +GitHub workflows in `.github/workflows/`: |
| 180 | +- `run_tests.yml` — x86 unit tests with coverage |
| 181 | +- `samples_build.yml` — multi-board sample build matrix |
| 182 | +- `validate_code_style.yml` — formatting, licensing, compliance |
| 183 | +- `on-pr.yml` / `on-commit.yml` — triggered automatically on PRs and commits |
| 184 | + |
| 185 | +### Running CI checks locally |
| 186 | + |
| 187 | +The CI workflows invoke scripts from this repo and from `zephyr/`. All commands below run from the **workspace root**. Replace `<ncs-version>` with the version resolved from `west.yml`. |
| 188 | + |
| 189 | +#### Compliance check (yamllint, kconfig, devicetree, gitlint, …) |
| 190 | + |
| 191 | +Requires `zephyr/zephyr-env.sh` to be sourced and the compliance pip dependencies installed: |
| 192 | + |
| 193 | +```bash |
| 194 | +pip3 install -r ../zephyr/scripts/requirements-compliance.txt |
| 195 | +source ../zephyr/zephyr-env.sh |
| 196 | +cd sidewalk |
| 197 | +python3 scripts/ci/sid_compliance.py --annotate \ |
| 198 | + -m yamllint -m kconfigbasic -m devicetreebindings \ |
| 199 | + -m binaryfiles -m imagesize -m nits -m gitlint -m identity \ |
| 200 | + -c origin/main..HEAD |
| 201 | +``` |
| 202 | + |
| 203 | +`-c <base>..HEAD` sets the commit range to check. Use `origin/main..HEAD` for a local branch, or pass a specific commit SHA. |
| 204 | + |
| 205 | +#### Formatting check |
| 206 | + |
| 207 | +```bash |
| 208 | +pip3 install -r sidewalk/scripts/ci/requirements.txt |
| 209 | +python3 sidewalk/scripts/ci/verify_formatting.py -d -s sidewalk -c sidewalk/scripts/ci/formatter_cfg.yml |
| 210 | +``` |
| 211 | + |
| 212 | +#### License check |
| 213 | + |
| 214 | +```bash |
| 215 | +python3 sidewalk/scripts/ci/verify_license.py -s sidewalk -c sidewalk/scripts/ci/license.yml |
| 216 | +``` |
| 217 | + |
| 218 | +#### Unit tests (x86, no hardware needed) |
| 219 | + |
| 220 | +```bash |
| 221 | +source ../zephyr/zephyr-env.sh |
| 222 | +nrfutil toolchain-manager launch --ncs-version <ncs-version> --chdir .. -- \ |
| 223 | + west twister --test-config sidewalk/test_config.yaml \ |
| 224 | + --level="Github_tests" --testsuite-root sidewalk \ |
| 225 | + --platform native_sim --platform unit_testing \ |
| 226 | + --coverage --coverage-basedir sidewalk --coverage-formats html,xml \ |
| 227 | + --enable-ubsan --enable-lsan --enable-asan --inline-logs \ |
| 228 | + --overflow-as-errors -vvv |
| 229 | +``` |
0 commit comments