BASIS 2 Driver 0.1.0
API reference
Loading...
Searching...
No Matches
Namespaces | Classes | Enumerations | Functions | Variables
Driver types

Errors, results, configuration and the values an instrument reports. More...

Namespaces

namespace  alicat_basis2::gas
 The nine gases of M p.15.
 

Classes

struct  alicat_basis2::Result< T >
 The value of a call, or why there is none. More...
 
struct  alicat_basis2::Result< void >
 The result of a call that returns no value. More...
 
struct  alicat_basis2::Config
 The driver's configuration. Every default is the instrument's factory value or a documented driver choice; fields that exist because the manual is silent are described in docs/configuration.md. More...
 
struct  alicat_basis2::Decimal
 An exact decimal number as the instrument printed it: +0021513.0 is {215130, 1}. More...
 
struct  alicat_basis2::GasId
 A gas number. Not a closed enumeration: the V3.0.5 gas table allows numbers up to 255 (A5). More...
 
struct  alicat_basis2::StatusFlags
 Status flags of a data frame or of Modbus register 2101 (M p.10, p.21). More...
 
struct  alicat_basis2::Frame
 One data frame (A) or a DV selection; present says which fields were read. More...
 
struct  alicat_basis2::Text
 A short text value (serial number, firmware, unit label), NUL terminated. More...
 
struct  alicat_basis2::Ramp
 Result of ReadRamp(): rate and time unit as the instrument reported them. More...
 
struct  alicat_basis2::Gains
 Closed-loop gains (LCG, Modbus 519 and 520). More...
 
struct  alicat_basis2::Averages
 Result of ReadAverages(): the current or most recent measurement window. More...
 
struct  alicat_basis2::Ranges
 Result of ReadRanges(). More...
 
struct  alicat_basis2::PreviousMeasurement
 Result of ReadPreviousMeasurement() (Modbus only, registers 4210 to 4215). More...
 
struct  alicat_basis2::FullScale
 One reading of FPF: a value and its unit text. More...
 
struct  alicat_basis2::GasEntry
 One entry of the gas table of firmware 3.0.5 (Modbus 81 to 140, M p.26 to 27). More...
 
struct  alicat_basis2::GasTable
 The whole gas table: twelve entries. More...
 
struct  alicat_basis2::GasList
 Result of ReadGasList(): the parsed pairs, or the raw text when the grammar did not match (A5). More...
 
struct  alicat_basis2::Identity
 What Begin() learned: read-only knowledge of the instrument. More...
 

Enumerations

enum class  alicat_basis2::Error : uint8_t {
  alicat_basis2::Error::Ok = 0 , alicat_basis2::Error::NotInitialized , alicat_basis2::Error::InvalidArgument = 2 , alicat_basis2::Error::Bus = 3 ,
  alicat_basis2::Error::Timeout = 4 , alicat_basis2::Error::DeviceIdMismatch , alicat_basis2::Error::Crc = 6 , alicat_basis2::Error::Busy ,
  alicat_basis2::Error::DeviceFault = 8 , alicat_basis2::Error::Unsupported , alicat_basis2::Error::BadReply = 16 , alicat_basis2::Error::Rejected = 17 ,
  alicat_basis2::Error::OutOfRange = 18 , alicat_basis2::Error::Overflow = 19 , alicat_basis2::Error::VerifyMismatch = 20 , alicat_basis2::Error::FirmwareTooOld = 21 ,
  alicat_basis2::Error::StateUnknown , alicat_basis2::Error::RateLimited , alicat_basis2::Error::GuardNotConfirmed = 24
}
 Why a call failed. Every call of the driver returns one of these in its Result. More...
 
enum class  alicat_basis2::LogLevel : uint8_t { alicat_basis2::LogLevel::Error = 0 , alicat_basis2::LogLevel::Warning , alicat_basis2::LogLevel::Info , alicat_basis2::LogLevel::Debug }
 Severity passed to the optional Log() hook. More...
 
enum class  alicat_basis2::Protocol : uint8_t { alicat_basis2::Protocol::Ascii = 0 , alicat_basis2::Protocol::ModbusRtu = 1 }
 The command protocol one Basis2 object speaks. More...
 
enum class  alicat_basis2::DeviceKind : uint8_t { alicat_basis2::DeviceKind::Auto = 0 , alicat_basis2::DeviceKind::Meter = 1 , alicat_basis2::DeviceKind::Controller = 2 }
 Whether the instrument is a meter (B series) or a controller (BC series). More...
 
enum class  alicat_basis2::FrameLayout : uint8_t { alicat_basis2::FrameLayout::Auto = 0 , alicat_basis2::FrameLayout::Meter = 1 , alicat_basis2::FrameLayout::Controller = 2 }
 Which data frame layout is accepted (assumption A2: a meter's frame is not shown in the manual). More...
 
enum class  alicat_basis2::UnknownFlagPolicy : uint8_t { alicat_basis2::UnknownFlagPolicy::Report = 0 , alicat_basis2::UnknownFlagPolicy::Reject = 1 }
 What happens with a flag token the manual does not list. More...
 
enum class  alicat_basis2::EchoMode : uint8_t { alicat_basis2::EchoMode::None = 0 , alicat_basis2::EchoMode::Skip = 1 }
 Whether a half-duplex wiring that hears its own transmission is handled. More...
 
enum class  alicat_basis2::VerifyPolicy : uint8_t { alicat_basis2::VerifyPolicy::Off = 0 , alicat_basis2::VerifyPolicy::WhenNoRamp }
 Whether a setpoint is read back after it was set. More...
 
enum class  alicat_basis2::FirmwareGate : uint8_t { alicat_basis2::FirmwareGate::Enforce , alicat_basis2::FirmwareGate::Ignore = 1 }
 Whether the firmware gates of the register and command tables are enforced. More...
 
enum class  alicat_basis2::SetpointSource : uint8_t { alicat_basis2::SetpointSource::Analog = 0 , alicat_basis2::SetpointSource::SavedDigital , alicat_basis2::SetpointSource::UnsavedDigital = 2 }
 Setpoint source (LSS, Modbus 516; M p.11 to 12 and p.19). More...
 
enum class  alicat_basis2::TimeUnit : uint8_t { alicat_basis2::TimeUnit::Millisecond = 3 , alicat_basis2::TimeUnit::Second = 4 , alicat_basis2::TimeUnit::Minute = 5 }
 Time unit of the ramp command (SR r t, M p.12). More...
 
enum class  alicat_basis2::TotalizerLimit : uint8_t { alicat_basis2::TotalizerLimit::HoldNoError = 0 , alicat_basis2::TotalizerLimit::ResetNoError = 1 , alicat_basis2::TotalizerLimit::HoldWithError = 2 , alicat_basis2::TotalizerLimit::ResetWithError = 3 }
 Totalizer limit behaviour (TC, Modbus 54; M p.16). More...
 
enum class  alicat_basis2::FullScaleItem : uint8_t { alicat_basis2::FullScaleItem::Flow = 0 , alicat_basis2::FullScaleItem::TotalVolume = 1 , alicat_basis2::FullScaleItem::MaxTemperature = 2 }
 The item read by FPF (M p.16). More...
 
enum class  alicat_basis2::DataItem : uint8_t {
  alicat_basis2::DataItem::Flow = 1 , alicat_basis2::DataItem::Setpoint = 2 , alicat_basis2::DataItem::Temperature = 4 , alicat_basis2::DataItem::ValveDrive = 8 ,
  alicat_basis2::DataItem::Gas = 16 , alicat_basis2::DataItem::TotalVolume = 32 , alicat_basis2::DataItem::BatchRemaining = 64 , alicat_basis2::DataItem::Status = 128
}
 Items of DV (a bit mask, M p.11). More...
 
enum class  alicat_basis2::TriggerMode : uint8_t { alicat_basis2::TriggerMode::OnSetpointChange = 1 , alicat_basis2::TriggerMode::OnHoldChange = 2 , alicat_basis2::TriggerMode::OnAverageRead = 4 }
 Measurement trigger bits (MT, Modbus 4200; M p.13 to 14). More...
 
enum class  alicat_basis2::Baud : uint8_t {
  alicat_basis2::Baud::B4800 = 0 , alicat_basis2::Baud::B9600 = 1 , alicat_basis2::Baud::B19200 = 2 , alicat_basis2::Baud::B38400 = 3 ,
  alicat_basis2::Baud::B57600 = 4 , alicat_basis2::Baud::B115200 = 5
}
 Serial speeds the instrument offers (NCB, Modbus 21; M p.17, p.25). More...
 
enum class  alicat_basis2::CommandProtocol : uint8_t { alicat_basis2::CommandProtocol::BasisProtocol2 = 0 , alicat_basis2::CommandProtocol::BasisProtocol1 = 1 }
 Command protocol selector (P, Modbus 56). More...
 
enum class  alicat_basis2::FlowUnit : uint8_t {
  Sccm = 0 , Nccm = 1 , Slpm = 2 , Nlpm = 3 ,
  SmLs = 4 , NmLs = 5 , SmLm = 6 , NmLm = 7 ,
  SLh = 8 , NLh = 9 , Sccs = 10 , Nccs = 11 ,
  Sm3h = 12 , Nm3h = 13 , Sm3d = 14 , Nm3d = 15 ,
  Scim = 16 , Scfm = 17 , Scfh = 18 , Scfd = 19 ,
  alicat_basis2::FlowUnit::Other = 20
}
 Flow units (Modbus register 49, M p.26; M p.31). More...
 

Functions

constexpr const char * alicat_basis2::ToString (Error error) noexcept
 The name of an error, for logs.
 
constexpr uint32_t alicat_basis2::GetDriverVersionMajor () noexcept
 Major version of the driver, from the generated alicat_basis2_version.h.
 
constexpr uint32_t alicat_basis2::GetDriverVersionMinor () noexcept
 Minor version of the driver.
 
constexpr uint32_t alicat_basis2::GetDriverVersionPatch () noexcept
 Patch version of the driver.
 
constexpr const char * alicat_basis2::GetDriverVersion () noexcept
 The version as text, such as "0.1.0".
 
constexpr Error alicat_basis2::Validate (const Config &c) noexcept
 Check a configuration against the documented ranges.
 
constexpr const char * alicat_basis2::GasName (uint8_t number) noexcept
 The name of a gas of the nine of M p.15.
 
constexpr uint8_t alicat_basis2::operator| (DataItem a, DataItem b) noexcept
 Union of DataItem bits.
 
constexpr uint8_t alicat_basis2::operator| (uint8_t a, DataItem b) noexcept
 Union of a mask and an item.
 
constexpr StatusFlags alicat_basis2::StatusFromBits (uint32_t bits) noexcept
 Decode status bits (Modbus register 2101 or an integer DV status): +1 MOV, +2 TOV, +4 OVR, +8 HLD, +16 VTM.
 

Variables

constexpr uint8_t alicat_basis2::kDecimalsUnset = 0xFF
 "Not set" marker of Config::modbus_flow_decimals: Begin() fails in Modbus mode while it is.
 
constexpr std::size_t alicat_basis2::kMaxLine = 256
 Largest line or frame the driver buffers: the gas list (GS *) reply can be this long.
 
constexpr std::size_t alicat_basis2::kTextMax = 24
 Maximum characters kept of a text reply.
 
constexpr uint8_t alicat_basis2::kFlagCount = 5
 Position of the unit ID in a StatusFlags text: helper used by tests.
 

Detailed Description

Errors, results, configuration and the values an instrument reports.

Enumeration Type Documentation

◆ Baud

enum class alicat_basis2::Baud : uint8_t
strong

Serial speeds the instrument offers (NCB, Modbus 21; M p.17, p.25).

Enumerator
B4800 

Modbus code 0.

B9600 

Code 1.

B19200 

Code 2.

B38400 

Code 3, the default.

B57600 

Code 4 (firmware 2.2.2).

B115200 

Code 5 (firmware 2.2.2).

◆ CommandProtocol

enum class alicat_basis2::CommandProtocol : uint8_t
strong

Command protocol selector (P, Modbus 56).

Enumerator
BasisProtocol2 

The ASCII protocol this driver speaks.

BasisProtocol1 

The older protocol; the driver does not speak it (A14).

◆ DataItem

enum class alicat_basis2::DataItem : uint8_t
strong

Items of DV (a bit mask, M p.11).

Enumerator
Flow 

+1.

Setpoint 

+2.

Temperature 

+4.

ValveDrive 

+8.

Gas 

+16.

TotalVolume 

+32.

BatchRemaining 

+64.

Status 

+128.

◆ DeviceKind

enum class alicat_basis2::DeviceKind : uint8_t
strong

Whether the instrument is a meter (B series) or a controller (BC series).

Enumerator
Auto 

Learn it at Begin() from the first data frame (five numbers: controller).

Meter 

B series: no setpoint, no valve.

Controller 

BC series.

◆ EchoMode

enum class alicat_basis2::EchoMode : uint8_t
strong

Whether a half-duplex wiring that hears its own transmission is handled.

Enumerator
None 

The reply is the first line.

Skip 

A first line equal to the command just sent is dropped once.

◆ Error

enum class alicat_basis2::Error : uint8_t
strong

Why a call failed. Every call of the driver returns one of these in its Result.

Values 0 to 9 are the shared base set; chip-specific values start at 16. [[nodiscard]] on the type: a function that returns a bare Error cannot have it ignored either (KB-CPP20-037).

Enumerator
Ok 

The call succeeded.

NotInitialized 

EnsureInitialized() failed, or Begin() has not run where the call needs it.

InvalidArgument 

An argument or a Config field is out of range; nothing was sent.

Bus 

Write() returned false; nothing is pending afterwards.

Timeout 

No complete reply line (or frame) within the computed time.

DeviceIdMismatch 

The reply carried another unit ID or Modbus address than the one addressed.

Crc 

Modbus CRC-16 mismatch; the whole frame is discarded.

Busy 

The bus was not free (a transaction, quarantine or hold-off), or the line never went quiet: the transaction that met it was not sent (see docs/api-guide.md).

DeviceFault 

Reserved for the instrument's own fault reports.

Unsupported 

The feature is absent in this mode, on this kind of instrument, or on this port.

BadReply 

The line does not match the command's reply grammar.

Rejected 

The instrument answered with the error token ? or a Modbus exception reply.

OutOfRange 

A decoded value is outside what the instrument can physically report.

Overflow 

The reply exceeded the line buffer without a terminator.

VerifyMismatch 

The read-back after a setter differs from what was written.

FirmwareTooOld 

The call needs a newer firmware than the identity says.

StateUnknown 

A guarded command may have changed the line settings and was not confirmed.

RateLimited 

A saved-source setpoint change came sooner than the non-volatile memory allows.

GuardNotConfirmed 

A guarded call was made with a confirmation token of the wrong kind.

◆ FirmwareGate

enum class alicat_basis2::FirmwareGate : uint8_t
strong

Whether the firmware gates of the register and command tables are enforced.

Enumerator
Enforce 

A call that needs a newer firmware than the identity says fails with FirmwareTooOld.

Ignore 

Never refuse on the firmware version.

◆ FlowUnit

enum class alicat_basis2::FlowUnit : uint8_t
strong

Flow units (Modbus register 49, M p.26; M p.31).

Enumerator
Other 

A label not in the table of M p.31; the raw text is kept.

◆ FrameLayout

enum class alicat_basis2::FrameLayout : uint8_t
strong

Which data frame layout is accepted (assumption A2: a meter's frame is not shown in the manual).

Enumerator
Auto 

Learn from the first valid frame, reject a later frame of the other layout.

Meter 

Three numbers, then the gas, then the flags.

Controller 

Five numbers, then the gas, then the flags.

◆ FullScaleItem

enum class alicat_basis2::FullScaleItem : uint8_t
strong

The item read by FPF (M p.16).

Enumerator
Flow 

Full scale flow.

TotalVolume 

Largest total volume or batch.

MaxTemperature 

Maximum temperature.

◆ LogLevel

enum class alicat_basis2::LogLevel : uint8_t
strong

Severity passed to the optional Log() hook.

Enumerator
Error 

A transaction failed.

Warning 

Something unexpected that the driver recovered from.

Info 

Lifecycle events.

Debug 

Detail for bring-up.

◆ Protocol

enum class alicat_basis2::Protocol : uint8_t
strong

The command protocol one Basis2 object speaks.

Enumerator
Ascii 

"BASIS Protocol 2": ASCII lines, the default (M p.10 to 17).

ModbusRtu 

Modbus RTU, functions 3, 6 and 16 (M p.18 to 27).

◆ SetpointSource

enum class alicat_basis2::SetpointSource : uint8_t
strong

Setpoint source (LSS, Modbus 516; M p.11 to 12 and p.19).

Enumerator
Analog 

a: the analog input; digital setpoint commands are not accepted.

SavedDigital 

s: the last digital setpoint is used at power-up; wears non-volatile memory.

UnsavedDigital 

u: recommended for frequent changes.

◆ TimeUnit

enum class alicat_basis2::TimeUnit : uint8_t
strong

Time unit of the ramp command (SR r t, M p.12).

Enumerator
Millisecond 

3.

Second 

4.

Minute 

5.

◆ TotalizerLimit

enum class alicat_basis2::TotalizerLimit : uint8_t
strong

Totalizer limit behaviour (TC, Modbus 54; M p.16).

Enumerator
HoldNoError 

Keep at the maximum, no OVR.

ResetNoError 

Reset to zero, no OVR.

HoldWithError 

Keep at the maximum, OVR.

ResetWithError 

Reset to zero, OVR.

◆ TriggerMode

enum class alicat_basis2::TriggerMode : uint8_t
strong

Measurement trigger bits (MT, Modbus 4200; M p.13 to 14).

Enumerator
OnSetpointChange 

+1: a digital setpoint change starts a measurement.

OnHoldChange 

+2: a hold-percent change while held.

OnAverageRead 

+4: reading the average flow starts the next measurement.

◆ UnknownFlagPolicy

enum class alicat_basis2::UnknownFlagPolicy : uint8_t
strong

What happens with a flag token the manual does not list.

Enumerator
Report 

Count it in StatusFlags::unknown_count and return the frame.

Reject 

BadReply; no value is exposed.

◆ VerifyPolicy

enum class alicat_basis2::VerifyPolicy : uint8_t
strong

Whether a setpoint is read back after it was set.

Enumerator
Off 

No read-back.

WhenNoRamp 

Read it back unless a setpoint ramp is active (the instrument then lags on purpose).

Function Documentation

◆ GasName()

constexpr const char * alicat_basis2::GasName ( uint8_t  number)
constexprnoexcept

The name of a gas of the nine of M p.15.

Parameters
numberThe gas number.
Returns
A static short name ("N2"), or nullptr for a number outside 0 to 8.

◆ GetDriverVersion()

constexpr const char * alicat_basis2::GetDriverVersion ( )
constexprnoexcept

The version as text, such as "0.1.0".

Returns
A static string.

◆ GetDriverVersionMajor()

constexpr uint32_t alicat_basis2::GetDriverVersionMajor ( )
constexprnoexcept

Major version of the driver, from the generated alicat_basis2_version.h.

Returns
The number.

◆ GetDriverVersionMinor()

constexpr uint32_t alicat_basis2::GetDriverVersionMinor ( )
constexprnoexcept

Minor version of the driver.

Returns
The number.

◆ GetDriverVersionPatch()

constexpr uint32_t alicat_basis2::GetDriverVersionPatch ( )
constexprnoexcept

Patch version of the driver.

Returns
The number.

◆ operator|() [1/2]

constexpr uint8_t alicat_basis2::operator| ( DataItem  a,
DataItem  b 
)
constexprnoexcept

Union of DataItem bits.

Parameters
aFirst.
bSecond.
Returns
a | b as a mask value.

◆ operator|() [2/2]

constexpr uint8_t alicat_basis2::operator| ( uint8_t  a,
DataItem  b 
)
constexprnoexcept

Union of a mask and an item.

Parameters
aMask.
bItem.
Returns
a | b.

◆ StatusFromBits()

constexpr StatusFlags alicat_basis2::StatusFromBits ( uint32_t  bits)
constexprnoexcept

Decode status bits (Modbus register 2101 or an integer DV status): +1 MOV, +2 TOV, +4 OVR, +8 HLD, +16 VTM.

Parameters
bitsThe bits; anything above bit 4 is counted as unknown.
Returns
The flags.

◆ ToString()

constexpr const char * alicat_basis2::ToString ( Error  error)
constexprnoexcept

The name of an error, for logs.

Parameters
errorThe error.
Returns
A static string such as "Timeout"; "Unknown" for a value that is not an enumerator.

◆ Validate()

constexpr Error alicat_basis2::Validate ( const Config &  c)
constexprnoexcept

Check a configuration against the documented ranges.

Parameters
cThe configuration.
Returns
Ok or InvalidArgument.