161 lines
5.2 KiB
Markdown
161 lines
5.2 KiB
Markdown
|
A
|
# Unit 11 — README.md
|
||
|
|
|
||
|
|
## Goal
|
||
|
|
Write the main `README.md` at the project root. This is the last unit — written after all code exists.
|
||
|
|
|
||
|
|
## File
|
||
|
|
- `README.md`
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Required Sections
|
||
|
|
|
||
|
|
### Header
|
||
|
|
- Project name + one-line description
|
||
|
|
- Badges (optional): Python version, license
|
||
|
|
|
||
|
|
### Architecture Diagram
|
||
|
|
Copy from `design.md`:
|
||
|
|
```
|
||
|
|
┌─────────────────────────────────────────┐
|
||
|
|
│ Server Host (srsRAN gNB) │
|
||
|
|
│ - srsRAN gNB │
|
||
|
|
│ - Open5GS Core (or free5gc) │
|
||
|
|
│ - Subscriber database │
|
||
|
|
└─────────────┬───────────────────────────┘
|
||
|
|
│ 5G NR
|
||
|
|
▼
|
||
|
|
┌─────────────────────────────────────────┐
|
||
|
|
│ UE WiFi AP Drop │
|
||
|
|
│ (Android device or Raspberry Pi) │
|
||
|
|
│ - WiFi AP (open network) │
|
||
|
|
│ - eSIM Provisioning Server │
|
||
|
|
│ - Captive Portal │
|
||
|
|
└─────────────┬───────────────────────────┘
|
||
|
|
│ WiFi
|
||
|
|
▼
|
||
|
|
End User Devices
|
||
|
|
```
|
||
|
|
|
||
|
|
### User Flow (numbered list)
|
||
|
|
1. User connects to open WiFi `Emergency-5G`
|
||
|
|
2. Captive portal auto-redirects to activation page
|
||
|
|
3. User taps "Activate eSIM"
|
||
|
|
4. Server generates IMSI/Ki/OPc/ICCID
|
||
|
|
5. eSIM profile downloaded to device
|
||
|
|
6. User installs profile via Settings
|
||
|
|
7. Device connects to 5G network automatically
|
||
|
|
|
||
|
|
### System Requirements
|
||
|
|
|
||
|
|
**Raspberry Pi:**
|
||
|
|
- Raspberry Pi 4 (4GB+ RAM)
|
||
|
|
- Quectel RM500Q 5G modem (or compatible)
|
||
|
|
- Raspberry Pi OS Lite 64-bit
|
||
|
|
- Python 3.11+
|
||
|
|
|
||
|
|
**Android:**
|
||
|
|
- Android 9+ with Termux (F-Droid)
|
||
|
|
- 5G-capable device
|
||
|
|
- Pre-provisioned SIM for gNB backhaul
|
||
|
|
|
||
|
|
**End-user devices:**
|
||
|
|
- eSIM-capable device (eUICC support)
|
||
|
|
- Any OS (Android, iOS, Windows)
|
||
|
|
|
||
|
|
### Quick Start (5 commands)
|
||
|
|
```bash
|
||
|
|
git clone <repo>
|
||
|
|
cd esim-provisioning
|
||
|
|
python3 -m venv venv && source venv/bin/activate
|
||
|
|
pip install -r requirements.txt
|
||
|
|
cp config.yaml.example config.yaml # edit as needed
|
||
|
|
python scripts/init_db.py
|
||
|
|
python -m server.app
|
||
|
|
# → Server running at http://localhost:5000
|
||
|
|
```
|
||
|
|
|
||
|
|
### Configuration Guide
|
||
|
|
|
||
|
|
Key `config.yaml` fields:
|
||
|
|
|
||
|
|
| Field | Description | Example |
|
||
|
|
|-------|-------------|---------|
|
||
|
|
| `network.mcc` | Mobile Country Code | `"302"` |
|
||
|
|
| `network.mnc` | Mobile Network Code | `"720"` |
|
||
|
|
| `network.op_key` | Operator key (hex, 16 bytes) | `"63bfa..."` |
|
||
|
|
| `wifi.ip` | WiFi AP IP address | `"192.168.4.1"` |
|
||
|
|
| `database.path` | SQLite database path | `"/opt/.../subscribers.db"` |
|
||
|
|
| `rate_limiting.window_hours` | Rate limit window | `1` |
|
||
|
|
| `core.type` | Core adapter | `"open5gs"` / `"none"` |
|
||
|
|
| `core.mongodb_uri` | MongoDB connection | `"mongodb://localhost:27017"` |
|
||
|
|
|
||
|
|
### Raspberry Pi Installation
|
||
|
|
Reference `scripts/setup_wifi_ap.sh` for automated setup, or follow manual steps from `configs/` directory.
|
||
|
|
|
||
|
|
### Android / Termux Installation
|
||
|
|
```bash
|
||
|
|
bash android/termux_setup.sh
|
||
|
|
~/esim-provisioning/start.sh
|
||
|
|
```
|
||
|
|
See `android/README.md` for detailed instructions and limitations.
|
||
|
|
|
||
|
|
### API Reference
|
||
|
|
| Endpoint | Method | Description |
|
||
|
|
|----------|--------|-------------|
|
||
|
|
| `/activate` | GET | Captive portal page |
|
||
|
|
| `/api/provision` | POST | Generate eSIM profile |
|
||
|
|
| `/api/profile/<id>` | GET | Download profile |
|
||
|
|
| `/api/export` | GET | Export all subscribers (JSON) |
|
||
|
|
| `/api/status` | GET | Health check |
|
||
|
|
|
||
|
|
### Troubleshooting
|
||
|
|
|
||
|
|
**Profile generation fails:**
|
||
|
|
```
|
||
|
|
Check: python -c "from server.profile_generator import generate_ki; print(generate_ki().hex())"
|
||
|
|
Check: OP key is 32 hex chars (16 bytes) in config.yaml
|
||
|
|
```
|
||
|
|
|
||
|
|
**Captive portal not showing:**
|
||
|
|
```
|
||
|
|
Check: nslookup google.com 192.168.4.1 → should return 192.168.4.1
|
||
|
|
Check: systemctl status dnsmasq nginx
|
||
|
|
Check: iptables -t nat -L PREROUTING
|
||
|
|
```
|
||
|
|
|
||
|
|
**5G authentication fails after eSIM install:**
|
||
|
|
```
|
||
|
|
Check: IMSI/Ki/OPc in subscriber database matches what's in Open5GS
|
||
|
|
Check: PLMN (MCC+MNC) matches gNB configuration
|
||
|
|
Check: python scripts/sync_subscribers.py
|
||
|
|
Check: Open5GS UDM/AMF logs: journalctl -u open5gs-udmd
|
||
|
|
```
|
||
|
|
|
||
|
|
**Rate limit blocking legitimate user:**
|
||
|
|
```sql
|
||
|
|
-- Find and clear rate limit for a MAC:
|
||
|
|
sqlite3 /path/to/subscribers.db \
|
||
|
|
"DELETE FROM subscribers WHERE mac_address='aa:bb:cc:dd:ee:ff';"
|
||
|
|
```
|
||
|
|
|
||
|
|
### Architecture Notes
|
||
|
|
- **Adapter pattern**: Adding a new core (e.g., srsRAN-CN) requires only a new class in `server/core_adapters/`
|
||
|
|
- **IMSI space**: 10^10 possible MSINs per MCC+MNC — effectively unlimited for field use
|
||
|
|
- **Rate limiting**: Per MAC address, 1 profile per hour window. SQLite-backed, survives restarts
|
||
|
|
- **Profile format**: Phase 1 mock (JSON bytes). Phase 2: real SGP.22 via pySim for eUICC compatibility
|
||
|
|
|
||
|
|
### License
|
||
|
|
MIT (or as appropriate for deployment context)
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Writing Notes
|
||
|
|
|
||
|
|
When writing the actual README.md:
|
||
|
|
- Keep it scannable — use tables, code blocks, headers
|
||
|
|
- Lead with the architecture diagram
|
||
|
|
- Quick Start must work in <5 minutes on a fresh Pi
|
||
|
|
- Troubleshooting section is critical — include it prominently
|
||
|
|
- Do not duplicate design.md — link to it for deep dives
|