nrsuite-protocol¶

Wire protocol specification for the NRSuite security research toolkit.

This repo is the single source of truth for the frame format and JSON payload schema used between the NRSuite Android app and NRSuite ESP32 firmware. Both repos are versioned independently; this spec is what keeps them compatible.

If your change adds, removes, or modifies any command, response field, or frame type, update this spec and bump the version before merging either side's implementation.

Community¶

Join the NRSuite Discord server for setup help, build showcases, release news, and development discussion:

Use #support for help, #showcase for builds, and #github for repo/code discussion.

Versioning¶

This spec uses MAJOR.MINOR versioning:

MAJOR bumped for breaking changes (removed fields, changed frame layout, renamed commands)
MINOR bumped for additive changes (new commands, new optional response fields, new frame types)

App and firmware releases each declare which spec version they implement. See the compatibility table.

Current wire major: 1.0

Latest additive revision: proto_minor 2 (pull-based scan results)

Draft next major/minor: 1.1 (Mesh Foundation)

Repository layout¶

PROTOCOL-SPEC.md - core transport, frame format, session lifecycle, JSON envelope, STATUS response, and error handling
commands/ - command reference by radio category, including mesh commands
events/ - event reference by category, including mesh events
COMPATIBILITY.md - app/firmware/protocol compatibility matrix

Core spec sections¶

License¶

GNU General Public License v3.0 or later

This protocol specification and its documentation are free software: you may redistribute and/or modify them under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.