update docs

Author: c-lydia

.github/workflows/deploy-docs.yml

@@ -1,12 +1,16 @@
 name: Build & Deploy Documentation
 
-# Touching this file triggers a fresh Pages deployment.
+# Touching this file or the docs sources triggers a fresh Pages deployment.
 
 on:
   push:
     branches:
       - main
     paths:
+      - 'README.md'
+      - 'concepts.md'
+      - 'notes.md'
+      - 'user_manual.md'
       - 'docs/**'
       - '.github/workflows/deploy-docs.yml'
   workflow_dispatch:
@@ -42,8 +46,7 @@ jobs:
 
       - name: Build HTML documentation
         run: |
-          cd docs
-          sphinx-build -W --keep-going -b html source build/html
+          sphinx-build -W --keep-going -b html docs/source docs/build/html
 
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3

README.md

@@ -16,6 +16,7 @@ This repository includes:
 - User guide: [user_manual.md](user_manual.md)
 - Concepts guide: [concepts.md](concepts.md)
 - Theoretical calculation summary: [notes.md](notes.md)
+- PCB and KiCad sources: [pcb/wall_e_pcb_v1.0](pcb/wall_e_pcb_v1.0)
 - Sphinx docs index: `docs/source/index.rst`
 
 The Sphinx site includes the same high-level concepts and firmware details in a published format.
@@ -258,6 +259,14 @@ Host-side ROS 2 nodes can process these into cleaner and fused signals:
   - Inputs: `/imu/filter`, `/range/filter`
   - Outputs: `/fusion/height`, `/fusion/vertical_velocity`, `/fusion/debug`
 
+## PCB and Speed Sensing
+
+The board design lives in [pcb/wall_e_pcb_v1.0](pcb/wall_e_pcb_v1.0).
+
+The current schematic includes the ESP32 module, motor driver stages, the MPU6050, the HC-SR04 range sensor, and paired hall-effect sensors for wheel-speed or rotation feedback.
+
+Use the KiCad project as the source of truth for connector pinouts, board placement, and DRC/GERBER work before changing firmware wiring assumptions.
+
 This keeps firmware responsibilities focused on sensor I/O and control while allowing filter tuning on the host.
 
 ## Control and Localization Pipeline (Host)

concepts.md

@@ -123,3 +123,13 @@ When debugging from serial logs, treat these messages as distinct fault classes:
 Practical design point:
 
 - Keep early sensor checks before ROS startup so hardware faults are visible even if middleware setup blocks or restarts.
+
+## Board-Level Hardware
+
+The PCB design in [pcb/wall_e_pcb_v1.0](pcb/wall_e_pcb_v1.0) is the hardware reference for the current build.
+
+It includes the ESP32 carrier, motor drivers, the MPU6050, the HC-SR04 sensor path, and paired hall-effect sensors that can be used for wheel-speed or rotation feedback.
+
+This matters for the software stack because the firmware and localization layers should describe the same physical wiring and sensor roles as the board project.
+
+If wheel-speed or rotation pulses are added from the hall-effect sensors, treat them as another raw input stream and document whether they feed odometry directly or are only used for calibration.

docs/source/architecture.rst

@@ -43,6 +43,7 @@ ESP32 Firmware
 - **FreeRTOS**: Real-time operating system
 - **micro-ROS Client**: Lightweight ROS 2 client library
 - **Sensor drivers**: I2C for IMU, GPIO for ultrasonic sensor
+- **Board-level speed sensing**: hall-effect sensors are available on the PCB for wheel-speed or rotation feedback
 
 Communication Flow
 ==================

docs/source/concepts.rst

@@ -147,3 +147,14 @@ Related Reading
 - :doc:`architecture`
 - :doc:`firmware/esp32_controller`
 - :doc:`workflow_and_commands`
+
+Board-Level Hardware
+====================
+
+The PCB project in ``pcb/wall_e_pcb_v1.0`` is the hardware reference for the current build.
+
+It includes the ESP32 carrier, motor drivers, the MPU6050, the HC-SR04 sensor path, and paired hall-effect sensors that can be used for wheel-speed or rotation feedback.
+
+The software stack should keep its wiring assumptions aligned with the board project so firmware, localization, and documentation describe the same hardware layout.
+
+If wheel-speed or rotation pulses are added from the hall-effect sensors, treat them as another raw input stream and document whether they feed odometry directly or are only used for calibration.

docs/source/firmware/esp32_controller.rst

@@ -6,6 +6,8 @@ ESP32 Controller
 
 The ESP32 controller runs FreeRTOS with micro-ROS micro-sage communication. Two variants are provided: a full-featured **motor controller** with safety systems, and a lightweight **sensor-only** reference implementation for validation.
 
+The board-level design also includes paired hall-effect sensors for wheel-speed or rotation feedback, so the firmware and localization notes should stay aligned with the PCB wiring.
+
 Application Variants
 ====================
 
@@ -34,6 +36,8 @@ Features:
 - Lightweight for simulation and validation
 - Publishing: /imu/data, /range/data
 
+Use this app as the reference when you want the raw sensor path without the motor-control layer.
+
 Overview
 ========
 
@@ -64,6 +68,13 @@ Ultrasonic Sensor
 - **Trigger Pin**: GPIO 5 (motor variant) / GPIO 9 (sensor-only variant)
 - **Echo Pin**: GPIO 18 (motor variant) / GPIO 10 (sensor-only variant)
 
+Hall-Effect Speed Sensors
+-------------------------
+
+The PCB schematic includes paired hall-effect sensors for wheel-speed or rotation feedback.
+
+They are board-level inputs rather than part of the IMU or ultrasonic path, so document their GPIO routing and pulse-to-speed conversion wherever they are wired into firmware or localization.
+
 Motor Control (Motor Variant Only)
 ----------------------------------
 

docs/source/index.rst

@@ -4,7 +4,7 @@ Wall-E
 
 Welcome to Wall-E's comprehensive documentation. This project provides an integrated development environment combining ESP32 firmware, FreeRTOS, and ROS 2 Humble for advanced embedded robotics applications.
 
-The published site is built automatically from this source tree on pushes to `main`.
+The published site is built automatically from the ``docs/source`` tree on pushes to ``main``.
 
 .. toctree::
   :maxdepth: 2

notes.md

@@ -225,3 +225,19 @@ Wheel visual orientation uses a fixed $\frac{\pi}{2}$ roll, with quaternion:
 $$q = [x, y, z, w] = [\sin(\pi/4),\; 0,\; 0,\; \cos(\pi/4)] \approx [0.7071,\; 0,\; 0,\; 0.7071]$$
 
 These static publishers are conditionally disabled when `joint_state_publisher` is enabled.
+
+## Hall-Effect Wheel Speed Conversion
+
+Source: PCB hall-effect sensors in [pcb/wall_e_pcb_v1.0](pcb/wall_e_pcb_v1.0)
+
+The PCB includes paired hall-effect sensors that can be used for wheel-speed or rotation feedback.
+
+If the sensor produces a pulse train with pulse frequency $f$ and the wheel produces $PPR$ pulses per revolution, wheel speed in revolutions per minute is:
+
+$$rpm = \frac{60 f}{PPR}$$
+
+Linear wheel speed can then be derived from wheel diameter $D$:
+
+$$v = \frac{\pi D \cdot rpm}{60}$$
+
+Use the actual wheel geometry and pulse-per-revolution count from the KiCad design or assembly notes when calibrating this path.

user_manual.md

@@ -366,3 +366,16 @@ Defaults and behavior notes:
 
 - Main controller firmware: `firmware/custom/esp32_controller`
 - Reference firmware variant: `firmware/freertos_apps/apps/esp32_controller`
+
+## PCB, KiCad, and Speed Sensing
+
+The hardware design lives in [pcb/wall_e_pcb_v1.0](pcb/wall_e_pcb_v1.0).
+
+The KiCad schematic and PCB describe the current carrier board, including:
+
+- ESP32 module placement and power wiring
+- Motor driver connections
+- MPU6050 and HC-SR04 sensor connectors
+- Paired hall-effect sensors for wheel-speed or rotation feedback
+
+Treat the PCB project as the source of truth when checking connector pinouts or planning sensor wiring changes.