HardFOC board HAL

Vortex V1 HAL

The software layer for the HardFOC Vortex V1 motor controller board. One Vortex object gives your ESP32-C6 application the TMC9660 motor controller, encoders, the IMU, temperatures, ADC channels, GPIO, CAN, storage and a status LED, through a small set of managers that know the board's wiring.

Quickstart Architecture Source on GitHub

This repository (hf-hal-vortex-v1) turns the board into C++ objects. Your application does not touch GPIO numbers or SPI frames; it calls vortex.motors, vortex.encoders, vortex.temp.

Single-axis motor controller board Vortex V1 HardFOC

MCU

ESP32-C6 (RISC-V, Wi-Fi 6, BLE, 802.15.4, TWAI); ESP-IDF release/v5.5

Motor controller

TMC9660: integrated gate drivers, on-chip FOC current, velocity and position loops; BLDC, stepper or brushed DC; host link UART 115200 baud (default) or SPI2

Sensors

AS5047U 14-bit magnetic angle encoder slot (SPI2) · BNO08x 9-axis IMU (I2C) · NTC thermistor on TMC9660 AIN3

I/O

PCAL95555 16-bit I2C expander: TMC9660 control lines, IMU boot and reset, CAN standby, power good

Communication

CAN 500 kbit/s (TWAI) · I2C 100 kHz · USB Serial/JTAG (console, flashing)

Power

Motor supply, needed only to spin a motor; the board starts and logs from USB without it

Status

One WS2812 RGB LED

Hardware · Pin map

Vortex V1 HAL, layer by layer

Figure description and sources

From top to bottom, each layer only calls the one under it. Your application asks the facade singleton for the managers. The managers (one per board function) are MCU-free: they own the hf-core handlers, which wrap one chip driver each, and they get every bus, MCU pin, NVS namespace and the status LED from the board binding. The binding is the only HAL code that names an ESP32 type; it constructs the ESP32 implementations of the interface classes, which sit on ESP-IDF. Drivers talk to hardware only through those interface classes. Every name in a band is read from the code: the managers from the facade's member references, the binding's classes from its #include lines, the handlers, drivers and interface classes from the managers' and handlers' #include lines.

Drawn from: lib/api/Vortex.h Vortex (manager references); lib/managers #includes; lib/core/handlers #includes; lib/managers/bsp_bind/esp32c6 #includes; figure module docs/diagrams/figures/hal-layers.py.

What you get

• One Vortex object that brings the board up in a fixed order and reports what failed (Initialisation).
• One manager per board function: motor, encoders, IMU, ADC, temperature, GPIO, LED, communication, storage (Managers).
• The TMC9660 over UART or SPI, with unit-aware motor- and load-frame velocity and position, and every TMCL parameter through visitDriver() (MotorController).
• A pin map generated from the board's pin header, across the ESP32-C6, the PCAL95555 and the TMC9660 (Pin map).
• Diagnostics for every manager: GetLastError(), health snapshots, statistics dumps (Errors and diagnostics).
• Example and bench apps for every chip, most built by CI on every pull request (Examples).

Where to go next

• Quickstart

  Install ESP-IDF, clone with submodules, build, flash and watch the first example.

• Bring-up and troubleshooting

  The first power-up, step by step, and what each start-up failure means.

• Hardware

  Buses, chips and the pin map, generated from the board's pin header.

• Architecture

  Layers, start-up order, ownership, threading and errors.

• Managers

  One page per manager: what it does, its API, an example and its pitfalls.

• Examples

  Every buildable app, generated from app_config.yml.