A decentralized mesh network flood early warning system built in Rust for the Rust Africa Hackathon 2026.
FloodPulse is a real-time flood monitoring and alert system designed for urban drainage networks. It uses a mesh network of sensor nodes to detect rising water levels, propagate alerts downstream, and visualize flood conditions through a web-based dashboard.
The system targets Lagos, Nigeria as a demonstration scenario, modeling the city's drainage infrastructure to showcase how early warnings can cascade through a sensor network before flooding reaches downstream areas.
floodpulse/
├── crates/
│ ├── core/ # Shared types and simulation logic (no_std compatible)
│ ├── server/ # WebSocket server and simulation runner
│ └── firmware/ # Embedded firmware for ESP32/RP2040 sensor nodes
└── web/ # Browser-based visualization dashboard
The floodpulse-core crate provides platform-agnostic types and algorithms:
- Node: Sensor node state machine with status (Normal, Warning, Alert, Offline)
- MeshNetwork: Network topology and message routing between nodes
- FloodModel: Water propagation physics and rainfall simulation
- AlertCascade: Threshold detection and downstream alert propagation
The core library supports no_std environments for embedded targets while also working in standard library contexts.
The floodpulse-server crate runs the simulation and serves the web interface:
- Real-time simulation of water levels and flood propagation
- WebSocket API for live state updates and control commands
- REST endpoints for simulation control (start, pause, reset, trigger rain)
- Static file serving for the web dashboard
The floodpulse-firmware crate targets embedded microcontrollers:
- ESP32-C3: RISC-V based WiFi/BLE SoC
- RP2040: ARM Cortex-M0+ (Raspberry Pi Pico)
Uses Embassy async runtime for concurrent sensor reading and LoRa mesh communication.
Browser-based visualization built with vanilla JavaScript and Leaflet.js:
- Real-time map of Lagos drainage network with sensor locations
- Node status indicators (color-coded by severity)
- Water level visualization
- Alert feed with cascade propagation
- Rainfall simulation controls
- Rust 1.75+ (2021 edition)
- Node.js (optional, for development server)
# Clone the repository
git clone https://github.com/your-username/floodpulse.git
cd floodpulse
# Build and run the server
cargo run -p floodpulse-serverOpen http://localhost:3000 in your browser to view the dashboard.
- Start: Begin the simulation
- Pause: Freeze the simulation state
- Reset: Clear all water levels and alerts
- Trigger Rain: Start a rainfall event on upstream nodes
# Run all tests
cargo test
# Run core library tests
cargo test -p floodpulse-core# Install the Rust ESP toolchain
rustup target add riscv32imc-unknown-none-elf
# Build with ESP32 feature
cd crates/firmware
cargo build --release --target riscv32imc-unknown-none-elf --features esp32# Install the ARM target
rustup target add thumbv6m-none-eabi
# Build with RP2040 feature
cd crates/firmware
cargo build --release --target thumbv6m-none-eabi --features rp2040Connect to ws://localhost:3000/ws for real-time updates.
Inbound Messages (Client to Server)
| Command | Description |
|---|---|
start |
Start the simulation |
pause |
Pause the simulation |
reset |
Reset all state |
rain:INTENSITY |
Trigger rain with intensity in mm/hr |
stop_rain |
Stop current rain event |
Outbound Messages (Server to Client)
| Event Type | Description |
|---|---|
Snapshot |
Full state with all nodes, alerts, and time |
Event |
Incremental update (water level, status change, alert) |
| Endpoint | Method | Description |
|---|---|---|
/api/status |
GET | Current simulation status |
/api/control/start |
POST | Start simulation |
/api/control/pause |
POST | Pause simulation |
/api/control/reset |
POST | Reset simulation |
/api/control/rain |
POST | Trigger rain (body: {"intensity": 100}) |
| Level | Threshold | Description |
|---|---|---|
| Normal | < 70% | Water level within safe limits |
| Warning | >= 70% | Prepare for possible flooding |
| Critical | >= 90% | Imminent flooding |
| Breach | >= 100% | Channel capacity exceeded |
- Rust: Core implementation language
- Tokio: Async runtime for the server
- Axum: HTTP/WebSocket server framework
- Embassy: Async embedded runtime for firmware
- Serde: Serialization for API and persistence
- Leaflet.js: Interactive map rendering
| Crate | Lines | Purpose |
|---|---|---|
floodpulse-core |
~700 | Shared types, mesh network, flood model |
floodpulse-server |
~600 | Simulation runner, HTTP/WS server |
floodpulse-firmware |
~100 | Embedded node firmware (template) |
MIT License. See LICENSE for details.
FloodPulse Team - Rust Africa Hackathon 2026