AlicatBasis2Handler Class Reference

Thread-safe access layer to one BASIS-2 instrument on a shared bus. More...

#include <AlicatBasis2Handler.h>

Classes
struct	DiscoveredDevice
	One discovered instrument and the baud rate it was found at. More...

Public Types
using	DriverType = alicat_basis2::Driver< HalUartAlicatBasis2Comm >
using	HostBaudSetter = std::function< bool(std::uint32_t bps)>
	Callback used by DiscoverAcrossBauds / NormalizeBusBaud to retune the host UART when probing a new baud rate.

Public Member Functions
	AlicatBasis2Handler (BaseUart &uart, const AlicatBasis2HandlerConfig &config, RtosMutex *bus_mutex=nullptr) noexcept
	AlicatBasis2Handler (const AlicatBasis2Handler &)=delete
AlicatBasis2Handler &	operator= (const AlicatBasis2Handler &)=delete
bool	EnsureInitialized () noexcept
	Lazy initialisation; reads identity, caches flow_decimals_.
bool	IsInitialized () const noexcept
std::uint8_t	Address () const noexcept
std::uint8_t	DeviceIndex () const noexcept
const alicat_basis2::InstrumentIdentity &	Identity () const noexcept
	Cached identity (filled by EnsureInitialized).
std::uint8_t	FlowDecimals () const noexcept
alicat_basis2::DriverResult< alicat_basis2::InstantaneousData >	ReadInstantaneous () noexcept
alicat_basis2::DriverResult< alicat_basis2::InstrumentIdentity >	RereadIdentity () noexcept
alicat_basis2::DriverResult< void >	Tare () noexcept
alicat_basis2::DriverResult< void >	SetGas (alicat_basis2::Gas g) noexcept
alicat_basis2::DriverResult< void >	SetSetpoint (float user_units) noexcept
alicat_basis2::DriverResult< void >	SetSetpointSource (alicat_basis2::SetpointSource s) noexcept
alicat_basis2::DriverResult< void >	SetCommWatchdogMs (std::uint16_t ms) noexcept
alicat_basis2::DriverResult< void >	SetMaxSetpointRamp (std::uint32_t pct_per_ms_x_10e7) noexcept
alicat_basis2::DriverResult< void >	SetAutotareEnabled (bool enabled) noexcept
alicat_basis2::DriverResult< void >	ResetTotalizer () noexcept
alicat_basis2::DriverResult< void >	SetTotalizerLimitMode (alicat_basis2::TotalizerLimitMode m) noexcept
alicat_basis2::DriverResult< void >	SetTotalizerBatch (std::uint32_t value_scaled) noexcept
alicat_basis2::DriverResult< void >	SetFlowAveragingMs (std::uint16_t ms) noexcept
alicat_basis2::DriverResult< void >	SetReferenceTemperatureC (float c) noexcept
alicat_basis2::DriverResult< void >	ConfigureMeasurementTrigger (std::uint16_t bits) noexcept
alicat_basis2::DriverResult< void >	StartMeasurementSamples (std::uint16_t n) noexcept
alicat_basis2::DriverResult< alicat_basis2::MeasurementData >	ReadMeasurement () noexcept
alicat_basis2::DriverResult< void >	SetModbusAddress (std::uint8_t addr) noexcept
alicat_basis2::DriverResult< void >	SetAsciiUnitId (char id) noexcept
alicat_basis2::DriverResult< void >	SetBaudRate (alicat_basis2::BaudRate br) noexcept
alicat_basis2::DriverResult< void >	FactoryRestore () noexcept
alicat_basis2::DriverResult< std::uint8_t >	Discover (std::uint8_t *present_bitmap, std::size_t bitmap_bytes, std::uint16_t probe_timeout_ms=30) noexcept
	Bus-wide discovery sweep at the current host baud only.
alicat_basis2::DriverResult< std::size_t >	DiscoverAcrossBauds (DiscoveredDevice *out, std::size_t max_devices, const HostBaudSetter &set_host_baud, std::uint16_t probe_timeout_ms=30, std::uint32_t settle_ms=25, const std::uint32_t *baud_list_bps=nullptr, std::size_t baud_list_count=0) noexcept
	Sweep multiple baud rates, returning every BASIS-2 found on the bus along with the baud rate it answered at.
alicat_basis2::DriverResult< std::size_t >	NormalizeBusBaud (std::uint32_t target_bps, const DiscoveredDevice *devices, std::size_t device_count, const HostBaudSetter &set_host_baud, std::uint8_t *failed_addresses_bitmap=nullptr, std::size_t failed_bitmap_bytes=0, std::uint16_t verify_timeout_ms=100) noexcept
	Normalise every device on the bus to the same baud rate.
DriverType *	GetDriver () noexcept
	Direct access to the underlying driver (for advanced use; mutex must be held).

Private Member Functions
bool	EnsureInitializedLocked () noexcept

Private Attributes
AlicatBasis2HandlerConfig	config_
HalUartAlicatBasis2Comm	comm_
std::unique_ptr< DriverType >	driver_
alicat_basis2::InstrumentIdentity	identity_ {}
std::uint8_t	flow_decimals_ {3}
std::atomic< bool >	initialized_ {false}
RtosMutex	private_mutex_
RtosMutex *	bus_mutex_ {&private_mutex_}

Detailed Description

Thread-safe access layer to one BASIS-2 instrument on a shared bus.

Lifecycle

• Construct lightweight (no SPI / UART traffic).
• EnsureInitialized() lazily probes the instrument and caches identity.
• All read / write entry points are mutex-guarded by the per-bus mutex.

Multi-instrument bus

Pass the same BaseUart to every handler that shares the bus. The first handler created with a nullptr mutex pointer creates the shared mutex; subsequent handlers must be constructed with a pointer to that same mutex object so transactions are properly serialised.

Member Typedef Documentation

DriverType

using AlicatBasis2Handler::DriverType = alicat_basis2::Driver<HalUartAlicatBasis2Comm>

HostBaudSetter

using AlicatBasis2Handler::HostBaudSetter = std::function<bool(std::uint32_t bps)>

Callback used by DiscoverAcrossBauds / NormalizeBusBaud to retune the host UART when probing a new baud rate.

Returns

true if the host UART successfully switched to bps, false to skip that baud entry.

Note

This is intentionally injected from the application — the handler only knows about a BaseUart& (which has no runtime baud setter), so the caller wires in whichever MCU-specific call applies (e.g. EspUart::SetBaudRate(bps)).

Constructor & Destructor Documentation

AlicatBasis2Handler() [1/2]

AlicatBasis2Handler::AlicatBasis2Handler ( BaseUart &  uart, const AlicatBasis2HandlerConfig &  config, RtosMutex *  bus_mutex = nullptr  )

noexcept

Parameters

uart	Reference to the (already-configured) BaseUart.
config	Per-slave configuration.
bus_mutex	Optional shared mutex when several handlers share the same bus. Pass nullptr for a private mutex.

AlicatBasis2Handler() [2/2]

AlicatBasis2Handler::AlicatBasis2Handler ( const AlicatBasis2Handler &  )

delete

Member Function Documentation

Address()

std::uint8_t AlicatBasis2Handler::Address ( ) const

inlinenoexcept

ConfigureMeasurementTrigger()

al::DriverResult< void > AlicatBasis2Handler::ConfigureMeasurementTrigger ( std::uint16_t  bits )

noexcept

DeviceIndex()

std::uint8_t AlicatBasis2Handler::DeviceIndex ( ) const

inlinenoexcept

Discover()

al::DriverResult< std::uint8_t > AlicatBasis2Handler::Discover ( std::uint8_t *  present_bitmap, std::size_t  bitmap_bytes, std::uint16_t  probe_timeout_ms = 30  )

noexcept

Bus-wide discovery sweep at the current host baud only.

Parameters

[out]	present_bitmap	≥32-byte bitmap; bit N = address N is alive.
	bitmap_bytes	Size of present_bitmap (must be ≥32).
	probe_timeout_ms	Per-address probe timeout (ms).

Returns

Number of present devices, or DriverError on bus failure.

Note

Disables the per-handler address temporarily; restored on exit. This finds devices that match the host UART's current baud only — use DiscoverAcrossBauds() to also find devices at other baud rates.

DiscoverAcrossBauds()

al::DriverResult< std::size_t > AlicatBasis2Handler::DiscoverAcrossBauds ( DiscoveredDevice *  out, std::size_t  max_devices, const HostBaudSetter &  set_host_baud, std::uint16_t  probe_timeout_ms = 30, std::uint32_t  settle_ms = 25, const std::uint32_t *  baud_list_bps = nullptr, std::size_t  baud_list_count = 0  )

noexcept

Sweep multiple baud rates, returning every BASIS-2 found on the bus along with the baud rate it answered at.

For each baud in baud_list the handler:

1. Calls set_host_baud(baud) to retune the host UART.
2. Sleeps settle_ms so any stale RX bytes drain.
3. Runs DiscoverPresentAddresses() at that baud.
4. Records {addr, baud} for every responder that isn't already in out (first-seen-baud wins).

When baud_list is nullptr the handler iterates over every value in alicat_basis2::BaudRate (4800/9600/19200/38400/57600/115200).

On exit the host UART is restored to whatever baud was active last — typically you should follow the call with NormalizeBusBaud() (which retunes again) or an explicit set_host_baud(target).

Parameters

[out]	out	Destination buffer (caller-allocated).
	max_devices	Capacity of out in elements.
	set_host_baud	Callback that retunes the host UART.
	probe_timeout_ms	Per-address timeout passed to the sweep.
	settle_ms	Delay after each baud change to let UART glitches subside (default 25 ms).
	baud_list_bps	Optional explicit baud-rate list in bits-per-second. nullptr = all six supported rates.
	baud_list_count	Number of entries in baud_list_bps.

Returns

Number of devices populated into out on success; BufferTooSmall if out overflows; transport error if set_host_baud rejects every requested rate.

EnsureInitialized()

bool AlicatBasis2Handler::EnsureInitialized ( )

noexcept

Lazy initialisation; reads identity, caches flow_decimals_.

EnsureInitializedLocked()

bool AlicatBasis2Handler::EnsureInitializedLocked ( )

privatenoexcept

FactoryRestore()

al::DriverResult< void > AlicatBasis2Handler::FactoryRestore ( )

noexcept

FlowDecimals()

std::uint8_t AlicatBasis2Handler::FlowDecimals ( ) const

inlinenoexcept

GetDriver()

DriverType * AlicatBasis2Handler::GetDriver ( )

inlinenoexcept

Direct access to the underlying driver (for advanced use; mutex must be held).

Identity()

const alicat_basis2::InstrumentIdentity & AlicatBasis2Handler::Identity ( ) const

inlinenoexcept

Cached identity (filled by EnsureInitialized).

IsInitialized()

bool AlicatBasis2Handler::IsInitialized ( ) const

inlinenoexcept

NormalizeBusBaud()

al::DriverResult< std::size_t > AlicatBasis2Handler::NormalizeBusBaud ( std::uint32_t  target_bps, const DiscoveredDevice *  devices, std::size_t  device_count, const HostBaudSetter &  set_host_baud, std::uint8_t *  failed_addresses_bitmap = nullptr, std::size_t  failed_bitmap_bytes = 0, std::uint16_t  verify_timeout_ms = 100  )

noexcept

Normalise every device on the bus to the same baud rate.

For every {addr, baud} in devices whose baud != target_bps:

1. Retune the host UART to the device's current baud.
2. Address that slave and issue SetBaudRate(target). The device switches immediately — the response may be lost or garbled (datasheet calls this out explicitly), so the operation is logged but never aborts on a single failure.
3. Retune the host UART to target_bps.
4. Verify with a short identity read; on failure the device is left in failed_addresses (if provided).

Devices already at target_bps are skipped (verified only). On exit the host UART is left at target_bps.

Parameters

	target_bps	Final baud rate everyone should use.
	devices	Output of DiscoverAcrossBauds().
	device_count	Length of devices.
	set_host_baud	Callback that retunes the host UART.
[out]	failed_addresses	Optional buffer for slaves that could not be normalised; use a 32-byte bitmap.
	verify_timeout_ms	Per-device verify timeout (ms).

Returns

Number of devices that successfully end up at target_bps (verified by identity read), or transport / parameter error.

operator=()

AlicatBasis2Handler & AlicatBasis2Handler::operator= ( const AlicatBasis2Handler &  )

delete

ReadInstantaneous()

al::DriverResult< al::InstantaneousData > AlicatBasis2Handler::ReadInstantaneous ( )

noexcept

ReadMeasurement()

al::DriverResult< al::MeasurementData > AlicatBasis2Handler::ReadMeasurement ( )

noexcept

RereadIdentity()

al::DriverResult< al::InstrumentIdentity > AlicatBasis2Handler::RereadIdentity ( )

noexcept

ResetTotalizer()

al::DriverResult< void > AlicatBasis2Handler::ResetTotalizer ( )

noexcept

SetAsciiUnitId()

al::DriverResult< void > AlicatBasis2Handler::SetAsciiUnitId ( char  id )

noexcept

SetAutotareEnabled()

al::DriverResult< void > AlicatBasis2Handler::SetAutotareEnabled ( bool  enabled )

noexcept

SetBaudRate()

al::DriverResult< void > AlicatBasis2Handler::SetBaudRate ( alicat_basis2::BaudRate  br )

noexcept

SetCommWatchdogMs()

al::DriverResult< void > AlicatBasis2Handler::SetCommWatchdogMs ( std::uint16_t  ms )

noexcept

SetFlowAveragingMs()

al::DriverResult< void > AlicatBasis2Handler::SetFlowAveragingMs ( std::uint16_t  ms )

noexcept

SetGas()

al::DriverResult< void > AlicatBasis2Handler::SetGas ( alicat_basis2::Gas  g )

noexcept

SetMaxSetpointRamp()

al::DriverResult< void > AlicatBasis2Handler::SetMaxSetpointRamp ( std::uint32_t  pct_per_ms_x_10e7 )

noexcept

SetModbusAddress()

al::DriverResult< void > AlicatBasis2Handler::SetModbusAddress ( std::uint8_t  addr )

noexcept

SetReferenceTemperatureC()

al::DriverResult< void > AlicatBasis2Handler::SetReferenceTemperatureC ( float  c )

noexcept

SetSetpoint()

al::DriverResult< void > AlicatBasis2Handler::SetSetpoint ( float  user_units )

noexcept

SetSetpointSource()

al::DriverResult< void > AlicatBasis2Handler::SetSetpointSource ( alicat_basis2::SetpointSource  s )

noexcept

SetTotalizerBatch()

al::DriverResult< void > AlicatBasis2Handler::SetTotalizerBatch ( std::uint32_t  value_scaled )

noexcept

SetTotalizerLimitMode()

al::DriverResult< void > AlicatBasis2Handler::SetTotalizerLimitMode ( alicat_basis2::TotalizerLimitMode  m )

noexcept

StartMeasurementSamples()

al::DriverResult< void > AlicatBasis2Handler::StartMeasurementSamples ( std::uint16_t  n )

noexcept

Tare()

al::DriverResult< void > AlicatBasis2Handler::Tare ( )

noexcept

Member Data Documentation

bus_mutex_

RtosMutex* AlicatBasis2Handler::bus_mutex_ {&private_mutex_}

private

comm_

HalUartAlicatBasis2Comm AlicatBasis2Handler::comm_

private

config_

AlicatBasis2HandlerConfig AlicatBasis2Handler::config_

private

driver_

std::unique_ptr<DriverType> AlicatBasis2Handler::driver_

private

flow_decimals_

std::uint8_t AlicatBasis2Handler::flow_decimals_ {3}

private

identity_

alicat_basis2::InstrumentIdentity AlicatBasis2Handler::identity_ {}

private

initialized_

std::atomic<bool> AlicatBasis2Handler::initialized_ {false}

private

private_mutex_

RtosMutex AlicatBasis2Handler::private_mutex_

private

---

The documentation for this class was generated from the following files:

• AlicatBasis2Handler.h
• AlicatBasis2Handler.cpp