diff --git a/docs/payloads.md b/docs/payloads.md index 5af04932f..c3bee38dd 100644 --- a/docs/payloads.md +++ b/docs/payloads.md @@ -350,7 +350,7 @@ The data contained in the ciphertext uses the format below: | Field | Size (bytes) | Description | |--------------|-----------------|----------------------------------------------| -| flags | 1 | 0x8 (upper 4 bits), prefix_only (lowest bit) | +| flags | 1 | 0x8 (upper 4 bits), prefix_only (bit 0), request radio2 profile (bit 1) | | type_filter | 1 | bit for each ADV_TYPE_* | | tag | 4 | randomly generate by sender | | since | 4 | (optional) epoch timestamp (0 by default) | @@ -364,6 +364,10 @@ The data contained in the ciphertext uses the format below: | tag | 4 | reflected back from DISCOVER_REQ | | pubkey | 8 or 32 | node's ID (or prefix) | +Repeaters append an optional [radio2 profile trailer](radio_profiles.md#discover-the-local-radio2-profile) +when request bit 1 is set. Without that bit, the response is unchanged. Legacy +responders omit the trailer even when requested. + ## Trace diff --git a/docs/radio_profiles.md b/docs/radio_profiles.md index dc4cf990d..a35db553b 100644 --- a/docs/radio_profiles.md +++ b/docs/radio_profiles.md @@ -68,6 +68,44 @@ If the second profile cannot transmit MeshCore, media uses the normal channel/global route; `set tx.media radio2` instead requires radio2 with no primary fallback. See [application TX routing](#companion-media-and-ssh-tx-routing). +### Discover the local radio2 profile + +Clients can request a repeater's current MeshCore radio2 profile through public, +zero-hop discovery. Set bit 1 (`0x02`) of the `DISCOVER_REQ` flags byte: `0x82` +for the full public key, or `0x83` with the prefix-only bit also set. The type +filter, tag and optional `since` fields keep their existing meanings. Omit +`since` or send zero when requesting current settings; radio changes do not +update the discovery timestamp. + +The requested `DISCOVER_RESP` appends this version-1 trailer immediately after +the public key, at payload offset 38 (full key) or 14 (8-byte prefix): + +| Field | Bytes | Meaning | +| --- | --- | --- | +| version | 1 | `1` | +| flags | 1 | Bit 0: configured; bits 1–2: mode (`0` off, `1` rx, `2` rxtx); bit 3: temporary; other bits zero | +| frequency | 4 | Little-endian unsigned integer, MHz × 1000, rounded | +| bandwidth | 4 | Little-endian unsigned integer, kHz × 1000, rounded | +| SF | 1 | Spreading factor | +| CR | 1 | Coding-rate denominator (`5` means 4/5) | + +For example, the MediaMesh preset reports frequency `911150`, bandwidth +`250000`, SF `7`, CR `5` and flags `0x05`. An active `tempradio2` reports its +current settings with bit 3 set. Clients use automatic preamble; the trailer +does not carry a preamble value. + +When radio2 is off, unsupported, or using a foreign protocol, the trailer is +only `[1][0]`. Full responses are therefore 50 bytes with a profile or 40 bytes +without one; prefix-only responses are 26 or 16 bytes. Without the request bit, +responses remain 38 or 14 bytes. A legacy responder's missing trailer means +unsupported, not disabled. Clients should ignore unknown versions and +incomplete trailers. + +Replies remain on the main radio with zero hops and share the existing limit +of four replies per two minutes. Existing visibility controls still apply. +Discovery is public and unauthenticated. See [control data](payloads.md#control-data) +for the base packet fields. + ### Channel spacing When setting a saved, temporary or scheduled second profile, the response warns diff --git a/examples/simple_repeater/MyMesh.cpp b/examples/simple_repeater/MyMesh.cpp index 9ce88fc2c..72b2a110e 100644 --- a/examples/simple_repeater/MyMesh.cpp +++ b/examples/simple_repeater/MyMesh.cpp @@ -3514,13 +3514,34 @@ void MyMesh::onControlDataRecv(mesh::Packet* packet) { if ((filter & (1 << ADV_TYPE_REPEATER)) != 0 && _prefs.discovery_mod_timestamp >= since) { bool prefix_only = packet->payload[0] & 1; - uint8_t data[6 + PUB_KEY_SIZE]; + uint8_t data[6 + PUB_KEY_SIZE + 12]; + size_t length = 6 + (prefix_only ? 8 : PUB_KEY_SIZE); data[0] = CTL_TYPE_NODE_DISCOVER_RESP | ADV_TYPE_REPEATER; // low 4-bits for node type data[1] = packet->_snr; // let sender know the inbound SNR ( x 4) memcpy(&data[2], &tag, 4); // include tag from request, for client to match to - memcpy(&data[6], self_id.pub_key, PUB_KEY_SIZE); - auto resp = createControlData(data, prefix_only ? 6 + 8 : 6 + PUB_KEY_SIZE); + memcpy(&data[6], self_id.pub_key, length - 6); + if (packet->payload[0] & 0x02) { // optional radio2 profile, version 1 + data[length++] = 1; + data[length++] = 0; + const auto* profiles = _radio->profiles(); + // V1 describes a usable MeshCore profile, not a foreign radio2 owner. + if (profiles && (profiles->secondary.mode == mesh::RadioProfileMode::Rx + || profiles->secondary.mode == mesh::RadioProfileMode::RxTx) + && profiles->secondary.params.protocol == mesh::RadioProfileProtocol::MeshCore) { + const auto& secondary = profiles->secondary; + data[length - 1] = 1 | (static_cast(secondary.mode) << 1) + | (profiles->secondary_temporary ? 0x08 : 0); + const uint32_t frequency = static_cast(lroundf(secondary.params.freq * 1000.0f)); + const uint32_t bandwidth = static_cast(lroundf(secondary.params.bw * 1000.0f)); + for (unsigned shift = 0; shift < 32; shift += 8) data[length++] = frequency >> shift; + for (unsigned shift = 0; shift < 32; shift += 8) data[length++] = bandwidth >> shift; + data[length++] = secondary.params.sf; + data[length++] = secondary.params.cr; + } + } + auto resp = createControlData(data, length); if (resp) { + resp->tx_radio = mesh::RADIO_TX_PRIMARY; sendZeroHop(resp, getRetransmitDelay(resp)*4); // apply random delay (widened x4), as multiple nodes can respond to this } } diff --git a/test/test_companion_discovery.py b/test/test_companion_discovery.py index 2f218e1fc..8c4444cb8 100644 --- a/test/test_companion_discovery.py +++ b/test/test_companion_discovery.py @@ -18,6 +18,7 @@ class CompanionDiscoveryTests(unittest.TestCase): #include #include #include +#include #define DISCOVERED_NODES_TABLE_SIZE 4 #define CTL_TYPE_NODE_DISCOVER_RESP 0x90 static uint32_t now=100; @@ -56,6 +57,19 @@ int main(){ mesh.disc_node_req_at=0xfffffff0;now=20; mesh.checkControlDataForPendingDiscovery(response,14);assert(mesh.disc_nodes_count==1); assert(mesh.discovered_nodes[0].name[31]==0&&mesh.discovered_nodes[0].snr_out==5.0f); + // Existing clients must accept both key sizes with no trailer, the two-byte + // off marker, or the full twelve-byte radio2 profile, retaining the prefix. + for(size_t length : {14U,16U,26U,38U,40U,50U}){ + MyMesh legacy;legacy.disc_node_req_at=now; + uint8_t extended[50];memset(extended,0xAB,sizeof(extended)); + memcpy(extended,response,14); + size_t offset=length<=26?14:38; + if(length>offset){extended[offset]=1;extended[offset+1]=length-offset==2?0:5;} + legacy.checkControlDataForPendingDiscovery(extended,length); + assert(legacy.disc_nodes_count==1); + assert(memcmp(legacy.discovered_nodes[0].pubkey_prefix,response+6,8)==0); + assert(legacy.discovered_nodes[0].type==2&&legacy.discovered_nodes[0].snr_out==5.0f); + } for(int i=0;i<10;i++)mesh.checkControlDataForPendingDiscovery(response,14); assert(mesh.disc_nodes_count==4); DiscoveredNode result[4];assert(mesh.getDiscoveredNodes(result,100)==4); diff --git a/test/test_repeater_discovery.py b/test/test_repeater_discovery.py index f5cd7be66..07faa876d 100644 --- a/test/test_repeater_discovery.py +++ b/test/test_repeater_discovery.py @@ -23,6 +23,7 @@ HARNESS = r''' #include #include #include "examples/simple_repeater/RateLimiter.h" +#include "src/RadioProfiles.h" @CONSTANTS@ #define MESH_DEBUG_PRINTLN(...) ((void)0) static uint32_t now_ms = 100; @@ -47,10 +48,24 @@ struct Identity { struct Packet { uint8_t payload[64] = {}; uint8_t payload_len = 0; + uint8_t tx_radio = RADIO_TX_AUTO; + uint8_t radio_profile = 1; + bool radio_reply = true, radio_bound = false, radio_reply_force = false, radio_local = true; int8_t _snr = -20; + uint8_t getPayloadType() const { return PAYLOAD_TYPE_CONTROL; } float getSNR() const { return _snr / 4.0f; } int getRSSI() const { return -90; } }; +struct Radio { + mesh::RadioProfiles state; + bool available = true; + const mesh::RadioProfiles* profiles() const { return available ? &state : nullptr; } +}; +struct Dispatcher { + const Radio* _radio; + uint8_t getTransmitProfileMask(const Packet* packet) const; +}; +@DISPATCHER@ } struct MyMesh { struct { @@ -63,6 +78,8 @@ struct MyMesh { uint32_t getCurrentTime() const { return now; } } rtc_clock; RateLimiter @LIMITER@; + mesh::Radio radio; + mesh::Radio* _radio = &radio; mesh::Identity self_id, neighbour; mesh::Packet response; uint32_t pending_discover_tag = 0, pending_discover_until = 1000; @@ -90,6 +107,10 @@ struct MyMesh { } void sendZeroHop(mesh::Packet* packet, uint32_t delay) { require(packet == &response, "radio sent the wrong reply packet"); + require(packet->tx_radio == mesh::RADIO_TX_PRIMARY, + "discovery response was not restricted to the main radio"); + require(mesh::Dispatcher{_radio}.getTransmitProfileMask(packet) == 1, + "dispatcher would send discovery response on radio2 or both profiles"); ++sent_packets; sent_delay = delay; } @@ -103,9 +124,10 @@ struct MyMesh { }; @HANDLER@ static mesh::Packet request(bool prefix = false, uint32_t since = 0, - bool include_since = false) { + bool include_since = false, bool include_radio2 = false) { mesh::Packet packet; - packet.payload[0] = CTL_TYPE_NODE_DISCOVER_REQ | (prefix ? 1 : 0); + packet.payload[0] = CTL_TYPE_NODE_DISCOVER_REQ | (prefix ? 1 : 0) + | (include_radio2 ? 2 : 0); packet.payload[1] = 1 << ADV_TYPE_REPEATER; const uint32_t tag = 0x78563412; std::memcpy(packet.payload + 2, &tag, sizeof(tag)); @@ -118,13 +140,14 @@ static void policy() { for (uint16_t flood : {uint16_t(0), uint16_t(30)}) { for (bool repeat_off : {false, true}) { for (bool prefix : {false, true}) { + for (bool include_radio2 : {false, true}) { MyMesh receiver; receiver._prefs.advert_interval = local; receiver._prefs.flood_advert_interval = flood; receiver._prefs.disable_fwd = repeat_off; const bool hidden = local == 0 && flood == 0; require(receiver.isHiddenNode() == hidden, "hidden predicate misread advert intervals"); - auto packet = request(prefix); + auto packet = request(prefix, 0, false, include_radio2); receiver.onControlDataRecv(&packet); if (hidden) { require(receiver.create_attempts == 0 && receiver.sent_packets == 0, @@ -133,36 +156,41 @@ static void policy() { require(receiver.create_attempts == 1 && receiver.sent_packets == 1, "visible node or repeat-off observer lost discovery"); } + } } } } } } static void gates() { + for (unsigned flags = 0; flags < 4; ++flags) { for (size_t length = 0; length < 6; ++length) { MyMesh receiver; - auto packet = request(); + auto packet = request(flags & 1, 0, false, flags & 2); packet.payload_len = length; receiver.onControlDataRecv(&packet); require(receiver.create_attempts == 0, "truncated request produced a reply"); } for (uint8_t filter : {uint8_t(0), uint8_t(1 << 3)}) { MyMesh receiver; - auto packet = request(); + auto packet = request(flags & 1, 0, false, flags & 2); packet.payload[1] = filter; receiver.onControlDataRecv(&packet); require(receiver.create_attempts == 0, "unrelated node filter produced a reply"); } for (uint32_t since : {499U, 500U, 501U}) { MyMesh receiver; - auto packet = request(false, since, true); + auto packet = request(flags & 1, since, true, flags & 2); receiver.onControlDataRecv(&packet); require(receiver.sent_packets == (since <= 500 ? 1U : 0U), "discovery timestamp boundary changed"); } + } MyMesh limited; auto packet = request(); for (unsigned count = 1; count <= 5; ++count) { + // The optional trailer and key-prefix flags share one limiter. + packet.payload[0] = CTL_TYPE_NODE_DISCOVER_REQ | ((count - 1) & 3); limited.onControlDataRecv(&packet); require(limited.sent_packets == (count <= 4 ? count : 4), "discovery rate limit changed"); @@ -204,6 +232,106 @@ static void wire() { require(exhausted.create_attempts == 1 && exhausted.sent_packets == 0, "allocation failure attempted to transmit a reply"); } +static uint32_t little_endian(const uint8_t* bytes) { + return uint32_t(bytes[0]) | (uint32_t(bytes[1]) << 8) + | (uint32_t(bytes[2]) << 16) | (uint32_t(bytes[3]) << 24); +} +static void radio2_wire() { + for (bool prefix : {false, true}) { + for (bool temporary : {false, true}) { + for (auto mode : {mesh::RadioProfileMode::Rx, mesh::RadioProfileMode::RxTx}) { + for (float bandwidth : {62.5f, 125.0f, 250.0f}) { + MyMesh receiver; + auto& profiles = receiver.radio.state; + profiles.secondary.mode = mode; + // Strict decimal CLI parsing may land one float ULP below the + // literal. Both values must round back to the requested 911150 kHz. + profiles.secondary.params.freq = temporary ? nextafterf(911.150f, 0.0f) : 911.150f; + profiles.secondary.params.bw = bandwidth; + profiles.secondary.params.sf = 7; + profiles.secondary.params.cr = 5; + profiles.secondary_temporary = temporary; + // Ordinary discovery must remain byte-for-byte compatible, even + // while a temporary radio2 profile and cross-radio replies are active. + profiles.cross = mesh::RadioCrossMode::On; + profiles.reply_tx = mesh::RADIO_TX_BOTH; + profiles.reply_force = true; + auto original = request(prefix); + receiver.onControlDataRecv(&original); + const size_t offset = 6 + (prefix ? 8 : PUB_KEY_SIZE); + require(receiver.response.payload_len == offset, + "unsolicited radio2 trailer changed ordinary discovery"); + uint8_t baseline[6 + PUB_KEY_SIZE]; + std::memcpy(baseline, receiver.response.payload, offset); + auto opted_in = request(prefix, 0, false, true); + receiver.onControlDataRecv(&opted_in); + require(receiver.response.payload_len == offset + 12, + "active MeshCore radio2 reply has the wrong trailer length"); + require(std::memcmp(baseline, receiver.response.payload, offset) == 0, + "radio2 trailer changed the existing discovery fields"); + const uint8_t* trailer = receiver.response.payload + offset; + const uint8_t flags = mode == mesh::RadioProfileMode::Rx ? 3 : 5; + require(trailer[0] == 1 && trailer[1] == (flags | (temporary ? 8 : 0)), + "radio2 version, configured/mode or temporary flags changed"); + require(little_endian(trailer + 2) == 911150, + "radio2 frequency was truncated or encoded in the wrong units/order"); + require(little_endian(trailer + 6) == uint32_t(bandwidth * 1000), + "radio2 bandwidth lost fractional kHz or used the wrong units/order"); + require(trailer[10] == 7 && trailer[11] == 5, + "radio2 spreading factor or coding rate changed"); + require(receiver.sent_packets == 2 && receiver.sent_delay == 28, + "extended discovery changed zero-hop reply count or random delay"); + // The unchanged full-key parser accepts optional trailing bytes. + MyMesh peer; + peer.pending_discover_tag = 0x78563412; + receiver.response.payload[6] ^= 1; // A different repeater identity. + peer.onControlDataRecv(&receiver.response); + require(peer.neighbours == (prefix ? 0U : 1U), + "optional trailer broke full-key discovery parsing"); + } + } + } + } +} +static void radio2_disabled() { + for (bool prefix : {false, true}) { + for (int inactive_reason : {0, 1, 2, 3, 4}) { + MyMesh receiver; + auto& profiles = receiver.radio.state; + profiles.secondary.params.freq = 911.150f; + profiles.secondary.params.bw = 250; + profiles.secondary.params.sf = 7; + profiles.secondary.params.cr = 5; + profiles.secondary_temporary = true; + if (inactive_reason == 0) receiver.radio.available = false; + if (inactive_reason >= 2) { + profiles.secondary.mode = mesh::RadioProfileMode::RxTx; + profiles.secondary.params.protocol = inactive_reason == 2 + ? mesh::RadioProfileProtocol::Meshtext : mesh::RadioProfileProtocol::Ethernet; + } + if (inactive_reason == 4) { + profiles.secondary.mode = static_cast(3); + profiles.secondary.params.protocol = mesh::RadioProfileProtocol::MeshCore; + } + auto packet = request(prefix, 0, false, true); + receiver.onControlDataRecv(&packet); + const size_t offset = 6 + (prefix ? 8 : PUB_KEY_SIZE); + require(receiver.response.payload_len == offset + 2, + "unavailable/off/foreign radio2 advertised usable MeshCore settings"); + require(receiver.response.payload[offset] == 1 && receiver.response.payload[offset + 1] == 0, + "disabled radio2 did not use the two-byte version/off trailer"); + require(std::memcmp(receiver.response.payload + 6, receiver.self_id.pub_key, + prefix ? 8 : PUB_KEY_SIZE) == 0, + "disabled radio2 trailer overwrote the public key or prefix"); + } + MyMesh exhausted; + exhausted.fail_allocation = true; + auto packet = request(prefix, 0, false, true); + exhausted.onControlDataRecv(&packet); + require(exhausted.create_attempts == 1 && exhausted.sent_packets == 0, + "extended discovery allocation failure attempted transmission"); + } +} static void received() { MyMesh receiver; receiver._prefs.advert_interval = 0; @@ -241,6 +369,8 @@ int main(int argc, char** argv) { if (std::strcmp(argv[1], "policy") == 0) policy(); else if (std::strcmp(argv[1], "gates") == 0) gates(); else if (std::strcmp(argv[1], "wire") == 0) wire(); + else if (std::strcmp(argv[1], "radio2_wire") == 0) radio2_wire(); + else if (std::strcmp(argv[1], "radio2_disabled") == 0) radio2_disabled(); else if (std::strcmp(argv[1], "received") == 0) received(); else return 2; } @@ -256,6 +386,8 @@ class RepeaterDiscoveryTests(unittest.TestCase): source = (ROOT / "examples/simple_repeater/MyMesh.cpp").read_text() header = (ROOT / "examples/simple_repeater/MyMesh.h").read_text() handler = extract_braced(source, "void MyMesh::onControlDataRecv(") + dispatcher = extract_braced((ROOT / "src/Dispatcher.cpp").read_text(), + "uint8_t Dispatcher::getTransmitProfileMask(") hidden = extract_braced(header, "bool isHiddenNode() const") constants = [] for text, name in ( @@ -263,6 +395,8 @@ class RepeaterDiscoveryTests(unittest.TestCase): (source, "CTL_TYPE_NODE_DISCOVER_RESP"), ((ROOT / "src/helpers/AdvertDataHelpers.h").read_text(), "ADV_TYPE_REPEATER"), ((ROOT / "src/MeshCore.h").read_text(), "PUB_KEY_SIZE"), + ((ROOT / "src/Packet.h").read_text(), "PAYLOAD_TYPE_CONTROL"), + ((ROOT / "src/Packet.h").read_text(), "PAYLOAD_TYPE_OTA"), ): constants.append(re.search(rf"^#define {name}\s+[^\n]+", text, re.M).group()) limiter = re.search(r"discover_limiter\(\d+,\s*\d+\)", source).group() @@ -277,6 +411,7 @@ class RepeaterDiscoveryTests(unittest.TestCase): code = (HARNESS.replace("@CONSTANTS@", "\n".join(constants)) .replace("@LIMITER@", limiter) .replace("@HIDDEN@", hidden) + .replace("@DISPATCHER@", dispatcher) .replace("@HANDLER@", body)) work = Path(cls.temporary.name) cpp, binary = work / f"{name}.cpp", work / name @@ -311,6 +446,14 @@ class RepeaterDiscoveryTests(unittest.TestCase): checked = self.run_case("received") self.assertEqual(checked.returncode, 0, checked.stderr) + def test_requested_active_radio2_trailer_bytes_and_legacy_parser(self): + checked = self.run_case("radio2_wire") + self.assertEqual(checked.returncode, 0, checked.stderr) + + def test_unavailable_disabled_and_foreign_profiles_have_only_off_marker(self): + checked = self.run_case("radio2_disabled") + self.assertEqual(checked.returncode, 0, checked.stderr) + def test_removed_hidden_protection_fails_the_same_policy_contract(self): checked = self.run_case("policy", "without_hidden_guard") self.assertEqual(checked.returncode, 1, checked.stderr)