Add opt-in NimBLE Full Companion trials for V4 and XIAO S3

This commit is contained in:
mikecarper committed 2026-09-08 09:30:31 -07:00
1 parent 7ff11a2d64
commit 7f1bd8b1d2
11 files changed
+789 -27

No files matched your search

+7
View File
@@ -0,0 +1,7 @@
#pragma once
#include <stdint.h>
#include <stddef.h>
#include <stdio.h>
#include <string.h>
inline uint32_t test_millis = 100;
inline unsigned long millis() { return test_millis; }
+170
View File
@@ -0,0 +1,170 @@
#pragma once
// Test doubles for the pinned NimBLE-Arduino 2.5.1 API. Firmware builds check
// the real headers/library; this harness injects controller and bonding faults
// into the actual SerialBLEInterface implementation.
#include <stdint.h>
#include <cstring>
#include <string>
#include <vector>
#include <memory>
#include <cassert>
constexpr uint8_t BLE_ADDR_PUBLIC = 0, BLE_ADDR_RANDOM = 1;
constexpr uint8_t BLE_OWN_ADDR_PUBLIC = 0, BLE_OWN_ADDR_RANDOM = 1;
constexpr uint8_t BLE_HS_IO_DISPLAY_ONLY = 0, BLE_HS_ADV_F_BREDR_UNSUP = 4;
struct ble_addr_t { uint8_t type = 0; uint8_t val[6] = {}; };
namespace NIMBLE_PROPERTY {
constexpr uint32_t READ = 1, NOTIFY = 2, READ_AUTHEN = 4, WRITE = 8, WRITE_AUTHEN = 16;
}
struct NimBLEAddress {
ble_addr_t value;
explicit NimBLEAddress(const ble_addr_t& address) : value(address) {}
const ble_addr_t* getBase() const { return &value; }
};
struct NimBLEConnInfo {
ble_addr_t identity = {BLE_ADDR_PUBLIC, {0x8e, 0x6e, 0xf9, 0xeb, 0x27, 0xb8}};
bool encrypted = true, authenticated = true, bonded = true;
uint16_t handle = 7;
bool isEncrypted() const { return encrypted; }
bool isAuthenticated() const { return authenticated; }
bool isBonded() const { return bonded; }
uint16_t getConnHandle() const { return handle; }
NimBLEAddress getIdAddress() const { return NimBLEAddress(identity); }
};
class NimBLEServer;
class NimBLECharacteristic;
struct NimBLEServerCallbacks {
virtual ~NimBLEServerCallbacks() = default;
virtual uint32_t onPassKeyDisplay() { return 0; }
virtual void onAuthenticationComplete(NimBLEConnInfo&) {}
virtual void onConnect(NimBLEServer*, NimBLEConnInfo&) {}
virtual void onDisconnect(NimBLEServer*, NimBLEConnInfo&, int) {}
virtual void onMTUChange(uint16_t, NimBLEConnInfo&) {}
};
struct NimBLECharacteristicCallbacks {
virtual ~NimBLECharacteristicCallbacks() = default;
virtual void onWrite(NimBLECharacteristic*, NimBLEConnInfo&) {}
virtual void onSubscribe(NimBLECharacteristic*, NimBLEConnInfo&, uint16_t) {}
};
struct NimBLEAdvertisementData {
uint8_t flags = 0;
bool setFlags(uint8_t value) { flags = value; return true; }
};
namespace fake_nimble {
inline bool initialized = false, persisted = true, accept_notification = true;
inline std::string failure;
inline std::vector<std::string> calls;
inline uint8_t address[6] = {}, own_type = BLE_OWN_ADDR_PUBLIC, io_cap = 255;
inline ble_addr_t allowlisted;
inline uint16_t mtu = 179;
inline uint32_t pin = 0;
inline bool bonding = false, mitm = false, sc = false;
inline std::vector<std::vector<uint8_t>> transmitted;
inline unsigned disconnects = 0;
}
inline int ble_gap_wl_set(const ble_addr_t* peers, uint8_t count) {
assert(count == 1);
fake_nimble::allowlisted = *peers;
return fake_nimble::failure == "allowlist" ? 1 : 0;
}
struct NimBLEAdvertising {
bool active = false, scan_response = false, scan_filter = false, connect_filter = false;
std::string name, service;
bool start(uint32_t = 0, const NimBLEAddress* = nullptr) {
fake_nimble::calls.push_back("advertise"); active = true; return true;
}
bool stop() { active = false; return true; }
void enableScanResponse(bool value) { scan_response = value; }
void setScanFilter(bool scan, bool connect) { scan_filter = scan; connect_filter = connect; }
bool setAdvertisementData(const NimBLEAdvertisementData&) { name.clear(); service.clear(); return true; }
bool setName(const std::string& value) { name = value; return true; }
bool addServiceUUID(const char* value) { service = value; return true; }
};
struct NimBLECharacteristic {
std::string uuid;
uint32_t properties;
NimBLECharacteristicCallbacks* callbacks = nullptr;
std::vector<uint8_t> value;
NimBLECharacteristic(const char* id, uint32_t props) : uuid(id), properties(props) {}
void setCallbacks(NimBLECharacteristicCallbacks* cb) { callbacks = cb; }
const std::vector<uint8_t> getValue() const { return value; }
void setValue(const uint8_t* data, size_t size) { value.assign(data, data + size); }
bool notify(uint16_t handle = 0xffff) const {
assert(handle == 7);
if (!fake_nimble::accept_notification) return false;
fake_nimble::transmitted.push_back(value);
return true;
}
};
struct NimBLEService {
std::vector<std::unique_ptr<NimBLECharacteristic>> characteristics;
NimBLECharacteristic* createCharacteristic(const char* id, uint32_t props) {
if (fake_nimble::failure == (characteristics.empty() ? "tx" : "rx")) return nullptr;
characteristics.emplace_back(new NimBLECharacteristic(id, props));
return characteristics.back().get();
}
};
struct NimBLEServer {
NimBLEAdvertising advertising;
std::unique_ptr<NimBLEService> service;
NimBLEServerCallbacks* callbacks = nullptr;
bool owns_callbacks = true, auto_advertise = true, connected = false;
~NimBLEServer() { if (owns_callbacks) delete callbacks; }
void setCallbacks(NimBLEServerCallbacks* cb, bool take_ownership = true) {
callbacks = cb; owns_callbacks = take_ownership;
}
void advertiseOnDisconnect(bool value) { auto_advertise = value; }
bool start() { return true; }
uint8_t getConnectedCount() const { return connected; }
uint16_t getPeerMTU(uint16_t) const { return fake_nimble::mtu; }
bool disconnect(uint16_t) const { ++fake_nimble::disconnects; return true; }
NimBLEAdvertising* getAdvertising() { return &advertising; }
NimBLEService* createService(const char*) {
if (fake_nimble::failure == "service") return nullptr;
service.reset(new NimBLEService()); return service.get();
}
};
struct NimBLEDevice {
inline static std::unique_ptr<NimBLEServer> server;
static bool init(const std::string&) {
fake_nimble::calls.push_back("init");
return fake_nimble::initialized = fake_nimble::failure != "init";
}
static bool deinit(bool clear = false) {
fake_nimble::initialized = false;
if (clear) server.reset();
return true;
}
static bool deleteAllBonds() { fake_nimble::calls.push_back("clear-bonds"); return fake_nimble::failure != "clear-bonds"; }
static bool deleteBond(const NimBLEAddress&) { return true; }
static bool isBonded(const NimBLEAddress&) { return fake_nimble::persisted; }
static bool setOwnAddr(const uint8_t* address) {
fake_nimble::calls.push_back("address");
memcpy(fake_nimble::address, address, 6);
return fake_nimble::failure != "address";
}
static bool setOwnAddrType(uint8_t type) {
fake_nimble::calls.push_back("address-type"); fake_nimble::own_type = type;
return fake_nimble::failure != "address-type";
}
static bool setMTU(uint16_t mtu) { fake_nimble::mtu = mtu; return true; }
static void setSecurityPasskey(uint32_t pin) { fake_nimble::pin = pin; }
static void setSecurityIOCap(uint8_t value) { fake_nimble::io_cap = value; }
static void setSecurityAuth(bool bond, bool mitm, bool sc) {
fake_nimble::bonding = bond; fake_nimble::mitm = mitm; fake_nimble::sc = sc;
}
static NimBLEServer* createServer() {
if (fake_nimble::failure == "server") return nullptr;
if (!server) server.reset(new NimBLEServer());
return server.get();
}
};
#define BLEDevice NimBLEDevice
#define BLEServer NimBLEServer
#define BLEService NimBLEService
#define BLECharacteristic NimBLECharacteristic
#define BLEServerCallbacks NimBLEServerCallbacks
#define BLECharacteristicCallbacks NimBLECharacteristicCallbacks
#define BLEAddress NimBLEAddress
#define BLEAdvertising NimBLEAdvertising
#define BLEAdvertisementData NimBLEAdvertisementData
+8
View File
@@ -0,0 +1,8 @@
#pragma once
#include <stdint.h>
#include <string.h>
inline int esp_efuse_mac_get_default(uint8_t* address) {
const uint8_t factory[] = {0x44, 0x1b, 0xf6, 0x69, 0xcf, 0x98};
memcpy(address, factory, sizeof(factory));
return 0;
}
@@ -0,0 +1,4 @@
#pragma once
#include <stdint.h>
using BaseType_t = int;
constexpr BaseType_t pdTRUE = 1;
+31
View File
@@ -0,0 +1,31 @@
#pragma once
#include "FreeRTOS.h"
#include <deque>
#include <vector>
#include <cstring>
struct StaticQueue_t {
size_t capacity = 0, size = 0;
std::deque<std::vector<uint8_t>> frames;
};
using QueueHandle_t = StaticQueue_t*;
inline QueueHandle_t xQueueCreateStatic(size_t capacity, size_t size,
uint8_t*, StaticQueue_t* queue) {
queue->capacity = capacity;
queue->size = size;
queue->frames.clear();
return queue;
}
inline size_t uxQueueMessagesWaiting(QueueHandle_t queue) { return queue->frames.size(); }
inline int xQueueReset(QueueHandle_t queue) { queue->frames.clear(); return pdTRUE; }
inline int xQueueSend(QueueHandle_t queue, const void* value, int) {
if (queue->frames.size() == queue->capacity) return 0;
const auto* bytes = static_cast<const uint8_t*>(value);
queue->frames.emplace_back(bytes, bytes + queue->size);
return pdTRUE;
}
inline int xQueueReceive(QueueHandle_t queue, void* value, int) {
if (queue->frames.empty()) return 0;
memcpy(value, queue->frames.front().data(), queue->size);
queue->frames.pop_front();
return pdTRUE;
}
+192
View File
@@ -0,0 +1,192 @@
#include <helpers/esp32/SerialBLEInterface.h>
#include <algorithm>
#include <array>
#include <cassert>
#include <cstdio>
using mesh::companion::BluetoothPeerIdentity;
using namespace fake_nimble;
static void reset() {
NimBLEDevice::deinit(true);
failure.clear(); calls.clear(); transmitted.clear();
persisted = true; accept_notification = true; disconnects = 0;
test_millis = 100;
}
static void test_identity_modes() {
// The common MAC policy supplies human-order addresses for all four
// custom/random modes. The actual adapter must hand the controller exactly
// those bytes in NimBLE order before any advertisement can start.
const std::array<std::array<uint8_t, 6>, 4> addresses = {{
{{0xc2, 0x12, 0x34, 0x56, 0x78, 0x9a}},
{{0xd3, 0xff, 0x00, 0x7e, 0x01, 0x02}},
{{0xe4, 0x10, 0x20, 0x30, 0x40, 0x50}},
{{0xf5, 0x11, 0x22, 0x33, 0x44, 0x55}},
}};
for (const auto& chosen : addresses) {
reset();
SerialBLEInterface interface;
assert(interface.begin("MeshCore-", "trial", 246810, chosen.data(), true));
assert(own_type == BLE_OWN_ADDR_RANDOM);
for (size_t i = 0; i < 6; ++i) assert(address[i] == chosen[5 - i]);
auto* server = NimBLEDevice::server.get();
assert(!server->owns_callbacks && !server->auto_advertise);
assert(!server->advertising.active);
assert(pin == 246810 && bonding && mitm && sc && io_cap == BLE_HS_IO_DISPLAY_ONLY);
interface.enable();
assert(server->advertising.active);
assert(std::find(calls.begin(), calls.end(), "address-type") <
std::find(calls.begin(), calls.end(), "advertise"));
assert(server->advertising.name == "MeshCore-trial");
assert(server->advertising.service == "6E400001-B5A3-F393-E0A9-E50E24DCCA9E");
assert(server->callbacks->onPassKeyDisplay() == 246810);
assert(interface.takePairingRequest());
assert(!interface.takePairingRequest());
NimBLEDevice::deinit(true); // Must never delete the application interface.
}
reset();
own_type = BLE_OWN_ADDR_RANDOM;
SerialBLEInterface interface;
assert(interface.begin("MeshCore-", "default", 123456));
assert(own_type == BLE_OWN_ADDR_PUBLIC);
assert(std::find(calls.begin(), calls.end(), "address") == calls.end());
NimBLEDevice::deinit(true);
}
static void test_startup_failures() {
const uint8_t custom[] = {0xc2, 0x12, 0x34, 0x56, 0x78, 0x9a};
for (const char* step : {"clear-bonds", "address", "address-type", "server", "service", "tx", "rx"}) {
reset(); failure = step;
SerialBLEInterface interface;
assert(!interface.begin("MeshCore-", "trial", 123456, custom, true));
assert(!initialized && !NimBLEDevice::server);
assert(std::find(calls.begin(), calls.end(), "advertise") == calls.end());
failure.clear();
assert(interface.begin("MeshCore-", "trial", 123456, custom, true));
for (size_t i = 0; i < 6; ++i) assert(address[i] == custom[5 - i]);
NimBLEDevice::deinit(true);
}
reset();
SerialBLEInterface interface;
const uint8_t invalid[] = {0x44, 1, 2, 3, 4, 5};
assert(!interface.begin("MeshCore-", "trial", 123456, invalid));
assert(calls.empty());
}
static void authenticate(SerialBLEInterface& interface, NimBLEConnInfo& info) {
auto* server = NimBLEDevice::server.get();
server->connected = true;
server->callbacks->onConnect(server, info);
server->callbacks->onAuthenticationComplete(info);
uint8_t discarded[MAX_FRAME_SIZE];
interface.checkRecvFrame(discarded);
}
static void test_authentication_and_bond_lifecycle() {
for (unsigned missing = 0; missing < 3; ++missing) {
reset(); SerialBLEInterface interface;
assert(interface.begin("MeshCore-", "trial", 123456));
NimBLEConnInfo info;
if (missing == 0) info.encrypted = false;
if (missing == 1) info.authenticated = false;
if (missing == 2) info.bonded = false;
authenticate(interface, info);
assert(!interface.isConnected() && !interface.takeSuccessfulConnection());
assert(disconnects == 1);
NimBLEDevice::deinit(true);
}
reset(); SerialBLEInterface interface;
assert(interface.begin("MeshCore-", "trial", 123456, nullptr, false, true));
interface.enable();
NimBLEConnInfo info;
// Check an identity address, not a temporary over-the-air private address.
info.identity.type = BLE_ADDR_RANDOM;
info.identity.val[5] = 0xd6;
authenticate(interface, info);
assert(interface.isConnected());
BluetoothPeerIdentity peer;
persisted = false;
assert(!interface.takeSuccessfulConnection(&peer));
persisted = true;
assert(interface.takeSuccessfulConnection(&peer));
assert(peer.type == mesh::companion::BLUETOOTH_PEER_ADDRESS_RANDOM);
for (size_t i = 0; i < 6; ++i) assert(peer.address[i] == info.identity.val[5 - i]);
assert(!interface.takeSuccessfulConnection(&peer));
assert(interface.enableBondedOnlyAdvertising(peer));
assert(allowlisted.type == BLE_ADDR_RANDOM);
assert(memcmp(allowlisted.val, info.identity.val, 6) == 0);
auto* server = NimBLEDevice::server.get();
assert(server->advertising.scan_filter && server->advertising.connect_filter);
assert(!server->advertising.scan_response && server->advertising.name.empty());
assert(interface.isConnected());
NimBLEDevice::deinit(true);
reset(); SerialBLEInterface rebooted;
persisted = false;
assert(rebooted.begin("MeshCore-", "trial", 123456, nullptr, false, false, &peer));
rebooted.enable();
assert(!NimBLEDevice::server->advertising.active);
assert(rebooted.takeBondedOnlyRecovery());
NimBLEDevice::deinit(true);
}
static void test_real_transport_frames() {
reset(); SerialBLEInterface interface;
assert(interface.begin("MeshCore-", "trial", 123456));
interface.enable();
NimBLEConnInfo info;
authenticate(interface, info);
auto* server = NimBLEDevice::server.get();
auto* tx = server->service->characteristics[0].get();
auto* rx = server->service->characteristics[1].get();
assert(tx->properties & NIMBLE_PROPERTY::READ_AUTHEN);
assert(rx->properties & NIMBLE_PROPERTY::WRITE_AUTHEN);
uint8_t frame[MAX_FRAME_SIZE];
for (size_t i = 0; i < sizeof(frame); ++i) frame[i] = i;
frame[0] = 0x0d;
uint8_t received[MAX_FRAME_SIZE] = {};
assert(interface.writeFrame(frame, sizeof(frame)) == sizeof(frame));
interface.checkRecvFrame(received);
assert(transmitted.empty()); // Subscription is still pending.
tx->callbacks->onSubscribe(tx, info, 1);
mtu = 23;
interface.checkRecvFrame(received);
assert(transmitted.empty()); // Never truncate a full protocol frame.
mtu = 179;
accept_notification = false;
interface.checkRecvFrame(received);
assert(interface.hasPendingIO() && transmitted.empty());
test_millis += 61;
accept_notification = true;
interface.checkRecvFrame(received);
assert(transmitted.size() == 1 && transmitted[0].size() == sizeof(frame));
assert(memcmp(transmitted[0].data(), frame, sizeof(frame)) == 0);
test_millis += 61;
interface.checkRecvFrame(received);
assert(transmitted.size() == 1); // No late-status duplicate.
rx->setValue(frame, sizeof(frame));
info.authenticated = false;
rx->callbacks->onWrite(rx, info);
assert(interface.checkRecvFrame(received) == 0);
info.authenticated = true;
rx->callbacks->onWrite(rx, info);
assert(interface.checkRecvFrame(received) == sizeof(frame));
assert(memcmp(frame, received, sizeof(frame)) == 0);
uint8_t oversized[MAX_FRAME_SIZE + 1] = {};
rx->setValue(oversized, sizeof(oversized));
rx->callbacks->onWrite(rx, info);
assert(interface.checkRecvFrame(received) == 0);
NimBLEDevice::deinit(true);
}
int main() {
test_identity_modes();
test_startup_failures();
test_authentication_and_bond_lifecycle();
test_real_transport_frames();
puts("NimBLE adapter: identity, faults, bonding, stealth and full frames PASS");
}
+30
View File
@@ -0,0 +1,30 @@
#!/usr/bin/env python3
"""Exercise the real ESP32 Companion adapter against the NimBLE 2.5 API."""
from pathlib import Path
import subprocess
import tempfile
import unittest
ROOT = Path(__file__).resolve().parents[1]
class NimbleCompanionTests(unittest.TestCase):
def test_identity_security_and_data_path_under_sanitizers(self):
with tempfile.TemporaryDirectory(prefix="meshcore-nimble-") as temp:
binary = Path(temp) / "nimble-companion"
result = subprocess.run([
"c++", "-std=c++17", "-g", "-fsanitize=address,undefined",
"-DMESH_USE_NIMBLE_ARDUINO=1",
"-I", str(ROOT / "test/fixtures/nimble_companion/mocks"),
"-I", str(ROOT / "src"),
str(ROOT / "src/helpers/esp32/SerialBLEInterface.cpp"),
str(ROOT / "test/fixtures/nimble_companion/test_nimble_companion.cpp"),
"-o", str(binary),
], text=True, capture_output=True)
self.assertEqual(result.returncode, 0, result.stderr)
result = subprocess.run([str(binary)], text=True, capture_output=True)
self.assertEqual(result.returncode, 0, result.stderr)
if __name__ == "__main__":
unittest.main()