https://github.com/ktauchathuranga/openwall
Write. Feel. Be heard. | Hosted on a ESP32
https://github.com/ktauchathuranga/openwall
esp32 hacktoberfest openwall
Last synced: 2 months ago
JSON representation
Write. Feel. Be heard. | Hosted on a ESP32
- Host: GitHub
- URL: https://github.com/ktauchathuranga/openwall
- Owner: ktauchathuranga
- License: mit
- Created: 2025-09-06T06:03:06.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-10-13T14:15:43.000Z (8 months ago)
- Last Synced: 2026-02-11T15:22:32.730Z (4 months ago)
- Topics: esp32, hacktoberfest, openwall
- Language: C++
- Homepage:
- Size: 303 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# OpenWall - Write. Feel. Be heard.
A standalone ESP32-based web application for collecting and displaying poems, quotes, and thoughts.
## Hardware Requirements
- ESP32 Development Board
- MicroSD Card Module (optional for testing)
- MicroSD Card formatted as FAT32 (optional for testing)
- Wiring connections:
```
ESP32 SD Card Module
----- --------------
GPIO 5 --> CS
GPIO 23 --> MOSI
GPIO 19 --> MISO
GPIO 18 --> SCK
3.3V --> VCC
GND --> GND
```
## Software Requirements
### For ESP32:
- Arduino CLI or Arduino IDE
- ESP32 Board Support Package (version 3.x+)
- Required Libraries:
- WiFi (built-in)
- WebServer (built-in)
- SD (built-in)
- SPI (built-in)
- ESPmDNS (built-in)
- ArduinoJson (install via Library Manager)
- mbedtls (built-in with ESP32)
### For Web Development:
- Python 3.x (for build script)
- Make (optional, for Makefile)
### For Admin Credentials Tool:
- Rust (latest stable version)
- Cargo
## Project Structure
```
openwall/
├── build_web.py # web files updater
├── Cargo.lock # dep info.
├── Cargo.toml # credential conf
├── LICENSE # you know what this is
├── Makefile # full automated build
├── openwall.ino # esp32 source code
├── README.md # dude, really?
├── src
│ └── main.rs # credential helper source code
├── web
│ ├── admin.html # admin panel web source
│ └── index.html # public web source
└── web_pages.h # auto generated file containing web pages [DO NOT MANUALLY EDIT THIS FILE]
```
## Installation
### 1. Install Arduino CLI
**Linux:**
```bash
curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | sh
```
**Windows:**
```powershell
winget install ArduinoSA.CLI
```
### 2. Setup Arduino CLI
```bash
# Initialize configuration
arduino-cli config init
# Add ESP32 board support
arduino-cli config add board_manager.additional_urls https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
# Update package index
arduino-cli core update-index
# Install ESP32 platform
arduino-cli core install esp32:esp32
# Install ArduinoJson library
arduino-cli lib install "ArduinoJson"
```
### 3. Clone or Download Project
```bash
git clone https://github.com/ktauchathuranga/openwall.git
cd openwall
```
### 4. Configure the Project
Open `openwall.ino` and modify these settings:
```cpp
// SD Card: Set to true when you have SD card, false for in-memory testing
#define USE_SD_CARD false
// mDNS hostname (access via openwall.local)
#define MDNS_HOSTNAME "openwall"
// WiFi Mode: true = Access Point, false = Connect to existing WiFi
#define WIFI_MODE_AP true
// If AP mode (WIFI_MODE_AP = true):
#define AP_SSID "OpenWall"
#define AP_PASSWORD "openwall2024"
// If Station mode (WIFI_MODE_AP = false):
#define STA_SSID "YourWiFiSSID"
#define STA_PASSWORD "YourWiFiPassword"
// IMPORTANT: Change this to your own secret key
#define SECRET_KEY "your-super-secret-key-change-this-12345"
// SD Card pins (adjust if needed)
#define SD_CS_PIN 5
#define SD_MOSI_PIN 23
#define SD_MISO_PIN 19
#define SD_SCK_PIN 18
```
## Building and Uploading
### Method 1: Using Makefile (Recommended)
```bash
# Build web files, compile, upload, and monitor
make flash
# Just build and upload
make all upload
# Only convert web files
make web
# Only compile
make build
# Monitor serial output
make monitor
# Clean build artifacts
make clean
```
### Method 2: Manual Commands
```bash
# 1. Convert web files to C++ header
python3 build_web.py
# 2. Find your ESP32 port
arduino-cli board list
# 3. Compile
arduino-cli compile --fqbn esp32:esp32:esp32 openwall.ino
# 4. Upload (replace /dev/ttyUSB0 with your port)
arduino-cli upload -p /dev/ttyUSB0 --fqbn esp32:esp32:esp32 openwall.ino
# 5. Monitor serial output
arduino-cli monitor -p /dev/ttyUSB0 -c baudrate=115200
```
## Web Development Workflow
### 1. Edit HTML Files
Edit files in the `web/` directory:
- `web/index.html` - Main public page
- `web/admin.html` - Admin panel
### 2. Test in Browser (Optional)
```bash
# Serve files locally for testing
cd web
python3 -m http.server 8000
# Open browser to http://localhost:8000/index.html
```
### 3. Build and Deploy
```bash
# Convert HTML to C++ and upload
make flash
# Or manually:
python3 build_web.py
arduino-cli compile --fqbn esp32:esp32:esp32 openwall.ino
arduino-cli upload -p /dev/ttyUSB0 --fqbn esp32:esp32:esp32 openwall.ino
```
## Usage
### Accessing the Main Page
**Access via mDNS (if in Station mode):**
```
http://openwall.local
```
**Access via IP:**
- AP Mode: Connect to "OpenWall" WiFi, then visit `http://192.168.4.1`
- Station Mode: Check Serial Monitor for IP address
### Submitting Content
1. Click "Submit Your Memo" button
2. Write your poem/quote (max 200 characters)
3. Click Submit
4. Wait for admin approval
### Admin Access
#### Build Admin Credentials Tool (One Time)
```bash
cd admin_tool
cargo build --release
# IMPORTANT: Edit main.rs and change SECRET_KEY to match openwall.ino
nano main.rs
# Change: const SECRET_KEY: &str = "your-super-secret-key-change-this-12345";
cargo build --release
```
#### Get Daily Admin Credentials
```bash
# Run the tool
./target/release/openwall
# Or on Windows:
target\release\openwall.exe
```
Output will show:
```
+========================================================+
| OpenWall Admin Credentials |
+========================================================+
| Date (Asia/Colombo): 2025-10-10 |
+========================================================+
| Admin URL: |
| /admin_abc123456789 |
+========================================================+
| Username: admin |
+========================================================+
| Password: |
| 1a2b3c4d5E6F7G8H!@#$9i0j1k2l |
+========================================================+
Full Admin URL: http://[YOUR_ESP32_IP]/admin_abc123456789
```
#### Access Admin Panel
1. Visit the full admin URL (e.g., `http://openwall.local/admin_abc123456789`)
2. Enter username: `admin`
3. Enter password from the tool output
4. Approve, reject, or delete submissions
### Admin Panel Features
- **Statistics Dashboard**: View pending, approved, and total counts
- **Pending Tab**: Review and approve/reject new submissions
- **Approved Tab**: View all approved memos and delete if needed
- **Auto-refresh**: Panel refreshes every 30 seconds
## Configuration Options
### Change Timezone
```cpp
// In openwall.ino
#define GMT_OFFSET_SEC 19800 // Asia/Colombo = UTC+5:30
// Change to your timezone offset in seconds
```
### Adjust Rate Limits
```cpp
#define MAX_SUBMISSIONS_PER_DAY 2 // Submissions per IP per day
#define MAX_REQUESTS_PER_10MIN 10 // Requests per IP per 10 min
#define MAX_REQUESTS_PER_SECOND 10 // Requests per IP per second
```
### Change Posts Per Page
In `web/index.html`, modify:
```javascript
const limit = 3; // Number of posts per page
```
### Custom SD Card Pins
```cpp
#define SD_CS_PIN 5
#define SD_MOSI_PIN 23
#define SD_MISO_PIN 19
#define SD_SCK_PIN 18
```
### Change mDNS Hostname
```cpp
#define MDNS_HOSTNAME "openwall" // Access via openwall.local
```
## Data Storage
### With SD Card (USE_SD_CARD = true)
- Pending submissions: `/pending.csv` on SD card
- Approved posts: `/approved.csv` on SD card
- Format: `timestamp,"content","ip_address"`
- Data persists across reboots
### Without SD Card (USE_SD_CARD = false)
- Pending submissions: In RAM (std::vector)
- Approved posts: In RAM (std::vector)
- Data lost on reboot (for testing only)
## Security Notes
1. **Change the SECRET_KEY** in both `openwall.ino` and `admin_creds.rs`
2. Admin URL and password change daily at midnight Asia/Colombo time
3. Rate limiting prevents spam (2 submissions per day per IP)
4. DDoS protection limits requests per IP
5. All submissions require admin approval before appearing on the wall
6. Admin panel uses HTTP Basic Authentication
## Troubleshooting
### SD Card Not Detected
- Check wiring connections
- Ensure SD card is formatted as FAT32
- Try a different SD card
- Verify SD_CS_PIN matches your module
- Set `USE_SD_CARD false` to test without SD card
### WiFi Connection Failed
- Verify SSID and password are correct
- Check WiFi signal strength
- ESP32 only supports 2.4GHz WiFi (not 5GHz)
- Try AP mode if Station mode fails
### mDNS Not Working (openwall.local not resolving)
- mDNS works best in Station mode (connected to WiFi)
- In AP mode, use IP address instead
- Check if your device supports mDNS:
- Linux: Install avahi-daemon
- Windows 10+: Built-in support
- Use IP address as fallback
### Time Not Syncing
- Ensure ESP32 has internet connection (Station mode only)
- Check NTP_SERVER setting
- In AP mode, time sync won't work (uses uptime instead)
- Admin credentials will still work with fallback time
### Admin Credentials Don't Match
- Ensure SECRET_KEY is identical in both `openwall.ino` and `main.rs`
- Verify timezone is correct (Asia/Colombo)
- Check if date is correct on both systems
- Rebuild Rust tool after changing SECRET_KEY
### Cannot Upload to ESP32
- Check USB cable (must be data cable, not charge-only)
- Verify correct port with `arduino-cli board list`
- Press and hold BOOT button during upload
- Try different upload speed: `--upload-speed 115200`
- Check USB permissions on Linux: `sudo usermod -a -G dialout $USER`
### Compilation Errors
- Ensure ESP32 core version 3.x+ is installed
- Update ArduinoJson: `arduino-cli lib upgrade ArduinoJson`
- Clean build: `make clean && make build`
- Check for syntax errors in web files
### Web Pages Not Loading
- Run `python3 build_web.py` before compiling
- Check Serial Monitor for errors
- Verify `web_pages.h` file exists
- Try accessing via IP address instead of mDNS
## Development Tips
### Editing Web Interface
1. Edit HTML files in `web/` directory
2. Test in browser: `python3 -m http.server 8000` in web/ folder
3. Convert to C++: `python3 build_web.py`
4. Upload: `make upload`
### Adding New Web Pages
1. Create HTML file in `web/` directory
2. Edit `build_web.py` to add new file:
```python
pages = {
'index.html': 'INDEX_HTML',
'admin.html': 'ADMIN_HTML',
'newpage.html': 'NEWPAGE_HTML' # Add this
}
```
3. Run `python3 build_web.py`
4. In `openwall.ino`, add route:
```cpp
server.on("/newpage", [](){
server.send_P(200, "text/html", NEWPAGE_HTML);
});
```
### Debugging
Enable verbose output:
```bash
arduino-cli compile --fqbn esp32:esp32:esp32 --verbose openwall.ino
arduino-cli upload -p /dev/ttyUSB0 --fqbn esp32:esp32:esp32 --verbose openwall.ino
```
Monitor serial output:
```bash
arduino-cli monitor -p /dev/ttyUSB0 -c baudrate=115200
```
## License
This project is open source and available for personal and educational use.
## Contributing
Contributions are welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request