promisc.h File Reference

Wi-Fi promiscuous (monitor) capture (PROTOCORE_ENABLE_PROMISC) - passive 802.11 sniffing. More...

#include "protocore_config.h"

Go to the source code of this file.

Classes
struct	WifiFrameInfo
	Decoded 802.11 MAC header. src / dst / bssid point into the frame (6 bytes) or null. More...
struct	PromiscNs
	Dispatch table. Addressed by offset, so the layout is asserted below. More...

Typedefs
typedef enum PROTO_ENUM_PACKED	WifiFrameType
	802.11 frame type (frame-control bits 2-3).
typedef void(*	protocore_promisc_sink_fn) (const uint8_t *frame, uint16_t len, int8_t rssi, uint8_t channel)
	Sink for one captured frame: the raw 802.11 bytes plus radio metadata.

Enumerations
enum	PROTO_ENUM_PACKED { WIFI_FT_MGMT = 0 , WIFI_FT_CTRL = 1 , WIFI_FT_DATA = 2 , WIFI_FT_EXT = 3 }
	802.11 frame type (frame-control bits 2-3). More...

Functions
	PROTOCORE_NS_LAYOUT (PromiscNs, wifi_frame_parse, begin, set_channel, end)
proto_bool	protocore_promisc_wifi_frame_parse (uint8_t *work, const uint8_t *frame, uint16_t len, WifiFrameInfo *out)
	Parse an 802.11 MAC header (IEEE 802.11 §9.2 / §9.3.2, the .
proto_bool	protocore_promisc_begin (uint8_t *work, uint8_t channel, protocore_promisc_sink_fn sink)
	Start promiscuous capture on channel; every frame is delivered to .
void	protocore_promisc_set_channel (uint8_t *work, uint8_t channel)
	Retune the capture to a different channel (1..14).
void	protocore_promisc_end (uint8_t *work)
	Stop promiscuous capture.
uint8_t *	protocore_promisc_span (void)
	The PROTOCORE_PROMISC_BORROW bytes this module's state lives in.

Variables
PROTOCORE_NS PromiscNs Promisc	PROTOCORE_UNUSED
	Module namespace.

Detailed Description

Wi-Fi promiscuous (monitor) capture (PROTOCORE_ENABLE_PROMISC) - passive 802.11 sniffing.

A read-only capture path: instead of joining a network and terminating traffic, listen to every 802.11 frame on a channel and hand it to a sink. The canonical wiring feeds the sink into the forwarding plane (network_drivers/network/forward), so captured Wi-Fi frames are bridged to another interface (e.g. Ethernet) for a wired collector - "capture on Wi-Fi, forward to Ethernet".

Two host-testable pieces plus the ESP32 radio binding:

• wifi_frame_parse(): decode the 802.11 MAC header (type/subtype, the to/from-DS address layout -> src / dst / bssid, sequence number, header length). Pure.
• pcap_* : build the classic libpcap global + per-record headers (DLT_IEEE802_11) so a forwarded frame is a valid PCAP stream a wired Wireshark / tcpdump can read. Pure.
• protocore_promisc_begin() / _set_channel() / _end(): monitor-mode bring-up whose rx callback copies each frame (with RSSI + channel) to the registered sink. ESP32 only.

Capture is strictly passive (no injection) and fail-closed: the sink is expected to drop, not block, when its downstream is full, so the live data path is never stalled.

work is PROTOCORE_PROMISC_BORROW bytes the CALLER took, at an address it knows. It is not held past the call, so nothing here aliases it. How those bytes are carved is this module's and is never named here.

Author

Douglas Quigg (dstroy0)

Date

2026

Definition in file promisc.h.

Typedef Documentation

WifiFrameType

typedef enum PROTO_ENUM_PACKED WifiFrameType

802.11 frame type (frame-control bits 2-3).

protocore_promisc_sink_fn

typedef void(* protocore_promisc_sink_fn)(const uint8_t *frame, uint16_t len, int8_t rssi, uint8_t channel)

Sink for one captured frame: the raw 802.11 bytes plus radio metadata.

Parameters

frame	the 802.11 MAC frame (points into the driver buffer; copy if retained).
len	frame length in bytes.
rssi	received signal strength (dBm).
channel	the channel it was captured on.

Definition at line 70 of file promisc.h.

Enumeration Type Documentation

PROTO_ENUM_PACKED

enum PROTO_ENUM_PACKED

802.11 frame type (frame-control bits 2-3).

Enumerator
WIFI_FT_MGMT
WIFI_FT_CTRL
WIFI_FT_DATA
WIFI_FT_EXT

Definition at line 39 of file promisc.h.

Function Documentation

PROTOCORE_NS_LAYOUT()

PROTOCORE_NS_LAYOUT	(	PromiscNs	,
		wifi_frame_parse	,
		begin	,
		set_channel	,
		end
	)

protocore_promisc_wifi_frame_parse()

proto_bool protocore_promisc_wifi_frame_parse	(	uint8_t *	work,
		const uint8_t *	frame,
		uint16_t	len,
		WifiFrameInfo *	out
	)

Parse an 802.11 MAC header (IEEE 802.11 §9.2 / §9.3.2, the .

Parameters

work	PROTOCORE_PROMISC_BORROW bytes the caller took. Not held past the call.
frame	Frame
len	Len
out	Out

Returns

PROTO_TRUE on success.

protocore_promisc_begin()

proto_bool protocore_promisc_begin	(	uint8_t *	work,
		uint8_t	channel,
		protocore_promisc_sink_fn	sink
	)

Start promiscuous capture on channel; every frame is delivered to .

Parameters

work	PROTOCORE_PROMISC_BORROW bytes the caller took. Not held past the call.
channel	Channel
sink	Sink

Returns

PROTO_TRUE on success.

protocore_promisc_set_channel()

void protocore_promisc_set_channel	(	uint8_t *	work,
		uint8_t	channel
	)

Retune the capture to a different channel (1..14).

Parameters

work	PROTOCORE_PROMISC_BORROW bytes the caller took. Not held past the call.
channel	Channel

protocore_promisc_end()

void protocore_promisc_end

(

uint8_t *

work

)

Stop promiscuous capture.

Parameters

work	PROTOCORE_PROMISC_BORROW bytes the caller took. Not held past the call.

protocore_promisc_span()

uint8_t * protocore_promisc_span

(

void

)

The PROTOCORE_PROMISC_BORROW bytes this module's state lives in.

Stated beside the namespace rather than on it: an entry takes a borrow, and this is where that borrow comes from. Taken once from the end of the pool, which no mark and no release walks, so the state lasts the life of the program.

Returns

the span.

Variable Documentation

PROTOCORE_UNUSED

PROTOCORE_NS PromiscNs Promisc PROTOCORE_UNUSED

Initial value:

= {.wifi_frame_parse = protocore_promisc_wifi_frame_parse,
                                                   .begin = protocore_promisc_begin,
                                                   .set_channel = protocore_promisc_set_channel,
                                                   .end = protocore_promisc_end}

Module namespace.

Definition at line 131 of file promisc.h.