Skip to content

Commit 83f93d5

Browse files
mirkoserticmirkosertic
committed
Bug fixing / Added PID block
1 parent 9eec66d commit 83f93d5

19 files changed

Lines changed: 1694 additions & 1379 deletions

File tree

‎BLOCKS.md‎

Lines changed: 37 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
# Blockly Blocks Documentation
22

3-
**Generated:** 2026-01-25
3+
**Generated:** 2026-01-26
44

5-
This documentation covers all 72 blocks used in the Megahub project, including 24 custom blocks and 48 standard Blockly blocks with custom colors.
5+
This documentation covers all 73 blocks used in the Megahub project, including 25 custom blocks and 48 standard Blockly blocks with custom colors.
66

77
Block images are rendered as high-quality PNG screenshots to accurately show all block features including text inputs, checkboxes, and statement blocks.
88

@@ -20,6 +20,7 @@ Block images are rendered as high-quality PNG screenshots to accurately show all
2020
- [FastLED](#fastled) (4 blocks)
2121
- [IMU](#imu) (1 blocks)
2222
- [UI](#ui) (1 blocks)
23+
- [Algorithms](#algorithms) (1 blocks)
2324
- [Debug](#debug) (2 blocks)
2425

2526
## Control flow
@@ -940,6 +941,37 @@ Block images are rendered as high-quality PNG screenshots to accurately show all
940941

941942
---
942943

944+
## Algorithms
945+
946+
### mh_alg_pid
947+
948+
![mh_alg_pid](docs/blocks/algorithms/mh_alg_pid.png)
949+
950+
**Description:** Proportional-Integral-Derivative controller. Returns control output based on setpoint and process variable (PV).
951+
952+
**Type:** Custom Value Block
953+
954+
**Message:** `PID controller %1 setpoint: %2 PV: %3
955+
%4 Kp: %5 Ki: %6 Kd: %7 %8
956+
output: %9 to %10`
957+
958+
**Inputs:**
959+
960+
| Name | Type | Check |
961+
|------|------|-------|
962+
| undefined | input_dummy | Any |
963+
| SETPOINT | input_value | Number |
964+
| PV | input_value | Number |
965+
| undefined | input_dummy | Any |
966+
| KP | input_value | Number |
967+
| KI | input_value | Number |
968+
| KD | input_value | Number |
969+
| undefined | input_dummy | Any |
970+
| OUT_MIN | input_value | Number |
971+
| OUT_MAX | input_value | Number |
972+
973+
---
974+
943975
## Debug
944976

945977
### mh_debug_free_heap
@@ -964,10 +996,10 @@ Block images are rendered as high-quality PNG screenshots to accurately show all
964996

965997
## Generation Statistics
966998

967-
- Total blocks: 72
968-
- Custom Megahub blocks: 24
999+
- Total blocks: 73
1000+
- Custom Megahub blocks: 25
9691001
- Standard Blockly blocks: 48
970-
- PNG images generated: 72
1002+
- PNG images generated: 73
9711003

9721004
---
9731005

‎CLAUDE.md‎

Lines changed: 261 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,261 @@
1+
# Claude AI Assistant Guide for Megahub Project
2+
3+
## Project Overview
4+
5+
Megahub is an ESP32-based robotics experimentation platform that combines LEGO WeDo/Powered Up! device support with Lua scripting and Blockly visual programming. The project consists of:
6+
7+
- **Firmware**: C++ embedded code running on ESP32 (PlatformIO)
8+
- **Frontend**: Web-based IDE built with Vite, Blockly, and vanilla JavaScript
9+
- **Libraries**: Custom ESP32 libraries for Bluetooth, UART, IMU, etc.
10+
11+
## Critical Development Guidelines
12+
13+
### Memory Management
14+
15+
**ESP32 memory is severely constrained. Always be mindful of:**
16+
17+
1. **Stack Usage**: The ESP32 has limited stack space (~8KB per task). Avoid large local arrays or deep recursion.
18+
2. **Heap Fragmentation**: Minimize dynamic allocations. Reuse buffers where possible.
19+
3. **PSRAM**: The board may have PSRAM, but don't assume it's always available.
20+
4. **String Operations**: Be careful with String class; prefer fixed buffers or std::string with reserve().
21+
5. **Lua VM Memory**: The Lua interpreter runs in constrained memory. Large scripts can cause crashes.
22+
23+
**Memory Best Practices:**
24+
- Use the already existing custim `INFO`, `ERROR` or `WARN` logging macros instead of excessive `Serial.print()`
25+
- Avoid creating temporary String objects in loops
26+
- Monitor free heap with `ESP.getFreeHeap()` during development
27+
- Use `const` and `PROGMEM` for large constant data
28+
29+
### Bluetooth BLE Connectivity
30+
31+
**Bluetooth is complex and fragile on ESP32. Follow these rules strictly:**
32+
33+
1. **Connection State Management**: Always track connection state properly. Don't assume connections persist.
34+
2. **MTU Negotiation**: Handle MTU size properly. Default is 23 bytes, negotiated up to 512.
35+
3. **Notification Callbacks**: BLE notifications are asynchronous. Handle them in a non-blocking manner.
36+
4. **Pairing & Bonding**: The Web Bluetooth API has specific pairing requirements.
37+
5. **Multiple Connections**: The ESP32 can handle multiple BLE connections, but each consumes memory.
38+
6. **Classic BT vs BLE**: The project uses both Classic Bluetooth (for HID gamepads) and BLE (for LEGO devices and Web Bluetooth API).
39+
40+
**Bluetooth Best Practices:**
41+
- Never block in BLE callbacks
42+
- Always implement proper error handling for disconnections
43+
- Test with actual devices, not just simulators
44+
- Be aware of Web Bluetooth API browser compatibility (Chrome/Edge/Opera only)
45+
- Handle reconnection scenarios gracefully
46+
- Monitor connection events and clean up resources on disconnect
47+
48+
### LEGO Device Communication
49+
50+
**LEGO Powered Up protocol specifics:**
51+
52+
1. **UART Protocol**: Uses custom UART communication at specific baud rates
53+
2. **Device Detection**: Devices send identification messages on connection
54+
3. **Command Timing**: Some devices require specific timing between commands
55+
4. **Power Management**: Devices can enter sleep mode; handle wake-up properly
56+
5. **Port Configuration**: Track which devices are on which ports (0-3)
57+
58+
**LEGO Best Practices:**
59+
- Implement proper device initialization sequences
60+
- Handle device disconnection/reconnection
61+
- Respect command rate limits to avoid overwhelming devices
62+
- Parse device responses correctly (byte order, message structure)
63+
64+
### Build System & Project Structure
65+
66+
**PlatformIO Configuration:**
67+
- Build environment: `esp32dev`
68+
- Framework: Arduino + ESP-IDF hybrid
69+
- Custom partition table: [custom_4mb_noota.csv](custom_4mb_noota.csv)
70+
- Pre-build scripts: [gitversion.py](gitversion.py), [buildfrontend.py](buildfrontend.py), [embedfiles.py](embedfiles.py)
71+
72+
**Directory Structure:**
73+
```
74+
/lib/ Custom ESP32 libraries
75+
/btremote/ Bluetooth BLE server & Classic BT HID host
76+
/commands/ Command processing system
77+
/configuration/ WiFi & system configuration
78+
/hubwebserver/ HTTP server (PsychicHttp)
79+
/imu/ MPU6050 IMU support
80+
/lpfuart/ LEGO Powered Up UART protocol
81+
/lua/ Lua 5.4 interpreter
82+
/megahub/ Main application library
83+
/portstatus/ Port status tracking
84+
/inputdevices/ Gamepad/input device support
85+
/statusmonitor/ System monitoring
86+
87+
/src/ Main application entry point
88+
main.cpp Arduino setup() and loop()
89+
90+
/frontend/ Web-based IDE
91+
/src/ JavaScript source files
92+
package.json NPM dependencies (Blockly, Vite)
93+
vite.config.js Vite build configuration
94+
```
95+
96+
**Build Process:**
97+
1. Pre-build scripts run (git version, frontend build, file embedding)
98+
2. Frontend is built and embedded into firmware as compressed files
99+
3. PlatformIO compiles C++ code
100+
4. Single binary is flashed to ESP32
101+
102+
### Frontend Development
103+
104+
**Frontend Tech Stack:**
105+
- **Vite**: Build tool and dev server
106+
- **Blockly**: Visual programming blocks
107+
- **Vanilla JS**: No framework (intentionally lightweight)
108+
- **Web Bluetooth API**: Browser-based BLE communication
109+
- **Prism.js**: Syntax highlighting for Lua code
110+
111+
**Frontend Build Modes:**
112+
- `dev`: Development mode with hot reload
113+
- `bt`: Bluetooth mode (Deployed as Megahub IDE on Github)
114+
- `web`: Web mode (WebServer is running on firmware)
115+
116+
**Frontend Best Practices:**
117+
- Keep bundle size small (embedded in ESP32 flash)
118+
- Minimize dependencies
119+
- Handle Web Bluetooth API errors gracefully
120+
- Test in supported browsers (Chrome, Edge, Opera)
121+
- Use compression (gzip) for embedded files
122+
123+
### Code Review & Implementation
124+
125+
**IMPORTANT: When making code changes to this project:**
126+
127+
For significant code changes or new features, please use the **implement-review-loop** agent. This ensures:
128+
- Code is reviewed before being committed
129+
- Potential issues are caught early
130+
- Changes follow project conventions
131+
- Memory and Bluetooth considerations are validated
132+
133+
To invoke this agent, Claude should use:
134+
```
135+
Task tool with subagent_type="implement-review-loop"
136+
```
137+
138+
**When to use implement-review-loop:**
139+
- Adding new features to firmware or frontend
140+
- Modifying Bluetooth communication code
141+
- Changing memory-critical sections
142+
- Refactoring core libraries
143+
- Adding new Lua bindings
144+
145+
**When NOT to use it:**
146+
- Trivial documentation updates
147+
- Simple bug fixes (< 10 lines)
148+
- Configuration file changes
149+
150+
### Common Pitfalls to Avoid
151+
152+
1. **Bluetooth Race Conditions**: Always use proper synchronization when accessing BLE state from multiple tasks
153+
2. **Memory Leaks**: Every `new` or `malloc` must have corresponding `delete` or `free`
154+
3. **Stack Overflow**: Don't allocate large arrays on the stack; use heap or static storage
155+
4. **String Concatenation**: Avoid repeated `+=` operations on String objects
156+
5. **Blocking Operations**: Never block in BLE callbacks, ISRs, or FreeRTOS tasks without proper timeout
157+
6. **Lua Errors**: Always wrap Lua execution in error handlers to prevent firmware crashes
158+
7. **Frontend Bundle Size**: Keep JavaScript bundles small; the ESP32 flash is limited
159+
8. **Web Bluetooth Permissions**: User gesture required to trigger Bluetooth pairing
160+
9. **LEGO Device Timeouts**: Some LEGO devices timeout if no command is received within ~1 second
161+
10. **IMU Calibration**: MPU6050 requires proper initialization sequence; don't skip delays
162+
163+
### Testing & Debugging
164+
165+
**Serial Monitor:**
166+
- Baud rate: 115200
167+
- Use `pio device monitor` or VSCode PlatformIO extension
168+
- Log levels controlled by `CORE_DEBUG_LEVEL` (currently set to 2)
169+
170+
**Common Debugging Techniques:**
171+
- Monitor free heap: `ESP.getFreeHeap()`
172+
- Check task stack: `uxTaskGetStackHighWaterMark()`
173+
- Use ESP32 exception decoder for crash analysis
174+
- Web browser console for frontend debugging
175+
- Bluetooth HCI logs (enable in ESP-IDF menuconfig)
176+
177+
**Unit Testing:**
178+
- Framework: Unity (PlatformIO)
179+
- Test files should be in `/test` directory
180+
- Run with `pio test`
181+
182+
### Git Workflow
183+
184+
- Main branch: `main`
185+
- Commit messages should be clear and descriptive
186+
- Include "Co-Authored-By: Claude <noreply@anthropic.com>" when applicable
187+
- Don't commit secrets or credentials (use `config/secrets.ini`)
188+
189+
### External Dependencies
190+
191+
**PlatformIO Libraries:**
192+
- ArduinoJson 7.4.2
193+
- PubSubClient 2.8.0 (MQTT)
194+
- PsychicHttp 2.1.1 (HTTP server)
195+
- SC16IS752 (UART expander)
196+
- MPU6050 (IMU)
197+
- FastLED (LED control)
198+
199+
**Frontend Dependencies:**
200+
- Blockly 12.3.1
201+
- Vite 5.0.0
202+
- Prism.js 1.30.0
203+
204+
### Important Files Reference
205+
206+
- [platformio.ini](platformio.ini) - Build configuration
207+
- [src/main.cpp](src/main.cpp) - Application entry point
208+
- [lib/btremote/src/btremote.cpp](lib/btremote/src/btremote.cpp) - Bluetooth implementation
209+
- [lib/megahub/src/libluahub.cpp](lib/megahub/src/libluahub.cpp) - Lua bindings
210+
- [frontend/src/bleclient.js](frontend/src/bleclient.js) - Web Bluetooth client
211+
- [frontend/src/index.js](frontend/src/index.js) - Frontend main application
212+
213+
### Key Architecture Concepts
214+
215+
1. **Dual Mode Operation**: The device can operate in Bluetooth mode (default) or WiFi mode
216+
2. **Embedded Web Server**: Frontend files are embedded in firmware and served via PsychicHttp
217+
3. **Command Pattern**: All operations use a command pattern (see [lib/commands](lib/commands))
218+
4. **Port Abstraction**: Generic port interface supports both LEGO and standard devices
219+
5. **Lua Sandbox**: Lua scripts run in a controlled environment with custom bindings
220+
6. **Blockly Code Generation**: Blockly blocks generate Lua code which is then executed
221+
222+
### Performance Considerations
223+
224+
- **WiFi vs Bluetooth**: WiFi has better throughput but higher power consumption
225+
- **Lua Execution**: Lua is interpreted; performance-critical code should be in C++
226+
- **BLE MTU**: Larger MTU = better throughput but requires negotiation
227+
- **FastLED**: Can consume significant CPU time; use carefully in time-critical code
228+
- **I2C Bus Speed**: IMU and other I2C devices share a bus; consider timing
229+
230+
### Resources & Documentation
231+
232+
- [README.md](README.md) - User-facing documentation
233+
- [BLOCKS.md](BLOCKS.md) - Blockly blocks reference, automatically generated
234+
- ESP32 Documentation: https://docs.espressif.com/projects/esp-idf/
235+
- Web Bluetooth API: https://developer.mozilla.org/en-US/docs/Web/API/Web_Bluetooth_API
236+
- Lua 5.4 Reference: https://www.lua.org/manual/5.4/
237+
- Blockly Documentation: https://developers.google.com/blockly
238+
239+
---
240+
241+
## Quick Reference for Claude
242+
243+
**Before making changes:**
244+
1. Read relevant source files to understand current implementation
245+
2. Consider memory implications (heap, stack, flash)
246+
3. For Bluetooth code, review connection state management
247+
4. For LEGO code, verify protocol compliance
248+
5. Use implement-review-loop agent for significant changes
249+
250+
**When in doubt:**
251+
- Ask the user for clarification
252+
- Check existing code for patterns and conventions
253+
- Test on actual hardware when possible
254+
- Document assumptions and limitations
255+
256+
**Remember:**
257+
- ESP32 memory is limited - optimize aggressively
258+
- Bluetooth is fragile - handle errors gracefully
259+
- LEGO protocol is strict - follow specifications
260+
- Frontend must be lightweight - minimize bundle size
261+
- Always consider multi-threading implications (FreeRTOS)

‎README.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,9 @@
44

55
## Introduction
66

7-
Megahub is an ESP32-based alternative hub designed for LEGO© enthusiasts and robotics builders. It combines the flexibility of the ESP32 platform with native support for LEGO© WeDo/Powered Up! devices, offering both Lua scripting and Blockly visual programming for easy control and automation.
7+
Megahub is an ESP32-based experimentation platform designed for robotics enthusiasts and tinkerers. It brings together the versatility of the entire ESP32 ecosystem with convenient support for LEGO© WeDo/Powered Up! devices, offering both Lua scripting and Blockly visual programming for easy control and automation.
88

9-
This project provides a powerful, open-source alternative to proprietary solutions, giving makers complete control over their robotic creations while maintaining compatibility with popular LEGO© sensors and motors.
9+
This open-source project empowers makers to explore and build robotic creations using the full capabilities of the ESP32 platform – from WiFi and Bluetooth connectivity to a vast array of sensors and actuators – while seamlessly integrating popular LEGO© components alongside standard electronics.
1010
It comes with the hardware schematics, production files and the Megahub firmware as a PlatformIO project as well.
1111

1212
**Build and use it at your own Risk!!**
@@ -19,7 +19,7 @@ It comes with the hardware schematics, production files and the Megahub firmware
1919
- **IDE**: Configure and program Megahub through the intuitive [Megahub IDE](https://mirkosertic.github.io/Megahub/)
2020
- **Visual Programming Interface**: Blockly visual programming for beginners
2121
- **SD-Card**: Built-in SD-card reader to store multiple projects (autostart possible)
22-
- **4 UART Ports**: Connect up to 4 LEGO© WeDo/Powered Up! devices simultaneously (motors, sensors, etc.)
22+
- **4 Motors / Devices**: Connect up to 4 generic or LEGO© WeDo 2.0/Powered Up! devices simultaneously (motors, sensors, etc.)
2323
- **Built-in IMU**: Integrated MPU6050 6-axis accelerometer and gyroscope for motion sensing
2424
- **FastLED/NeoPixel Support**: Built-in support for addressable RGB LED strips
2525
- **Flexible GPIO**: Additional GPIO pins available for custom sensors, buttons, and peripherals

‎docs/blocks/algorithms/mh_alg_pid.png‎

22.4 KB
Loading

0 commit comments

Comments
 (0)