pi-pm3/NETWORK_IMPLEMENTATION.md

Network Implementation Notes

This document describes the current WiFi/network architecture and known issues.

Architecture Overview

The Dangerous Pi image uses a dual-mode WiFi configuration:

Access Point Mode (Default)

• hostapd creates an AP on wlan0
• dnsmasq provides DHCP
• Default configuration:
  • SSID: Dangerous-Pi
  • Password: dangerous123
  • IP Range: 192.168.4.2-20
  • Gateway: 192.168.4.1

Client Mode (Manual)

wlan0 can be switched to client mode to connect to an existing network:

# Stop AP services
sudo systemctl stop hostapd
sudo systemctl stop dnsmasq

# Connect to WiFi
echo -e 'network={\n    ssid="YOUR_SSID"\n    psk="YOUR_PASSWORD"\n}' > ~/wifi.conf
sudo wpa_supplicant -B -i wlan0 -c ~/wifi.conf

# Get IP address
sudo dhcpcd wlan0

To return to AP mode:

sudo killall wpa_supplicant
sudo systemctl start hostapd
sudo systemctl start dnsmasq

Known Issues

WiFi API Detection

• The systemd service must have /sbin:/usr/sbin in PATH for iw command to work
• This was fixed in the service file (2026-01-01)

AP/Client Mode Switching

• wlan0 is configured as "unmanaged" by NetworkManager when hostapd is running
• hostapd must be stopped before wlan0 can connect as a client
• dhclient is not installed; use dhcpcd instead

Mode Detection

• Current mode detection reports "client" when in AP mode because it checks for SSID presence
• Should check for type AP in iw dev output for accurate detection
• TODO: Fix mode detection to properly identify AP mode

USB WiFi Adapter (wlan1)

• If present, wlan1 can be used for client connectivity while wlan0 stays in AP mode
• Configuration in .env.example: USB_WLAN_INTERFACE=wlan1

Future Improvements

Planned features for easier network switching:

1. Web UI toggle for AP/Client mode
2. Persistent WiFi client configuration
3. Auto-fallback to AP mode if client connection fails
4. USB WiFi adapter auto-detection

Service Dependencies

Service	Port	Purpose
hostapd	-	WiFi Access Point
dnsmasq	53, 67	DNS & DHCP for AP clients
dangerous-pi	8000	Main backend API
dangerous-pi-frontend	3000	Remix frontend
pisugar-server	8421-8423	UPS battery management

Tested Configurations

• Raspberry Pi Zero 2 W with onboard WiFi
• Debian Trixie (arm64)
• wpa_supplicant + dhcpcd for client connections
• PiSugar 2 UPS (detected via I2C)

Verified Working (Phase 3 Testing - 2026-01-01)

Feature	Status	Notes
WiFi AP	✅ Working	SSID: Dangerous-Pi at 192.168.4.1
WiFi API	✅ Working	After PATH fix in systemd service
PM3 Device	✅ Working	/dev/ttyACM0, Iceman firmware
PM3 API	✅ Working	Command execution verified
UPS (PiSugar 2)	✅ Working	Battery status, AC power detection
BLE	✅ Working	Advertising as DangerousPi
Frontend	✅ Working	Remix serving on port 3000
Backend	✅ Working	FastAPI on port 8000

---

Last updated: 2026-01-01