- JavaScript 44.9%
- C++ 27.9%
- Jinja 27.2%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| custom_templates | ||
| dashboards | ||
| docs | ||
| esphome | ||
| packages | ||
| www | ||
| .DS_Store | ||
| configuration.yaml | ||
| readme.md | ||
Innovation Factory Cyber-Physical Assembly Testbed
A modular, scalable firmware and Home Assistant backend architecture for a multi-station manual assembly testbed. Each assembly station features 8 independent HX711 load cell bins with real-time digital signal processing (DSP), dynamic part-weight catalog syncing, high-frequency 100ms MQTT telemetry logging, real-time 3D artifact orientation (25Hz / 40ms) and Bill of Materials (BOM) tracking across stations, and an automated optical encoder artifact quality verification system.
Table of Contents
- Repository Structure & File Reference
- Dashboard UI & Visual Overview
- System Architecture & Core Subsystems
- Prerequisites
- Step-by-Step Installation Guide
- Standard Operating Procedures (SOP)
- Scaling the Testbed
- Tunable Parameters & Engineering Reference
- Hardware Limitations & Physical Constraints
- Hardware Best Practices
Repository Structure & File Reference
The repository mirrors the target /config/ directory structure of a production Home Assistant instance:
└── homeassistant/
├── configuration.yaml # Core HA config: enables packages, QC rig logic, stepper REST commands & artifact tracking
├── custom_templates/
│ └── artifact_tracking.jinja # Reusable Jinja2 macros for station part-consumption & BOM verification
├── packages/
│ └── parts_catalog.yaml # Self-contained Master Parts DB, scripts, dropdowns & auto-discovery automations
├── www/
│ ├── artifact.glb # 3D GLTF/GLB model of the smart artifact for real-time dashboard rendering
│ └── imu-visualizer.js # Custom Three.js WebGL card script for real-time 3D roll/pitch/yaw visualization
├── dashboards/
│ ├── full-assy-line-dashboard.yaml # Complete multi-view Lovelace dashboard for all stations & quality control
│ ├── imu-visualizer.yaml # Standalone Lovelace YAML for the 3D Artifact IMU Visualizer card
│ ├── parts-catalog.yaml # Standalone Lovelace YAML for the Master Parts Catalog manager card
│ └── quality-control-card.yaml # Standalone Lovelace YAML for the Quality Check HUD & tactile rig controls
└── esphome/
├── assembly-station-1.yaml # Station 1 ESP32 node definition (substitutions, Wi-Fi/OTA, includes common config)
├── assembly-01.yaml # Smart Artifact 01 ESP32 node definition (includes artifact_config.yaml)
├── madgwick_sensor.h # Custom C++ sensor header implementing FastMadgwick quaternion AHRS IMU fusion
└── common/
├── assembly_station_config.yaml # Shared station config: 8x load_cell_template includes & 100ms MQTT telemetry
├── load_cell_template.yaml # Parameterized single load-cell DSP, Kalman filter & calibration template
└── artifact_config.yaml # Shared M5StickC Plus 2 config (MPU6886 IMU, BLE iBeacon, ST7789V LCD, Optical RPM)
Component Breakdown
| File Path | Role in the Architecture |
|---|---|
configuration.yaml |
Loads the packages/ directory, defines the stepper motor REST commands (quality_test, stepper_stop, stepper_play_fur_elise), evaluates sliding-window RPM quality checks, and instantiates the active artifact BOM tracker. |
custom_templates/artifact_tracking.jinja |
Provides Jinja2 macros (station_part_inventory, station_parts_picked, verify_artifact_bom) that calculate real-time part consumption deltas across all 8 bins of the active station. |
packages/parts_catalog.yaml |
Implements the event-driven Master Parts Database (sensor.master_parts_catalog), CRUD scripts, per-bin input_select helpers, and regex auto-discovery automations that push unit weights to ESPHome nodes. |
www/imu-visualizer.js & artifact.glb |
Defines the <imu-3d-card> custom WebGL element using Three.js (v0.160.0) and GLTFLoader to auto-scale, center, and rotate /local/artifact.glb in real time using YXZ intrinsic Euler angles. |
esphome/madgwick_sensor.h |
Implements the FastMadgwick C++ class (beta = 0.1f) using the fast inverse square root (0x5f3759df) algorithm to fuse raw 100Hz accelerometer and gyroscope readings into quaternion-derived Roll, Pitch, and Yaw angles. |
esphome/common/load_cell_template.yaml |
Parameterized package instantiated 8 times per station. Contains the HX711 driver, 9-sample median spike filter, adaptive 1D Kalman filter, flash-safe thermal drift tracker, and stability-gated item counter. |
esphome/common/assembly_station_config.yaml |
Maps the 8 load cells to their physical ESP32 GPIO pins, staggers ADC polling intervals, and broadcasts a unified JSON telemetry payload over MQTT every 100ms with UNIX millisecond timestamps. |
esphome/common/artifact_config.yaml |
Shared firmware profile for the M5StickC Plus 2 smart artifact: manages 5s startup gyro bias calibration, 40ms (25Hz) MQTT & HA orientation streaming, BLE iBeacon broadcasting (50ms–80ms), ST7789V on-screen display, non-linear LiPo battery curve, and GPIO32 optical encoder RPM verification. |
Dashboard UI & Visual Overview
Note: Place your screenshot images inside a
docs/images/folder in the repository (or update the paths below to match your image filenames).
1. Station Load Cell & Bucket KPI Card (dashboards/full-assy-line-dashboard.yaml)
Each of the 8 load cells per station is rendered using a compact #BA0C2F KPI header (custom:button-card) paired with inline part assignment, Tare, and Calibrate controls:
2. Master Parts Catalog Manager (dashboards/parts-catalog.yaml)
Operators can add new parts, update unit weights in grams, or remove obsolete parts directly from the UI without reflashing any ESP32 nodes:
3. Real-Time 3D IMU Digital Twin (dashboards/imu-visualizer.yaml)
Streams 25Hz Roll, Pitch, and Yaw telemetry from the artifact's MPU6886 IMU into an interactive Three.js WebGL canvas rendering artifact.glb:
4. Artifact Quality Verification HUD & Rig Controls (dashboards/quality-control-card.yaml)
Displays real-time pass/wait status alongside tactile controls for starting the optical RPM test, adjusting stepper target RPM, and triggering an immediate Emergency Stop:
System Architecture & Core Subsystems
1. Multi-Stage Load Cell DSP Pipeline (load_cell_template.yaml)
Raw HX711 load cell readings are susceptible to ESP32 Wi-Fi current dips, bit-bang timing interrupts, ambient temperature drift, and operator hand pressure. Each load cell executes a 4-stage real-time filter pipeline directly on the station ESP32; the full signal-flow diagram is discussed again in the load-cell limitations section.
- Staggered Polling & Spike Rejection (
load_raw): The 8 HX711 sensors per station are polled at staggered intervals (93msto107ms) to prevent CPU lockups during100msMQTT broadcasts. A 9-sample moving median filter discards momentary bit-shift glitches up to400mslong. - Adaptive 1D Kalman Filter (
load_mass): Dynamically switches process noise covariance (Q) between ultra-smooth resting tracking (Q = 0.0005) and instantaneous step response (Q = 2.0) when a weight change> 1.2\text{ g}is confirmed for 3 consecutive ticks (300ms). - Flash-Safe Continuous Thermal & Creep Compensation: Tracks an internal
thermal_anchorin RAM. Continuous ambient temperature drift and mechanical strain-gauge creep are bled off at0.5\%per tick without writing to ESP32 NVS flash memory. Maximum correction speeds are clamped to prevent fighting physical settling vibrations, completely eliminating stepped "dead zone" drift on the graphs. - "Hand-in-Bin" Stability Gate & Fractional Hysteresis (
l_item_count): Prevents false item-count spikes when an operator reaches into a bin. The item counter freezes whenever the bin weight is actively changing (\Delta m \ge 0.5\text{ g}) and only updates after the scale settles for 4 consecutive ticks (800ms), using a\pm 0.60\text{ item}deadband to eliminate rounding flicker.
2. Smart Artifact Telemetry, IMU Fusion & On-Device Display (artifact_config.yaml)
Each smart artifact is powered by an M5StickC Plus 2 running a high-frequency sensor fusion and telemetry loop; the end-to-end telemetry path is shown in the diagram below:
- Startup Gyro Bias Calibration &
FastMadgwickAHRS (madgwick_sensor.h): The onboardMPU6886IMU is sampled every10ms(100Hz). On boot, the first250samples (5 seconds) are averaged to establish baseline gyroscope offsets (gx_offset,gy_offset,gz_offset). Subsequent readings are integrated every20ms(50Hz) via quaternion gradient descent (beta = 0.1f) and published to Home Assistant and MQTT (testbed/telemetry/artifact-XX) every40ms(25Hz). - Hardware Button Controls:
- Button A (GPIO37 — Single Press): Immediately zeros out the Madgwick quaternion (
q0=1, q1=0, q2=0, q3=0), resets Pitch, Roll, Yaw, and RPM to0.0on the dashboard, clears theQuality Check Passedlatch, and silences the buzzer. - Button B (GPIO39 — Single Click): Toggles the
ST7789VLCD backlight and display rendering loop to conserve battery. - Button B (GPIO39 — Double Click): Suspends or resumes the
MPU6886IMU component (gyro_is_on), indicated by a green/red status dot in the bottom-left corner of the artifact screen.
- Button A (GPIO37 — Single Press): Immediately zeros out the Madgwick quaternion (
- BLE iBeacon Station Localization: Broadcasts an iBeacon frame every
50ms–80ms(UUID: c29ce823-e67a-4e71-bff2-abaa32e77a98,major: ${artifact_num}) for room/station-level proximity tracking. - On-Board Optical Encoder RPM & Quality Pass Band: Reads optical slot pulses on
GPIO32(pulse_meter,multiply: 0.03333for a 30-slot encoder wheel), applies a0.1sthrottle average followed by a 20-sample circular moving-average buffer, and triggers an onboard pass (248.0to252.0 RPMheld for2s) with an audible double-beep on the piezo buzzer (GPIO2) and greenQUALITY CHECK PASSEDscreen banner.
3. Dynamic Master Parts Catalog (packages/parts_catalog.yaml)
- Zero-Reflash Part Management: Operators can add, edit, or delete parts and their average unit weights directly from the Home Assistant UI.
- Persistent Event-Driven Database: Stored inside a trigger-based template sensor (
sensor.master_parts_catalog) that survives Home Assistant restarts. - Regex Auto-Discovery: Automations automatically detect all station dropdowns matching
input_select.assembly_station_<X>_load_<Y>_partand push the selected part's weight to the corresponding ESP32 entity (number.station_<X>_assembly_station_<X>_load_<Y>_average_part_weight).
4. Real-Time BOM Part Tracking & Quality Check Rig (configuration.yaml)
- Bin-to-Artifact Part Tracking: As an artifact enters an assembly station, Home Assistant snapshots the station's 8 load cell item counts and tracks the net consumption delta (
\Delta = \text{Initial Count} - \text{Current Count}) for every assigned part name against the required Bill of Materials (BOM). - Sliding-Window RPM Verification: Evaluates the artifact's RPM sensor during spin testing. To prevent defective parts (such as an artifact with extra slots whose average RPM climbs through the target band) from triggering a false positive, the binary sensor requires at least 2 consecutive sliding-window updates strictly inside
[min_rpm, max_rpm]and immediately revokes the pass if the RPM overshootsmax_rpm.
5. ESP Wiring Diagrams
- The wiring guides below let you match the GPIO pins in the code to the physical GPIO pins on your microcontroller. If different wiring is desired, the pins in the
assembly_station_config.yamlorartifact_config.yamlfiles must be changed to match.
Prerequisites
- Home Assistant OS / Supervised / Container (2024.4 or newer recommended).
- ESPHome Integration & Add-on for compiling and OTA-flashing station and artifact nodes.
- MQTT Broker (e.g., Mosquitto Add-on) configured in both Home Assistant and ESPHome for the
100msstation and40msartifact telemetry streams. - Local NTP Server reachable by the ESP32 nodes (configured as
ntp.mgmt.laninartifact_config.yaml) to ensure sub-millisecond UNIX timestamp synchronization across edge payloads. - HACS (Home Assistant Community Store) with button-card (
custom:button-card) installed. - Internet/CDN Access on Dashboard Client Devices:
imu-visualizer.jsdynamically imports Three.js (https://esm.sh/three@0.160.0) in the browser.
Step-by-Step Installation Guide
Step 1: Copy Repository Files to Home Assistant
Copy the contents of the homeassistant/ directory in this repository directly into your Home Assistant /config/ directory so that custom_templates/, packages/, www/, and esphome/ merge into /config/.
Verify that /config/configuration.yaml includes the package loader at the top level (ensure there is no colon after !include_dir_named):
homeassistant:
packages: !include_dir_named packages
Step 2: Register the 3D IMU Visualizer Frontend Resource
To allow Home Assistant to render the custom <imu-3d-card> WebGL element (www/imu-visualizer.js) and load the 3D model (www/artifact.glb):
- In Home Assistant, navigate to Settings
\rightarrowDashboards. - Click the Three Dots (
\vdots) menu in the top-right corner and select Resources. - Click Add Resource and enter:
- URL:
/local/imu-visualizer.js - Resource Type:
JavaScript Module
- URL:
- Click Create and perform a hard refresh (
Ctrl + F5) in your browser. - Add the card to any view using the following configuration (
dashboards/imu-visualizer.yaml):
type: custom:imu-3d-card
title: "Artifact 01 Orientation"
pitch_entity: sensor.assembly_01_imu_pitch
roll_entity: sensor.assembly_01_imu_roll
yaw_entity: sensor.assembly_01_imu_yaw
Step 3: Configure Secrets & Flash ESPHome Nodes
Ensure your /config/esphome/secrets.yaml defines your Wi-Fi, OTA, API, and MQTT credentials, and verify that your MQTT broker (homeassistant.servers.lan) and NTP server (ntp.mgmt.lan) in common/artifact_config.yaml and common/assembly_station_config.yaml match your local network.
- Open the ESPHome Dashboard in Home Assistant.
- Compile and flash your station nodes (
assembly-station-1.yaml, etc.) and smart artifact nodes (assembly-01.yaml). - Important on Artifact Boot: Keep the smart artifact completely flat and stationary for the first 5 seconds after power-on or reboot while it collects
250samples to calibrate its gyroscope zero-rate offsets.
Step 4: Reload Home Assistant Backend & Import Dashboards
- Go to Developer Tools
\rightarrowYAML, click Check Configuration, and restart Home Assistant to initialize theparts_catalog.yamlpackage andartifact_tracking.jinjamacros. - To deploy the full assembly line dashboard:
- Create a new dashboard under Settings
\rightarrowDashboards\rightarrowAdd Dashboard. - Open the new dashboard, click Edit (pencil icon)
\rightarrowThree Dots (\vdots)\rightarrowRaw configuration editor. - Paste the contents of
dashboards/full-assy-line-dashboard.yamland click Save.
- Create a new dashboard under Settings
Standard Operating Procedures (SOP)
1. Managing the Master Parts Catalog
All part weights are managed centrally from the Parts Catalog card (dashboards/parts-catalog.yaml):
- Add a New Part: Enter the part name into 1. Enter Part Name, enter the single-piece weight (in grams) into 2. Enter Single Part Weight (g), and click SAVE PART. The part immediately appears in the catalog table and populates into all station bin dropdowns.
- Update an Existing Part's Weight: Enter the exact existing name of the part into 1. Enter Part Name, enter the updated weight into 2. Enter Single Part Weight (g), and click SAVE PART. Every station bin currently assigned to that part will automatically receive the updated weight within milliseconds.
- Delete a Part: Enter the exact part name into 1. Enter Part Name and click DELETE.
- Assign a Part to a Bucket: Select the part from the Part dropdown directly underneath any bucket's
#BA0C2FKPI card.
2. Taring & Calibrating a Load Cell Bucket
- Zero / Tare: Empty the bucket completely and click Tare underneath that bucket's KPI card.
- Adjust Calibration Reference Mass: Press and hold (
hold_action) on the Calibrate button to open theCalibration Massinput popup (default500 g). - Calibrate Known Mass: Place your reference calibration weight into the empty, tared bucket, wait 1 second for the reading to settle, and tap Calibrate.
3. Operating the Smart Artifact & Resetting IMU Drift
- Re-Zeroing the 3D Model (
Button A): Place the physical artifact in its reference home orientation and press the front Button A (M5button, GPIO37). This resets the onboard quaternion to identity(1, 0, 0, 0), snaps the 3D visualizer back to(0^\circ, 0^\circ, 0^\circ), and clears any prior quality check pass state. - Power Saving (
Button B):- Single-click the side Button B (GPIO39) to toggle the LCD screen and backlight ON/OFF.
- Double-click Button B to suspend/resume the MPU6886 IMU (indicated by the bottom-left status dot turning red when suspended or green when active).
4. Operating the Quality Verification Rig
- Set the target test speed in Target Stepper RPM (
input_number.stepper_rpm). - Click START QUALITY TEST to trigger
rest_command.quality_test. - The HUD card will display WAITING TO PASS QUALITY (pulsing amber) until the RPM stabilizes inside the target pass window without overshooting, at which point it transitions to PASSED QUALITY CHECK (glowing neon green) and triggers the artifact's onboard piezo chime.
- Click EMERGENCY STOP at any time to halt the stepper motor via
rest_command.stepper_stop.
Scaling the Testbed
Adding a New Assembly Station (e.g., Station 4)
- Create the ESPHome Node: Duplicate
esphome/assembly-station-1.yamlasesphome/assembly-station-4.yamland update the node name and substitutions:
esphome:
name: "assembly-station-4"
friendly_name: Assembly Station 4
substitutions:
station_id: "04"
station_num: "4"
packages:
station_common: !include common/assembly_station_config.yaml
- Add Station Dropdown Helpers: Open
packages/parts_catalog.yamland duplicate the 8input_selectlines underinput_select:, changing_3_(or_1_) to_4_(assembly_station_4_load_1_partthroughassembly_station_4_load_8_part). - Hot-Reload: In Home Assistant, go to Developer Tools
\rightarrowYAML and click Input Selects. The regex auto-discovery automations (^assembly_station_\d+_load_\d+_part$) will automatically detect Station 4 and sync all 8 load cells.
Tunable Parameters & Engineering Reference
1. Load Cell DSP Parameters (esphome/common/load_cell_template.yaml)
| Parameter / Variable | Location | Default | Description & Tuning Guidance |
|---|---|---|---|
gain |
sensor.hx711 |
128 |
HX711 Channel A PGA gain (128 or 64). 128 provides 1 extra bit of noise-free resolution. Recalibrate after changing. |
window_size |
sensor.hx711 \rightarrow median |
9 |
Number of raw samples in the median filter. Rejects up to \frac{N-1}{2} consecutive corrupted samples (400ms at 100ms polling). |
diff > 1.2 |
load${num}_mass lambda |
1.2 (\text{g}) |
Step-detection threshold. Lower to 0.4 if measuring micro-parts under 0.8\text{ g}; increase to 2.5 in high-vibration environments. |
step_confirm_count >= 3 |
load${num}_mass lambda |
3 (ticks) |
Number of consecutive 100ms ticks a weight jump must persist to trigger fast Kalman response. |
q (Resting / Step) |
load${num}_mass lambda |
0.0005 / 2.0 |
Kalman process noise covariance (Q). Lower resting q (0.0001) for heavier smoothing; increase step q for faster jumps. |
r |
load${num}_mass lambda |
0.5 |
Kalman measurement noise covariance (R). Increase (e.g., 1.0) if raw load cell noise is high. |
fabs(drift) > 0.05 |
load${num}_mass lambda |
0.05 (\text{g}) |
Micro-noise ignore threshold. Prevents the thermal compensator from chasing minor sensor jitter under 0.05\text{g}. |
correction_max |
load${num}_mass lambda |
\pm 0.01 (\text{g}) |
Clamps maximum speed of thermal compensation so it does not falsely absorb physical settling after a part is placed. |
fabs(estimate) < 0.25 |
load${num}_mass lambda |
0.25 (\text{g}) |
Empty-bin zero snap threshold. Readings within \pm 0.25\text{ g} of zero report 0.00 g. |
fabs(current_mass - prev_mass) < 0.5 |
l${num}_item_count lambda |
0.5 (\text{g}) |
Stability gate threshold. If mass moves by \ge 0.5\text{ g} between 200ms ticks (hand in bin), the item counter freezes. |
stable_ticks >= 4 |
l${num}_item_count lambda |
4 (ticks) |
Settling time (4 \times 200\text{ ms} = 800\text{ ms}) required after a hand leaves the bin before the item count updates. |
>= 0.60 |
l${num}_item_count lambda |
0.60 (items) |
Fractional hysteresis deadband. Prevents item count from flickering when weight sits near a 0.5 rounding boundary. |
2. Smart Artifact IMU, Optical RPM & Visualizer Parameters (artifact_config.yaml, madgwick_sensor.h, imu-visualizer.js)
| Parameter / Variable | Location | Default | Description & Tuning Guidance |
|---|---|---|---|
CAL_SAMPLES |
artifact_config.yaml (20ms interval) |
250 (5.0s) |
Number of stationary gyro samples averaged at boot to cancel zero-rate bias. Increase to 500 (10s) for tighter yaw stability. |
beta |
madgwick_sensor.h |
0.1f |
Madgwick filter divergence gain (\beta). Higher values (0.2f–0.5f) snap faster to accelerometer gravity but pass more vibration noise; lower values (0.03f–0.05f) rely more on the gyroscope. |
publish_counter >= 2 |
artifact_config.yaml (20ms interval) |
2 (40ms / 25Hz) |
Decimation ratio between the 50Hz Madgwick integration loop and Home Assistant state publishing. |
multiply: 0.03333 |
sensor.pulse_meter (rpm_sensor) |
0.03333 (\frac{1}{30}) |
Converts raw pulses/minute from a 30-slot optical encoder disk into true shaft RPM (\text{RPM} = \frac{\text{Pulses/min}}{\text{Slots}}). Adjust to \frac{1}{N} if slot count changes. |
window[20] |
sensor.pulse_meter (rpm_sensor) |
20 (2.0s) |
Circular moving-average window size applied after the 0.1s throttle average. Resets immediately to 0.0 when x <= 0.01f (timeout: 0.25s). |
248.0 to 252.0 |
binary_sensor.rpm_in_pass_band |
250 \pm 2\text{ RPM} |
On-device RPM pass band required for delayed_on: 2s to trigger the M5StickC screen pass banner and buzzer chime. |
delta > 0.18f |
binary_sensor.assembly_moving |
0.18g (3 ticks) |
Planar XY acceleration delta required for 3 consecutive ticks to flag the artifact as actively moving (delayed_off: 2000ms). |
targetSize |
www/imu-visualizer.js |
3.0 |
Bounding-box normalization scale factor in Three.js units for artifact.glb. |
Hardware Limitations & Physical Constraints
Understanding the physical limitations of the low-cost sensors used in this testbed is essential when choosing part weights, calibrating bins, and interpreting orientation data. The signal-processing path for the load cells is summarized below and reflects the same 4-stage filter chain described in the DSP section above:
1. HX711 & Strain-Gauge Load Cell Noise Floor (\approx \pm 0.3\text{ g} to 0.8\text{ g} Peak-to-Peak)
- Baseline Noise Floor: Even with
gain: 128, a 9-sample median filter, and adaptive 1D Kalman filtering (q = 0.0005,r = 0.5), standard1\text{ kg}to5\text{ kg}aluminum strain-gauge load cells paired with generic HX711 breakouts exhibit a resting peak-to-peak noise floor of approximately0.6\text{ g}to $0.8\text{ g}$ (\approx \pm 0.3\text{ g}to\pm 0.4\text{ g}) under a1,500\text{ g}static load (\approx 0.05\%full-scale). - Minimum Part Weight Constraint: Because the item counter requires a
\pm 0.60\text{ item}hysteresis threshold and the Kalman step detector looks for jumps> 1.2\text{ g}, individual parts should ideally weigh $\ge 1.5\text{ g}$ for100\%single-piece counting reliability. Parts lighter than1.0\text{ g}approach the resting thermal/ADC noise floor and may get absorbed by the sub-0.45\text{ g}thermal drift compensator unless picked in multiples. - Asynchronous Clock Slip & Bit-Bang Glitches: The HX711 lacks hardware SPI/I2C and relies on bit-banged clock pulses where any
CLK HIGHpulse stretched beyond60\text{ }\mu\text{s}by an ESP32 Wi-Fi/FreeRTOS interrupt triggers a power-down reset spike. While the 9-sample median filter (400ms) and10,000gbounds check reject these glitches in software, polling faster than80mson un-modified10HzHX711 boards is not possible without bridging the hardwareRATEpin toVCC(80Hzmode, which increases raw RMS noise by\approx \sqrt{8}). - Mechanical Creep & Thermal Sensitivity: Strain gauges physically creep under sustained heavy loads and react to convective air drafts across the HX711's on-board voltage divider resistors. The software thermal anchor compensates for slow drift (
< 0.45\text{ g}), but sudden HVAC blasts or leaning on the station frame can exceed the compensation window.
2. 6-DOF IMU Yaw Drift & Startup Calibration Constraints (MPU6886)
- Unbounded Yaw (Heading) Drift: The M5StickC Plus 2 integrates a 6-DOF IMU (
MPU6886— 3-axis accelerometer + 3-axis gyroscope) and does not have a 3-axis magnetometer (compass). WhileFastMadgwickuses the accelerometer's gravity vector to continuously lock Roll and Pitch against long-term drift, there is no horizontal magnetic reference to anchor Yaw ($Z$-axis rotation). Consequently, minor uncompensated gyroscope bias and temperature shifts will cause the Yaw angle to slowly drift over time (typically0.5^\circto3^\circper minute).- Mitigation: Press Button A (GPIO37) on the artifact prior to critical orientation tasks to instantaneously zero the quaternion (
global_madgwick.reset()), or double-click Button B (GPIO39) to suspend the IMU when stationary.
- Mitigation: Press Button A (GPIO37) on the artifact prior to critical orientation tasks to instantaneously zero the quaternion (
- Mandatory Stationary Boot Window (
5 Seconds): During the first250loops (5.0 seconds) after power-on, the firmware sums raw gyroscope readings to computegx_offset,gy_offset, andgz_offset. If an operator is holding or moving the artifact while it boots or reboots, the motion will be baked into the static offset, causing severe, continuous spinning of the 3D model in Home Assistant. If this occurs, set the artifact down on a flat surface and reboot it. - Linear Acceleration Distortion: During rapid translational movement (sliding the artifact quickly across workstations) or high-speed spin testing, centrifugal and linear accelerations temporarily distort the gravity vector used by the Madgwick filter (
beta = 0.1f), causing brief tilt artifacts in Roll/Pitch until the artifact comes back to rest. - Gimbal Lock at
\pm 90^\circPitch: Although internal state integration uses quaternions (q0..q3) which are immune to gimbal lock, the telemetry output converts orientation to Euler angles (asinffor pitch,atan2ffor roll/yaw) and applies them inYXZorder in Three.js. Pitch angles approaching exactly\pm 90^\circwill exhibit Euler angle coupling between Roll and Yaw.
3. Optical Encoder & Battery Measurement Constraints
- Smoothing Latency vs. Instantaneous RPM: The optical encoder (
GPIO32) uses a0.1sthrottle average cascaded into a 20-sample circular moving average (2.0 secondstotal fill time) to eliminate slot-to-slot jitter. While stopping the wheel (timeout: 0.25s) immediately resets the buffer to0 RPM, accelerating from0to250\text{ RPM}requires up to2.0\text{ seconds}for the circular buffer to fully converge—which is why the quality check logic enforces a multi-sample settling window. - Battery Voltage Under Load: The
GPIO38ADC battery percentage lookup table models a resting 1-cell LiPo discharge curve (3.10\text{ V}to4.20\text{ V}). High Wi-Fi/BLE transmission bursts and full LCD backlight brightness cause a temporary $50\text{ mV}$–100\text{ mV}voltage sag, which can make the reported percentage dip by $5%$–10\%until the load is reduced.
Hardware Best Practices
- Power Supply Decoupling: Solder a
10\text{ }\mu\text{F}to100\text{ }\mu\text{F}electrolytic capacitor in parallel with a0.1\text{ }\mu\text{F}ceramic capacitor acrossVCCandGNDat the HX711 power rails to absorb ESP32100msWi-Fi current spikes. - Airflow & Draft Isolation: Cover the HX711 IC and its on-board voltage-divider SMD resistors (
R1/R2) with closed-cell foam or Kapton tape to prevent HVAC air currents from creating localized thermal gradients across the reference divider. - Analog Ground Tie (
E-toGND): On green HX711 breakout PCBs, verify continuity betweenE-andGNDwith a multimeter. If isolated, solder a jumper bridge betweenE-andGNDto eliminate60\text{ Hz}common-mode noise.