# 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:

```bash
# 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:
```bash
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*