# WiFi Setup Feature

The LED Matrix project includes a WiFi setup feature that allows you to configure WiFi connections through a web interface. When the Raspberry Pi is not connected to WiFi, it automatically broadcasts an access point (AP) that you can connect to for initial setup.

## Features

- **Automatic AP Mode**: When no WiFi connection is detected, the Raspberry Pi automatically creates a WiFi access point named "LEDMatrix-Setup"
- **Web Interface**: Access the WiFi setup interface through your web browser
- **Network Scanning**: Scan for available WiFi networks from the web interface
- **Secure Connection**: Save WiFi credentials securely
- **Automatic Management**: The WiFi monitor daemon automatically enables/disables AP mode based on connection status

## Requirements

The following packages are required for WiFi setup functionality:

- **hostapd**: Access point software
- **dnsmasq**: DHCP server for AP mode
- **NetworkManager** (or **iwlist**): WiFi management tools

These packages are automatically checked and can be installed during the WiFi monitor service installation.

## Installation

### 1. Install WiFi Monitor Service

Run the installation script to set up the WiFi monitor daemon:

```bash
cd /home/ledpi/LEDMatrix
sudo ./scripts/install/install_wifi_monitor.sh
```

This script will:
- Check for required packages and offer to install them
- Create the systemd service file
- Enable and start the WiFi monitor service
- Configure the service to start on boot

### 2. Verify Service Status

Check that the WiFi monitor service is running:

```bash
sudo systemctl status ledmatrix-wifi-monitor
```

You should see output indicating the service is active and running.

## Usage

### Accessing the WiFi Setup Interface

1. **If WiFi is NOT connected**: The Raspberry Pi will automatically create an access point
   - Connect to the WiFi network: **LEDMatrix-Setup**
   - Password: **ledmatrix123** (default)
   - Open a web browser and navigate to: `http://192.168.4.1:5000`
   - Or use the IP address shown in the web interface

2. **If WiFi IS connected**: Access the web interface normally
   - Navigate to: `http://<raspberry-pi-ip>:5000`
   - Click on the **WiFi** tab in the navigation

### Connecting to a WiFi Network

1. Navigate to the **WiFi** tab in the web interface
2. Click **Scan** to search for available networks
3. Select a network from the dropdown menu, or enter the SSID manually
4. Enter the WiFi password (leave empty for open networks)
5. Click **Connect**
6. The system will attempt to connect to the selected network
7. Once connected, AP mode will automatically disable

### Manual AP Mode Control

You can manually enable or disable AP mode from the web interface:

- **Enable AP Mode**: Click "Enable AP Mode" button (only available when WiFi is not connected)
- **Disable AP Mode**: Click "Disable AP Mode" button (only available when AP mode is active)

## How It Works

### WiFi Monitor Daemon

The WiFi monitor daemon (`wifi_monitor_daemon.py`) runs as a background service that:

1. Checks WiFi connection status every 30 seconds (configurable)
2. Automatically enables AP mode only if:
   - `auto_enable_ap_mode` is enabled in config AND
   - No WiFi connection is detected AND
   - No Ethernet connection is detected
3. Automatically disables AP mode when WiFi or Ethernet connection is established
4. Logs all state changes for troubleshooting

**Note**: By default, `auto_enable_ap_mode` is `true`, meaning AP mode will automatically activate when both WiFi and Ethernet are disconnected. This ensures you can always configure the device even when it has no network connection.

### WiFi Manager Module

The WiFi manager (`src/wifi_manager.py`) provides:

- **Connection Status**: Checks current WiFi connection state
- **Network Scanning**: Scans for available WiFi networks
- **Connection Management**: Connects to WiFi networks and saves credentials
- **AP Mode Control**: Manages access point mode (hostapd/dnsmasq)

### Configuration

WiFi settings are stored in `config/wifi_config.json`:

```json
{
  "ap_ssid": "LEDMatrix-Setup",
  "ap_password": "ledmatrix123",
  "ap_channel": 7,
  "auto_enable_ap_mode": true,
  "saved_networks": [
    {
      "ssid": "MyNetwork",
      "password": "mypassword",
      "saved_at": 1234567890.0
    }
  ]
}
```

**Configuration Options:**
- `ap_ssid`: SSID for the access point (default: "LEDMatrix-Setup")
- `ap_password`: Password for the access point (default: "ledmatrix123")
- `ap_channel`: WiFi channel for AP mode (default: 7)
- `auto_enable_ap_mode`: Automatically enable AP mode when WiFi/Ethernet disconnect (default: `true`)
  - When `true`: AP mode automatically enables when both WiFi and Ethernet are disconnected
  - When `false`: AP mode must be manually enabled through the web interface
- `saved_networks`: List of saved WiFi network credentials

### Access Point Configuration

The AP mode uses `hostapd` and `dnsmasq` for access point functionality:

- **SSID**: LEDMatrix-Setup (configurable)
- **IP Range**: 192.168.4.2 - 192.168.4.20
- **Gateway**: 192.168.4.1
- **Channel**: 7 (configurable)

## Troubleshooting

### WiFi Monitor Service Not Starting

Check the service logs:

```bash
sudo journalctl -u ledmatrix-wifi-monitor -n 50
```

Common issues:
- Missing packages (hostapd, dnsmasq)
- Permission issues
- Network interface not available

### Cannot Access AP Mode

1. Check if AP mode is active:
   ```bash
   sudo systemctl status hostapd
   ```

2. Check if dnsmasq is running:
   ```bash
   sudo systemctl status dnsmasq
   ```

3. Verify WiFi interface exists:
   ```bash
   ip link show wlan0
   ```

### Cannot Connect to WiFi Network

1. Verify the SSID and password are correct
2. Check if the network requires a password (some networks may appear open but require a password)
3. Check WiFi monitor logs for connection errors:
   ```bash
   sudo journalctl -u ledmatrix-wifi-monitor -f
   ```

4. Check NetworkManager logs:
   ```bash
   sudo journalctl -u NetworkManager -n 50
   ```

### AP Mode Not Disabling

If AP mode doesn't disable after connecting to WiFi:

1. Check WiFi connection status:
   ```bash
   nmcli device status
   ```

2. Manually disable AP mode from the web interface
3. Restart the WiFi monitor service:
   ```bash
   sudo systemctl restart ledmatrix-wifi-monitor
   ```

## Service Management

### Useful Commands

```bash
# Check service status
sudo systemctl status ledmatrix-wifi-monitor

# Start the service
sudo systemctl start ledmatrix-wifi-monitor

# Stop the service
sudo systemctl stop ledmatrix-wifi-monitor

# Restart the service
sudo systemctl restart ledmatrix-wifi-monitor

# View logs
sudo journalctl -u ledmatrix-wifi-monitor -f

# Disable service from starting on boot
sudo systemctl disable ledmatrix-wifi-monitor

# Enable service to start on boot
sudo systemctl enable ledmatrix-wifi-monitor
```

### Configuration Options

You can modify the check interval by editing the service file:

```bash
sudo systemctl edit ledmatrix-wifi-monitor
```

Or modify the service file directly:

```bash
sudo nano /etc/systemd/system/ledmatrix-wifi-monitor.service
```

Change the `--interval` parameter in the `ExecStart` line (default is 30 seconds).

After modifying, reload and restart:

```bash
sudo systemctl daemon-reload
sudo systemctl restart ledmatrix-wifi-monitor
```

## Security Considerations

- **Default AP Password**: The default AP password is "ledmatrix123". Consider changing this in `config/wifi_config.json` for production use
- **WiFi Credentials**: Saved WiFi credentials are stored in `config/wifi_config.json`. Ensure proper file permissions:
  ```bash
  sudo chmod 600 config/wifi_config.json
  ```
- **Network Access**: When in AP mode, anyone within range can connect to the setup network. Use strong passwords for production deployments

## API Endpoints

The WiFi setup feature exposes the following API endpoints:

- `GET /api/v3/wifi/status` - Get current WiFi connection status
- `GET /api/v3/wifi/scan` - Scan for available WiFi networks
- `POST /api/v3/wifi/connect` - Connect to a WiFi network
- `POST /api/v3/wifi/ap/enable` - Enable access point mode
- `POST /api/v3/wifi/ap/disable` - Disable access point mode

## Technical Details

### WiFi Detection Methods

The WiFi manager tries multiple methods to detect WiFi status:

1. **NetworkManager (nmcli)** - Preferred method if available
2. **iwconfig** - Fallback method for systems without NetworkManager

### Network Scanning

The system supports multiple scanning methods:

1. **nmcli** - Fast, preferred method
2. **iwlist** - Fallback method for older systems

### Access Point Setup

AP mode configuration:

- Uses `hostapd` for WiFi access point functionality
- Uses `dnsmasq` for DHCP and DNS services
- Configures wlan0 interface in AP mode
- Provides DHCP range: 192.168.4.2-20
- Gateway IP: 192.168.4.1

## Development

### Testing WiFi Manager

You can test the WiFi manager directly:

```python
from src.wifi_manager import WiFiManager

# Create WiFi manager instance
wifi_manager = WiFiManager()

# Get status
status = wifi_manager.get_wifi_status()
print(f"Connected: {status.connected}, SSID: {status.ssid}")

# Scan networks
networks = wifi_manager.scan_networks()
for net in networks:
    print(f"{net.ssid}: {net.signal}% ({net.security})")

# Connect to network
success, message = wifi_manager.connect_to_network("MyNetwork", "password")
print(f"Connection: {success}, Message: {message}")
```

### Running Monitor Daemon Manually

For testing, you can run the daemon in foreground mode:

```bash
sudo python3 wifi_monitor_daemon.py --interval 10 --foreground
```

## Support

For issues or questions:
1. Check the logs: `sudo journalctl -u ledmatrix-wifi-monitor -f`
2. Review this documentation
3. Check the main project README for general troubleshooting
4. Open an issue on GitHub if needed