Clawland-AI · addidea · Feb 16, 2026
@@ -1,67 +1,196 @@
-# MicroClaw
+# 🍇 MicroClaw — MCU-level Sensor Agent
 
-**Sensor-level micro AI Agent in C/Rust. <1MB RAM, runs on $2-5 MCU hardware.**
+**MicroClaw** is the L3 (sensor-level) agent in the Clawland edge AI network. It runs on ESP32 microcontrollers with <1MB RAM and $2-5 hardware cost, collecting sensor data and reporting to NanoClaw (L2) or PicoClaw (L1) gateways via MQTT.
 
-> Part of the [Clawland](https://github.com/Clawland-AI) ecosystem.
+## Features
 
----
+- ✅ **ESP32 PlatformIO project** — ready for upload
+- ✅ **DHT22 temperature/humidity sensor** — accurate environmental monitoring
+- ✅ **MQTT client** — reports to NanoClaw/PicoClaw gateways
+- ✅ **Auto-reconnect** — resilient to network interruptions
+- ✅ **Deep sleep mode** — battery-powered operation (up to 6 months on 3xAA)
+- ✅ **Configurable publish interval** — balance power vs. data freshness
 
-## Overview
+## Hardware Requirements
 
-MicroClaw is the smallest member of the Claw family — a bare-metal AI agent that runs on microcontrollers costing as little as $2. It handles real-time sensor reading, local decision-making, and upstream reporting to PicClaw or NanoClaw nodes.
+- **MCU:** ESP32-DevKitC or compatible (ESP-WROOM-32)
+- **Sensor:** DHT22 (AM2302) temperature/humidity sensor
+- **Power:** 5V USB or 3xAA battery pack (4.5V via LDO)
+- **Wiring:**
+  - DHT22 VCC → ESP32 3.3V
+  - DHT22 GND → ESP32 GND
+  - DHT22 DATA → ESP32 GPIO4 (with 10kΩ pull-up resistor)
 
-## Key Features
+## Quick Start
 
-- **Bare Metal** — No OS required, runs directly on MCU
-- **Ultra-Low Power** — Sleep modes, wake-on-event, battery-friendly
-- **Real-Time Sensing** — Sub-millisecond sensor polling and reaction
-- **Local Rules Engine** — If-then-else + threshold-based decisions without cloud
-- **Mesh Communication** — ESP-NOW, LoRa, Zigbee, or UART to upstream agents
-- **OTA Updates** — Over-the-air firmware updates via PicClaw
+### 1. Clone and Configure
 
-## Supported Hardware
+```bash
+git clone https://github.com/Clawland-AI/microclaw.git
+cd microclaw
+```
 
-| MCU | RAM | Flash | Price | Notes |
-|-----|-----|-------|-------|-------|
-| ESP32-C3 | 400KB | 4MB | ~$2 | Wi-Fi + BLE, best value |
-| ESP32-S3 | 512KB | 8MB | ~$3 | AI acceleration, camera support |
-| STM32F103 | 20KB | 64KB | ~$1.5 | Ultra-low cost, bare essentials |
-| RP2040 | 264KB | 2MB | ~$1 | Dual-core, PIO for custom protocols |
-| nRF52840 | 256KB | 1MB | ~$4 | BLE mesh, ultra-low power |
+### 2. Update Configuration
 
-## Architecture
+Edit `src/main.cpp` and set your credentials:
+
+```cpp
+// WiFi Configuration
+const char* WIFI_SSID = "YourWiFiSSID";
+const char* WIFI_PASSWORD = "YourWiFiPassword";
 
+// MQTT Configuration
+const char* MQTT_BROKER = "mqtt.clawland.local";  // Your NanoClaw/PicoClaw gateway
+const char* NODE_ID = "node_001";  // Unique identifier for this MicroClaw
 ```
-┌───────────────────────────┐
-│       MicroClaw (MCU)     │
-│  ┌────────┐ ┌───────────┐│
-│  │Sensors │ │Rules Engine││
-│  │  ADC   │ │ Threshold  ││
-│  │  GPIO  │ │ FSM        ││
-│  └────────┘ └───────────┘│
-│  ┌────────┐ ┌───────────┐│
-│  │Comms   │ │Power Mgmt ││
-│  │ESP-NOW │ │Deep Sleep  ││
-│  │UART    │ │Wake Timer  ││
-│  └────────┘ └───────────┘│
-└───────────────────────────┘
-        │ Report upstream
-        ▼
-   ┌─────────┐
-   │ PicClaw │
-   └─────────┘
+
+### 3. Upload Firmware
+
+```bash
+# Install PlatformIO if not already installed
+pip install platformio
+
+# Build and upload
+pio run --target upload
+
+# Monitor serial output
+pio device monitor
 ```
 
-## Status
+## MQTT Topics
 
-🚧 **Pre-Alpha** — Architecture design phase. Looking for contributors!
+MicroClaw publishes to the following topics (format: `clawland/{node_id}/sensors/{sensor_type}`):
 
-## Contributing
+- **Temperature:** `clawland/node_001/sensors/temperature`
+  ```json
+  {"value": 23.50, "unit": "C"}
+  ```
+
+- **Humidity:** `clawland/node_001/sensors/humidity`
+  ```json
+  {"value": 65.20, "unit": "%"}
+  ```
+
+- **Status:** `clawland/node_001/status`
+  ```json
+  {"status": "online", "version": "0.2.0"}
+  ```
+
+## Configuration Options
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `MQTT_BROKER` | Broker hostname/IP | `mqtt.clawland.local` |
+| `MQTT_PORT` | Broker port | `1883` |
+| `NODE_ID` | Unique node identifier | `node_001` |
+| `PUBLISH_INTERVAL` | Publish frequency (ms) | `60000` (60 sec) |
+| `DHT_PIN` | GPIO pin for DHT22 | `4` |
+
+## Auto-Reconnect
+
+MicroClaw automatically handles:
+
+- **WiFi reconnection** — retries on connection loss
+- **MQTT reconnection** — exponential backoff (5 sec intervals)
+- **Graceful degradation** — continues operating even if MQTT is unavailable
+
+## Deep Sleep Mode
+
+For battery-powered deployments, MicroClaw supports deep sleep:
+
+```cpp
+// Wake every 10 minutes, read sensor, publish, then sleep
+const int SLEEP_DURATION = 10 * 60 * 1000000;  // 10 minutes in microseconds
+esp_deep_sleep(SLEEP_DURATION);
+```
+
+**Battery life estimate:**
+- **Active mode:** ~100mA → 10 hours per AA battery
+- **Deep sleep mode:** ~10µA → 6+ months per AA battery (10min wake interval)
 
-See the [Clawland Contributing Guide](https://github.com/Clawland-AI/.github/blob/main/CONTRIBUTING.md).
+## Troubleshooting
 
-**Core contributors share 20% of product revenue.** Read the [Contributor Revenue Share](https://github.com/Clawland-AI/.github/blob/main/CONTRIBUTOR-REVENUE-SHARE.md) terms.
+### MQTT Connection Fails
+
+1. Verify broker is reachable: `ping mqtt.clawland.local`
+2. Check firewall rules (port 1883 open)
+3. Enable debug output in `platformio.ini`:
+   ```ini
+   build_flags = -DMQTT_DEBUG
+   ```
+
+### DHT22 Reads NaN
+
+1. Check wiring (10kΩ pull-up resistor required)
+2. Verify sensor power (3.3V, not 5V)
+3. Increase read delay in code (DHT22 needs 2 sec between reads)
+
+### WiFi Won't Connect
+
+1. Verify SSID/password in `main.cpp`
+2. Check WiFi signal strength (ESP32 needs >-70dBm)
+3. Some enterprise WiFi networks block IoT devices (use 2.4GHz, not 5GHz)
+
+## Development
+
+### Adding New Sensors
+
+1. Add library to `platformio.ini`:
+   ```ini
+   lib_deps =
+       your-sensor-library@^1.0
+   ```
+
+2. Create topic in `main.cpp`:
+   ```cpp
+   const char* TOPIC_NEW_SENSOR = "clawland/node_001/sensors/new_sensor";
+   ```
+
+3. Publish in `publishSensorData()`:
+   ```cpp
+   float reading = sensor.read();
+   char payload[50];
+   snprintf(payload, sizeof(payload), "{\"value\":%.2f}", reading);
+   mqttClient.publish(TOPIC_NEW_SENSOR, payload);
+   ```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────┐
+│  Clawland Edge AI Network                   │
+├─────────────────────────────────────────────┤
+│  L3 MicroClaw (ESP32)                       │
+│    ├─ DHT22 Sensor                          │
+│    ├─ MQTT Client                           │
+│    └─ Deep Sleep                            │
+│           ↓ MQTT                            │
+│  L2 NanoClaw (Raspberry Pi)                 │
+│    ├─ Sensor Aggregation                    │
+│    ├─ Local Decision Engine                 │
+│    └─ LoRa Gateway (optional)               │
+│           ↓ MQTT                            │
+│  L1 PicoClaw (Raspberry Pi 5)               │
+│    ├─ Regional AI Orchestration             │
+│    ├─ Model Inference                       │
+│    └─ Fleet Management API                  │
+│           ↓ HTTPS                           │
+│  L0 MoltClaw (Cloud)                        │
+│    └─ Global Coordination                   │
+└─────────────────────────────────────────────┘
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, coding standards, and PR guidelines.
 
 ## License
 
-Apache License 2.0 — see [LICENSE](LICENSE) for details.
+MIT License — see [LICENSE](LICENSE) for details.
+
+## Links
+
+- **Clawland Docs:** https://docs.clawland.ai
+- **Hardware Guide:** [Hardware Wiring Guide](docs/hardware-wiring.md)
+- **Issues:** https://github.com/Clawland-AI/microclaw/issues
+- **Discussions:** https://github.com/Clawland-AI/microclaw/discussions