FluxPlatformBind.h File Reference

The MCU-family seam of the Flux V1 HAL: what a binding must provide to the managers. More...

#include <cstddef>
#include <cstdint>
#include "core/hf-core-drivers/internal/hf-internal-interface-wrap/inc/base/BaseAdc.h"
#include "core/hf-core-drivers/internal/hf-internal-interface-wrap/inc/base/BaseCan.h"
#include "core/hf-core-drivers/internal/hf-internal-interface-wrap/inc/base/BaseGpio.h"
#include "core/hf-core-drivers/internal/hf-internal-interface-wrap/inc/base/BaseNvs.h"
#include "core/hf-core-drivers/internal/hf-internal-interface-wrap/inc/base/BaseSpi.h"
#include "core/hf-core-drivers/internal/hf-internal-interface-wrap/inc/base/BaseTemperature.h"
#include "core/hf-core-drivers/internal/hf-internal-interface-wrap/inc/base/BaseUart.h"
#include "core/hf-core-drivers/internal/hf-internal-interface-wrap/inc/base/BaseUsbSerialJtag.h"

Include dependency graph for FluxPlatformBind.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	flux::bsp::GpioSpec
	Electrical configuration of one MCU GPIO. More...
struct	flux::bsp::SpiBusSpec
	One SPI controller and its pins. More...
struct	flux::bsp::SpiDeviceSpec
	One chip select on an SPI bus. More...
struct	flux::bsp::CanSpec
	The CAN controller and its pins. More...
struct	flux::bsp::UartSpec
	One hardware UART, 8N1, no flow control. More...
struct	flux::bsp::LedStripSpec
	An addressable RGB LED strip on one data pin. More...

Namespaces
namespace	flux
namespace	flux::bsp

Functions
BaseGpio *	flux::bsp::CreateGpio (size_t slot, const GpioSpec &spec) noexcept
	Create the GPIO object for slot. No hardware access until the object is initialised.
void	flux::bsp::DestroyGpio (size_t slot) noexcept
	Destroy the GPIO object in slot (releases the pin).
uint8_t	flux::bsp::InternalAdcChannelCount () noexcept
	Number of channels per unit of the MCU ADC (0 when the family has none).
BaseAdc *	flux::bsp::CreateInternalAdc (uint8_t unit, uint32_t channel_mask) noexcept
	Create and initialise the MCU ADC unit with the given channels enabled.
void	flux::bsp::DestroyInternalAdc () noexcept
	Destroy the MCU ADC unit.
BaseTemperature *	flux::bsp::CreateDieTemperature () noexcept
	Create the MCU die-temperature sensor (not initialised). nullptr if the family has none.
void	flux::bsp::DestroyDieTemperature () noexcept
	Destroy the die-temperature sensor.
BaseNvs &	flux::bsp::NvsRegion (size_t slot, const char *name_space) noexcept
	The NVS region in slot, created on first call for name_space (no flash access).
bool	flux::bsp::CreateSpiBus (size_t bus, const SpiBusSpec &spec) noexcept
	Create and initialise SPI bus bus.
BaseSpi *	flux::bsp::CreateSpiDevice (size_t bus, const SpiDeviceSpec &spec) noexcept
	Add a device to an initialised SPI bus.
void	flux::bsp::DestroySpiBus (size_t bus) noexcept
	Destroy SPI bus bus and every device on it.
BaseCan *	flux::bsp::CreateCan (const CanSpec &spec) noexcept
	Create the CAN controller (configured, not started). nullptr on failure.
void	flux::bsp::DestroyCan () noexcept
	Destroy the CAN controller.
BaseUart *	flux::bsp::CreateUart (const UartSpec &spec, bool *rs485) noexcept
	Create and initialise a UART. When spec.rts >= 0 the port is switched to RS-485 half duplex.
void	flux::bsp::DestroyUart (uint8_t port) noexcept
	Destroy the UART on port.
BaseUsbSerialJtag *	flux::bsp::AcquireUsbSerialJtag (const hf_usb_serial_jtag_config_t &cfg) noexcept
	The USB Serial/JTAG controller, initialised. nullptr when the family has none or the feature is compiled out (HF_CORE_ENABLE_USB_SERIAL_JTAG=OFF). First call wins cfg.
bool	flux::bsp::LedStripBegin (const LedStripSpec &spec) noexcept
	Create and start the strip.
void	flux::bsp::LedStripSetPixel (uint16_t index, uint32_t rgb) noexcept
	Stage a 0xRRGGBB colour for LED index (sent on LedStripShow).
void	flux::bsp::LedStripSetBrightness (uint8_t brightness) noexcept
	Global brightness 0..255 applied to the next LedStripShow.
bool	flux::bsp::LedStripShow () noexcept
	Send the staged colours.
void	flux::bsp::LedStripEnd () noexcept
	Stop the strip and release its peripheral.
uint32_t	flux::bsp::LastResetReason () noexcept
	Opaque reset cause of the previous boot (family-specific numbering; 0 when unknown).
void	flux::bsp::SystemRestart () noexcept
	Software reset of the MCU. Does not return.
uint32_t	flux::bsp::FreeHeapBytes () noexcept
	Free bytes in the default heap (0 when unknown).
uint32_t	flux::bsp::LargestFreeHeapBlock () noexcept
	Largest contiguous free block in the default heap (0 when unknown).

Variables
constexpr size_t	flux::bsp::kMaxGpioSlots = 64
	GPIO objects (one per functional pin index)
constexpr size_t	flux::bsp::kMaxSpiBuses = 2
	SPI controllers in use.
constexpr size_t	flux::bsp::kMaxSpiDevicesPerBus = 4
	Chip selects per SPI bus.
constexpr size_t	flux::bsp::kMaxUartPorts = 3
	Hardware UART ports.
constexpr size_t	flux::bsp::kMaxNvsRegions = 3
	NVS namespaces opened by NvsManager.
constexpr uint8_t	flux::bsp::kMaxInternalAdcChannels = 16
	Upper bound on MCU ADC channels per unit.

Detailed Description

The MCU-family seam of the Flux V1 HAL: what a binding must provide to the managers.

The managers above this header are MCU-free: they decide what to bring up (which pins, which buses, which namespaces, in which order, and what a failure means) and talk to the result through hf-core Base* interfaces. This header names the small set of factory and system functions that turn a plain-data spec into a Base* object. Each MCU family implements every function once, in its own directory:

Directory	Built when	Backs the objects with
bsp_bind/esp32s3/	ESP-IDF build (HF_CORE_MCU=ESP32)	Esp* wrappers, ESP-IDF, RMT driver
bsp_bind/host/	host test build	hf-core host mocks

Exactly one family is linked into an image. ESP-IDF, FreeRTOS and Esp* headers may appear only under bsp_bind/<family>/ (enforced by tools/lint/lint_hal_boundary.sh).

Ownership: every object returned here lives in fixed static storage inside the binding (one slot per pin, bus, port or region). Nothing is heap-allocated by the binding itself; ESP-IDF drivers that allocate internally do so inside the Create* call, i.e. during the owning manager's EnsureInitialized().

Callers: managers only (the *Manager.cpp files in lib/managers) and the Flux facade for the system calls. Applications never include this header.

Thread safety: none inside the binding. Each slot has exactly one owning manager, which serialises its own calls (manager mutex or init-time only).

Error handling: Create* returns nullptr / false on failure and leaves the slot empty; the calling manager records the error. Destroy* on an empty slot is a no-op.

Author

HardFOC Team

Date

2026