9dc35a57a2
- Introduced a web GUI for managing 5G connections, replacing the standalone 5g-router service. - Updated scripts to ensure exclusive access to the AT port, preventing conflicts. - Improved troubleshooting documentation in 5G_MODEM_TROUBLESHOOTING.md, adding checks for processes using the AT port. - Enhanced connection management in the web app, including auto-connect and detailed status APIs. - Updated installation scripts to reflect changes in service management and dependencies.
261 lines
7.0 KiB
Markdown
261 lines
7.0 KiB
Markdown
# Alpine 5G Router - Raspberry Pi 5 + Fibocom FM350-GL
|
||
|
||
A complete 5G router setup using Alpine Linux on Raspberry Pi 5 with a Fibocom FM350-GL modem.
|
||
|
||
## ✅ Status: Working
|
||
|
||
The 5G modem is fully operational with CYTA Cyprus SIM card.
|
||
|
||
## Documentation
|
||
|
||
| File | Description |
|
||
|------|-------------|
|
||
| [README.md](README.md) | This file – overview and reference |
|
||
| [docs/QUICKSTART.md](docs/QUICKSTART.md) | **Quick start** – clone → install script → config → start |
|
||
| [docs/DEPLOY.md](docs/DEPLOY.md) | First-time SSH and key-based deploy |
|
||
| [docs/DNS.md](docs/DNS.md) | DNS (resolv.conf, dnsmasq) for router and LAN |
|
||
| [5G_MODEM_TROUBLESHOOTING.md](5G_MODEM_TROUBLESHOOTING.md) | Modem AT commands and troubleshooting |
|
||
| [configure_fm350_5g.sh](configure_fm350_5g.sh) | Manual configuration script (uses `/etc/5g-router.conf`) |
|
||
| [CHANGELOG.md](CHANGELOG.md) | Version and feature notes |
|
||
| [docs/WEBGUI.md](docs/WEBGUI.md) | Web GUI – login (admin/support), permissions, install |
|
||
|
||
## Hardware
|
||
|
||
- **Board:** Raspberry Pi 5
|
||
- **Modem:** Fibocom FM350-GL (USB ID: 0e8d:7126)
|
||
- **OS:** Alpine Linux v3.23.3
|
||
- **SIM:** CYTA Cyprus (APN: `internet`)
|
||
|
||
## Network Architecture
|
||
|
||
```
|
||
Internet (CYTA 5G)
|
||
│
|
||
▼
|
||
FM350-GL Modem
|
||
(RNDIS eth1)
|
||
│
|
||
▼
|
||
Raspberry Pi 5
|
||
Alpine Linux
|
||
│
|
||
▼
|
||
eth0.100 VLAN
|
||
(192.168.1.1)
|
||
│
|
||
▼
|
||
LAN Clients
|
||
```
|
||
|
||
## Quick Start (new device)
|
||
|
||
For a **single-command flow** from a fresh device, see **[docs/QUICKSTART.md](docs/QUICKSTART.md)**. Summary:
|
||
|
||
1. Clone or copy this repo to the device.
|
||
2. Install packages: `apk add iptables python3 py3-flask` and `pip install pyserial`.
|
||
3. Run **`./scripts/install.sh`** – installs Web GUI, config, and enables 5g-webgui service.
|
||
4. Edit `/etc/5g-router.conf` if needed (APN, interfaces).
|
||
5. Start: `service 5g-webgui start`
|
||
6. Open **http://\<device-ip\>:5000** to manage the router.
|
||
|
||
**Note:** The Web GUI now includes integrated 5G connection management. The standalone `5g-router` service is kept for manual/fallback use but is no longer the default.
|
||
|
||
For SSH and key setup: **[docs/DEPLOY.md](docs/DEPLOY.md)**.
|
||
|
||
---
|
||
|
||
## Manual Quick Start (step-by-step)
|
||
|
||
### 1. Install Required Packages
|
||
|
||
```bash
|
||
# Enable community repository
|
||
sed -i 's|#.*community|http://mirrors.neterra.net/alpine/v3.23/community|' /etc/apk/repositories
|
||
apk update
|
||
|
||
# Install packages
|
||
apk add modemmanager dnsmasq iptables libmbim-tools qmi-utils
|
||
```
|
||
|
||
### 2. Configure and Connect Modem
|
||
|
||
```bash
|
||
# Set APN for CYTA
|
||
cat /dev/ttyUSB1 & CAT_PID=$!
|
||
sleep 0.3
|
||
echo -e 'AT+CGDCONT=1,"IP","internet"\r' > /dev/ttyUSB1
|
||
sleep 2
|
||
kill $CAT_PID
|
||
|
||
# Activate connection
|
||
cat /dev/ttyUSB1 & CAT_PID=$!
|
||
sleep 0.3
|
||
echo -e 'AT+CGACT=1,1\r' > /dev/ttyUSB1
|
||
sleep 3
|
||
kill $CAT_PID
|
||
|
||
# Get modem IP
|
||
cat /dev/ttyUSB1 & CAT_PID=$!
|
||
sleep 0.3
|
||
echo -e 'AT+CGPADDR=1\r' > /dev/ttyUSB1
|
||
sleep 2
|
||
kill $CAT_PID
|
||
# Note the IP address returned (e.g., 10.156.167.104)
|
||
```
|
||
|
||
### 3. Configure Network Interface
|
||
|
||
```bash
|
||
# Replace MODEM_IP with the IP from AT+CGPADDR=1
|
||
MODEM_IP="10.156.167.104"
|
||
|
||
ip link set eth1 up
|
||
ip addr flush dev eth1
|
||
ip addr add $MODEM_IP/32 dev eth1
|
||
ip route add default dev eth1 metric 50
|
||
|
||
# Test connectivity
|
||
ping -c 3 8.8.8.8
|
||
```
|
||
|
||
### 4. Setup NAT for LAN
|
||
|
||
```bash
|
||
# Enable IP forwarding
|
||
echo 1 > /proc/sys/net/ipv4/ip_forward
|
||
|
||
# Configure NAT
|
||
iptables -t nat -A POSTROUTING -o eth1 -j MASQUERADE
|
||
iptables -A FORWARD -i eth0.100 -o eth1 -j ACCEPT
|
||
iptables -A FORWARD -i eth1 -o eth0.100 -m state --state RELATED,ESTABLISHED -j ACCEPT
|
||
|
||
# Save rules
|
||
iptables-save > /etc/iptables/rules.v4
|
||
```
|
||
|
||
## Key Configuration Details
|
||
|
||
### Modem USB Modes
|
||
|
||
| Mode | USB ID | Description | Status |
|
||
|------|--------|-------------|--------|
|
||
| 40 | 0e8d:7126 | RNDIS mode | ✅ Working |
|
||
| 41 | 0e8d:7127 | Extended mode | ❌ AT broken |
|
||
|
||
**Important:** Stay in Mode 40 - AT commands work on `/dev/ttyUSB1`.
|
||
|
||
### Working AT Commands
|
||
|
||
| Command | Description |
|
||
|---------|-------------|
|
||
| `AT` | Test communication |
|
||
| `AT+CSQ` | Signal strength |
|
||
| `AT+CGDCONT=1,"IP","internet"` | Set APN |
|
||
| `AT+CGACT=1,1` | Activate connection |
|
||
| `AT+CGPADDR=1` | Get assigned IP |
|
||
| `AT+CGCONTRDP=1` | Get DNS servers |
|
||
| `AT+GTUSBMODE?` | Check USB mode |
|
||
|
||
### CYTA Cyprus Network Info
|
||
|
||
- **APN:** `internet`
|
||
- **DNS Primary:** 195.14.130.220
|
||
- **DNS Secondary:** 195.14.154.100
|
||
|
||
## Services
|
||
|
||
The following services are configured to start on boot:
|
||
|
||
```bash
|
||
# Check service status
|
||
rc-status
|
||
|
||
# Services enabled:
|
||
# - dnsmasq (DHCP/DNS)
|
||
# - iptables-restore (firewall rules)
|
||
# - 5g-router (connection script)
|
||
```
|
||
|
||
## Files on Device (after install)
|
||
|
||
| Path | Purpose |
|
||
|------|---------|
|
||
| `/etc/5g-router.conf` | Config (APN, interfaces, failover, watchdog) – from repo `etc/5g-router.conf.example` |
|
||
| `/usr/local/bin/connect-5g.sh` | Connection script (run by service or manually) |
|
||
| `/usr/local/bin/status-5g.sh` | Status (modem, interface, route, last speedtest) |
|
||
| `/usr/local/bin/healthcheck-5g.sh` | Health check for monitoring (exit 0/1) |
|
||
| `/usr/local/bin/speedtest-5g.sh` | Optional speedtest cron target |
|
||
| `/usr/local/bin/rotate-5g-log.sh` | Optional log rotation for 5g-router.log |
|
||
| `/etc/init.d/5g-router` | OpenRC service |
|
||
| `/etc/init.d/iptables-restore` | Firewall restore service |
|
||
| `/etc/iptables/rules.v4` | Saved firewall rules (from repo `etc/iptables/rules.v4`) |
|
||
| `/etc/dnsmasq.conf` | DHCP configuration (if using dnsmasq) |
|
||
| `/var/log/5g-router.log` | Connection log |
|
||
| `/var/log/speedtest-5g.log` | Optional speedtest log |
|
||
|
||
## Troubleshooting
|
||
|
||
### Modem not up (WAN down, no IP)
|
||
|
||
**On the device**, run the modem/WAN diagnostic:
|
||
|
||
```bash
|
||
/usr/local/bin/diag-modem-up.sh
|
||
```
|
||
|
||
It reports service status, modem USB (Mode 40 vs 41), WAN interface state, AT port, last log lines, and suggested fixes. See [docs/WEBGUI.md](docs/WEBGUI.md) → Troubleshooting: Modem not up.
|
||
|
||
### Modem not responding to AT commands
|
||
|
||
1. Check modem is in Mode 40: `lsusb | grep 7126`
|
||
2. Use `/dev/ttyUSB1` for AT commands
|
||
3. Don't use `stty` - send commands directly
|
||
|
||
### DHCP not working on eth1
|
||
|
||
This is normal - RNDIS mode doesn't provide DHCP. Configure IP manually using the address from `AT+CGPADDR=1`.
|
||
|
||
### Connection drops
|
||
|
||
Re-run the connection script:
|
||
```bash
|
||
/usr/local/bin/connect-5g.sh
|
||
```
|
||
|
||
Or restart the service:
|
||
```bash
|
||
service 5g-router restart
|
||
```
|
||
|
||
## Verification Commands
|
||
|
||
```bash
|
||
# Status script (modem, interface, default route, last speedtest)
|
||
/usr/local/bin/status-5g.sh
|
||
/usr/local/bin/status-5g.sh --json
|
||
|
||
# Diagnostics (run on device to debug modem/WAN or AT port)
|
||
/usr/local/bin/diag-modem-up.sh # why modem not up
|
||
/usr/local/bin/diag-at-port.sh # why no AT data in Web GUI
|
||
|
||
# Health check (for Nagios / Uptime Kuma)
|
||
/usr/local/bin/healthcheck-5g.sh
|
||
|
||
# Manual checks
|
||
lsusb | grep -i fibocom
|
||
ip addr show eth1
|
||
ip route show
|
||
ping -c 3 8.8.8.8
|
||
iptables -t nat -L -n -v
|
||
tail -f /var/log/5g-router.log
|
||
```
|
||
|
||
## Optional: scheduled speedtest and log rotation
|
||
|
||
```bash
|
||
# Cron: speedtest every 6 hours, log rotation daily
|
||
# Add to crontab -e (root):
|
||
# 0 */6 * * * /usr/local/bin/speedtest-5g.sh
|
||
# 0 3 * * * /usr/local/bin/rotate-5g-log.sh
|
||
```
|