MotorGo Axis

MotorGo Axis

The MotorGo Axis is a two-channel ESP32-S3 BLDC motor-control board from Every Flavor Robotics. The espp::MotorGoAxis component provides a singleton board abstraction for the documented pin mapping of its 6-PWM motor outputs, encoder chip-selects, onboard LSM6DS33 IMU, Qwiic and internal I2C buses, and user/status LEDs.

It also provides helper methods for:

  • initializing the two 6-PWM motor channels via espp::BldcDriver

  • initializing the shared SSI/SPI encoder bus and creating two espp::Mt6701<SSI> helpers

  • initializing the onboard LSM6DS33 IMU on the hidden I2C bus via the espp::Lsm6dso helper

  • controlling the user and status LEDs with direct brightness setters or a Gaussian breathing effect

API Reference

Header File

Classes

class MotorGoAxis : public espp::BaseComponent

MotorGoAxis is a lightweight board-support component for the MotorGo Axis hardware.

It exposes the documented pin mapping for the board’s:

  • two 6-PWM BLDC motor outputs

  • two encoder chip-selects on a shared SSI/SPI bus

  • one onboard LSM6DS3TR IMU on the hidden I2C bus

  • Qwiic and hidden I2C buses

  • user (green) and status (blue) LEDs

The class is a singleton and can be accessed with get().

MotorGo Axis Example

  auto &board = espp::MotorGoAxis::get();

  if (!board.initialize_leds()) {
    logger.warn("Failed to initialize indicator LEDs");
  } else {
    board.start_led_breathing();
  }

  if (!board.initialize_motors()) {
    logger.warn("Failed to initialize BLDC motor drivers");
  } else {
    logger.info("Motor drivers initialized and left disabled");
  }

  if (!board.initialize_imu()) {
    logger.warn("Failed to initialize onboard IMU");
  } else {
    logger.info("IMU initialized");
  }

  log_board_info(board);

#if CONFIG_MOTORGO_AXIS_EXAMPLE_ENABLE_ENCODER_POLLING
  if (!board.initialize_encoders(false)) {
    logger.warn("Failed to initialize encoders");
  } else {
    logger.info("Encoder polling enabled");
  }
#else
  logger.info("Encoder polling disabled");
#endif

  while (true) {
#if CONFIG_MOTORGO_AXIS_EXAMPLE_ENABLE_ENCODER_POLLING
    log_encoder_angles(board);
#endif

    log_imu_data(board);

    using namespace std::chrono_literals;
    std::this_thread::sleep_for(500ms);
  }

Public Types

using Encoder = espp::Mt6701<espp::Mt6701Interface::SSI>

Alias for the SSI-based magnetic encoder helper used on each motor channel.

using MotorDriver = espp::BldcDriver

Alias for the 6-PWM BLDC motor driver helper used on each motor channel.

using Imu = espp::Lsm6dso<espp::lsm6dso::Interface::I2C>

Alias for the onboard hidden-bus IMU helper.

Public Functions

MotorGoAxis(const MotorGoAxis&) = delete

Deleted copy constructor.

MotorGoAxis &operator=(const MotorGoAxis&) = delete

Deleted copy assignment operator.

MotorGoAxis(MotorGoAxis&&) = delete

Deleted move constructor.

MotorGoAxis &operator=(MotorGoAxis&&) = delete

Deleted move assignment operator.

I2c &get_external_i2c()

Get the external Qwiic I2C bus.

Returns:

Reference to the initialized external I2C bus.

I2c &qwiic_i2c()

Get the external Qwiic I2C bus.

Returns:

Reference to the initialized external I2C bus.

I2c &hidden_i2c()

Get the internal hidden I2C bus.

Returns:

Reference to the initialized internal I2C bus.

std::array<MotorPins, 2> motor_pins() const

Get the documented motor pin mappings for both channels.

Returns:

Array containing the six PWM pins for each motor channel.

MotorPins motor_pins(size_t index) const

Get one motor channel pin mapping.

Parameters:

index – Zero-based motor index in the range [0, num_motor_channels()).

Returns:

The motor pin mapping for the requested channel, or a default `MotorPins{}` with `GPIO_NUM_NC` entries if the index is invalid.

EncoderBusPins encoder_bus_pins() const

Get the shared encoder bus pin mapping.

Returns:

The shared SCLK and MISO pins used for the encoder bus.

std::array<gpio_num_t, 2> encoder_cs_pins() const

Get the two encoder chip-select pins.

Returns:

Array containing the chip-select pin for each encoder channel.

gpio_num_t encoder_cs_pin(size_t index) const

Get one encoder chip-select pin.

Parameters:

index – Zero-based encoder index in the range [0, num_motor_channels()).

Returns:

The requested encoder chip-select pin, or `GPIO_NUM_NC` if the index is invalid.

I2cPins qwiic_pins() const

Get the external Qwiic I2C pin mapping.

Returns:

The external Qwiic SDA/SCL pin mapping.

I2cPins hidden_i2c_pins() const

Get the hidden internal I2C pin mapping.

Returns:

The internal SDA/SCL pin mapping.

LedPins led_pins() const

Get the user/status LED pins.

Returns:

The documented user and status LED GPIOs.

bool initialize_motors(float power_supply_voltage = driver_default_power_supply_voltage(), float limit_voltage = driver_default_voltage_limit(), uint64_t dead_zone_ns = default_motor_dead_zone_ns())

Initialize the two BLDC motor driver helpers.

Parameters:

  • power_supply_voltage – Maximum motor supply voltage in volts.

  • limit_voltage – Optional motor voltage limit in volts. Values less than zero mean “no extra limit” and will be clamped to the supply voltage by `espp::BldcDriver`.

  • dead_zone_ns – Dead-time to apply to both sides of each phase PWM.

Returns:

True if both motor driver helpers were initialized successfully; false if the configuration is invalid or any channel could not be configured.

std::shared_ptr<MotorDriver> motor_driver(size_t index) const

Get one motor driver helper.

Parameters:

index – Zero-based motor index in the range [0, num_motor_channels()).

Returns:

Shared pointer to the requested motor driver helper, or `nullptr` if the index is invalid or that motor has not been initialized yet.

bool motor_driver_enabled(size_t index) const

Check whether one motor driver helper is currently enabled.

Parameters:

index – Zero-based motor index in the range [0, num_motor_channels()).

Returns:

True if the requested motor driver exists and is enabled.

bool enable_motor_driver(size_t index)

Enable one motor driver helper.

Parameters:

index – Zero-based motor index in the range [0, num_motor_channels()).

Returns:

True if the driver exists and was enabled.

void disable_motor_driver(size_t index)

Disable one motor driver helper.

Parameters:

index – Zero-based motor index in the range [0, num_motor_channels()).

void enable_all_motor_drivers()

Enable all initialized motor driver helpers.

void disable_all_motor_drivers()

Disable all initialized motor driver helpers.

bool initialize_encoders(bool run_tasks = true)

Initialize the shared encoder bus and create the two MT6701 SSI helpers.

Parameters:

run_tasks – If true, each encoder starts its own update task after initialization. If false, callers must invoke `Encoder::update()` manually.

Returns:

True if the shared bus and both encoder helpers were initialized successfully; false otherwise.

std::shared_ptr<Encoder> encoder(size_t index)

Get one encoder helper.

Parameters:

index – Zero-based encoder index in the range [0, num_motor_channels()).

Returns:

Shared pointer to the requested encoder helper, or `nullptr` if the index is invalid or that encoder has not been initialized yet.

void reset_encoder_accumulator(size_t index)

Reset one encoder’s accumulator.

If the encoder has not been initialized, the request is ignored after logging an error.

Parameters:

index – Zero-based encoder index in the range [0, num_motor_channels()).

bool initialize_imu (const Imu::filter_fn &orientation_filter=nullptr, const Imu::ImuConfig &imu_config={ .accel_range=Imu::AccelRange::RANGE_2G,.accel_odr=Imu::AccelODR::ODR_104_HZ,.gyro_range=Imu::GyroRange::DPS_1000,.gyro_odr=Imu::GyroODR::ODR_104_HZ, })

Initialize the onboard IMU on the hidden I2C bus.

Parameters:

  • orientation_filter – Optional orientation filter callback used by the IMU driver when update() is called.

  • imu_config – Basic accelerometer / gyroscope configuration to apply during initialization.

Returns:

True if the hidden-bus I2C device and IMU helper were initialized successfully; false otherwise.

std::shared_ptr<Imu> imu() const

Get the onboard IMU helper.

Returns:

Shared pointer to the initialized IMU helper, or `nullptr` if initialize_imu() has not been called yet.

bool initialize_leds(float breathing_period = 3.5f)

Initialize the user/status LED helpers.

Parameters:

breathing_period – Default breathing period in seconds for start_led_breathing().

Returns:

True if the indicator LED PWM helper and breathing task were created successfully; false if they were already initialized or the LEDs could not be driven after setup.

void start_led_breathing()

Start breathing both indicator LEDs.

This uses the shared Gaussian waveform returned by gaussian().

void stop_led_breathing()

Stop breathing and turn both indicator LEDs off.

bool set_user_led_brightness(float brightness)

Set the user LED brightness in the range [0, 1].

Parameters:

brightness – Desired brightness, clamped to [0.0, 1.0].

Returns:

True if the user LED duty cycle was updated; false if the LEDs have not been initialized or the breathing task is currently running.

float get_user_led_brightness()

Get the user LED brightness in the range [0, 1].

Returns:

Current user LED brightness normalized to [0.0, 1.0], or 0.0f if the LEDs have not been initialized or the duty cycle could not be read.

bool set_status_led_brightness(float brightness)

Set the status LED brightness in the range [0, 1].

Parameters:

brightness – Desired brightness, clamped to [0.0, 1.0].

Returns:

True if the status LED duty cycle was updated; false if the LEDs have not been initialized or the breathing task is currently running.

float get_status_led_brightness()

Get the status LED brightness in the range [0, 1].

Returns:

Current status LED brightness normalized to [0.0, 1.0], or 0.0f if the LEDs have not been initialized or the duty cycle could not be read.

bool set_led_breathing_period(float period)

Set the LED breathing period in seconds.

Parameters:

period – Breathing period in seconds. Must be greater than zero.

Returns:

True if the period was accepted; false if the value is not positive.

float get_led_breathing_period()

Get the LED breathing period in seconds.

Returns:

The configured LED breathing period in seconds.

std::shared_ptr<espp::Led> leds()

Get the LED helper used for the indicator LEDs.

Returns:

Shared pointer to the indicator LED helper, or `nullptr` if initialize_leds() has not been called yet.

espp::Gaussian &gaussian()

Get the Gaussian waveform used for LED breathing.

Returns:

Reference to the Gaussian waveform object used by the LED breathing task.

inline const std::string &get_name() const

Get the name of the component

Note

This is the tag of the logger

Returns:

A const reference to the name of the component

inline void set_log_tag(const std::string_view &tag)

Set the tag for the logger

Parameters:

tag – The tag to use for the logger

inline espp::Logger::Verbosity get_log_level() const

Get the log level for the logger

See also

Logger::Verbosity

See also

Logger::set_verbosity

Returns:

The verbosity level of the logger

inline void set_log_level(espp::Logger::Verbosity level)

Set the log level for the logger

See also

Logger::Verbosity

See also

Logger::set_verbosity

Parameters:

level – The verbosity level to use for the logger

inline void set_log_verbosity(espp::Logger::Verbosity level)

Set the log verbosity for the logger

See also

set_log_level

See also

Logger::Verbosity

See also

Logger::set_verbosity

Note

This is a convenience method that calls set_log_level

Parameters:

level – The verbosity level to use for the logger

inline espp::Logger::Verbosity get_log_verbosity() const

Get the log verbosity for the logger

See also

get_log_level

See also

Logger::Verbosity

See also

Logger::get_verbosity

Note

This is a convenience method that calls get_log_level

Returns:

The verbosity level of the logger

inline void set_log_rate_limit(std::chrono::duration<float> rate_limit)

Set the rate limit for the logger

See also

Logger::set_rate_limit

Note

Only calls to the logger that have _rate_limit suffix will be rate limited

Parameters:

rate_limit – The rate limit to use for the logger

Public Static Functions

static inline MotorGoAxis &get()

Access the singleton board instance.

Returns:

Reference to the singleton MotorGoAxis object.

static inline constexpr size_t num_motor_channels()

Get the number of supported motor channels.

Returns:

The number of motor channels exposed by the board.

static inline constexpr float driver_default_power_supply_voltage()

Get the default motor supply voltage used for the board definition.

Returns:

Default power supply voltage in volts.

static inline constexpr float driver_default_voltage_limit()

Get the default motor voltage limit used for the board definition.

Returns:

Default motor voltage limit in volts.

static inline constexpr uint64_t default_motor_dead_zone_ns()

Get the default BLDC driver dead-time.

Returns:

Default dead-time in nanoseconds.

static inline constexpr size_t encoder_spi_clock_speed_hz()

Get the encoder bus clock speed.

Returns:

Default encoder SSI/SPI clock speed in Hz.

static inline constexpr gpio_num_t user_led_pin()

Get the user LED GPIO.

Returns:

User LED pin.

static inline constexpr gpio_num_t status_led_pin()

Get the status LED GPIO.

Returns:

Status LED pin.

struct EncoderBusPins

Shared encoder SSI/SPI bus pins.

Public Members

gpio_num_t sclk = {GPIO_NUM_NC}

Shared encoder clock pin.

gpio_num_t miso = {GPIO_NUM_NC}

Shared encoder data pin.

struct I2cPins

I2C pin mapping.

Public Members

gpio_num_t sda = {GPIO_NUM_NC}

I2C SDA pin.

gpio_num_t scl = {GPIO_NUM_NC}

I2C SCL pin.

struct LedPins

User-visible LED pin mapping.

Public Members

gpio_num_t user = {GPIO_NUM_NC}

User LED pin.

gpio_num_t status = {GPIO_NUM_NC}

Status LED pin.

struct MotorPins

Pin mapping for one BLDC motor channel.

Public Members

gpio_num_t u_high = {GPIO_NUM_NC}

Phase U high-side PWM pin.

gpio_num_t u_low = {GPIO_NUM_NC}

Phase U low-side PWM pin.

gpio_num_t v_high = {GPIO_NUM_NC}

Phase V high-side PWM pin.

gpio_num_t v_low = {GPIO_NUM_NC}

Phase V low-side PWM pin.

gpio_num_t w_high = {GPIO_NUM_NC}

Phase W high-side PWM pin.

gpio_num_t w_low = {GPIO_NUM_NC}

Phase W low-side PWM pin.