BASIS 2 Driver 0.1.0
API reference
Loading...
Searching...
No Matches
Namespaces | Classes | Concepts | Enumerations | Functions | Variables
alicat_basis2 Namespace Reference

The ALICAT_BASIS2 driver: everything it declares lives here; internals in detail. More...

Namespaces

namespace  ascii
 The ASCII grammar: table, encoder, validator, decoders.
 
namespace  gas
 The nine gases of M p.15.
 
namespace  modbus
 The Modbus RTU codec.
 
namespace  reg
 The ALICAT_BASIS2 Modbus register map.
 

Classes

struct  AddressScan
 The Modbus addresses that answered a scan: bit n of byte n/8 is address n. More...
 
struct  Averages
 Result of ReadAverages(): the current or most recent measurement window. More...
 
class  Basis2
 Driver for one instrument on a Bus. More...
 
class  Bus
 The transaction machine of one serial line, shared by every instrument on it. More...
 
struct  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  ConfirmAbandonProtocol2
 Confirms SwitchToProtocol1(): the instrument leaves the protocol this driver speaks. More...
 
struct  ConfirmAddressChange
 Confirms SetModbusAddress(): the Modbus address changes at once. More...
 
struct  ConfirmBaudChange
 Confirms ChangeBaud(): the reply arrives at the new speed and the port must follow. More...
 
struct  ConfirmFactoryRestore
 Confirms FactoryRestore(): unit ID, baud rate, Modbus address and protocol revert; power cycle. More...
 
struct  ConfirmReturnToProtocol2
 Guard token of SwitchToProtocol2. More...
 
struct  ConfirmUnitIdChange
 Confirms ChangeUnitId(): the instrument answers to the new ID afterwards; connect one instrument only. More...
 
struct  Decimal
 An exact decimal number as the instrument printed it: +0021513.0 is {215130, 1}. More...
 
struct  Frame
 One data frame (A) or a DV selection; present says which fields were read. More...
 
struct  FullScale
 One reading of FPF: a value and its unit text. More...
 
struct  Gains
 Closed-loop gains (LCG, Modbus 519 and 520). More...
 
struct  GasEntry
 One entry of the gas table of firmware 3.0.5 (Modbus 81 to 140, M p.26 to 27). More...
 
struct  GasId
 A gas number. Not a closed enumeration: the V3.0.5 gas table allows numbers up to 255 (A5). More...
 
struct  GasList
 Result of ReadGasList(): the parsed pairs, or the raw text when the grammar did not match (A5). More...
 
struct  GasTable
 The whole gas table: twelve entries. More...
 
struct  Identity
 What Begin() learned: read-only knowledge of the instrument. More...
 
struct  PreviousMeasurement
 Result of ReadPreviousMeasurement() (Modbus only, registers 4210 to 4215). More...
 
struct  Ramp
 Result of ReadRamp(): rate and time unit as the instrument reported them. More...
 
struct  Ranges
 Result of ReadRanges(). More...
 
struct  Reply
 A reply as received: one ASCII line without its CR, or one Modbus frame (raw bytes as chars). More...
 
class  Request
 One validated request. Only the factories of the grammar headers make one that can be sent. More...
 
struct  Result
 The value of a call, or why there is none. More...
 
struct  Result< void >
 The result of a call that returns no value. More...
 
struct  StatusFlags
 Status flags of a data frame or of Modbus register 2101 (M p.10, p.21). More...
 
struct  Text
 A short text value (serial number, firmware, unit label), NUL terminated. More...
 
struct  Timing
 What the bus needs to know about the instrument it talks to, per transaction. More...
 
class  UartInterface
 CRTP base of the platform serial port. More...
 
struct  UnitIdScan
 The unit IDs that answered a scan: bit 0 is A. More...
 

Concepts

concept  UartPort
 Satisfied by a class that derives from UartInterface<Port> and implements the five required hooks with exactly the types above, noexcept.
 

Enumerations

enum class  Command : uint8_t {
  Command::Poll = 0 , Command::ReadData , Command::SetSetpoint , Command::ReadSetpointSource ,
  Command::SetSetpointSource , Command::ReadRamp , Command::SetRamp , Command::DisableRamp ,
  Command::ReadWatchdog , Command::SetWatchdog , Command::HoldValve , Command::ResumeControl ,
  Command::ReadGains , Command::SetGains , Command::ReadReferenceTemperature , Command::SetReferenceTemperature ,
  Command::ReadAveraging , Command::SetAveraging , Command::ReadTrigger , Command::SetTrigger ,
  Command::StartMeasurement , Command::ReadAverages , Command::ReadRanges , Command::Tare ,
  Command::ReadAutotare , Command::SetAutotare , Command::ReadGas , Command::ReadGasList ,
  Command::SetGas , Command::ResetTotal , Command::SetBatch , Command::DisableBatch ,
  Command::ReadTotalizerLimit , Command::SetTotalizerLimit , Command::ReadFullScale , Command::ChangeUnitId ,
  Command::ReadSerialNumber , Command::ReadFirmware , Command::ReadModbusAddress , Command::SetModbusAddress ,
  Command::ReadBaud , Command::ChangeBaud , Command::ReadProtocol , Command::SwitchToProtocol1 ,
  Command::SwitchToProtocol2 , Command::FactoryRestore , Command::Modbus
}
 The 46 ASCII commands of M pp.10 to 17 (rows C01 to C46 of the coverage map), plus the Modbus kind. More...
 
enum class  Error : uint8_t {
  Error::Ok = 0 , Error::NotInitialized , Error::InvalidArgument = 2 , Error::Bus = 3 ,
  Error::Timeout = 4 , Error::DeviceIdMismatch , Error::Crc = 6 , Error::Busy ,
  Error::DeviceFault = 8 , Error::Unsupported , Error::BadReply = 16 , Error::Rejected = 17 ,
  Error::OutOfRange = 18 , Error::Overflow = 19 , Error::VerifyMismatch = 20 , Error::FirmwareTooOld = 21 ,
  Error::StateUnknown , Error::RateLimited , Error::GuardNotConfirmed = 24
}
 Why a call failed. Every call of the driver returns one of these in its Result. More...
 
enum class  LogLevel : uint8_t { LogLevel::Error = 0 , LogLevel::Warning , LogLevel::Info , LogLevel::Debug }
 Severity passed to the optional Log() hook. More...
 
enum class  Protocol : uint8_t { Protocol::Ascii = 0 , Protocol::ModbusRtu = 1 }
 The command protocol one Basis2 object speaks. More...
 
enum class  DeviceKind : uint8_t { DeviceKind::Auto = 0 , DeviceKind::Meter = 1 , DeviceKind::Controller = 2 }
 Whether the instrument is a meter (B series) or a controller (BC series). More...
 
enum class  FrameLayout : uint8_t { FrameLayout::Auto = 0 , FrameLayout::Meter = 1 , FrameLayout::Controller = 2 }
 Which data frame layout is accepted (assumption A2: a meter's frame is not shown in the manual). More...
 
enum class  UnknownFlagPolicy : uint8_t { UnknownFlagPolicy::Report = 0 , UnknownFlagPolicy::Reject = 1 }
 What happens with a flag token the manual does not list. More...
 
enum class  EchoMode : uint8_t { EchoMode::None = 0 , EchoMode::Skip = 1 }
 Whether a half-duplex wiring that hears its own transmission is handled. More...
 
enum class  VerifyPolicy : uint8_t { VerifyPolicy::Off = 0 , VerifyPolicy::WhenNoRamp }
 Whether a setpoint is read back after it was set. More...
 
enum class  FirmwareGate : uint8_t { FirmwareGate::Enforce , FirmwareGate::Ignore = 1 }
 Whether the firmware gates of the register and command tables are enforced. More...
 
enum class  SetpointSource : uint8_t { SetpointSource::Analog = 0 , SetpointSource::SavedDigital , SetpointSource::UnsavedDigital = 2 }
 Setpoint source (LSS, Modbus 516; M p.11 to 12 and p.19). More...
 
enum class  TimeUnit : uint8_t { TimeUnit::Millisecond = 3 , TimeUnit::Second = 4 , TimeUnit::Minute = 5 }
 Time unit of the ramp command (SR r t, M p.12). More...
 
enum class  TotalizerLimit : uint8_t { TotalizerLimit::HoldNoError = 0 , TotalizerLimit::ResetNoError = 1 , TotalizerLimit::HoldWithError = 2 , TotalizerLimit::ResetWithError = 3 }
 Totalizer limit behaviour (TC, Modbus 54; M p.16). More...
 
enum class  FullScaleItem : uint8_t { FullScaleItem::Flow = 0 , FullScaleItem::TotalVolume = 1 , FullScaleItem::MaxTemperature = 2 }
 The item read by FPF (M p.16). More...
 
enum class  DataItem : uint8_t {
  DataItem::Flow = 1 , DataItem::Setpoint = 2 , DataItem::Temperature = 4 , DataItem::ValveDrive = 8 ,
  DataItem::Gas = 16 , DataItem::TotalVolume = 32 , DataItem::BatchRemaining = 64 , DataItem::Status = 128
}
 Items of DV (a bit mask, M p.11). More...
 
enum class  TriggerMode : uint8_t { TriggerMode::OnSetpointChange = 1 , TriggerMode::OnHoldChange = 2 , TriggerMode::OnAverageRead = 4 }
 Measurement trigger bits (MT, Modbus 4200; M p.13 to 14). More...
 
enum class  Baud : uint8_t {
  Baud::B4800 = 0 , Baud::B9600 = 1 , Baud::B19200 = 2 , Baud::B38400 = 3 ,
  Baud::B57600 = 4 , Baud::B115200 = 5
}
 Serial speeds the instrument offers (NCB, Modbus 21; M p.17, p.25). More...
 
enum class  CommandProtocol : uint8_t { CommandProtocol::BasisProtocol2 = 0 , CommandProtocol::BasisProtocol1 = 1 }
 Command protocol selector (P, Modbus 56). More...
 
enum class  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 ,
  FlowUnit::Other = 20
}
 Flow units (Modbus register 49, M p.26; M p.31). More...
 
enum class  PollState : uint8_t { Idle = 0 , Pending = 1 , Done = 2 , Failed = 3 }
 State of a transaction as seen by Bus::Poll(). More...
 
enum class  BusState : uint8_t { Idle = 0 , Gap = 1 , AwaitReply = 2 , Settling = 3 }
 Internal phase of the bus. More...
 

Functions

constexpr Config KconfigDefaults () noexcept
 The configuration menuconfig selected, on top of the datasheet defaults.
 
constexpr const char * ToString (Error error) noexcept
 The name of an error, for logs.
 
constexpr uint32_t GetDriverVersionMajor () noexcept
 Major version of the driver, from the generated alicat_basis2_version.h.
 
constexpr uint32_t GetDriverVersionMinor () noexcept
 Minor version of the driver.
 
constexpr uint32_t GetDriverVersionPatch () noexcept
 Patch version of the driver.
 
constexpr const char * GetDriverVersion () noexcept
 The version as text, such as "0.1.0".
 
constexpr Error Validate (const Config &c) noexcept
 Check a configuration against the documented ranges.
 
constexpr const char * GasName (uint8_t number) noexcept
 The name of a gas of the nine of M p.15.
 
constexpr uint8_t operator| (DataItem a, DataItem b) noexcept
 Union of DataItem bits.
 
constexpr uint8_t operator| (uint8_t a, DataItem b) noexcept
 Union of a mask and an item.
 
constexpr StatusFlags 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 std::size_t kMaxRequest = 48
 Longest request the driver builds, in bytes.
 
constexpr uint8_t kDecimalsUnset = 0xFF
 "Not set" marker of Config::modbus_flow_decimals: Begin() fails in Modbus mode while it is.
 
constexpr std::size_t kMaxLine = 256
 Largest line or frame the driver buffers: the gas list (GS *) reply can be this long.
 
constexpr std::size_t kTextMax = 24
 Maximum characters kept of a text reply.
 
constexpr uint8_t kFlagCount = 5
 Position of the unit ID in a StatusFlags text: helper used by tests.
 
Bus requirements

What the instrument needs from the serial line and its supply (manual pp. 6, 10 and 17). A port and a board configuration check their settings against these with static_assert (handbook KB-CPP-123).

constexpr uint32_t kPortDefaultBaud = 38'400
 The baud rate after a factory restore, 8 data bits, no parity, 1 stop bit (M p.10).
 
constexpr uint32_t kMinBaudRate = 4'800
 The lowest baud rate the instrument offers (M p.17).
 
constexpr uint32_t kMaxBaudRate = 115'200
 The highest baud rate the instrument offers, firmware 2.2.2 or later (M p.17).
 
constexpr uint32_t kSilentBitTimes = 35
 
constexpr uint32_t kTurnaroundUs = 50'000
 
constexpr uint32_t kSupplyMinMv = 12'000
 Lowest supply, millivolts, on pin 4 only (M p.6).
 
constexpr uint32_t kSupplyMaxMv = 24'000
 Highest supply, millivolts (M p.6).
 

Detailed Description

The ALICAT_BASIS2 driver: everything it declares lives here; internals in detail.

Enumeration Type Documentation

◆ BusState

enum class alicat_basis2::BusState : uint8_t
strong

Internal phase of the bus.

Enumerator
Idle 

Nothing happening.

Gap 

Waiting out the idle time before a send.

AwaitReply 

Accumulating the reply.

Settling 

After a transaction: hold-off or quarantine drain.

◆ PollState

enum class alicat_basis2::PollState : uint8_t
strong

State of a transaction as seen by Bus::Poll().

Enumerator
Idle 

Nothing pending and no result waiting.

Pending 

Waiting for the gap, or for the reply.

Done 

The result is ready: Take() returns the reply.

Failed 

The transaction failed: Take() returns the error.

Function Documentation

◆ KconfigDefaults()

constexpr Config alicat_basis2::KconfigDefaults ( )
constexprnoexcept

The configuration menuconfig selected, on top of the datasheet defaults.

Returns
Config{} with the protocol, baud rate, timing and retries taken from Kconfig.

Variable Documentation

◆ kSilentBitTimes

constexpr uint32_t alicat_basis2::kSilentBitTimes = 35
inlineconstexpr

The idle time before the instrument acts on a command, in bit times: 3.5 characters of 10 bits (M p.10).

◆ kTurnaroundUs

constexpr uint32_t alicat_basis2::kTurnaroundUs = 50'000
inlineconstexpr

The instrument's turnaround that the reply wait adds to the line time, microseconds (an assumption, K-PROC).