BATMAN-adv

Type: Kernel Module (Layer 2 Mesh) Role in Styrene: Physical connectivity layer for fleet devices

BATMAN-adv (Better Approach To Mobile Adhoc Networking - advanced) is a Linux kernel module (net/batman-adv/) that creates a virtual network switch across multiple wireless hops. In mainline since Linux 2.6.38 (2011). Userspace tool: batctl.

Why Styrene Uses BATMAN-adv

Reticulum solves logical connectivity (identity-based routing, encryption). BATMAN-adv solves physical connectivity:

Layer Position

┌─────────────────────────────────────┐
│  Reticulum (identity + encryption)  │  ← Sees bat0 as just another interface
├─────────────────────────────────────┤
│  BATMAN-adv (bat0 virtual switch)   │  ← YOU ARE HERE
├─────────────────────────────────────┤
│  802.11s mesh (wlan0, mesh-styrene) │  ← WiFi mesh mode (HWMP disabled)
└─────────────────────────────────────┘

Virtual Interface

BATMAN-adv creates bat0, a virtual Ethernet interface:

• All mesh nodes share the same bat0 broadcast domain
• Frames encapsulated with ~32 bytes overhead (EtherType 0x4305)
• Hard interface MTU typically set to 1532 to allow 1500-byte payloads on bat0
• Applications see a simple Ethernet interface — IPv4, IPv6, DHCP, mDNS all work unmodified

Protocol Versions

BATMAN IV (Legacy)

• Originator Messages (OGMs) broadcast at configurable intervals (default: 1/sec)
• TQ (Transmission Quality): 0-255 packet-loss metric combining forward and reverse link quality
• Cannot distinguish between a 1 Mbps link with 0% loss and a 1 Gbps link with 0% loss

BATMAN V (Default since Linux 5.8)

• ELP (Echo Location Protocol): local neighbor discovery, never forwarded
• Throughput-based metric instead of packet-loss
• Per-interface type detection:

BATMAN V is critical for heterogeneous networks where links have vastly different capacities.

802.11s Integration (Current Best Practice)

Use 802.11s mesh point mode as the link layer, with batman-adv handling routing:

# Create 802.11s mesh interface
iw dev wlan0 set type mesh
iw dev wlan0 mesh join MyMesh freq 2412 HT20
ip link set mtu 1532 dev wlan0

# DISABLE 802.11s HWMP routing — batman-adv handles routing
iw dev wlan0 set mesh_param mesh_fwding=0

# Add to batman-adv
batctl interface add wlan0
ip link set up dev bat0

This gives the best of both worlds: 802.11s handles WiFi peering/beaconing/security, batman-adv handles multi-hop routing across all link types.

IBSS (ad-hoc) mode is deprecated — Freifunk Gluon dropped it after v2019.1.x.

802.11s vs BATMAN-adv Routing

Multi-Interface Architecture

batman-adv’s most powerful feature for Styrene:

• N+1 routing tables: per-interface tracking of best next-hop to each originator
• Interface alternating (default): switches interfaces at each hop (e.g., 5 GHz → 2.4 GHz → 5 GHz)
• Bonding mode: all interfaces used simultaneously, round-robin
• Per-interface ELP tuning: different probing intervals for WiFi vs Ethernet vs unknown
• Throughput override: set metrics via netlink for interfaces batman-adv can’t auto-detect

┌─────────────────────────────────────────────────┐
│                  bat0 (virtual L2 switch)        │
│              batman-adv kernel module             │
├──────────────┬──────────────┬────────────────────┤
│    wlan0     │    eth0      │    wg0 (GRETap)    │
│ (802.11s)    │ (backhaul)   │ (VPN mesh)         │
└──────────────┴──────────────┴────────────────────┘

Key Features

Styrene Configuration

Fleet devices use the batman-mesh.nix NixOS module:

styrene.mesh = {
  enable = true;
  meshId = "styrene";
  meshKey = "fleet-key-from-vault";
  channel = 6;
  gwMode = "client";  # or "server" or "off"
};

Gateway Modes

Reticulum over BATMAN-adv

Since bat0 is a standard Ethernet interface, Reticulum works over it using:

• AutoInterface: IPv6 link-local multicast discovery + UDP transport. Discovers all RNS nodes across the mesh automatically. Zero configuration.
• UDPInterface / TCPClientInterface: Standard IP over bat0. Works identically to any Ethernet.

This creates a double-mesh architecture:

Reticulum — identity-based, encrypted overlay
    │
UDP/IPv6 on bat0 (AutoInterface)
    │
batman-adv — L2 mesh routing
    │
802.11s mesh point — WiFi link layer
    │
Radio

The redundancy is deliberate: batman-adv provides the “dumb pipe” connectivity that Reticulum needs, Reticulum provides identity, encryption, and application-layer routing that batman-adv does not.

Real-World Implementations

• Haven: 802.11s + batman-adv + Reticulum. Bridges WiFi mesh, HaLow, and LoRa into unified backbone.
• OpenMANET: Pi-based MANET radio using Wi-Fi HaLow (802.11ah) with 802.11s + batman-adv.

BATMAN-adv over Bluetooth

Technically possible but practically difficult. batman-adv requires Linux network interfaces carrying Ethernet frames. Bluetooth PAN/BNEP creates bnep0 interfaces that qualify. However:

1. Point-to-point topology: each BT connection creates a separate bnepN. No shared broadcast domain. Each peer needs explicit connection management.
2. No auto-discovery: unlike WiFi 802.11s, nothing in the BT stack auto-discovers and connects peers. An external daemon must manage connections.
3. Deprecated PAN: modern BlueZ changed how PAN interfaces are created. The only attempt (batman-adv-pan) is abandoned.
4. Low bandwidth: BT Classic ~2-3 Mbps, BLE ~100-250 kbps. OGM/ELP overhead becomes significant.
5. BLE latency: connection intervals (7.5 ms-4 s) conflict with ELP probing (500 ms default).

Verdict: Use batman-adv for WiFi + Ethernet + VPN mesh. Use a native Reticulum BLE interface (see ble-mesh-transport) for Bluetooth — don’t try to force BLE through batman-adv.

Power Considerations

batman-adv has no built-in power management. Key parameters:

For battery devices, tune intervals up:

batctl orig_interval 5000   # 5 sec (slower route convergence)
batctl hardif wlan0 elp_interval 2000  # 2 sec probing

WiFi power save (iw dev wlan0 set power_save off) must typically be disabled — power save causes missed mesh frames. WiFi adapter draws ~50-60 mA continuously. batman-adv CPU overhead is negligible, but it requires always-on radios.

For battery-constrained mesh, consider ble-mesh-transport instead — BLE duty-cycling is 1000x more power-efficient than WiFi for low-bandwidth traffic.

Scalability

OGM overhead scales O(n^2) worst case. Real-world limits:

Freifunk Munich: 3,300+ active nodes across 150+ router models — segmented into domains, not one giant L2 mesh. Uses Gluon firmware (OpenWrt-based, batman-adv + WireGuard VPN + auto-configuration).

Debugging

# Show mesh neighbors
batctl n

# Show originators (all mesh nodes)
batctl o

# Show gateway list
batctl gwl

# Show transmission quality to node
batctl tq

# Show interface list
batctl if

# Throughput meter between nodes
batctl tp <originator-mac>

Resources

• BATMAN-adv Documentation
• BATMAN V Specification
• 802.11s Mesh Networking
• Gluon Firmware — community mesh framework
• OpenWrt batman-adv Tutorial
• Freifunk Munich (3300+ nodes)
• Haven Mesh Radio — batman-adv + Reticulum

Related

• Reticulum — Overlay network running on bat0
• LoRa — Long-range physical layer
• ble-mesh-transport — BLE as complementary/alternative mesh transport