OXRecorder::OXWirelessManager

Overview

OXWirelessManager owns the device's two radios — and nothing else. It is the transport layer: it brings the chips up, tracks their connection state, moves raw bytes in and out, and counts the traffic. It deliberately knows nothing about REST routes, command protocols, or business logic — that all lives one layer up in OXAPIManager. Splitting the two keeps hardware control and protocol logic from tangling together.

• Wi-Fi chip. Bring it up as an access point or join a router (startWifi/stopWifi), set credentials and mode, report the IP. The HTTP server runs here; each inbound request is forwarded to the registered consumer.
• Bluetooth chip. Advertise over BLE (startBluetooth), track whether a phone is connected, push notifications out (notify), and forward each inbound write to the registered consumer.
• Inbound consumer seam. A single consumer per channel registered with setHttpRequestHandler / setBtMessageHandler receives every inbound item. Normally that consumer is OXAPIManager, attached in its begin().
• Traffic statistics. Every application byte in and out of both radios is counted (see stats()).

Like the other OX managers it is cooperative and host-testable: the radios are injected behind IWifiDevice / IBluetoothDevice (real ESP32 backends on-device, fakes in tests), and poll() is pumped from loop().

Shared value types in include/OXWirelessTypes.h; the transport manager in include/OXWirelessManager.h / src/OXWirelessManager.cpp; the Wi-Fi backend in src/wifi/EspWifiDevice.cpp and the BLE backend (NimBLE) in src/bluetooth/EspBluetoothDevice.cpp.

WirelessConfig

Everything begin() needs. The auto-start flags let the device come up advertising over Bluetooth (the usual provisioning entry point) while Wi-Fi waits until credentials arrive.

WifiConfig

BluetoothConfig

These value types — along with WifiRequest, WifiResponse, BluetoothMessage, BluetoothReply, and the transport interfaces — live in include/OXWirelessTypes.h, shared by the transport and the API layer so neither header depends on the other.

API reference

Wi-Fi control

Bluetooth control

Inbound consumer seam

Statistics

Device injection

Examples

1. Bring up the radios; let OXAPIManager own the protocol

OXWirelessManager manages the chips; OXAPIManager attaches to it and owns the routes/commands. See the OXAPIManager reference for the handler side.

#include <Arduino.h>
#include "OXWirelessManager.h"
#include "OXAPIManager.h"

using namespace OXRecorder;

OXWirelessManager wireless;   // the radios (transport)
OXAPIManager      api;        // routes, commands, outbound client

void setup() {
  WirelessConfig cfg;                       // BT auto-starts; Wi-Fi waits
  strcpy(cfg.bluetooth.pairingName, "OX-Recorder-01");
  wireless.begin(cfg);
  api.begin(wireless);                    // wire API onto the transport
}

void loop() {
  wireless.poll();   // pump radios -> forwards inbound items to api
  api.poll();        // (reserved for future async work)
  delay(5);
}

2. Join a Wi-Fi network (Station mode) and fetch a page to the SD card

The defaults host an open access point; to reach the internet instead, put the radio in Station mode, hand it an SSID + password, and bring it up. Once isWifiUp() reports the join succeeded, the outbound HTTP client on OXAPIManager can call a remote server. Here we pull https://www.google.com and stream the response onto the SD card via OXFileManager.

#include <Arduino.h>
#include "OXWirelessManager.h"
#include "OXAPIManager.h"
#include "OXFileManager.h"

using namespace OXRecorder;

OXWirelessManager wireless;
OXAPIManager      api;
OXFileManager     files;

void setup() {
  wireless.begin();          // Wi-Fi waits; no auto-start
  api.begin(wireless);        // outbound HTTP client lives here
  files.beginExternal();      // mount the SD card (default validated wiring)

  // --- Point the radio at your router and join it -------------------
  wireless.setWifiMode(WifiMode::Station);
  wireless.setWifiCredentials("MyHomeNetwork", "sup3r-secret-pw");
  if (!wireless.startWifi()) {
    OXLog::error("Wi-Fi failed to start");
    return;
  }

  // Joining a router is asynchronous — poll until the link is up.
  for (int i = 0; i < 100 && !wireless.isWifiUp(); ++i) {
    wireless.poll();
    delay(100);                // ~10s budget to associate + get a DHCP lease
  }
  if (!wireless.isWifiUp()) {
    OXLog::error("Wi-Fi did not connect");
    return;
  }
  OXLog::info("connected, ip=%s", wireless.wifiIp());

  // --- Fetch the page; copy each buffer-full straight to the SD -----
  uint8_t buf[4096];
  HttpClientResult r = api.get("https://www.google.com", buf, sizeof(buf));
  if (!r.ok()) {
    OXLog::error("GET failed: status=%d", r.statusCode);  // negative = kHttpErr*
    return;
  }

  if (files.writeFile(Storage::External, "/google.html", buf, r.bodyLen)) {
    OXLog::info("saved %u bytes to /google.html%s", (unsigned)r.bodyLen,
                r.truncated ? " (truncated to buffer)" : "");
  } else {
    OXLog::error("SD write failed (card mounted?)");
  }
}

void loop() {
  wireless.poll();
  api.poll();
  delay(5);
}

3. Download a file larger than 4 KB (stream straight to the SD card)

A buffered get() reads the whole response into the buffer you hand it — so a big file would need a buffer as large as the file, which is impossible when the size is unknown and risky under TLS heap pressure. Use OXAPIManager::download() instead: it drains the response body off the socket in fixed-size chunks and hands each to a sink callback, so the body is never held in RAM. The sink writes every chunk to the SD card, so RAM stays flat no matter how big the download is.

• Small scratch buffer, off the stack. download() reads each socket chunk into the scratch buffer you pass; its size just sets the chunk granularity (4 KB is plenty). Make it static so it lives in .bss, not on loopTask's 8 KB stack.
• Open the SD file once, write through the open stream. Use an OXFileStream opened before the download, and write each chunk to it. Do not call the one-shot appendFile() per chunk — see the warning below.
• The sink writes each chunk. It runs once per chunk, in order; return true to keep receiving, or false to abort early (e.g. when a disk write fails). The data pointer is valid only for that call, so write it out before returning.

// Sink context: the open SD stream + a running total / failure flag.
struct SdSink {
  OXFileStream *file = nullptr;
  size_t total = 0;
  bool   failed = false;
};

// Called once per chunk as it arrives — write it to the already-open file.
static bool writeChunkToSd(const uint8_t *data, size_t len, void *ctx) {
  auto *s = static_cast<SdSink *>(ctx);
  if (s->file->write(data, len) != len) {
    s->failed = true;
    return false;   // stop the download: the link is fine, the disk isn't
  }
  s->total += len;
  // Commit periodically (~every 64 KB), NOT every chunk — see warning below.
  if ((s->total & 0xFFFF) < len) s->file->flush();
  return true;      // keep receiving
}

// ... in setup()/a task, with Wi-Fi already up: ...
const char *url  = "https://example.com/firmware/clip.bin";
const char *path = "/clip.bin";
static uint8_t scratch[4096];   // static => .bss; sets the chunk size

// Open the destination ONCE (false = truncate any existing file).
OXFileStream out = files.openWrite(Storage::External, path, /*append=*/false);
if (!out.isOpen()) {
  OXLog::error("could not open %s for writing (card mounted?)", path);
  return;
}

SdSink sink;
sink.file = &out;
HttpClientResult r = api.download(HttpMethod::Get, url, scratch,
                                  sizeof(scratch), writeChunkToSd, &sink);

out.flush();   // commit the tail
out.close();   // release the file handle

if (sink.failed) {
  OXLog::error("SD write failed after %u bytes", (unsigned)sink.total);
} else if (r.statusCode < 0) {
  OXLog::error("download failed: %d", r.statusCode);   // kHttpErr* (link/TLS/...)
} else if (!r.ok()) {
  OXLog::error("server returned HTTP %d", r.statusCode);
} else {
  OXLog::info("downloaded %u bytes to %s", (unsigned)sink.total, path);
}

4. Reading traffic statistics

const WirelessStats &s = wireless.stats();
OXLog::info("wifi rx=%u tx=%u | bt rx=%u tx=%u",
            s.wifiRxBytes, s.wifiTxBytes, s.btRxBytes, s.btTxBytes);
OXLog::info("total in=%u out=%u", s.totalRxBytes(), s.totalTxBytes());

5. Pushing a status update to the phone

if (wireless.isBluetoothConnected()) {
  wireless.notify("{\"event\":\"recording_started\"}");
}

6. Bring up Bluetooth and Wi-Fi at the same time

The two radios are independent — nothing stops you running both at once. The simplest way is to pre-fill a WirelessConfig with Station-mode credentials and flip both auto-start flags, so begin() advertises over BLE and joins the router in one call. (The usual flow leaves autoStartWifi off and waits for credentials to arrive over Bluetooth — see the note below — but when you already know the SSID this is the most direct path.)

#include <Arduino.h>
#include "OXWirelessManager.h"
#include "OXAPIManager.h"

using namespace OXRecorder;

OXWirelessManager wireless;
OXAPIManager      api;

void setup() {
  WirelessConfig cfg;

  // Bluetooth: advertise under this name (auto-starts by default).
  strcpy(cfg.bluetooth.pairingName, "OX-Recorder-01");

  // Wi-Fi: join an existing router instead of hosting an AP.
  cfg.wifi.mode = WifiMode::Station;
  strcpy(cfg.wifi.ssid, "MyHomeNetwork");
  strcpy(cfg.wifi.password, "sup3r-secret-pw");

  // Turn BOTH radios on during begin().
  cfg.autoStartBluetooth = true;   // (already the default)
  cfg.autoStartWifi      = true;

  if (!wireless.begin(cfg)) {
    // begin() returns false if a requested auto-start had no transport;
    // the radio that did come up is still usable.
    OXLog::warn("bt up=%d  wifi up=%d",
                wireless.isBluetoothUp(), wireless.isWifiUp());
  }
  api.begin(wireless);   // one protocol layer serves both channels

  OXLog::info("bt advertising=%d  wifi ip=%s",
              wireless.isBluetoothUp(), wireless.wifiIp());
}

void loop() {
  wireless.poll();   // pumps BOTH radios -> dispatches into api
  api.poll();
  delay(5);
}

Prefer to stage it instead? Bring Bluetooth up first and add Wi-Fi later with the same effect — handy when credentials arrive at runtime:

WirelessConfig cfg;
strcpy(cfg.bluetooth.pairingName, "OX-Recorder-01");
wireless.begin(cfg);                 // BT advertising; Wi-Fi idle

// ...later, once you have the SSID/password...
wireless.setWifiMode(WifiMode::Station);
wireless.setWifiCredentials("MyHomeNetwork", "sup3r-secret-pw");
wireless.startWifi();                  // now both radios are live

Notes

• Pump regularly. Both radios are serviced from poll(); keep loop() non-blocking so requests and commands are handled promptly.
• One consumer per channel. The HTTP and Bluetooth seams each hold a single handler. OXAPIManager::begin() registers itself on both; if you attach your own, you replace it.
• Provisioning flow. The device boots advertising over Bluetooth (no Wi-Fi yet). The phone sends a saveconfig command; the OXAPIManager handler calls wireless.setWifiCredentials() + startWifi(). From then on the REST API is reachable.
• Byte counts are application payload. Request/response bodies, command messages, and replies — not TCP/HTTP/BLE framing.