Skip to content

Profile README: README standard, link the portal #8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
N3b3x merged 3 commits into from
Nov 2, 2026
Merged

Profile README: README standard, link the portal #8

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
6986951
Profile README: README standard, link the portal
N3b3x Nov 2, 2026
2a200ce
README: what the repository holds, link the portal
N3b3x Nov 2, 2026
904b018
README: drop the license line; the repository has no license file
N3b3x Nov 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 14 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,2 +1,15 @@
# .github
README

The HardFOC organisation profile, the community files every repository inherits, and the scripts that keep
repository settings consistent.

**Organisation portal: <https://hardfoc.github.io/>**

| Path | What it is |
| --- | --- |
| [`profile/README.md`](profile/README.md) | The profile shown on <https://github.com/hardfoc> |
| [`CONTRIBUTING.md`](CONTRIBUTING.md), [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md), [`SECURITY.md`](SECURITY.md) | Defaults for every repository without its own |
| [`.github/ISSUE_TEMPLATE/`](.github/ISSUE_TEMPLATE), [`.github/PULL_REQUEST_TEMPLATE.md`](.github/PULL_REQUEST_TEMPLATE.md) | Default issue forms and pull request template |
| [`org/org-metadata.json`](org/org-metadata.json) | Description, homepage and topics of every repository; the portal's catalogue reads it |
| [`org/`](org/README.md) | Scripts that apply the metadata, rulesets, security settings and CODEOWNERS ([guide](org/README.md)) |

120 changes: 32 additions & 88 deletions profile/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,106 +1,50 @@
# HardFOC

HardFOC is firmware for ESP32-based motor and valve controller boards, built
on ESP-IDF and FreeRTOS. The name stands for hardware-based field-oriented
control: motor commutation runs on dedicated FOC driver ICs (such as the
Trinamic TMC9660) instead of in MCU software.
Open firmware for ESP32 motor and valve controller boards: hardware-agnostic C++ chip drivers, a shared core,
board HALs and one application per board, on ESP-IDF and FreeRTOS.

There are two boards today:
**Start at the portal: <https://hardfoc.github.io/>**

- **Vortex V1**: motor controller (ESP32-C6, TMC9660, AS5047U encoder).
- **Flux V1**: valve controller with on/off and proportional solenoid
channels (TLE92466ED, MAX22200).

## How the code is layered

Each box is a separate repository; each arrow is a Git submodule pinned to a
commit or tag. Chip drivers have no platform dependencies and can be used on
their own.
HardFOC stands for hardware-based field-oriented control: motor commutation runs on dedicated FOC driver chips,
such as the Trinamic TMC9660, instead of in MCU software.

```mermaid
flowchart LR
drv["Chip drivers<br/>hf-*-driver"] --> cd["hf-core-drivers"]
iw["hf-internal-interface-wrap<br/>hf-pincfg"] --> cd
ut["hf-utils-general<br/>hf-utils-rtos-wrap<br/>hf-utils-canopen"] --> cu["hf-core-utils"]
cd --> core["hf-core"]
cu --> core
drv["Chip drivers<br/>hf-*-driver"] --> core["hf-core<br/>(hf-core-drivers, hf-core-utils)"]
iw["hf-internal-interface-wrap<br/>hf-pincfg"] --> core
ut["hf-utils-general<br/>hf-utils-rtos-wrap<br/>hf-utils-canopen"] --> core
core --> hal["Board HALs<br/>hf-hal-vortex-v1<br/>hf-hal-flux-v1"]
hal --> prod["Products<br/>hardfoc-vortex-v1<br/>hardfoc-flux-v1"]
```

## Repositories

### Products and board HALs

| Repo | Role |
|------|------|
| [hardfoc-vortex-v1](https://github.com/hardfoc/hardfoc-vortex-v1) | Vortex V1 motor controller application firmware |
| [hf-hal-vortex-v1](https://github.com/hardfoc/hf-hal-vortex-v1) | Vortex V1 board HAL, built on hf-core |
| [hf-hal-flux-v1](https://github.com/hardfoc/hf-hal-flux-v1) | Flux V1 valve controller board HAL, built on hf-core |

### Core

| Repo | Role |
|------|------|
| [hf-core](https://github.com/hardfoc/hf-core) | Shared platform layer: device handlers, RTOS utilities, driver integration, CANopen |
| [hf-core-drivers](https://github.com/hardfoc/hf-core-drivers) | Collects the chip drivers, interface wrap and pin config as submodules |
| [hf-core-utils](https://github.com/hardfoc/hf-core-utils) | Collects the utility libraries as submodules |
| [hf-internal-interface-wrap](https://github.com/hardfoc/hf-internal-interface-wrap) | Peripheral base classes (GPIO, ADC, I2C, SPI, UART, CAN, PWM, ...) with ESP-IDF implementations |
| [hf-pincfg](https://github.com/hardfoc/hf-pincfg) | Functional pin definitions and per-board pin maps |
| [hf-utils-general](https://github.com/hardfoc/hf-utils-general) | Header-only C++17 helpers: PID, filters, curve fitting, buffers, monitors |
| [hf-utils-rtos-wrap](https://github.com/hardfoc/hf-utils-rtos-wrap) | C++ wrappers over FreeRTOS primitives |
| [hf-utils-canopen](https://github.com/hardfoc/hf-utils-canopen) | CANopen NMT/SDO frame builders and CiA 402 helpers |

### Chip drivers

Hardware-agnostic C++ drivers. Each one takes a small bus adapter you
implement for your platform, and ships ESP32 examples and docs.

| Repo | Device |
|------|--------|
| [hf-ads7952-driver](https://github.com/hardfoc/hf-ads7952-driver) | TI ADS7952 12-bit, 12-channel SAR ADC (SPI) |
| [hf-ads9324-driver](https://github.com/hardfoc/hf-ads9324-driver) | TI ADS9324 16-bit, 16-channel simultaneous-sampling SAR ADC (SPI) |
| [hf-alicat-basis2-driver](https://github.com/hardfoc/hf-alicat-basis2-driver) | Alicat BASIS-2 mass flow meters and controllers (Modbus RTU) |
| [hf-as5047u-driver](https://github.com/hardfoc/hf-as5047u-driver) | ams OSRAM AS5047U magnetic rotary encoder (SPI) |
| [hf-at25040-driver](https://github.com/hardfoc/hf-at25040-driver) | Microchip AT25010B/AT25020B/AT25040B EEPROMs (SPI) |
| [hf-bmp581-driver](https://github.com/hardfoc/hf-bmp581-driver) | Bosch BMP581 barometric pressure sensor (I2C/SPI) |
| [hf-bno08x-driver](https://github.com/hardfoc/hf-bno08x-driver) | CEVA BNO080/BNO085/BNO086 IMU and sensor-fusion hub (I2C/SPI/UART) |
| [hf-dynamixel-driver](https://github.com/hardfoc/hf-dynamixel-driver) | ROBOTIS DYNAMIXEL X-series servos, Protocol 2.0 (UART) |
| [hf-fdo2-driver](https://github.com/hardfoc/hf-fdo2-driver) | PyroScience FDO2-G2 optical oxygen sensor (UART) |
| [hf-isf15acp4-driver](https://github.com/hardfoc/hf-isf15acp4-driver) | NKK ISF15ACP4 RGB OLED pushbutton (SPI) |
| [hf-max22200-driver](https://github.com/hardfoc/hf-max22200-driver) | ADI MAX22200 octal solenoid and motor driver (SPI) |
| [hf-mcp9700-driver](https://github.com/hardfoc/hf-mcp9700-driver) | Microchip MCP9700/MCP9700A analog temperature sensor (ADC) |
| [hf-ntc-thermistor-driver](https://github.com/hardfoc/hf-ntc-thermistor-driver) | NTC thermistors (lookup table, Beta, Steinhart-Hart over ADC) |
| [hf-pca9685-driver](https://github.com/hardfoc/hf-pca9685-driver) | NXP PCA9685 16-channel 12-bit PWM controller (I2C) |
| [hf-pcal95555-driver](https://github.com/hardfoc/hf-pcal95555-driver) | NXP PCA9555 / PCAL9555A 16-bit I/O expanders (I2C) |
| [hf-pf1550-driver](https://github.com/hardfoc/hf-pf1550-driver) | NXP PF1550 PMIC with Li-ion charger (I2C) |
| [hf-se050-driver](https://github.com/hardfoc/hf-se050-driver) | NXP SE050 EdgeLock secure element (I2C) |
| [hf-sfm-flow-meter-driver](https://github.com/hardfoc/hf-sfm-flow-meter-driver) | Sensirion SF06-family gas mass flow meters, e.g. SFM4300 (I2C) |
| [hf-tle92466ed-driver](https://github.com/hardfoc/hf-tle92466ed-driver) | Infineon TLE92466ED six-channel low-side solenoid driver (SPI) |
| [hf-tmc5160-driver](https://github.com/hardfoc/hf-tmc5160-driver) | Trinamic TMC5130/TMC5160 stepper motor controllers (SPI/UART) |
| [hf-tmc9660-driver](https://github.com/hardfoc/hf-tmc9660-driver) | Trinamic TMC9660 BLDC/stepper FOC motor controller (SPI/UART, TMCL) |
| [hf-vortex-driver](https://github.com/hardfoc/hf-vortex-driver) | CANopen (CiA 301/402) client for Vortex controllers over CAN |
| [hf-ws2812-rmt-driver](https://github.com/hardfoc/hf-ws2812-rmt-driver) | WS2812 / NeoPixel LEDs via the ESP32 RMT peripheral |
Each box is one or more repositories; each arrow is a Git submodule pinned to a commit or tag.

### CI and tooling
## What is here

| Repo | Role |
|------|------|
| [hf-general-ci-tools](https://github.com/hardfoc/hf-general-ci-tools) | Reusable workflows: C++ lint and analysis, Markdown/YAML lint, docs publish, link check, release |
| [hf-espidf-ci-tools](https://github.com/hardfoc/hf-espidf-ci-tools) | Reusable workflows to build and release multi-app ESP-IDF projects |
| [hf-espidf-project-tools](https://github.com/hardfoc/hf-espidf-project-tools) | Scripts to install ESP-IDF and build/flash multi-app projects from a YAML config |
- **Two boards.** Vortex V1, a motor controller (ESP32-C6, TMC9660, AS5047U encoder, CANopen), and Flux V1, a
valve controller with on/off and proportional solenoid channels (ESP32-S3, TLE92466ED, MAX22200).
- **Chip drivers you can use on any MCU.** Each `hf-*-driver` is a C++ library with no platform code: you write
one small bus adapter, and every driver ships ESP32 examples built in CI.
- **A shared core.** `hf-core` gathers the drivers, the peripheral interface wrap, the pin maps and the utility
libraries (FreeRTOS wrappers, general helpers, CANopen).
- **Board HALs.** One object per board and one manager per board function, on top of `hf-core`.
- **Shared CI and documentation.** Reusable workflows and one documentation platform for every repository.

### Other
## Documentation

| Repo | Role |
|------|------|
| [hardfoc.github.io](https://github.com/hardfoc/hardfoc.github.io) | Organization website |
| [org-discussions](https://github.com/hardfoc/org-discussions) | Questions and announcements |
| [hf-drawio-diag](https://github.com/hardfoc/hf-drawio-diag) | draw.io diagram sources |
| [hf-utils-and-drivers](https://github.com/hardfoc/hf-utils-and-drivers) | Legacy; replaced by hf-core |
| Page | What it covers |
| --- | --- |
| [Get started](https://hardfoc.github.io/get-started/) | A path per board, and for a chip driver on your own MCU |
| [Repositories](https://hardfoc.github.io/repositories/) | Every public repository with its topics, documentation and latest release, searchable |
| [Architecture](https://hardfoc.github.io/architecture/) | The layers and how they are pinned together |
| [Vortex V1 HAL](https://hardfoc.github.io/hf-hal-vortex-v1/latest/) | The motor controller board: hardware, pin map, managers, examples |
| [Flux V1 HAL](https://hardfoc.github.io/hf-hal-flux-v1/latest/) | The valve controller board: hardware, pin map, managers, examples |
| [CI tools](https://hardfoc.github.io/hf-general-ci-tools/latest/) | Reusable workflows and the documentation platform |

## Contributing

See [CONTRIBUTING.md](https://github.com/hardfoc/.github/blob/main/CONTRIBUTING.md).
Report security issues privately as described in
[SECURITY.md](https://github.com/hardfoc/.github/blob/main/SECURITY.md).
Read [CONTRIBUTING.md](https://github.com/hardfoc/.github/blob/main/CONTRIBUTING.md) and the
[code of conduct](https://github.com/hardfoc/.github/blob/main/CODE_OF_CONDUCT.md). Report vulnerabilities
privately, as [SECURITY.md](https://github.com/hardfoc/.github/blob/main/SECURITY.md) describes; never in a public
issue. Questions and announcements go to
[org-discussions](https://github.com/hardfoc/org-discussions).