Skip to content

feat(bldc): Refactor bldc some to create new bldc_types component; add bldc_current_sense (untested); Improve motorgo APIs; Update BLDC examples to support running on Motorgo boards#658

Merged
finger563 merged 3 commits into
mainfrom
feat/bldc-types-refactor-improvement
Jun 29, 2026

Conversation

@finger563

Copy link
Copy Markdown
Contributor

Description

This PR is a set of related improvements to the BLDC motor stack. It factors the shared types and
concepts into a small dependency-light component, adds an (experimental) FOC
current-sense component and the driver hook it needs, makes the bldc_motor /
bldc_haptics examples runnable on the MotorGo Mini and Axis boards via Kconfig,
and gives the two MotorGo BSPs a symmetric API. Everything is additive /
backwards compatible.

1. New bldc_types component (shared types + concepts)

Moved the FOC value types (DqCurrent, DqVoltage, PhaseCurrent,
foc_utils.hpp), the control enums (bldc_types.hpp), and sensor_direction.hpp
out of bldc_motor into a new, dependency-light bldc_types component, and
added a new bldc_concepts.hpp that now holds the interface concepts
(DriverConcept, SensorConcept, CurrentSensorConcept, MotorConcept) plus
DummyCurrentSense. bldc_motor, bldc_haptics, and bldc_current_sense now
depend on bldc_types, which decouples them from each other (notably,
bldc_current_sense no longer depends on bldc_motor). Header moves are tracked
as git renames; bldc_motor.hpp still includes the same headers, so external
code that includes bldc_motor.hpp is unaffected.

2. Torque-control groundwork

  • Documented that TorqueControlType::VOLTAGE is fully supported (no current
    sense required), while DC_CURRENT / FOC_CURRENT are experimental and need a
    CurrentSensorConcept implementation + PWM-synchronized sampling + per-board
    tuning.
  • BldcDriver::register_pwm_sample_callback(): registers a callback fired at
    the MCPWM timer "empty" (TEZ) event — the instant the low-side FETs conduct in
    this center-aligned configuration — so callers can trigger a PWM-synchronized
    current-sense ADC read.
  • CurrentSensorConcept::driver_align() is now non-const (a real current sensor
    must capture calibration state); DummyCurrentSense updated to match.

3. New bldc_current_sense component (experimental)

Adds espp::CurrentSense<Driver>, a generic FOC current sensor implementing the
CurrentSensorConcept. It is decoupled from any specific ADC via a
read_phase_currents callback, and handles zero-current offset calibration
(driver_align()), per-phase gain-sign correction, two-phase reconstruction
(Ia + Ib + Ic = 0), and the Clarke + Park transforms (get_foc_currents() /
get_dc_current()). Includes a hardware-free example that statically asserts
concept conformance and exercises the calibration + transform pipeline, plus
docs. Marked EXPERIMENTAL: automatic phase-ordering / gain-sign discovery is not
implemented, and current-mode torque control must be validated on hardware.

4. Examples runnable on MotorGo boards via Kconfig

The bldc_motor and bldc_haptics examples gained Kconfig hardware options for
MotorGo Mini and MotorGo Axis (alongside the existing Test Stand /
Custom), plus a Motor 1 / Motor 2 channel choice. The examples build a
std::shared_ptr<BldcMotor> + std::shared_ptr<BldcDriver> from the selected
board.

5. Symmetric MotorGo Mini / Axis API

Both espp::MotorGoMini and espp::MotorGoAxis now expose the same zero-based,
index-based API (num_motor_channels(), initialize_encoders(),
initialize_motors(), encoder(i), motor_driver(i), motor(i),
reset_encoder_accumulator(i), the driver enable/disable helpers,
default_motor_config(i), and initialize_motor(i, config)), with shared
Encoder / MotorDriver / BldcMotor type aliases. Axis now owns the
BldcMotor objects (it previously exposed only drivers + encoders). All existing
methods on both boards are unchanged. With this, the example board branches
collapse to a single using Board = espp::MotorGoMini; (or MotorGoAxis;) and
identical setup code.

Motivation and Context

  • The BLDC components had grown circular/awkward coupling (shared types/concepts
    living inside bldc_motor); bldc_types cleanly factors them out.
  • Torque control was scaffolded but unusable without a current sensor;
    bldc_current_sense + the driver PWM hook provide the missing pieces (still
    experimental, pending hardware validation).
  • The MotorGo boards had diverged APIs, making board-agnostic code and examples
    awkward; the symmetric API makes switching boards a one-line change.

How has this been tested?

  • Environment: ESP-IDF v6.0.1, target esp32s3 (plus esp32p4/esp32s3 for
    unrelated BSP sanity where applicable).
  • Built the bldc_motor, bldc_haptics, bldc_current_sense, motorgo-mini,
    and motorgo-axis examples — all clean.
  • Built the bldc_motor and bldc_haptics examples in the default / MotorGo
    Mini / MotorGo Axis configurations (including the Motor 2 channel) — all clean.
  • bldc_current_sense example validates CurrentSenseConcept conformance via a
    compile-time static_assert and exercises the offset-removal + Clarke/Park +
    reconstruction pipeline in software (no hardware required).
  • Confirmed existing APIs still compile: the 1-based MotorGo Mini API, the
    existing MotorGo Axis API, and external includes of bldc_motor.hpp.

NOTE: the FOC current-feedback torque modes have not been validated on physical hardware in this PR.

Screenshots (if appropriate, e.g. schematic, board, console logs, lab pictures):

N/A

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • Documentation Update
  • Software change

Checklist:

  • My change requires a change to the documentation.
  • I have added / updated the documentation related to this change via either README or WIKI

Software

  • I have added tests to cover my changes.
  • I have updated the .github/workflows/build.yml file to add my new test to the automated cloud build github acti
  • All new and existing tests passed.
  • My code follows the code style of this project.

…add `bldc_current_sense` (untested); Improve motorgo APIs; Update BLDC examples to support running on Motorgo boards
@github-actions

github-actions Bot commented Jun 29, 2026

Copy link
Copy Markdown

✅Static analysis result - no issues found! ✅

@finger563 finger563 self-assigned this Jun 29, 2026
@finger563 finger563 added enhancement New feature or request motor control haptics bldc Related to Brushless DC Motors motorgo mini motorgo axis labels Jun 29, 2026
@finger563 finger563 merged commit f197765 into main Jun 29, 2026
120 checks passed
@finger563 finger563 deleted the feat/bldc-types-refactor-improvement branch June 29, 2026 16:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bldc Related to Brushless DC Motors enhancement New feature or request haptics motor control motorgo axis motorgo mini

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant