Skip to content

reference.md

Latest commit

 

History

History
70 lines (54 loc) · 3.41 KB

reference.md

File metadata and controls

70 lines (54 loc) · 3.41 KB
Raw

Reference

The exact shape of something is in the header that declares it. This repository has no generated API tree: the declarations carry per-field comments, and a second rendering of them is one more thing that can fall behind the code.

Start at the umbrella

#include <ultrawidelock/ultrawidelock.h>   // every public declaration

Or include a single role:

Header For
<ultrawidelock/reader.h> the lock side: sessions, the key ladder, the unlock decision
<ultrawidelock/device.h> the initiator side, which is what a phone stand-in builds
<ultrawidelock/tlv.h> the codec alone, with no radio and no storage
<ultrawidelock/ultrawidelock_hal.h> the five seams a port implements

include/ultrawidelock/ owns the public surface. Anything reachable only from modules/*/include/ is internal by construction, and a port that reaches for it fails make purity.

Where the protocol lives

Most of the protocol is preprocessor constants rather than functions: attribute IDs, frame lengths, key-block offsets, bitmask layouts. Read them where they are defined.

Looking for Look in
credential APDUs, provisioning, the approach state machine modules/ultrawidelock_cred/include/
CCC sessions, the key derivation ladder, DS-TWR, FiRa modules/ultrawidelock_uwb/include/
side of the door: fusion, latch, seal, witnesses modules/ultrawidelock_anchor/include/
the Matter node's clusters and transport modules/ultrawidelock_matter/
ECP and the reader transports modules/ultrawidelock_nfc/
the OS, flash, log and byte-order contracts modules/ultrawidelock_port/include/

Ports add their own surfaces under ports/<port>/: the ESP32 tree carries ultrawidelock_ble, ultrawidelock_crypto, ultrawidelock_reader, ultrawidelock_satlink and the target-specific board-pin API as ESP-IDF components.

The CMake package

cmake -S . -B build/sdk -DCMAKE_INSTALL_PREFIX="$PWD/build/sdk-install"
cmake --build build/sdk
cmake --install build/sdk

Exports UltraWideLock::headers and UltraWideLock::tlv; the version comes from the root VERSION. add_subdirectory also works, and make sdk-check verifies both paths against examples/cmake/consumer/. Full firmware is consumed through the Zephyr module or the ESP-IDF components.

Where to look

Question Where to look
What are the fields of this struct? What is this constant's value? the header, above
Which files make up this subsystem, and what depends on what? the subsystem graph, built by make docs
What can I include from outside the tree? PORTING.md and make sdk-check
Why is it built this way? What went wrong on the bench? the guides: esp32-gotchas.md for the ESP32-S3 port, dwm3001cdk-surgery.md for the DWM3001CDK
What is the wire format? protocol-notes.md, then protocol-research.md

If a declaration's shape is not obvious from its header, the fix is a doc comment at the declaration.