A self-contained, offline communication and coordination system for disaster relief scenarios inspired-by-piratebox. Turn your router into a lifeline when the internet goes down.
Core Features (Working ✅):
- ✅ Group chat system with real-time updates
- ✅ File sharing (up to 5GB files)
- ✅ SQLite database backend
- ✅ Offline-first architecture
- ✅ Multi-user support (20-50 concurrent)
In Development (Planned 🎯):
- 🎯 ATAK-style tactical mapping (offline OpenStreetMap)
- 🎯 Voice message support
See ATAK.md for planned mapping features and COMPETITION.md for project positioning.
- Overview
- Features
- Hardware Requirements
- Quick Start
- Technology Stack
- Architecture
- Security Considerations
- User Interface
- Documentation
- Contributing
- License
EmergencyBox transforms an ASUS RT-AC68U router into a standalone Wi-Fi hotspot that provides critical communication infrastructure when traditional networks fail. Designed specifically for disaster relief, emergency response, and remote coordination scenarios where internet connectivity is unavailable or compromised.
- No Internet Required - Operates completely offline on an isolated network
- Instant Deployment - Plug in, power on, connect
- Multi-User Support - 20-50 concurrent users on a single router
- Disaster-Resilient - Built for harsh environments and unreliable power
- No Authentication - By design for emergency scenarios - anyone can connect and help
- Router-Based - Leverages existing hardware, no servers needed
- Disaster Relief Operations - Coordinate rescue teams, share critical information
- Emergency Response - First responder communication in infrastructure-down scenarios
- Remote Communities - Communication hub for areas without internet access
- Field Operations - Military, research expeditions, construction sites
- Event Coordination - Large gatherings in remote locations
- Anonymous Messaging - No account creation, no login required
- Priority Messages - Flag urgent communications for visibility
- File Linking - Reference shared files directly in chat messages
- Real-Time Updates - 2-second polling for near-instant message delivery
- Message Persistence - SQLite database stores complete chat history
- Username Support - Optional usernames for coordination (not authentication)
- Large File Support - Upload files up to 1GB (configurable to 5GB+)
- Category Organization - Emergency, Media, Documents, General folders
- Custom Folders - Create new directories on-the-fly
- Progress Tracking - Visual upload progress with speed and ETA
- File Browser - Search, filter, and download shared resources
- File Metadata - Automatic file type detection and size formatting
- Offline OpenStreetMap Tiles - Pre-downloaded maps for disaster areas
- Tactical Markers - Hazards, safe zones, medical, water sources, meeting points
- Distance & Area Tools - Measure distances and areas for planning
- Route Planning - Multi-waypoint route creation with distance calculation
- Coordinate Sharing - Share locations directly in group chat
- Photo Markers - Attach photos to map locations
- Geolocation Tracking - Optional GPS position sharing (client-side)
- Layer Filtering - Toggle marker types on/off for clarity
See ATAK.md for complete tactical mapping specification and implementation roadmap.
- Zero Internet Dependency - All processing on-router
- SQLite Backend - Embedded database, no external services
- Vanilla JavaScript - No CDN dependencies, works completely offline
- USB Storage - Expandable storage via USB drives
- Auto-Recovery - Survives power cycles and router reboots
- Announcements - Broadcast important messages to all users
- Chat Moderation - Clear chat history when needed
- File Management - Delete files, manage storage
- System Monitoring - Connection status, user count
- Voice Messages - Record and share audio messages
- Image Thumbnails - Preview images in file browser
- Message Search - Search chat history
Primary Support:
- ASUS RT-AC68U (Recommended)
- ASUS RT-AC66U
- ASUS RT-N66U
Potentially Compatible:
- Other ASUS routers with ARM architecture
- High-end DD-WRT compatible routers (256MB+ RAM)
| Requirement | Minimum | Recommended |
|---|---|---|
| RAM | 256MB | 512MB+ |
| CPU | ARM Cortex-A9 | Dual-core 1GHz+ |
| Firmware | DD-WRT or Asuswrt-Merlin | DD-WRT (better PHP support) |
| USB Port | USB 2.0 | USB 3.0 |
Two-Partition Setup:
-
Partition 1 (Entware) - ext4 filesystem
- Minimum: 2GB
- Stores: Entware packages, PHP, lighttpd, SQLite
-
Partition 2 (Data) - ext4 filesystem
- Minimum: 8GB
- Recommended: 32GB - 128GB
- Stores: Web application, uploads, database
USB Drive Recommendations:
- USB 3.0 for faster transfers
- ext4 formatted (not FAT32)
- Quality brands for reliability (SanDisk, Samsung, Kingston)
- Consider dual-USB setup for redundancy
- WiFi Standard: 802.11ac (5GHz) or 802.11n (2.4GHz)
- Expected Range: 150-300 feet indoors
- Concurrent Users: 20-30 recommended, 50 maximum
- IP Configuration: Static IP recommended (192.168.1.1)
- ASUS RT-AC68U router with DD-WRT firmware
- USB drive (8GB+, formatted as ext4)
- SSH access to router
- Basic Linux command line knowledge
# 1. SSH into your router
ssh root@192.168.1.1
# 2. Install Entware package manager
wget -O - http://bin.entware.net/armv7sf-k3.2/installer/generic.sh | sh
opkg update
# 3. Install required packages
opkg install php8-cli php8-cgi php8-mod-sqlite3 php8-mod-fileinfo \
lighttpd lighttpd-mod-fastcgi sqlite3-cli
# 4. Deploy EmergencyBox from your computer
cd emergencybox
chmod +x deploy.sh
./deploy.sh 192.168.1.1 root
# 5. Access the interface
# Open browser: http://192.168.1.1- Connect to the router's WiFi network
- Navigate to
http://192.168.1.1in your browser - Test sending a chat message
- Upload a small file to verify file sharing
- Refresh page to confirm message persistence
- Read INSTALLATION.md for detailed setup
- Review USAGE.md for user guide
- Check QUICK_START.md for fast reference
| Component | Technology | Version | Purpose |
|---|---|---|---|
| Web Server | lighttpd | Latest | Lightweight HTTP server optimized for embedded systems |
| Application | PHP | 8.4.7 | Server-side scripting and API layer |
| Database | SQLite3 | 3.x | Embedded relational database for messages |
| Package Manager | Entware | Latest | ARM package repository for DD-WRT |
| Firmware | DD-WRT | Latest | Router operating system |
| Component | Technology | Why |
|---|---|---|
| HTML5 | Semantic markup | Modern, accessible interface |
| CSS3 | Custom cyberpunk theme | No framework overhead |
| JavaScript | Vanilla ES6+ | Zero dependencies, works offline |
| AJAX | XMLHttpRequest | Polling-based real-time updates |
USB Drive (ext4)
├── /opt/share/www/ # Web application root
│ ├── index.html # Main interface
│ ├── admin.html # Admin panel
│ ├── css/style.css # Cyberpunk theme
│ ├── js/app.js # Frontend logic
│ ├── api/*.php # Backend APIs
│ └── uploads/ # File storage
│ ├── emergency/
│ ├── media/
│ ├── documents/
│ └── general/
└── /opt/share/data/
└── emergencybox.db # SQLite database
| Endpoint | Method | Purpose |
|---|---|---|
/api/send_message.php |
POST | Send chat message |
/api/get_messages.php |
GET | Retrieve chat history |
/api/delete_message.php |
POST | Delete specific message |
/api/clear_chat.php |
POST | Clear all messages |
/api/upload.php |
POST | Upload file with chunking |
/api/get_files.php |
GET | List uploaded files |
/api/delete_file.php |
POST | Delete uploaded file |
/api/set_announcement.php |
POST | Set announcement banner |
/api/get_announcement.php |
GET | Retrieve current announcement |
/api/clear_announcement.php |
POST | Clear announcement |
/api/init_db.php |
GET | Initialize database schema |
EmergencyBox is built on three core principles:
- Offline-First - No external dependencies, no internet required
- Router-Based - Leverage existing hardware, minimal additional equipment
- Emergency-Ready - Simple, reliable, works when everything else fails
┌─────────────────────────────────────────────────────────────┐
│ USERS (Devices) │
│ 📱 Smartphones 💻 Laptops 📱 Tablets 🖥️ Desktops │
└──────────────┬──────────────────────────────────────────────┘
│
│ WiFi (802.11ac/n)
│ No Internet Required
│
┌──────────────▼──────────────────────────────────────────────┐
│ ASUS RT-AC68U Router (DD-WRT) │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ EmergencyBox Application │ │
│ │ │ │
│ │ Frontend (HTML/CSS/JS) ←→ Backend (PHP APIs) │ │
│ │ ↓ ↓ │ │
│ │ Browser Display SQLite Database │ │
│ │ ↓ │ │
│ │ File Storage (USB) │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ System Services (Entware) │ │
│ │ • lighttpd (Web Server) │ │
│ │ • PHP 8.4.7 (FastCGI) │ │
│ │ • SQLite3 (Database Engine) │ │
│ └─────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
│ USB 3.0 Connection
│
┌──────────────▼──────────────────────────────────────────────┐
│ USB Storage Drive │
│ Partition 1: Entware (ext4, 2GB) │
│ Partition 2: Data (ext4, 8-128GB) │
└─────────────────────────────────────────────────────────────┘
Advantages over traditional server deployments:
- Portability - Fits in a backpack, deploy anywhere
- Power Efficiency - 15W power consumption vs 200W+ for servers
- Built-in WiFi - No additional access points needed
- Cost-Effective - Use existing hardware, under $50 used
- Familiar Interface - Everyone knows how to connect to WiFi
- Battery Compatible - Can run on portable power banks
- Rugged - Designed for consumer use, handles temperature/humidity
Partition 1 (Entware):
- System packages and dependencies
- Survives across EmergencyBox updates
- Can be reused for other router projects
Partition 2 (Data):
- Application code and user data
- Easy backup and restore
- Swappable between routers for redundancy
- Can be mounted read-only for security
- Embedded - No separate database server process
- Reliable - ACID compliant, handles power failures
- Fast - Sufficient for 50 concurrent users
- Simple - Single file database, easy backup
- Portable - Database file can be moved between systems
- Availability - DD-WRT has mature PHP packages
- Performance - Sufficient for embedded use
- Ecosystem - Large library of code examples
- SQLite Support - Native PHP-SQLite integration
- Low Memory - Runs in 256MB RAM environments
EmergencyBox is designed for offline, isolated, trusted networks in emergency scenarios. It is NOT designed for internet-facing or hostile environments.
| Security Feature | Status | Notes |
|---|---|---|
| Input Sanitization | ✅ Implemented | PHP input filtering on all endpoints |
| SQL Injection Prevention | ✅ Implemented | Parameterized SQLite queries |
| Path Traversal Protection | ✅ Implemented | File upload directory restrictions |
| File Type Validation | ✅ Implemented | MIME type checking |
| XSS Prevention | ✅ Implemented | Output escaping in JavaScript |
| CSRF Tokens | ❌ Not implemented | Not needed for offline use |
| Rate Limiting | Simple flood protection |
| Security Feature | Status | Rationale |
|---|---|---|
| User Authentication | ❌ By design | Emergency scenarios require open access |
| Encryption (HTTPS) | ❌ Not implemented | Local network, self-signed certs problematic |
| File Malware Scanning | ❌ Not implemented | No AV available for ARM routers |
| Access Control Lists | ❌ Not implemented | All users trusted in disaster scenarios |
| Audit Logging | Basic logs only, no user tracking | |
| Content Filtering | ❌ Not implemented | Trusted user assumption |
If deploying in less-trusted environments:
- Enable WiFi Encryption - Use WPA2/WPA3 with strong passphrase
- Change Default Passwords - Router admin password must be changed
- Disable WAN Access - Block all external connections
- Add HTTPS - Generate self-signed certificates for encryption
- Implement Authentication - Add simple password protection
- Enable Logging - Monitor access and uploads
- Regular Backups - Backup database and critical files
- Network Isolation - Run on dedicated WiFi network
| Risk | Severity | Mitigation |
|---|---|---|
| Malicious File Upload | High | Manual review, trusted users only |
| Storage Exhaustion | Medium | Monitor disk space, set quotas |
| Chat Abuse/Spam | Low | Admin clear chat function |
| Unauthorized Access | Medium | WiFi password, physical security |
| Data Loss | Medium | Regular backups, redundant hardware |
For disaster relief deployments:
- Physical Security - Secure router in locked container
- WiFi Password - Share only with authorized personnel
- Data Review - Periodically review uploaded content
- Clean Shutdown - Backup before powering down
- Incident Response - Clear chat/files if compromised
EmergencyBox features a custom-designed cyberpunk aesthetic built for readability in low-light emergency conditions.
Color Palette:
- Cyber Cyan (#00f5ff) - Primary actions, links
- Cyber Pink (#ff006e) - Danger actions, priority messages
- Cyber Purple (#9d4edd) - Accents, hover states
- Cyber Yellow (#ffbe0b) - Warnings, announcements
- Cyber Green (#06ffa5) - Success states, online indicators
Design Features:
- Monospace font (Courier New) for terminal aesthetic
- Subtle grid background for depth
- Neon glow effects on interactive elements
- Dark backgrounds (#0a0e27) to reduce eye strain
- High contrast text for readability
┌────────────────────────────────────────────────────────┐
│ 📦 EmergencyBox - Offline Communication & File Sharing │
│ 🟢 42 users connected │
├─────────────────────┬──────────────────────────────────┤
│ GROUP CHAT │ FILE SHARING │
│ │ │
│ [Messages...] │ Upload File: [Browse...] │
│ User1: Hello │ Category: [Emergency ▼] │
│ User2: Copy that │ [Upload Button] │
│ 🔴 URGENT: Help! │ │
│ │ 📁 Emergency/ │
│ [Username: ____] │ map.pdf (2.3 MB) │
│ [Message: _____] │ contacts.xlsx (45 KB) │
│ ☑️ Priority │ 📁 Media/ │
│ 📎 Link File │ photo1.jpg (1.2 MB) │
│ [Send] │ 📁 Documents/ │
│ │ procedures.pdf (850 KB) │
└─────────────────────┴──────────────────────────────────┘
- Desktop (1200px+) - Two-column layout, full features
- Tablet (768px-1199px) - Stacked layout, touch-optimized
- Mobile (320px-767px) - Single column, simplified controls
- Semantic HTML5 markup
- ARIA labels on interactive elements
- Keyboard navigation support
- High contrast color scheme
- Scalable text (respects browser zoom)
Screenshots showing the EmergencyBox interface in action:
Main Interface:
- Split-panel view with chat on left, files on right
- Cyberpunk theme with cyan/pink accent colors
- Status bar showing online users
- Real-time message updates
File Upload:
- Drag-and-drop zone
- Progress bar with percentage and speed
- Category selection dropdown
- Custom folder creation
Priority Messages:
- Red/pink highlighted urgent messages
- Visual priority flag icon
- Stands out in chat stream
Admin Panel:
- Announcement banner controls
- System statistics
- Chat moderation tools
- File management interface
Comprehensive documentation is available in the repository:
| Document | Status | Description |
|---|---|---|
| INSTALLATION.md | ✅ Complete | Complete installation guide for DD-WRT and Asuswrt-Merlin |
| QUICK_START.md | ✅ Complete | Fast reference for experienced users |
| USAGE.md | ✅ Complete | End-user guide for chat and file sharing |
| DEVELOPMENT.md | ✅ Complete | Developer documentation for customization |
| PHP_COMPATIBILITY.md | ✅ Complete | Troubleshooting PHP installation issues |
| ATAK.md | ✅ Complete | ATAK-style tactical mapping specification and roadmap |
| COMPETITION.md | ✅ Complete | Competitive analysis vs POSM, FreeTAKServer, PirateBox, etc. |
| Document | Status | Description |
|---|---|---|
| DEPLOYMENT.md | 🎯 Planned | Advanced deployment scenarios, multi-router mesh |
| TROUBLESHOOTING.md | 🎯 Planned | Common issues and solutions |
| FIELD_GUIDE.md | 🎯 Planned | Quick reference card for disaster deployment |
Contributions are welcome! EmergencyBox is designed for humanitarian use, and we appreciate help improving its reliability and features.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- Code Style - Follow existing PHP and JavaScript conventions
- Testing - Test on actual hardware (ASUS RT-AC68U preferred)
- Documentation - Update relevant docs with your changes
- Humanitarian Focus - Keep emergency use cases in mind
- Offline-First - No external dependencies or internet requirements
High Priority:
- Automated testing framework
- Image thumbnail generation
- Multi-language support (i18n)
- Message search functionality
- Export chat history feature
Medium Priority:
- User nickname system (optional)
- Multiple chat rooms
- File preview modal
- Upload resumption on disconnect
- Admin authentication layer
Low Priority:
- Message editing/deletion
- Emoji picker
- Dark/light theme toggle
- Voice message upload
- QR code for quick WiFi sharing
Before submitting a PR, verify:
- Works on ASUS RT-AC68U with DD-WRT
- No external dependencies introduced
- Upload/download tested with 100MB+ files
- Multi-user concurrent access tested
- Database migrations (if applicable) tested
- No PHP errors in lighttpd logs
- Responsive design verified on mobile
- Documentation updated
MIT License
Copyright (c) 2024 EmergencyBox Contributors
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
EmergencyBox is specifically designed for humanitarian purposes including:
- Disaster relief operations
- Emergency response coordination
- Community resilience in remote areas
- Crisis communication scenarios
Organizations using EmergencyBox for humanitarian purposes are encouraged to share their experiences and contribute improvements back to the project.
Built with consideration for:
- Disaster relief workers worldwide
- Emergency first responders
- Remote communities without internet access
- Humanitarian organizations (Red Cross, FEMA, NGOs)
Inspired by:
- PirateBox - Original offline file sharing concept (discontinued 2015)
- LibraryBox - Educational offline content delivery
- POSM - Portable OpenStreetMap for humanitarian field mapping
- ATAK - Android Tactical Assault Kit for situational awareness
- FreeTAKServer - Open source TAK server
- DD-WRT Community - Firmware and support ecosystem
Special Thanks:
- ASUS for creating hackable, powerful routers
- DD-WRT developers for amazing firmware
- Entware maintainers for ARM package repository
- Open source community for tools and libraries
Current Version: 0.9 (Beta)
Status:
- Group chat with real-time updates
- File sharing (up to 5GB)
- SQLite database
- Admin panel (announcements, moderation)
- ATAK-style tactical mapping - Offline maps with markers, routes, measurements
- See ATAK.md for full specification
- Deployment testing and bug fixes
- Documentation improvements
(No promises, just things I'd like to try)
- Voice message recording
- Image thumbnails in file browser
- Message search
- Better performance optimizations
Note: This is a hobby project. I work on it when I have time. No fixed timeline or guarantees. If you want to help, contributions are welcome!
- GitHub Issues - Bug reports and feature requests
- GitHub Discussions - General questions and community help
- DD-WRT Forums - Router-specific technical support
Note: This is a hobby project by a solo developer. I'll help when I can, but response times vary. Community contributions are very welcome!
Q: Can I use this on other routers? A: Possibly. Any DD-WRT router with 256MB+ RAM and ARM architecture should work, but only ASUS RT-AC68U is officially supported.
Q: Why no HTTPS/encryption? A: Self-signed certificates cause browser warnings, confusing for non-technical users in emergencies. It's designed for isolated offline networks.
Q: How many users can it support? A: 20-30 concurrent users comfortably, up to 50 tested. Performance depends on upload/download activity.
Q: Can I access it from the internet? A: Not recommended. EmergencyBox is designed for local, offline use only.
Q: How do I backup the data?
A: Copy /opt/share/data/emergencybox.db and /opt/share/www/uploads/ via SCP.
Q: What happens if the router loses power? A: SQLite is ACID-compliant. Recent messages/files are preserved. Services auto-restart on boot.
Q: Can I customize the look?
A: Yes! Edit /www/css/style.css to change colors, fonts, layout. See DEVELOPMENT.md.
- Project Homepage: GitHub Repository
- Documentation: /docs
- Issue Tracker: GitHub Issues
- DD-WRT: https://dd-wrt.com
- Entware: https://github.com/Entware/Entware
Built for humanity, in times of crisis
When the internet fails, EmergencyBox connects
Made with ❤️ for disaster relief workers worldwide