Layer 1 (Physical) - link bring-up and live egress-interface reporting. More...

#include "board_drivers/board_profiles/pc_platform.h"
#include "network_drivers/network/ip.h"
#include "protocore_config.h"
#include <stddef.h>
#include <stdint.h>

Macros
#define	PC_PHYSICAL_HAS_BACKEND 0

Typedefs
typedef void(*	pc_phy_frame_fn) (const uint8_t *frame, uint16_t len, int8_t rssi, uint8_t channel)
	One received frame, delivered in neutral terms.

Enumerations
enum class	pc_phy_ps : uint8_t { PC_PHY_PS_NONE = 0 , PC_PHY_PS_MIN_MODEM = 1 , PC_PHY_PS_MAX_MODEM = 2 }
	Radio power-save mode, in the library's own vocabulary. More...

Functions
bool	init_wifi_physical (const char ssid, const char password)
	Connect to a WiFi access point.

bool	wifi_ready ()
	True if the WiFi station link is up (associated + an IP is assigned).

bool	init_wifi_radio_physical (uint8_t channel)
	Bring the WiFi radio up in station mode WITHOUT associating to an AP.

bool	init_wifi_ap_physical (const char ssid, const char password)
	Bring up a softAP, enabling AP+STA coexistence so a station link can run alongside it.

bool	init_eth_physical (void)
	Bring up a wired Ethernet link (PC_ENABLE_ETHERNET).

bool	eth_ready (void)
	True if the Ethernet link is up and an IP is assigned.

bool	init_ipv6_physical (void)
	Enable IPv6 (dual-stack) on the Wi-Fi interface (PC_ENABLE_IPV6).

bool	net_global_ipv6 (pc_ip *out)
	The interface's global (routable) IPv6 address, if it has one.

bool	pc_ipv6_ready (void)
	True once the interface has a global IPv6 address (see net_global_ipv6()).

pc_iface	pc_net_egress (void)
	Which interface currently carries outbound traffic.

uint32_t	pc_net_egress_ip (void)
	IPv4 (network byte order) of the current egress interface, or 0 if none.

uint32_t	pc_net_ap_ip (void)
	softAP IPv4 (network byte order), or 0 if the softAP is not up (and on host builds).

int8_t	pc_net_rssi (void)
	Station link RSSI in dBm, or 0 if not associated (and on host builds).

bool	pc_net_mac (uint8_t out[6])
	Copy the WiFi station interface MAC (6 bytes) into `out`.

bool	pc_net_egress_mac (uint8_t out[6])
	Copy the MAC of the current egress interface (the live default-route netif) into `out`.

size_t	pc_net_ssid (char *out, size_t cap)
	Copy the associated SSID (null-terminated) into `out`.

uint8_t	pc_net_channel (void)
	Station WiFi channel (1..14), or 0 if not associated (and on host builds).

pc_iface	pc_net_classify_ip (uint32_t egress_ip, uint32_t sta_ip, uint32_t ap_ip)
	Classify an egress IPv4 against the WiFi station / softAP IPs (pure helper, exposed for unit testing).

bool	pc_phy_ps_set (pc_phy_ps mode)
	Apply a power-save mode.

pc_phy_ps	pc_phy_ps_get (void)
	Read the active power-save mode (PC_PHY_PS_NONE when unsupported).

bool	pc_phy_tx_power_set (int8_t dbm)
	Cap transmit power.

bool	pc_phy_monitor_begin (uint8_t channel, pc_phy_frame_fn cb)
	Enter monitor mode on `channel`, delivering frames to `cb`.

void	pc_phy_monitor_set_channel (uint8_t channel)
	Retune monitor mode to `channel`.

void	pc_phy_monitor_end (void)
	Leave monitor mode.

Detailed Description

Layer 1 (Physical) - link bring-up and live egress-interface reporting.

The "physical" link is the 802.11 radio or a wired Ethernet PHY, brought up by the vendor backend selected with PC_VENDOR_* (board_drivers/physical/<vendor>/). Failover between interfaces is owned by the network stack itself (it reselects the default route when a link drops) - this layer adds no manager and no polling tick; it only reports which interface currently carries outbound traffic via pc_net_egress(), read on demand from the live default route so the answer is always current.

Author: Douglas Quigg (dstroy0)

Date: 2026

Definition in file physical.h.

Macro Definition Documentation

◆ PC_PHYSICAL_HAS_BACKEND

#define PC_PHYSICAL_HAS_BACKEND 0

Definition at line 37 of file physical.h.

Typedef Documentation

◆ pc_phy_frame_fn

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

One received frame, delivered in neutral terms.

Deliberately not the vendor's received-packet struct: handing that upward is what leaked the vendor into the monitor service to begin with. The FCS is already stripped.

Parameters

frame	Frame bytes, valid only for the duration of the call.
len	Frame length in bytes, FCS excluded.
rssi	Received signal strength, dBm.
channel	Channel the frame arrived on.

Definition at line 208 of file physical.h.

Enumeration Type Documentation

◆ pc_phy_ps

enum class pc_phy_ps : uint8_t

strong

Radio power-save mode, in the library's own vocabulary.

Enumerator
PC_PHY_PS_NONE	Radio always on: lowest latency, highest average draw.
PC_PHY_PS_MIN_MODEM	Wake on every DTIM beacon.
PC_PHY_PS_MAX_MODEM	Wake on a longer listen interval: lowest draw, highest latency.

Definition at line 190 of file physical.h.

Function Documentation

◆ init_wifi_physical()

bool init_wifi_physical	(	const char *	ssid,
		const char *	password
	)

Connect to a WiFi access point.

Starts the station join and returns immediately; it does not block waiting for association. Poll wifi_ready() to check link status.

Parameters

ssid	Network SSID (null-terminated).
password	WPA2 passphrase (null-terminated).

Returns: Always returns true (the join is fire-and-forget).

Definition at line 41 of file physical.cpp.

◆ wifi_ready()

bool wifi_ready ( )

True if the WiFi station link is up (associated + an IP is assigned).

Definition at line 45 of file physical.cpp.

◆ init_wifi_radio_physical()

bool init_wifi_radio_physical ( uint8_t channel )

Bring the WiFi radio up in station mode WITHOUT associating to an AP.

For raw-radio use that needs the PHY running but no IP link: ESP-NOW peer messaging and promiscuous capture. Pins the radio to channel (1..14) when non-zero; pass 0 to leave the channel to a capture layer that sets its own (services/radio/promisc). Returns immediately.

Returns: true once the radio is started (always true on host builds).

Definition at line 49 of file physical.cpp.

◆ init_wifi_ap_physical()

bool init_wifi_ap_physical	(	const char *	ssid,
		const char *	password
	)

Bring up a softAP, enabling AP+STA coexistence so a station link can run alongside it.

Parameters

ssid	softAP SSID (null-terminated).
password	softAP passphrase (null-terminated; >= 8 chars for WPA2, "" for an open AP).

Returns: true if the softAP started (false on host builds).

Definition at line 53 of file physical.cpp.

◆ init_eth_physical()

bool init_eth_physical ( void )

Bring up a wired Ethernet link (PC_ENABLE_ETHERNET).

A thin wrapper over the Arduino ETH library (ETH.begin()); the RMII PHY pins / type / clock come from the standard ETH_PHY_* build flags for your board. Returns immediately (bring-up is asynchronous); poll eth_ready(). The egress reporting already classifies a wired route as pc_iface::PC_IFACE_ETH, so the server accepts on the link once it has an IP.

Returns: true if ETH.begin() started the driver; false if Ethernet is disabled at build time or the driver failed to start (and always false on host builds).

Definition at line 57 of file physical.cpp.

◆ eth_ready()

bool eth_ready ( void )

True if the Ethernet link is up and an IP is assigned.

Definition at line 61 of file physical.cpp.

◆ init_ipv6_physical()

bool init_ipv6_physical ( void )

Enable IPv6 (dual-stack) on the Wi-Fi interface (PC_ENABLE_IPV6).

Turns on IPv6 for the netif so it acquires a SLAAC link-local address and, if the network advertises a prefix, a global address. Returns immediately (address configuration is asynchronous); poll pc_ipv6_ready(). The listeners already bind IPADDR_TYPE_ANY, so the server answers over IPv6 as soon as an address is up.

Returns: true if IPv6 was enabled; false if disabled at build time or on host builds.

Definition at line 65 of file physical.cpp.

◆ net_global_ipv6()

bool net_global_ipv6 ( pc_ip * out )

The interface's global (routable) IPv6 address, if it has one.

Parameters

[out] out receives the address (family pc_ip_family::PC_IP_V6) when true is returned.

Returns: true if a valid global IPv6 address is assigned; false otherwise (incl. host builds).

Definition at line 69 of file physical.cpp.

◆ pc_ipv6_ready()

bool pc_ipv6_ready ( void )

True once the interface has a global IPv6 address (see net_global_ipv6()).

Definition at line 73 of file physical.cpp.

◆ pc_net_egress()

pc_iface pc_net_egress ( void )

Which interface currently carries outbound traffic.

Reads the live lwIP default route, so it reflects the current state after any failover the stack performed - no polling, no cached state. Returns pc_iface::PC_IFACE_ETH / pc_iface::PC_IFACE_STA / pc_iface::PC_IFACE_AP, or pc_iface::PC_IFACE_ANY when no route is up (and on host builds).

Definition at line 81 of file physical.cpp.

References PC_IFACE_ANY.

◆ pc_net_egress_ip()

uint32_t pc_net_egress_ip ( void )

IPv4 (network byte order) of the current egress interface, or 0 if none.

Definition at line 77 of file physical.cpp.

◆ pc_net_ap_ip()

uint32_t pc_net_ap_ip ( void )

softAP IPv4 (network byte order), or 0 if the softAP is not up (and on host builds).

Definition at line 85 of file physical.cpp.

◆ pc_net_rssi()

int8_t pc_net_rssi ( void )

Station link RSSI in dBm, or 0 if not associated (and on host builds).

Definition at line 89 of file physical.cpp.

◆ pc_net_mac()

bool pc_net_mac ( uint8_t out[6] )

Copy the WiFi station interface MAC (6 bytes) into out.

This is specifically the 802.11 STA address (what ESP-NOW and WiFi diagnostics want). It is only valid once the WiFi driver is up; on an Ethernet-only device (e.g. the P4 that never starts WiFi) it reads back as zeros. For "the MAC this device is actually using on the wire right now", regardless of link type, use pc_net_egress_mac().

Returns: true on success; false if out is null or on a host build (out is left untouched).

◆ pc_net_egress_mac()

bool pc_net_egress_mac ( uint8_t out[6] )

Copy the MAC of the current egress interface (the live default-route netif) into out.

Vendor- and link-neutral: returns the Ethernet PHY's MAC on a wired link, the WiFi STA MAC on a wireless one - whichever netif currently carries outbound traffic (the same interface pc_net_egress_ip() reports).

Returns: true and fills out when a default interface with a 6-byte hwaddr exists; false otherwise (no egress up, out null, or a host build), leaving out untouched.

◆ pc_net_ssid()

size_t pc_net_ssid	(	char *	out,
		size_t	cap
	)

Copy the associated SSID (null-terminated) into out.

Returns: the SSID length in bytes, or 0 if not associated, cap is 0, or on a host build.

Definition at line 126 of file physical.cpp.

◆ pc_net_channel()

uint8_t pc_net_channel ( void )

Station WiFi channel (1..14), or 0 if not associated (and on host builds).

Definition at line 134 of file physical.cpp.

◆ pc_net_classify_ip()

pc_iface pc_net_classify_ip	(	uint32_t	egress_ip,
		uint32_t	sta_ip,
		uint32_t	ap_ip
	)

Classify an egress IPv4 against the WiFi station / softAP IPs (pure helper, exposed for unit testing).

A live egress IP equal to the station or softAP IP is that WiFi interface; any other live IP is a wired (Ethernet) route; 0 is no route.

Parameters

egress_ip	Current default-route IPv4 (network order), 0 if none.
sta_ip	WiFi station IPv4 (network order), 0 if not connected.
ap_ip	softAP IPv4 (network order), 0 if the softAP is not up.

Definition at line 20 of file physical.cpp.

References PC_IFACE_ANY, PC_IFACE_AP, PC_IFACE_ETH, and PC_IFACE_STA.

◆ pc_phy_ps_set()

bool pc_phy_ps_set ( pc_phy_ps mode )

Apply a power-save mode.

Returns: false if there is no radio backend.

Definition at line 104 of file physical.cpp.

◆ pc_phy_ps_get()

pc_phy_ps pc_phy_ps_get ( void )

Read the active power-save mode (PC_PHY_PS_NONE when unsupported).

Definition at line 108 of file physical.cpp.

References PC_PHY_PS_NONE.

◆ pc_phy_tx_power_set()

bool pc_phy_tx_power_set ( int8_t dbm )

Cap transmit power.

Parameters

dbm	Maximum transmit power in whole dBm; the backend converts to its own unit.

Returns: false if there is no radio backend.

Definition at line 112 of file physical.cpp.

◆ pc_phy_monitor_begin()

bool pc_phy_monitor_begin	(	uint8_t	channel,
		pc_phy_frame_fn	cb
	)

Enter monitor mode on channel, delivering frames to cb.

Definition at line 116 of file physical.cpp.

◆ pc_phy_monitor_set_channel()

void pc_phy_monitor_set_channel ( uint8_t channel )

Retune monitor mode to channel.

Definition at line 120 of file physical.cpp.

◆ pc_phy_monitor_end()

void pc_phy_monitor_end ( void )

Leave monitor mode.

Definition at line 123 of file physical.cpp.

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ PC_PHYSICAL_HAS_BACKEND

Typedef Documentation

◆ pc_phy_frame_fn

Enumeration Type Documentation

◆ pc_phy_ps

Function Documentation

◆ init_wifi_physical()

◆ wifi_ready()

◆ init_wifi_radio_physical()

◆ init_wifi_ap_physical()

◆ init_eth_physical()

◆ eth_ready()

◆ init_ipv6_physical()

◆ net_global_ipv6()

◆ pc_ipv6_ready()

◆ pc_net_egress()

◆ pc_net_egress_ip()

◆ pc_net_ap_ip()

◆ pc_net_rssi()

◆ pc_net_mac()

◆ pc_net_egress_mac()

◆ pc_net_ssid()

◆ pc_net_channel()

◆ pc_net_classify_ip()

◆ pc_phy_ps_set()

◆ pc_phy_ps_get()

◆ pc_phy_tx_power_set()

◆ pc_phy_monitor_begin()

◆ pc_phy_monitor_set_channel()

◆ pc_phy_monitor_end()