System Architecture

Wala Works follows a decentralized, local-first architecture where all components communicate over your local network without requiring cloud services.

Overview

┌─────────────────────────────────────────────────────────────┐
│                    Your Local Network                        │
│                                                              │
│  ┌──────────────┐      ┌──────────────┐                     │
│  │  MotorWala   │      │  RelayWala   │                     │
│  │  Devices     │      │  Devices     │                     │
│  └──────┬───────┘      └──────┬───────┘                     │
│         │                     │                              │
│    REST API / MQTT       REST API / MQTT                     │
│         │                     │                              │
│  ┌──────┴──────────────────────┴───────┐                    │
│  │     Automation Platform              │                    │
│  │  - Home Assistant                    │                    │
│  │  - Node-RED                          │                    │
│  │  - OpenHAB                           │                    │
│  │  - Custom Scripts                    │                    │
│  └──────────────┬───────────────────────┘                    │
│                 │                                            │
│         ┌───────┴────────┐                                   │
│         │  MQTT Broker   │                                   │
│         │  (Optional)    │                                   │
│         └────────────────┘                                   │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Communication Protocols

1. HTTP REST API

All devices expose REST APIs for direct control:

Advantages:

Simple to use and test
Wide language support
Stateless operations
No broker required

Use cases:

Direct device control
Status monitoring
One-off commands
Testing and debugging

Example:

curl -X POST http://192.168.1.100/api/motor/open

2. MQTT

Devices support MQTT for event-driven automation:

Advantages:

Real-time updates
Publish-subscribe pattern
Low bandwidth
Persistent connections

Use cases:

Home Assistant integration
Multi-device coordination
Event-driven automations
State synchronization

Example:

mosquitto_pub -t "motorwala/bedroom/set" -m "OPEN"

3. WebSocket

Real-time bidirectional communication:

Advantages:

Live position updates
Instant feedback
Two-way communication
Low latency

Use cases:

Web dashboards
Mobile apps
Real-time monitoring
Live control interfaces

Example:

const ws = new WebSocket('ws://192.168.1.100/ws');
ws.send(JSON.stringify({ action: 'open' }));

Device Architecture

MotorWala

┌─────────────────────────────────────┐
│         MotorWala Hardware          │
│                                     │
│  ┌────────────┐    ┌─────────────┐ │
│  │   ESP32    │───▶│ H-Bridge    │ │
│  │  (WiFi)    │    │ Motor Driver│─┼──▶ DC Motor
│  └────────────┘    └─────────────┘ │
│        │                            │
│  ┌─────▼──────┐                     │
│  │  Position  │                     │
│  │  Encoder   │                     │
│  └────────────┘                     │
└─────────────────────────────────────┘

Firmware layers:

Hardware Abstraction - Motor control, position tracking
Network Layer - WiFi, HTTP server, WebSocket, MQTT client
API Layer - REST endpoints, command handling
State Management - Position tracking, calibration

RelayWala

┌─────────────────────────────────────┐
│         RelayWala Hardware          │
│                                     │
│  ┌────────────┐    ┌─────────────┐ │
│  │   ESP32    │───▶│  4-Channel  │ │
│  │  (WiFi)    │    │ Relay Board │─┼──▶ AC/DC Loads
│  └────────────┘    └─────────────┘ │
│                                     │
└─────────────────────────────────────┘

Firmware layers:

Hardware Abstraction - Relay control, safety timers
Network Layer - WiFi, HTTP server, MQTT client
API Layer - REST endpoints, scheduling
State Management - Relay states, schedules

Integration Patterns

Pattern 1: Direct Control

Simplest setup - direct HTTP calls from automation platform:

# Home Assistant automation
automation:
  - alias: "Morning Routine"
    trigger:
      - platform: time
        at: "07:00:00"
    action:
      - service: rest_command.open_blinds
        data: {}

Pros: Simple, no broker needed Cons: No state feedback, one-way communication

Pattern 2: MQTT Integration

Full integration with state synchronization:

# Home Assistant device config
cover:
  - platform: mqtt
    name: "Bedroom Blinds"
    command_topic: "motorwala/bedroom/set"
    state_topic: "motorwala/bedroom/state"
    position_topic: "motorwala/bedroom/position"

Pros: Bidirectional, state updates, multiple subscribers Cons: Requires MQTT broker

Pattern 3: Hybrid Approach

REST for commands, MQTT for state updates:

# Send command via REST
requests.post('http://192.168.1.100/api/motor/open')

# Subscribe to state updates via MQTT
client.subscribe('motorwala/bedroom/position')

Pros: Best of both worlds Cons: More complex setup

Network Architecture

Local-Only Operation

All communication stays on your local network:

Internet ──X─┐
            │  (No cloud connection)
            │
┌───────────┴──────────────┐
│   Your WiFi Network      │
│                          │
│  Router: 192.168.1.1     │
│    │                     │
│    ├─ MotorWala (.100)   │
│    ├─ RelayWala (.101)   │
│    ├─ Home Assistant     │
│    └─ MQTT Broker        │
└──────────────────────────┘

Benefits:

No internet required
Zero latency
Complete privacy
Works during outages
No subscription fees

Optional Cloud Integration

You can add cloud access through your automation platform:

Internet ───────────────────┐
                           │
                    ┌──────▼─────────┐
                    │ Home Assistant │
                    │   Cloud        │
                    └──────┬─────────┘
                           │
                           │ (Secure tunnel)
                           │
┌──────────────────────────┴──────┐
│   Your Local Network            │
│                                 │
│  Home Assistant ◀──▶ MotorWala  │
└─────────────────────────────────┘

Data Flow

Command Flow

User Action
    ↓
Automation Platform
    ↓
HTTP POST /api/motor/open
    ↓
MotorWala receives command
    ↓
Motor starts moving
    ↓
Position updates published to MQTT
    ↓
Automation Platform updates UI
    ↓
Motor reaches target position
    ↓
Final state published

State Synchronization

MotorWala Position Change
    ↓
MQTT Publish: motorwala/bedroom/position = 75
    ↓
MQTT Broker
    ↓
├──▶ Home Assistant (updates UI)
├──▶ Node-RED (triggers flows)
└──▶ Custom Dashboard (live update)

Security Considerations

Network Isolation

Recommended network setup:

┌────────────────────────────────┐
│  Main Network (192.168.1.0/24) │
│  - Computers, phones, tablets  │
└────────────────────────────────┘
              │
              │ VLAN / Firewall
              ↓
┌────────────────────────────────┐
│  IoT Network (192.168.2.0/24)  │
│  - Wala Works devices          │
│  - Home Assistant              │
│  - MQTT Broker                 │
└────────────────────────────────┘

Authentication

Enable API authentication in device settings:

# Device configuration
api:
  enabled: true
  authentication: true
  token: "your-secure-token-here"

Then use bearer token in requests:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  http://192.168.1.100/api/status

MQTT Security

Secure your MQTT broker:

# mosquitto.conf
allow_anonymous false
password_file /etc/mosquitto/passwd

# TLS encryption
listener 8883
cafile /etc/mosquitto/ca.crt
certfile /etc/mosquitto/server.crt
keyfile /etc/mosquitto/server.key

Scaling Considerations

Small Setup (1-5 devices)

Direct REST API control
Optional MQTT for state updates
Single Home Assistant instance

Medium Setup (5-20 devices)

MQTT broker for coordination
Home Assistant with automations
Device grouping by room/function

Large Setup (20+ devices)

Dedicated MQTT broker (Mosquitto)
Multiple automation controllers
Network segmentation
Centralized logging
Backup automation platform

Performance

Latency

REST API: ~50-100ms (local network)
MQTT: ~20-50ms (with broker)
WebSocket: ~10-30ms (direct connection)

Throughput

Commands: 100 req/min per device
State updates: 10 msg/sec over MQTT
WebSocket: Real-time, no artificial limits

Reliability

Devices auto-reconnect to WiFi
MQTT persistent sessions
Last will and testament for offline detection
Position state survives power loss

Troubleshooting

Devices not communicating?

Check all devices on same network
Verify no firewall blocking ports 80, 1883, 8883
Test with ping and curl
Check router DHCP leases

MQTT messages not arriving?

Verify broker is running
Check device MQTT configuration
Test with mosquitto_sub
Review broker logs

Slow response times?

Check WiFi signal strength
Reduce network congestion
Use 2.4GHz for better range
Consider WiFi mesh for large homes

Next Steps

Hardware Setup - Physical installation
Software Setup - Configure integrations
API Reference - Secure your devices

Questions? Check FAQ or contact support

System Architecture

Overview

Communication Protocols

1. HTTP REST API

2. MQTT

3. WebSocket

Device Architecture

MotorWala

RelayWala

Integration Patterns

Pattern 1: Direct Control

Pattern 2: MQTT Integration

Pattern 3: Hybrid Approach

Network Architecture

Local-Only Operation

Optional Cloud Integration

Data Flow

Command Flow

State Synchronization

Security Considerations

Network Isolation

Authentication

MQTT Security

Scaling Considerations

Small Setup (1-5 devices)

Medium Setup (5-20 devices)

Large Setup (20+ devices)

Performance

Latency

Throughput

Reliability

Troubleshooting

Devices not communicating?

MQTT messages not arriving?

Slow response times?

Next Steps

On This Page