Balance bot: ESP32 PID balance controller with BLE dashboard

README.md

@@ -81,6 +81,7 @@ Commit and push. CI rebuilds firmware artifacts on `firmware/**` changes and com
 ```
 firmware/esp32_robot_idf/   ESP32 firmware (ESP-IDF)
 firmware/pi_robot/          Raspberry Pi firmware (Python + bless)
+packages/                   Reusable ESP-IDF components (pid, sensors, filters)
 public/                     Dashboard — static ES modules, no build step
 tests/                      Pure-function unit tests · make smoke
 .claude/                    Agent + project context

firmware/esp32_robot_idf/CMakeLists.txt

@@ -34,6 +34,12 @@ if(EXISTS "${MANAGED_COMPONENTS}" AND EXISTS "${PATCH_DIR}")
     endforeach()
 endif()
 
+list(APPEND EXTRA_COMPONENT_DIRS
+    "${CMAKE_CURRENT_SOURCE_DIR}/../../packages/pid"
+    "${CMAKE_CURRENT_SOURCE_DIR}/../../packages/sensors"
+    "${CMAKE_CURRENT_SOURCE_DIR}/../../packages/complementary"
+    "${CMAKE_CURRENT_SOURCE_DIR}/../../packages/kalman")
+
 include($ENV{IDF_PATH}/tools/cmake/project.cmake)
 
 project(esp32_robot)

firmware/esp32_robot_idf/README.md

@@ -34,6 +34,12 @@ main/
   telemetry.{c,h}   — uptime / heap / IP, every 10s
   webrtc_peer.{c,h} — wss signaling, esp_peer, ota + video + control data channels
   restart_util.{c,h} — deferred restart (used by pin/cam/ota commit paths)
+  balance.{c,h}      — 100 Hz FreeRTOS balance task (core 1); PID + lean/turn + I-dump timer
+  Kconfig.projbuild  — CONFIG_BALANCE_BOT_ENABLED + I2C pin / address / invert flags
+
+packages/ (EXTRA_COMPONENT_DIRS)
+  pid/               — generic discrete PID with anti-windup (no platform deps)
+  sensors/           — MPU6050 I2C driver, complementary filter → pitch angle
 ```
 
 ## Partition table

firmware/esp32_robot_idf/main/CMakeLists.txt

@@ -23,6 +23,7 @@ idf_component_register(
         "telemetry.c"
         "webrtc_peer.c"
         "http_stream.c"
+        "balance.c"
     INCLUDE_DIRS
         "."
     PRIV_REQUIRES
@@ -47,4 +48,7 @@ idf_component_register(
         esp_timer
         # JSON parsing (cJSON via ESP-IDF's json component)
         json
+        # Balance bot packages
+        pid
+        sensors
 )

firmware/esp32_robot_idf/main/Kconfig.projbuild

@@ -0,0 +1,43 @@
+menu "Balance Bot"
+
+    config BALANCE_BOT_ENABLED
+        bool "Enable balance bot (MPU6050 + PID)"
+        default n
+        help
+            Adds IMU polling task, balance PID loop, and four BLE
+            characteristics: BALANCE_CMD, BALANCE_PID, BALANCE_STATE,
+            BALANCE_TARGET. The MOTOR_CHAR remains for status reads but
+            the balance loop owns the actuators. Raw motor writes are
+            overridden immediately by the 100 Hz control task.
+
+    config BALANCE_BOT_I2C_PORT
+        int "I2C port number (0 or 1)"
+        depends on BALANCE_BOT_ENABLED
+        default 0
+
+    config BALANCE_BOT_I2C_SDA
+        int "MPU6050 SDA GPIO"
+        depends on BALANCE_BOT_ENABLED
+        default 21
+
+    config BALANCE_BOT_I2C_SCL
+        int "MPU6050 SCL GPIO"
+        depends on BALANCE_BOT_ENABLED
+        default 22
+
+    config BALANCE_BOT_IMU_ADDR
+        hex "MPU6050 I2C address"
+        depends on BALANCE_BOT_ENABLED
+        default 0x68
+        help
+            0x68 when AD0 pin is LOW (default). 0x69 when AD0 is HIGH.
+
+    config BALANCE_BOT_IMU_PITCH_INVERT
+        bool "Invert pitch sign"
+        depends on BALANCE_BOT_ENABLED
+        default n
+        help
+            Enable if the robot leans forward but the pitch angle reads
+            negative. Depends on how the MPU6050 is mounted on the frame.
+
+endmenu

firmware/esp32_robot_idf/main/app_main.c

@@ -4,6 +4,9 @@
 #include "esp_mac.h"
 #include "nvs_flash.h"
 
+#if CONFIG_BALANCE_BOT_ENABLED
+#include "balance.h"
+#endif
 #include "ble_host.h"
 #include "camera.h"
 #include "flash.h"
@@ -62,6 +65,11 @@ void app_main(void) {
     flash_init(pins.flash);
     motors_init(&pins);
 
+#if CONFIG_BALANCE_BOT_ENABLED
+    // Must run before fw_info_init so balance_enabled() reflects IMU status.
+    balance_init();
+#endif
+
     // fw-info reflects the cap surface; built once after caps are up.
     // Changes (camera profile, pin config) reboot, so a fresh boot
     // rebuilds it.