# How the OpenThread tree in `src/` was assembled

The library vendors pinned, lightly-patched copies of OpenThread and mbedtls so
that a plain Arduino library build (recursive `src/` compile, single `-Isrc`
include root, no per-library compiler flags) produces a working FTD stack.

## Sources and versions

| Component | Source | Version |
| --------- | ------ | ------- |
| OpenThread core + public headers | https://github.com/openthread/openthread | `fa3213ec` |
| mbedtls | https://github.com/Mbed-TLS/mbedtls | `e185d7fd` (3.6.5, OT's pinned submodule) |

## Layout mapping

Arduino resolves quoted includes against `-I<lib>/src`, so the OpenThread
`src/core/` tree is flattened to the `src/` root (its sources include each
other as `"common/... 'mac/..."` etc.):

| Upstream | Here |
| -------- | ---- |
| `openthread/src/core/<dir>/` (api, common, config, crypto, instance, mac, meshcop, net, radio, thread, utils, coap, ...) | `src/<dir>/` |
| `openthread/src/core/openthread-core-config.h` | `src/openthread-core-config.h` (patched, see below) |
| `openthread/src/include/common/*.hpp` | merged into `src/common/` |
| `openthread/include/openthread/**` | `src/openthread/` |
| `mbedtls/include/mbedtls/`, `include/psa/` | `src/mbedtls/`, `src/psa/` |
| `mbedtls/library/*.c|*.h` | `src/mbedtls_lib/` |

Excluded: build files, `src/cli`, `src/ncp`, `src/posix`, `src/lib`
(spinel/hdlc), tcplp (TCP is disabled), and
`src/core/instance/extension_example.cpp` (a template upstream excludes too —
Arduino would otherwise compile it).

## The three patches (all marked `ARDUINONRF-PATCH`)

1. **`src/openthread-core-config.h`** — defaults
   `OPENTHREAD_PROJECT_CORE_CONFIG_FILE` to `"arduino-ot-config.h"`. This is
   the official project-config hook; it is normally set with `-D`, which
   Arduino cannot do. Every core source includes this header first, so the
   whole configuration flows from `src/arduino-ot-config.h`.
2. **`src/mbedtls/mbedtls_config.h`** — replaced with OpenThread's
   `third_party/mbedtls/mbedtls-config.h` (same reason: `MBEDTLS_CONFIG_FILE`
   cannot be injected). The config self-adapts to the OT feature set.
3. **`src/arduino-ot-config.h`** — not a patch but the platform's build
   configuration: FTD device type, software MAC
   (CSMA/retransmit/ack-timeout/TX-security in the sub-MAC, matching the
   radio's `OT_RADIO_CAPS_NONE`), microsecond timer enabled, CSL/TCP off,
   logging to the platform sink. Also defines `PACKAGE_NAME`/`PACKAGE_VERSION`
   that OT's build system would normally inject.

## Re-vendoring to a newer OpenThread

1. Clone the new OpenThread, note the mbedtls submodule SHA
   (`git ls-tree HEAD third_party/mbedtls/repo`), and fetch mbedtls at it.
2. Re-run the copy mapping above into a scratch tree; delete
   `instance/extension_example.cpp`.
3. Re-apply the two header patches (diff them first — both files are small and
   change rarely) and keep `arduino-ot-config.h` as is.
4. Rebuild the examples; fix any new platform API (`otPlat*`) the core grew —
   that surface lives in `src/platform_impl.cpp` and
   `src/ot_radio_nrf52840.cpp` only.
