nexusguard/Nexus-Guard-Suite
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 6 Wiki Activity

docs: add ESP32 and iOS agent architecture reference

Browse Source 
- reference/esp32-agent/: DESIGN, HARDWARE, API_COMPAT, ARCHITECTURE, README

- reference/ios-agent/: DESIGN, API_COMPAT, UI_DESIGN, ARCHITECTURE, README

- Both mirror Android agent architecture, UI design, and heartbeat flow

- Architecture-only (no code) — avoids submodule conflicts

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
This commit is contained in:
datadunia
2026-07-06 14:20:10 +07:00
parent 4af46dadad
commit 84689b208e
10 changed files with 3565 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
reference/esp32-agent/docs/HARDWARE.md
+330
View File
@@ -0,0 +1,330 @@
# Hardware Reference
**Version**: 1.0.0
**Date**: 2026-06-26
## 1. Target Hardware
### 1.1 LW840X Module
The LW840X is an ESP32-based WiFi module designed for IoT applications.
| Specification | Value |
|---------------|-------|
| MCU | ESP32 (Xtensa LX7 dual-core) |
| Clock | 240 MHz |
| RAM | 520 KB SRAM |
| Flash | 4 MB (external) |
| WiFi | 802.11 b/g/n (2.4 GHz) |
| Bluetooth | None (LW840X) |
| GPIO | 20+ (depends on module) |
| ADC | 18 channels (12-bit) |
| Operating Temp | -40°C to +85°C |
| Voltage | 3.0V to 3.6V |
### 1.2 Pin Mapping
```
LW840X Module Pinout
┌─────────────────────────────────────┐
│ │
│ 3V3 ─┐ │
│ GND ─┤ │
│ EN ─┤ │
│ IO0 ─┤ Boot/Flash mode │
│ IO1 ─┤ TX0 (UART0) │
│ IO3 ─┤ RX0 (UART0) │
│ IO4 ─┤ Status LED │
│ IO5 ─┤ (reserved) │
│ IO12 ─┤ (reserved) │
│ IO13 ─┤ (reserved) │
│ IO14 ─┤ (reserved) │
│ IO15 ─┤ (reserved) │
│ IO16 ─┤ (reserved) │
│ IO17 ─┤ (reserved) │
│ IO18 ─┤ (reserved) │
│ IO19 ─┤ (reserved) │
│ IO21 ─┤ (reserved) │
│ IO22 ─┤ (reserved) │
│ IO23 ─┤ (reserved) │
│ IO25 ─┤ (reserved) │
│ IO26 ─┤ (reserved) │
│ IO27 ─┤ (reserved) │
│ IO32 ─┤ (reserved) │
│ IO33 ─┤ (reserved) │
│ IO34 ─┤ (reserved) │
│ IO35 ─┤ (reserved) │
│ │
└─────────────────────────────────────┘
```
### 1.3 Minimal Circuit
```
Power Supply:
3.3V ──── LW840X 3V3
GND ──── LW840X GND
Decoupling:
100nF ceramic capacitor between 3V3 and GND (close to module)
Boot/Flash:
IO0 ──── 10K pull-up to 3V3 (normal boot)
IO0 ──── GND (flash mode)
Status LED:
IO4 ──── 220Ω ──── LED ──── GND
UART (for debugging):
IO1 (TX0) ──── USB-UART RX
IO3 (RX0) ──── USB-UART TX
GND ──── USB-UART GND
```
## 2. Power Requirements
### 2.1 Current Consumption
| Mode | Current | Notes |
|------|---------|-------|
| Active (WiFi TX) | 130-170 mA | Transmitting data |
| Active (WiFi RX) | 80-100 mA | Receiving data |
| Modem Sleep | 15-20 mA | WiFi connected, low duty cycle |
| Light Sleep | 0.8-1.5 mA | CPU paused, WiFi wake |
| Deep Sleep | 5-10 µA | RTC only, wake on GPIO |
| Off | 0 µA | No power |
### 2.2 Power Supply Design
```
Recommended:
Input: 5V USB or 12V DC
Regulator: AMS1117-3.3 or similar LDO
Capacity: 500mA minimum
┌─────────┐ ┌─────────┐ ┌─────────┐
│ 5V USB │────▶│ LDO │────▶│ LW840X │
│ │ │ 3.3V │ │ │
└─────────┘ └─────────┘ └─────────┘
│
GND
```
### 2.3 Battery Operation
For battery-powered applications:
| Battery | Capacity | Runtime (Active) | Runtime (Sleep) |
|---------|----------|------------------|-----------------|
| CR2032 | 225 mAh | ~1.5 hours | ~2 years |
| 18650 | 3400 mAh | ~20 hours | ~30 years |
| LiPo 1000mAh | 1000 mAh | ~6 hours | ~10 years |
**Note**: Deep sleep with periodic wake (e.g., every 5 minutes) is recommended for battery operation.
## 3. Antenna Options
### 3.1 PCB Trace Antenna
- **Pros**: Low cost, compact
- **Cons**: Lower gain, sensitive to placement
- **Range**: 10-30m (indoor)
- **Use Case**: Short-range, cost-sensitive
### 3.2 U.FL Connector
- **Pros**: Higher gain, flexible placement
- **Cons**: Additional cost, larger size
- **Range**: 50-100m (indoor)
- **Use Case**: Longer range, industrial
### 3.3 External Antenna
- **Pros**: Best performance, directional options
- **Cons**: Highest cost, largest size
- **Range**: 100m+ (outdoor)
- **Use Case**: Outdoor, long-range
## 4. Development Board
### 4.1 ESP32-DevKitC
Recommended for development and prototyping.
| Feature | Specification |
|---------|---------------|
| MCU | ESP32-WROOM-32 |
| Flash | 4 MB |
| RAM | 520 KB SRAM |
| WiFi | 802.11 b/g/n |
| Bluetooth | BT 4.2 + BLE |
| USB | Micro-USB (CP2102) |
| GPIO | 38 pins |
| Price | ~$5-10 |
### 4.2 Flashing
```bash
# Install ESP-IDF
# https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/
# Set target
idf.py set-target esp32
# Build
idf.py build
# Flash (auto-detect port)
idf.py -p /dev/ttyUSB0 flash
# Monitor
idf.py -p /dev/ttyUSB0 monitor
```
### 4.3 Pin Connections (DevKit)
```
Status LED:
GPIO4 ──── 220Ω ──── LED ──── GND
Debug UART (optional):
GPIO1 (TX0) ──── USB-UART RX
GPIO3 (RX0) ──── USB-UART TX
GND ──── USB-UART GND
```
## 5. Production Board
### 5.1 Design Guidelines
1. **Power**:
- Use 3.3V LDO with 500mA capacity
- Add 100nF ceramic capacitor close to 3V3 pin
- Add 10µF tantalum capacitor for bulk decoupling
2. **Antenna**:
- Keep antenna area clear of copper pours
- Minimum 10mm clearance around antenna
- Use U.FL connector for external antenna
3. **Layout**:
- Route UART traces away from antenna
- Keep crystal traces short
- Ground plane under module
4. **Enclosure**:
- Use non-metallic enclosure (plastic)
- Ensure antenna is not shielded
- Provide mounting holes
### 5.2 Bill of Materials (BOM)
| Component | Quantity | Package | Notes |
|-----------|----------|---------|-------|
| LW840X | 1 | Module | ESP32-based |
| AMS1117-3.3 | 1 | SOT-223 | 3.3V LDO |
| 100nF | 2 | 0402 | Decoupling |
| 10µF | 1 | 0805 | Bulk cap |
| 220Ω | 1 | 0402 | LED resistor |
| LED | 1 | 0603 | Status indicator |
| U.FL | 1 | SMD | Antenna connector |
| Header | 1 | 2.54mm | Debug UART |
### 5.3 Schematic
```
┌─────────────────┐
│ LW840X │
3.3V ────────────┤ 3V3 GND ├──── GND
│ │
IO4 ──── 220Ω ───┤ IO4 TX0 ├──── UART RX
└── LED ──┤ RX0 ├──── UART TX
GND │ │
│ EN ├──── 10K ──── 3.3V
│ │
│ IO0 ├──── 10K ──── 3.3V
│ │ (flash: GND)
└─────────────────┘
```
## 6. Testing & Validation
### 6.1 Hardware Tests
1. **Power-on Test**:
- Verify 3.3V at module pin
- Check current consumption (~50mA idle)
- Confirm LED blinks on boot
2. **WiFi Test**:
- Scan for WiFi networks
- Connect to test AP
- Measure RSSI at distance
3. **UART Test**:
- Send AT commands (if firmware supports)
- Verify debug output
- Check baud rate (115200)
4. **Flash Test**:
- Write/read NVS data
- Verify flash size
- Test wear leveling
### 6.2 Production Test
1. **Functional Test**:
- Provision with test server
- Verify WireGuard handshake
- Check heartbeat response
2. **Stress Test**:
- Run for 24+ hours
- Monitor memory leaks
- Verify reconnection after WiFi drop
3. **Environmental Test**:
- Operating temperature range
- Humidity resistance
- Vibration resistance
## 7. Troubleshooting
### 7.1 Common Issues
| Symptom | Cause | Solution |
|---------|-------|----------|
| No boot | IO0 held low | Remove flash jumper |
| No WiFi | Antenna issue | Check antenna connection |
| High current | WiFi always on | Use modem sleep |
| Crash on boot | Stack overflow | Increase task stack size |
| Provision fail | Token expired | Get new token from server |
### 7.2 Debug Tools
- **Serial Monitor**: `idf.py monitor`
- **JTAG Debugger**: OpenOCD + GDB
- **Logic Analyzer**: Saleae or similar
- **Power Analyzer**: Monsoon or similar
## 8. Compliance
### 8.1 Certifications
- **FCC**: Required for US market
- **CE**: Required for EU market
- **IC**: Required for Canada market
- **TELEC**: Required for Japan market
### 8.2 Testing
- EMC testing (emissions and immunity)
- SAR testing (if applicable)
- Environmental testing (temperature, humidity)
## 9. References
- [ESP32 Hardware Design Guidelines](https://www.espressif.com/sites/default/files/documentation/esp32_hardware_design_guidelines_en.pdf)
- [ESP32 Datasheet](https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf)
- [LW840X Module Datasheet](link-to-datasheet)
- [ESP-IDF Programming Guide](https://docs.espressif.com/projects/esp-idf/)