GHOSTWAVES

00. What This Is

GHOSTWAVES is a thin C++ library that lets you send and receive raw 802.11 frames on ESP32, bypassing the standard Wi-Fi stack. Instead of connecting to a router, authenticating, getting an IP, and going through TCP/IP, you construct a frame in memory and hand it directly to the radio hardware via esp_wifi_80211_tx().

The tradeoff is straightforward: you skip all the overhead (faster, simpler, no infrastructure needed), but you also lose everything that overhead provides (encryption, reliability, delivery guarantees, error correction). This is useful for specific scenarios where speed and simplicity matter more than reliability.

01. Architecture

GHOSTWAVES is a C++ library for the Arduino-ESP32 ecosystem. It uses esp_wifi_80211_tx() for frame injection and promiscuous mode for reception. The library handles frame construction, OUI filtering, and thread-safe queuing between the Wi-Fi task and your application loop. Developed by OPT-OUT.

02. The Frame

GHOSTWAVES uses Vendor-Specific Action Frames — a legitimate 802.11 management frame type (subtype 0x0D, frame control 0x00D0). Category 0x7F marks the body as vendor-specific, followed by a 3-byte OUI that acts as a namespace. Our OUI is 0xBE 0xEF 0x00 — the magic bytes.

03. Channels & Frequencies

When you call GhostWaves.begin(6), you select Wi-Fi Channel 6. The ESP32 is a Wi-Fi chip, not a software-defined radio — you pick a channel number, and the hardware maps it to a fixed center frequency defined by the 802.11 standard. All nodes must be on the same channel to communicate.

Live Channel Switch

// Start on channel 6
GhostWaves.begin(6);

// Later: scan for the quietest channel
uint8_t best = GhostWaves.scanQuietestChannel(100);  // 100ms dwell per channel
Serial.printf("Quietest channel: %d\n", best);

// Retune instantly — no restart needed
GhostWaves.setChannel(best);

// Check where we are
Serial.printf("Now on channel %d\n", GhostWaves.getChannel());

Coordinated Migration

A Leader node scans, picks the best channel, broadcasts a HOP command, then switches itself. Followers listen for the HOP command and follow. See the GhostHop example for the full implementation.

// Leader: broadcast HOP command, then switch
#define GHOST_TYPE_HOP 0xF0

struct __attribute__((packed)) HopCommand {
  uint8_t new_channel;
  uint8_t reason;
};

HopCommand cmd = { .new_channel = best, .reason = 0 };
GhostWaves.send(broadcast, (const uint8_t*)&cmd, sizeof(cmd), GHOST_TYPE_HOP);
delay(20);
GhostWaves.setChannel(best);

// Follower: listen and follow
if (pkt.oui_type == GHOST_TYPE_HOP) {
  HopCommand* cmd = (HopCommand*)pkt.payload;
  GhostWaves.setChannel(cmd->new_channel);
}

04. API Reference

GHOSTWAVES exposes a singleton GhostWaves (like Serial or Wire) with a minimal, deliberate API.

GhostRxPacket Structure

05. Custom Frame Types

The oui_type byte is your protocol multiplexer. Define 0x01 as a heartbeat, 0x02 as sensor data, 0x20 as chat, 0x30 as relay — whatever your application needs. On receive, GhostRxPacket.oui_type tells you exactly what kind of frame arrived.

// Define your protocol
#define GHOST_TYPE_PING    0x01
#define GHOST_TYPE_SENSOR  0x02
#define GHOST_TYPE_CMD     0x03
#define GHOST_TYPE_CHAT    0x20
#define GHOST_TYPE_RELAY   0x30

// Send with a specific type
GhostWaves.send(dest, payload, len, GHOST_TYPE_SENSOR);

// Receive and dispatch
GhostRxPacket pkt;
if (GhostWaves.read(&pkt)) {
  switch (pkt.oui_type) {
    case GHOST_TYPE_PING:   handlePing(pkt);   break;
    case GHOST_TYPE_SENSOR: handleSensor(pkt); break;
    case GHOST_TYPE_CMD:    handleCmd(pkt);    break;
  }
}

Assigned Types

06. Limitations

Bypassing the Wi-Fi stack means giving up everything it provides. These are real tradeoffs, not edge cases. Understand them before choosing GHOSTWAVES over established protocols.

07. Ghostwaves vs ESP-NOW

ESP-NOW is a mature, Espressif-maintained protocol that handles encryption, retries, and peer management for you. For most ESP32-to-ESP32 communication, ESP-NOW is the better choice. GHOSTWAVES only makes sense when you specifically need something ESP-NOW can't do.

08. Examples

#include <GhostWaves.h>

#define GHOST_TYPE_PING    0x01
#define GHOST_TYPE_SENSOR  0x02

const uint8_t broadcast[6] = {0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF};
unsigned long lastPing = 0;

void setup() {
  Serial.begin(115200);
  GhostWaves.begin(6);
  Serial.println("GhostPing active on Channel 6.");
}

void loop() {
  // Broadcast a ping every 2 seconds
  if (millis() - lastPing > 2000) {
    lastPing = millis();
    const char* msg = "alive";
    GhostWaves.send(broadcast, (const uint8_t*)msg, strlen(msg), GHOST_TYPE_PING);
  }

  // Receive and dispatch by type
  if (GhostWaves.available()) {
    GhostRxPacket pkt;
    if (GhostWaves.read(&pkt)) {
      switch (pkt.oui_type) {
        case GHOST_TYPE_PING:
          Serial.printf("[PING] from %02X:%02X RSSI:%d\n",
            pkt.sender_mac[4], pkt.sender_mac[5], pkt.rssi);
          break;
        case GHOST_TYPE_SENSOR:
          Serial.printf("[SENSOR] %d bytes\n", pkt.length);
          break;
      }
    }
  }
}

#include <GhostWaves.h>

#define GHOST_TYPE_SENSOR  0x02
#define SLEEP_SECONDS      30

struct __attribute__((packed)) SensorPayload {
  uint8_t  node_id;
  float    temperature;
  float    humidity;
  float    battery_voltage;
};

const uint8_t broadcast[6] = {0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF};

void setup() {
  GhostWaves.begin(6);

  SensorPayload data = {
    .node_id = 1,
    .temperature = 23.5,
    .humidity = 61.2,
    .battery_voltage = 3.1
  };

  // One shot. No handshake. No ACK needed.
  GhostWaves.send(broadcast, (const uint8_t*)&data, sizeof(data), GHOST_TYPE_SENSOR);
  delay(10);

  GhostWaves.end();
  esp_deep_sleep(SLEEP_SECONDS * 1000000ULL);
}

void loop() {
  // Never reaches here.
}

#include <GhostWaves.h>

#define GHOST_TYPE_SWARM   0x10
#define MAX_PEERS          20

struct __attribute__((packed)) SwarmBeacon {
  uint8_t node_id;
  float   pos_x;
  float   pos_y;
  uint8_t state;    // 0=idle, 1=moving, 2=seeking
};

struct Peer {
  uint8_t  node_id;
  float    pos_x, pos_y;
  int8_t   rssi;
  unsigned long last_seen;
  bool     active;
};

Peer peers[MAX_PEERS];
const uint8_t broadcast[6] = {0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF};

void setup() {
  Serial.begin(115200);
  GhostWaves.begin(6);
  memset(peers, 0, sizeof(peers));
}

void loop() {
  // Broadcast our position every 500ms
  static unsigned long lastTx = 0;
  if (millis() - lastTx > 500) {
    lastTx = millis();
    SwarmBeacon b = { .node_id = 42, .pos_x = 1.5, .pos_y = -3.2, .state = 0 };
    GhostWaves.send(broadcast, (const uint8_t*)&b, sizeof(b), GHOST_TYPE_SWARM);
  }

  // Receive peer beacons and update table
  if (GhostWaves.available()) {
    GhostRxPacket pkt;
    if (GhostWaves.read(&pkt) && pkt.oui_type == GHOST_TYPE_SWARM) {
      SwarmBeacon* b = (SwarmBeacon*)pkt.payload;
      // Update peer table...
    }
  }
}

#include <GhostWaves.h>

#define GHOST_TYPE_CHAT 0x20

struct __attribute__((packed)) ChatMessage {
  char nick[8];
  char text[200];
};

const uint8_t broadcast[6] = {0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF};

void loop() {
  // Read serial input, pack into ChatMessage, send:
  //   GhostWaves.send(broadcast, (uint8_t*)&msg, len, GHOST_TYPE_CHAT);

  // Receive and print:
  if (GhostWaves.available()) {
    GhostRxPacket pkt;
    if (GhostWaves.read(&pkt) && pkt.oui_type == GHOST_TYPE_CHAT) {
      ChatMessage* msg = (ChatMessage*)pkt.payload;
      Serial.printf("[%s] %s\n", msg->nick, msg->text);
    }
  }
}

#include <GhostWaves.h>

#define GHOST_TYPE_RELAY 0x30
#define MAX_TTL          5

struct __attribute__((packed)) RelayFrame {
  uint16_t msg_id;
  uint8_t  origin_mac[6];
  uint8_t  ttl;
  uint8_t  hop_count;
  char     payload[180];
};

// On receive: check if already seen (ring buffer), print, decrement TTL, rebroadcast.
// Messages ripple outward like waves on water.
// Each node is both receiver and transmitter.
// The network has no center.

#include <GhostWaves.h>

#define GHOST_TYPE_HOP  0xF0
#define HOP_INTERVAL    30000   // Scan every 30s

struct __attribute__((packed)) HopCommand {
  uint8_t new_channel;
  uint8_t reason;
};

void loop() {
  // LEADER: periodic scan and migrate
  if (millis() - lastHop > HOP_INTERVAL) {
    lastHop = millis();
    uint8_t best = GhostWaves.scanQuietestChannel(100);

    if (best != GhostWaves.getChannel()) {
      // Broadcast HOP command 3x for reliability
      HopCommand cmd = { .new_channel = best, .reason = 0 };
      for (int i = 0; i < 3; i++) {
        GhostWaves.send(broadcast, (const uint8_t*)&cmd, sizeof(cmd), GHOST_TYPE_HOP);
        delay(5);
      }
      delay(20);
      GhostWaves.setChannel(best);
    }
  }

  // FOLLOWER: listen for HOP commands and follow
  if (GhostWaves.available()) {
    GhostRxPacket pkt;
    if (GhostWaves.read(&pkt) && pkt.oui_type == GHOST_TYPE_HOP) {
      HopCommand* cmd = (HopCommand*)pkt.payload;
      GhostWaves.setChannel(cmd->new_channel);
    }
  }
}

09. Use Cases & Roadmap

Where It Makes Sense

GHOSTWAVES is suited for scenarios where the Wi-Fi connection overhead is the bottleneck, where you need broadcast to many receivers, or where you want to define your own protocol. It's not suited for anything requiring reliability, security, or interoperability with non-ESP32 devices (without custom tooling).

Roadmap

These are features that would address the current limitations. Some are straightforward, others are significant engineering efforts. No timeline — contributions welcome.