Roomba WebUI 🤖

A complete, ready-to-build Dockerized project that provides a private "Roomba cloud" with a backend using dorita980 and a simple frontend UI. Control your iRobot Roomba vacuum cleaner from a web interface on your local network.

Features ✨

Web-based Control Interface: Clean, responsive UI for controlling your Roomba
Real-time Status Monitoring: Battery level, cleaning state, errors, and more
Secure API: All endpoints protected with API key authentication
Docker Ready: Easy deployment with Docker Compose
Persistent Storage: Roomba credentials saved securely to disk
Network Flexible: Supports both host networking and custom network configurations
Advanced Controls: Custom dorita980 method calls for power users

Quick Start 🚀

Prerequisites

Docker and Docker Compose installed
iRobot Roomba on the same LAN
Roomba BLID and password (see Getting Roomba Credentials)

1. Clone and Setup

git clone <your-repo-url>
cd doria980-webui
cp .env.example .env

2. Configure Environment

Edit .env and set your API key:

# Generate a secure API key
openssl rand -hex 32

# Edit .env file
API_KEY=your_generated_api_key_here
PORT=8080
ROOMBA_IP=  # Optional: leave empty for auto-discovery

3. Build and Run

# Build and start the service
docker-compose up --build -d

# Check logs
docker-compose logs -f roomba-ui

4. Access the Interface

Open your browser to http://localhost:8080 (or your configured port).

5. Configure Roomba Credentials

Click "⚙️ Settings & Configuration"
Enter your API key (from .env file)
Enter your Roomba BLID and password
Click "Set Credentials"

Getting Roomba Credentials 🔐

Your Roomba's BLID (Bluetooth Low Energy Identifier) and password are required for connection.

Method 1: Using the Helper Script (Recommended)

# Run the password helper for instructions
npm run getpassword

# Or inside Docker container:
docker exec -it roomba-webui npm run getpassword

Method 2: Using homebridge-roomba

# Install and run the password extraction tool
docker run -it --rm --net=host node:18-alpine sh -c "npm install -g homebridge-roomba && getpassword"

Method 3: Manual Process

Place Roomba on dock and ensure it's powered on
Hold HOME button until it plays tones (~2 seconds)
WiFi LED should start flashing
Use the homebridge-roomba getpassword utility
Follow the prompts to extract credentials

API Endpoints 📡

All endpoints require X-API-Key header with your API key.

GET /api/status

Returns current Roomba status including state, battery, charging status, and errors.

curl -H "X-API-Key: your_api_key" http://localhost:8080/api/status

POST /api/command

Send commands to Roomba: start, pause, stop, dock.

curl -X POST -H "X-API-Key: your_api_key" -H "Content-Type: application/json" \
  -d '{"command": "start"}' http://localhost:8080/api/command

POST /api/credentials

Set Roomba BLID and password.

curl -X POST -H "X-API-Key: your_api_key" -H "Content-Type: application/json" \
  -d '{"blid": "your_blid", "password": "your_password"}' http://localhost:8080/api/credentials

POST /api/custom

Call custom dorita980 methods.

curl -X POST -H "X-API-Key: your_api_key" -H "Content-Type: application/json" \
  -d '{"method": "getRobotState", "args": ["cleanMissionStatus", "batPct"]}' \
  http://localhost:8080/api/custom

GET /api/version

Get service and dependency versions.

curl -H "X-API-Key: your_api_key" http://localhost:8080/api/version

Docker Configuration Options 🐳

Default: Host Networking (Recommended)

The default docker-compose.yml uses host networking for easy Roomba discovery:

network_mode: "host"

Alternative: Custom Network (Advanced)

For custom network setups, uncomment the macvlan configuration in docker-compose.yml:

networks:
  roomba_network:
    driver: macvlan
    driver_opts:
      parent: eth0  # Change to your network interface
    ipam:
      config:
        - subnet: 192.168.1.0/24
          gateway: 192.168.1.1

Development 💻

Local Development

# Install dependencies
npm install

# Set environment variables
export API_KEY=your_api_key_here
export ROOMBA_IP=192.168.1.100  # Optional

# Start development server
npm run dev

Available Scripts

npm start - Start production server
npm run dev - Start development server with debugging
npm run build - Build check (no build step needed)
npm run getpassword - Show password extraction help

Security Considerations 🔒

API Key Protection

Generate strong API keys: openssl rand -hex 32
Never commit API keys to version control
Rotate keys regularly

Remote Access

For secure remote access, consider:

Tailscale (Recommended): Zero-config VPN
Reverse Proxy: nginx with HTTPS and basic auth
VPN: Connect to your home network securely

Example nginx configuration:

server {
    listen 443 ssl;
    server_name roomba.yourdomain.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    auth_basic "Roomba Control";
    auth_basic_user_file /etc/nginx/.htpasswd;
    
    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Network Security

Run on isolated VLAN if possible
Use strong WiFi passwords
Keep Roomba firmware updated
Monitor network traffic for anomalies

Troubleshooting 🔧

Connection Issues

Roomba not found:
- Ensure Roomba is on same network
- Try specifying ROOMBA_IP in .env
- Check if Roomba is awake (press CLEAN button)
Authentication failed:
- Verify BLID and password are correct
- Ensure no other apps are connected
- Try restarting Roomba
API key errors:
- Check X-API-Key header is included
- Verify API key matches .env file
- Ensure API_KEY environment variable is set

Container Issues

# Check container status
docker-compose ps

# View logs
docker-compose logs roomba-ui

# Restart service
docker-compose restart roomba-ui

# Access container shell
docker exec -it roomba-webui sh

Network Debugging

# Test Roomba connectivity
ping <roomba_ip>

# Check open ports
nmap -p 80,443,8080 <roomba_ip>

# Test API locally
curl -H "X-API-Key: your_key" http://localhost:8080/health

File Structure 📁

doria980-webui/
├── src/
│   ├── server.js          # Express server and API routes
│   └── roombaClient.js    # dorita980 wrapper client
├── public/
│   ├── index.html         # Web interface
│   └── app.js            # Frontend JavaScript
├── scripts/
│   └── getpassword.js    # Password extraction helper
├── Dockerfile            # Container configuration
├── docker-compose.yml    # Service orchestration
├── package.json          # Node.js dependencies
├── .env.example         # Environment template
└── README.md            # This file

Contributing 🤝

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

License 📄

MIT License - see LICENSE file for details.

Acknowledgments 🙏

dorita980 - Roomba communication library
homebridge-roomba - Credential extraction tools
iRobot for creating awesome vacuum robots

Support 💬

Create an issue for bug reports
Check existing issues before creating new ones
Include logs and system information in bug reports
Star the repo if you find it useful!

Made with ❤️ for the home automation community

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
.github		.github
public		public
scripts		scripts
src		src
.env.example		.env.example
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json

License

aasmoe/doria980-webui

Folders and files

Latest commit

History

Repository files navigation