🤖 AI AGENT QUICK-CONTEXT & ARCHITECTURE SUMMARY
(Token-efficient cheatsheet for AI Pair-Programmers & Subagents)
- Hardware: ESP32-D0WD-V3 (38-Pin Dev Module) on
COM4+ PCA9685 16-Ch 12-Bit PWM Driver (0x40I2C).- Pinout:
SDA=GPIO21,SCL=GPIO22,OE=-1(Disconnected, hardware pull-down enabled).- Joint Servo Channels & Limits:
$J_1$ (Base Yaw):CH 0|$0^\circ - 180^\circ$ (Def:$90^\circ$ )$J_2$ (Shoulder Boom):CH 1|$15^\circ - 165^\circ$ (Def:$90^\circ$ )$J_3$ (Elbow Linkage):CH 2|$10^\circ - 170^\circ$ (Def:$90^\circ$ )$J_4$ (Gripper Claw):CH 3|$0^\circ - 17^\circ$ (Def:$10^\circ$ )- FreeRTOS Dual-Core Architecture:
- Core 0: Wi-Fi Stack, Web Server & REST/JSON API (
webServerTask, Prio 1).- Core 1: 100Hz Real-Time Trajectory Engine & PWM Hardware Driver (
motionControlTask, Prio 2).- Kinematic Model: MeArm 4-Bar Parallel Linkage (
$L_0=50\text{mm}, L_1=110\text{mm}, L_2=100\text{mm}, L_3=50\text{mm}$ ).$J_3$ angle is ground-referenced. Top parallel rod keeps wrist platform level.- Wi-Fi Config: Station Mode (
SSID: "YOUR_WIFI_SSID",Pass: "YOUR_WIFI_PASSWORD"- set your own ininclude/config.h). AP Fallback (ESP32-RobotArm/robot1234).- Boot Mode:
ENABLE_AUTO_HOME_ON_BOOT false(Passive mode: zero movement on startup until commanded).- Web UI: Embedded HTML5/CSS Glassmorphic Industrial Console with live telemetry & micro-stepping controls.
- Build & Flash:
python -m platformio run --target upload --upload-port COM4
| Parameter | Value |
|---|---|
| Status | 🟢 DETECTED & CONNECTED |
| Port | COM4 (Silicon Labs CP210x USB to UART Bridge) |
| Target Microcontroller | ESP32-D0WD-V3 (Revision 3.1) @ 240MHz |
| Dual-Core Distribution | Core 0: Wi-Fi & Web UI | Core 1: 100Hz Motion Trajectory |
| I2C Bus | GPIO 21 (SDA), GPIO 22 (SCL) @ 400kHz Fast Mode |
| PWM Controller | PCA9685 at I2C Address 0x40 (50Hz Servo Frequency) |
c-robot-arm/
├── platformio.ini # Build settings, platform = espressif32, board = esp32dev
├── README.md # AI-optimized context & comprehensive project guide
├── LICENSE # MIT Open-Source License
├── .gitignore # Git exclusion rules
│
├── cad/ # 3D Mechanical CAD Assets
│ ├── renders/ # High-resolution PNG renderings (Assembly1_a/b/c)
│ └── models/ # Autodesk Inventor assembly (.iam) & parts (.ipt)
│
├── include/ # Core C++ Headers
│ ├── config.h # Pinout definitions, joint limits, Wi-Fi credentials
│ ├── ServoController.h # PCA9685 driver, pulse tick mapping (125-575), limits
│ ├── Kinematics.h # MeArm parallel 4-bar FK & IK trigonometric equations
│ ├── RobotArm.h # High-level coordinator, Teach & Repeat memory buffer
│ └── WebServerController.h # Embedded HTTP Web Server & JSON API dispatcher
│
├── src/ # C++ Implementation Files
│ ├── main.cpp # FreeRTOS Dual-Core task spawner (setup & dual loops)
│ ├── ServoController.cpp # 100Hz trajectory interpolation engine
│ ├── Kinematics.cpp # Analytic IK solver for (X, Y, Z) Cartesian coordinates
│ ├── RobotArm.cpp # Command dispatcher & pose keyframe storage
│ └── WebServerController.cpp # PROGMEM index.html Industrial Console UI
│
└── docs/ # KINEMATICS_GUIDE.md, HARDWARE_WIRING.md, SERIAL_PROTOCOL.md
- Verify device connection:
python -m platformio device list
- Build and upload to ESP32:
python -m platformio run --target upload --upload-port COM4
- Open Serial Monitor (115200 Baud):
python -m platformio device monitor -b 115200 -p COM4
If Could not open COM4 or connection timeout occurs:
- Hold down the BOOT (IO0) button on the ESP32 module.
- Press and release the EN / RST button once.
- Release the BOOT button. (ESP32 is now in flashing mode).
- Run the upload command.
| Endpoint / Command | Description | Example |
|---|---|---|
GET /api/status |
Returns JSON joint angles, XYZ, limits, and E-Stop state | - |
GET /api/move?j1=..&j2=..&j3=..&j4=.. |
Move joints to target angles | /api/move?j1=90&j2=90&j3=90&j4=10 |
GET /api/ik?x=..&y=..&z=.. |
Move to Cartesian position (mm) | /api/ik?x=120&y=0&z=100 |
GET /api/limits?j1_min=.. |
Update dynamic servo angle bounds | /api/limits?j4_min=0&j4_max=17 |
Serial CLI: J <j1> <j2> <j3> <j4> |
Direct joint move over Serial | J 90 90 90 10 |
Serial CLI: HOME / REST |
Move arm to preset positions | HOME |
This project is licensed under the MIT License - see the LICENSE file for details.