This repository contains the ESP32-S3 firmware for the Sparkie robot platform. Sparkie is a modular robotics system designed for educational and research purposes, featuring multiple sensors and actuators controlled through a Protocol Buffer-based communication system.
- ESP32-S3 microcontroller with USB-CDC communication
- IMU (Inertial Measurement Unit) - 9-axis sensor for motion detection
- Motor Control - Brushed DC motor control with encoder feedback
- Servo Motors - Precise angle control for articulated movements
- Ultrasonic Sensors - Distance measurement and obstacle detection
- LED Strip - Programmable RGB lighting with various effects
- AHT Temperature/Humidity Sensor - Environmental monitoring
- Air Quality Sensor (CCS811) - eCO2 and TVOC measurement
- Status LED - Visual feedback for system status
- Component-based design - Modular architecture with pluggable components
- Protocol Buffer communication - Efficient binary serialization
- Message batching - Optimized data transmission
- USB-CDC interface - High-speed communication with host computer
- FreeRTOS integration - Real-time task management
- I2C sensor management - Centralized sensor communication
sparkie_esp/
├── main/
│ ├── components/ # Core system components
│ │ ├── agent/ # Communication agent
│ │ ├── imu/ # IMU sensor component
│ │ ├── motors/ # Motor control component
│ │ ├── servo/ # Servo motor component
│ │ ├── ultrasonic/ # Ultrasonic sensor component
│ │ ├── ledstrip/ # LED strip component
│ │ ├── aht/ # Temperature/humidity sensor
│ │ └── airq/ # Air quality sensor
│ ├── hardware/ # Low-level hardware drivers
│ ├── ledEffects/ # LED animation effects
│ ├── misc/ # Utility functions
│ ├── proto/ # Generated protobuf files
│ ├── config.hpp # Hardware configuration
│ ├── constants.hpp # System constants
│ └── main.cpp # Application entry point
├── protos/ # Protocol buffer definitions
├── nanopb/ # Nanopb library for embedded protobuf
├── python_reader/ # Python tools for data reading
└── managed_components/ # ESP-IDF managed components
The system uses Protocol Buffers for structured communication between the ESP32 and host computer via USB-CDC. Messages are organized into different types:
- IMU Data - Accelerometer, gyroscope, and magnetometer readings
- Motor Control - Speed commands and encoder feedback
- Servo Control - Angle positioning commands
- Sensor Data - Ultrasonic, temperature, humidity, and air quality
- LED Control - Color patterns and animation effects
- System Status - Ping/pong and diagnostic information
The firmware implements intelligent message batching to optimize USB bandwidth:
- Groups multiple messages into single packets
- Adaptive timeout-based transmission
- Low-latency mode for time-critical data
- Statistics reporting for performance monitoring
- ESP-IDF v5.0 or later
- Python 3.8+ with required packages
- USB cable for programming and communication
-
Clone the repository:
git clone https://github.com/sparkiebot/sparkie_esp.git cd sparkie_esp -
Install ESP-IDF: Follow the ESP-IDF installation guide
-
Compile Protocol Buffers:
# Run the proto compilation task in VS Code, or manually: python3 nanopb/generator/nanopb_generator.py protos/*.proto -D main/proto -I protos
-
Configure the project:
idf.py menuconfig
-
Build and flash:
idf.py build flash monitor
The hardware pin assignments are defined in main/config.hpp:
- I2C Bus: SDA (GPIO 15), SCL (GPIO 16)
- Motors: PWM and direction pins
- Servos: PWM output pins
- Ultrasonic: Trigger and echo pins
- LED Strip: Data pin with WS2812 protocol
- Status LED: GPIO pin for system feedback
Each hardware component inherits from the SparkComponent base class and implements:
- Initialization: Hardware setup and configuration
- Message Handling: Protocol buffer message processing
- Periodic Tasks: Sensor reading and data publishing
The central communication hub that:
- Manages USB-CDC communication
- Handles message routing and batching
- Provides ping/pong connectivity testing
- Maintains system health monitoring
The python_reader/ directory contains Python tools for:
- Real-time data visualization
- Protocol buffer message decoding
- System testing and debugging
- Performance analysis
All message definitions are in the protos/ directory with comprehensive documentation of data structures and communication protocols.
- Message Batching: Up to 4 messages per packet for efficiency
- Adaptive Timeouts: Dynamic transmission timing based on queue status
- Background Processing: Non-blocking sensor reading and data processing
- Memory Management: Efficient buffer usage and memory allocation
- Real-time Statistics: Performance monitoring and diagnostics
The onboard LED provides visual feedback:
- Solid ON: System initializing
- Fast Blink: Successful ping response (connected)
- Slow Blink: Communication timeout (disconnected)
- OFF: Normal operation
This project is licensed under the MIT License - see the LICENSE file for details.
Contributions are welcome! Please follow the existing code style and ensure all Italian comments are translated to English. Each component should be well-documented and follow the established architectural patterns.
- Build Errors: Ensure ESP-IDF is properly installed and sourced
- Communication Issues: Check USB cable and driver installation
- Sensor Problems: Verify I2C connections and addresses
- Performance Issues: Monitor statistics and adjust batch settings
Enable debug logging by setting the appropriate log levels in idf.py menuconfig under Component Config → Log Output.