|
BASIS 2 Driver 0.1.0
API reference
|
Driver for one instrument on a Bus.
More...
#include <alicat_basis2.hpp>
Public Member Functions | |
| Basis2 (Bus< Port > &bus, const Config &config={}) noexcept | |
| Bind to a bus and store the configuration. No I/O, cannot fail. | |
| Basis2 (const Basis2 &)=delete | |
| One driver object per instrument. | |
| Basis2 & | operator= (const Basis2 &)=delete |
| One driver object per instrument. | |
Lifecycle | |
| Result< void > | EnsureInitialized () noexcept |
| Bring the port up and check the stored configuration; no instrument traffic. | |
| Result< void > | Begin () noexcept |
| Learn the instrument: a poll, the firmware, serial number, full scale, gas, totalizer limit, averaging, reference temperature and, for a controller, setpoint source, ramp and autotare. Sends no write. | |
| Result< void > | Recover () noexcept |
Find the instrument again after a guarded command left StateUnknown or after a lost line: poll the configured ID, else (only when Bus::DeviceCount() is one) scan A to Z or the Modbus addresses, adopt the ID that answers and run Begin(). StateUnknown ends only when that Begin() succeeds and the serial number, firmware and kind equal those learned before; on any failure the driver stays in StateUnknown and keeps its old ID. | |
| bool | IsInitialized () const noexcept |
| bool | IsReady () const noexcept |
| bool | IsStateUnknown () const noexcept |
| const Config & | GetConfig () const &noexcept |
| void | GetConfig () const &&=delete |
| Not on a temporary. | |
| const Identity & | GetIdentity () const &noexcept |
| void | GetIdentity () const &&=delete |
| Not on a temporary. | |
| uint8_t | LastException () const noexcept |
| Result< modbus::Response > | ReadRegisterRaw (uint16_t first, uint16_t count) noexcept |
Single-shot raw read of count registers from first (Modbus function 3): one frame, no retry, no scaling. The reply is still accepted only after its CRC, address and length check. | |
| Result< Reply > | ReadRawLine (Command command) noexcept |
| Single-shot raw read of one ASCII command that only reads (never one that writes): one request, no retry, no decoding; the reply line (without its CR) is returned as received. | |
| const Reply & | GetLastReply () const &noexcept |
| void | GetLastReply () const &&=delete |
| Not on a temporary. | |
Data | |
| Result< Frame > | ReadFrame () noexcept |
| Poll: the full data frame (C01), or the Modbus block 2100 to 2109. | |
| Result< Frame > | ReadData (uint8_t items) noexcept |
Read selected fields (DV n, C02). In Modbus mode the block is read and the fields asked are filled. | |
| Result< Decimal > | ReadFlow () noexcept |
| Flow in the configured unit. | |
| Result< Decimal > | ReadTemperature () noexcept |
| Temperature in C. | |
| Result< Decimal > | ReadTotal () noexcept |
| Totalizer. | |
| Result< Decimal > | ReadValveDrive () noexcept |
| Valve drive in percent (controllers). | |
| Result< Decimal > | ReadSetpointValue () noexcept |
| The current setpoint (controllers). | |
| Result< Decimal > | ReadBatchRemaining () noexcept |
| Batch volume remaining (controllers). | |
| Result< StatusFlags > | ReadStatus () noexcept |
| Status flags. | |
| Result< Frame > | ReadGas () noexcept |
| The selected gas (C27). | |
Setpoint and valve (controllers) | |
| Result< void > | SetSetpoint (double flow) noexcept |
| Set the setpoint (C03; Modbus registers 2053 to 2054). | |
| Result< SetpointSource > | ReadSetpointSource () noexcept |
| Read the setpoint source (C04, register 516). | |
| Result< void > | SetSetpointSource (SetpointSource source) noexcept |
Set the setpoint source (C05, register 516). SavedDigital wears non-volatile memory: use UnsavedDigital for frequent changes. | |
| Result< Ramp > | ReadRamp () noexcept |
| Read the ramp (C06, registers 524 to 525; Modbus: the raw register). | |
| Result< void > | SetRamp (double rate, TimeUnit unit) noexcept |
| Set the maximum setpoint ramp rate (C07; Modbus 524 to 525 after conversion with the full scale, A9). | |
| Result< void > | DisableRamp () noexcept |
| Disable ramp limiting (C08). | |
| Result< uint32_t > | ReadWatchdog () noexcept |
| Read the watchdog in ms (C09, register 514). | |
| Result< void > | SetWatchdog (uint32_t ms) noexcept |
Set the communication watchdog (C10, register 514). It acts only for Modbus-set setpoints with the unsaved digital source (M p.12 to 13, A8): never rely on it with ASCII; see WatchdogProtects(). | |
| Result< void > | HoldValve (double percent) noexcept |
| Hold the valve at a percentage of full drive (C11). ASCII only; the Modbus map has no such register. | |
| Result< void > | ResumeControl () noexcept |
| Resume closed-loop control after a hold (C12). | |
| Result< void > | OpenValve () noexcept |
Hold the valve fully open: HoldValve(100) (the FlowVision "open" button is not a command, A20). | |
| Result< void > | CloseValve () noexcept |
Hold the valve closed: HoldValve(0). Never refused for StateUnknown. | |
Control tuning (controllers) | |
| Result< Gains > | ReadGains () noexcept |
| Read the loop gains (C13, registers 519 and 520). | |
| Result< void > | SetGains (uint32_t p, uint32_t i) noexcept |
| Set the loop gains (C14). | |
| Result< bool > | ReadAutotare () noexcept |
| Read autotare (C25, register 515). | |
| Result< void > | SetAutotare (bool on) noexcept |
| Enable or disable autotare (C26): the zero is taken after 2 s at a zero setpoint. | |
| Result< uint8_t > | ReadMeasurementTrigger () noexcept |
| Read the measurement trigger bits (C19, register 4200). | |
| Result< void > | SetMeasurementTrigger (uint8_t mask) noexcept |
| Set the trigger bits (C20). | |
Measurement window and tare | |
| Result< void > | StartMeasurement (uint32_t duration_ms) noexcept |
| Start a measurement window (C21; Modbus register 4201 in samples of about 2.5 ms). | |
| Result< Averages > | ReadAverages () noexcept |
| Averages of the current or most recent window (C22). | |
| Result< Ranges > | ReadRanges () noexcept |
| Minimum and maximum of the current or most recent window (C23). | |
| Result< PreviousMeasurement > | ReadPreviousMeasurement () noexcept |
| The previous completed window (Modbus only; reading it may start a window, A17). | |
| Result< void > | Tare (uint32_t duration_ms) noexcept |
| Tare the flow sensor (C24; Modbus 51 and 39). Only on the pure process gas at true zero flow (M p.14). The bus stays closed for the duration. | |
| Result< void > | TareDefault () noexcept |
Tare(1000), the manual's example duration. | |
Gas, totalizer, processing | |
| Result< void > | SetGas (GasId gas) noexcept |
| Select the gas (C29, register 2100). | |
| Result< GasList > | ReadGasList () noexcept |
| The gases the instrument offers (C28, firmware 3.0.5). | |
| Result< GasTable > | ReadGasTable () noexcept |
| The twelve-entry gas table (Modbus only, firmware 3.0.5). | |
| Result< void > | ResetTotal () noexcept |
| Reset the totalizer (C30, register 53). | |
| Result< TotalizerLimit > | ReadTotalizerLimit () noexcept |
| Read the totalizer limit mode (C33, register 54). | |
| Result< void > | SetTotalizerLimit (TotalizerLimit mode) noexcept |
| Set the totalizer limit mode (C34). | |
| Result< void > | SetBatch (double volume) noexcept |
| Set a batch volume (C31; the valve closes after it has flowed). | |
| Result< void > | DisableBatch () noexcept |
| Disable the batch (C32). | |
| Result< uint32_t > | ReadAveraging () noexcept |
| Flow averaging time constant in ms (C17, register 55). | |
| Result< void > | SetAveraging (uint32_t ms) noexcept |
| Set the averaging time constant (C18). | |
| Result< Decimal > | ReadReferenceTemperature () noexcept |
| Reference temperature in C (C15, register 52). | |
| Result< void > | SetReferenceTemperature (double celsius) noexcept |
| Set the reference temperature (C16): 0 to 30.00 C (A10). | |
Identity | |
| Result< FullScale > | ReadFullScale (FullScaleItem item) noexcept |
| Read a full-scale value with its unit text (C35). | |
| Result< Text > | ReadSerialNumber () noexcept |
| Serial number (C37, registers 26 to 31). | |
| Result< Text > | ReadFirmware () noexcept |
| Firmware version (C38, register 25). | |
| Result< uint32_t > | ReadModbusAddress () noexcept |
| Modbus address (C39, register 45). | |
| Result< Baud > | ReadBaud () noexcept |
| Baud rate (C41, register 21). | |
| Result< CommandProtocol > | ReadProtocol () noexcept |
| Command protocol (C43, register 56). | |
| Result< FlowUnit > | ReadFlowUnit () noexcept |
| The flow unit code of register 49 (Modbus only). | |
| Result< uint32_t > | ReadFullScaleSccm () noexcept |
| The full scale in SCCM (registers 35 to 36, Modbus only). | |
| Result< uint16_t > | ReadSensorOffset () noexcept |
| The flow sensor offset (register 32, Modbus only). | |
Guarded commands | |
| Result< void > | ChangeUnitId (char new_id, ConfirmUnitIdChange) noexcept |
Change the unit ID (C36, register 46). Connect one instrument at a time (M p.16): refused when Bus::DeviceCount() is above one. The reply is accepted under either ID, then verified with a poll under the new ID; if that fails the state is StateUnknown until Recover(). | |
| Result< void > | SetModbusAddress (uint8_t address, ConfirmAddressChange) noexcept |
| Change the Modbus address (C40, register 45). | |
| Result< void > | ChangeBaud (Baud baud, ConfirmBaudChange) noexcept |
Change the baud rate (C42, register 21): the reply arrives at the new speed. Needs the port's SetBaud() hook. On failure the port is set back once and the state is StateUnknown. | |
| Result< void > | SwitchToProtocol1 (ConfirmAbandonProtocol2) noexcept |
Switch the instrument to BASIS Protocol 1 (C44, register 56). Only with the flow units SCCM, SLPM, NCCM or NLPM (M p.17). Afterwards the driver is abandoned: every call is Unsupported until SwitchToProtocol2() or Begin(). | |
| Result< void > | SwitchToProtocol2 (ConfirmReturnToProtocol2) noexcept |
| Switch back to BASIS Protocol 2 (C45). | |
| Result< void > | FactoryRestore (ConfirmFactoryRestore) noexcept |
Restore the factory configuration (C46, register 80). Unit ID, baud rate, Modbus address and protocol revert: the state is StateUnknown; power-cycle the instrument and call Recover(). | |
Scans | |
| Result< UnitIdScan > | ScanUnitIds () noexcept |
Poll A to Z (26 reads at most) and report which answered. | |
| Result< AddressScan > | ScanModbusAddresses (uint8_t first, uint8_t last) noexcept |
| Read register 25 at each address of a range (function 3 only). | |
Static Public Member Functions | |
| static constexpr bool | WatchdogProtects (Protocol protocol, SetpointSource source) noexcept |
| Whether the instrument's watchdog protects a setpoint (A8): only for Modbus-written setpoints with the unsaved digital source. | |
Driver for one instrument on a Bus.
Lifecycle: construct with the configuration (no I/O), then EnsureInitialized() (port up, configuration checked), then Begin() (a read-only sequence that learns the identity). Every call that touches the instrument returns NotInitialized before EnsureInitialized() has succeeded.
| Port | Your class derived from UartInterface<Port>. |
|
inlineexplicitnoexcept |
Bind to a bus and store the configuration. No I/O, cannot fail.
| bus | The serial line; it must outlive the driver. |
| config | Checked by EnsureInitialized() before any I/O. |
|
noexcept |
Learn the instrument: a poll, the firmware, serial number, full scale, gas, totalizer limit, averaging, reference temperature and, for a controller, setpoint source, ramp and autotare. Sends no write.
The instrument needs about one minute after power-up to settle (S19 p.1). In Modbus mode Config::modbus_flow_decimals must be set (A11).
Ok, NotInitialized, InvalidArgument (Modbus decimals unset), or the error of the first failing transaction.
|
noexcept |
Change the baud rate (C42, register 21): the reply arrives at the new speed. Needs the port's SetBaud() hook. On failure the port is set back once and the state is StateUnknown.
| baud | The new speed. |
Ok, Unsupported (no hook), FirmwareTooOld, StateUnknown or an error.
|
noexcept |
Change the unit ID (C36, register 46). Connect one instrument at a time (M p.16): refused when Bus::DeviceCount() is above one. The reply is accepted under either ID, then verified with a poll under the new ID; if that fails the state is StateUnknown until Recover().
| new_id | A to Z. |
Ok, GuardNotConfirmed, InvalidArgument, Unsupported or StateUnknown.
|
noexcept |
Hold the valve closed: HoldValve(0). Never refused for StateUnknown.
Ok or an error.
|
noexcept |
Disable the batch (C32).
Ok/error.
|
noexcept |
Disable ramp limiting (C08).
Ok or an error.
|
noexcept |
|
noexcept |
Restore the factory configuration (C46, register 80). Unit ID, baud rate, Modbus address and protocol revert: the state is StateUnknown; power-cycle the instrument and call Recover().
Ok or an error.
|
inlinenoexcept |
|
inlinenoexcept |
Begin() learned.
|
inlinenoexcept |
|
noexcept |
Hold the valve at a percentage of full drive (C11). ASCII only; the Modbus map has no such register.
| percent | 0 to 100. |
Ok, InvalidArgument, Unsupported (meter or Modbus) or a bus error.
|
inlinenoexcept |
EnsureInitialized() succeeded. No I/O.
|
inlinenoexcept |
Begin() succeeded and until a guarded command leaves the state unknown.
|
inlinenoexcept |
Recover() ends it. No I/O.
|
inlinenoexcept |
Rejected Modbus reply, else 0.
|
noexcept |
Hold the valve fully open: HoldValve(100) (the FlowVision "open" button is not a command, A20).
Ok or an error.
|
noexcept |
Read autotare (C25, register 515).
|
noexcept |
Averages of the current or most recent window (C22).
|
noexcept |
Flow averaging time constant in ms (C17, register 55).
|
noexcept |
Batch volume remaining (controllers).
|
noexcept |
Baud rate (C41, register 21).
|
noexcept |
Read selected fields (DV n, C02). In Modbus mode the block is read and the fields asked are filled.
| items | DataItem bits, 1 to 255; controller-only items on a meter are Unsupported. |
present == items.
|
noexcept |
Firmware version (C38, register 25).
V a.b.c).
|
noexcept |
Flow in the configured unit.
|
noexcept |
The flow unit code of register 49 (Modbus only).
|
noexcept |
Poll: the full data frame (C01), or the Modbus block 2100 to 2109.
|
noexcept |
Read a full-scale value with its unit text (C35).
| item | Which. |
|
noexcept |
The full scale in SCCM (registers 35 to 36, Modbus only).
|
noexcept |
Read the loop gains (C13, registers 519 and 520).
|
noexcept |
The selected gas (C27).
|
noexcept |
The gases the instrument offers (C28, firmware 3.0.5).
|
noexcept |
The twelve-entry gas table (Modbus only, firmware 3.0.5).
|
noexcept |
Read the measurement trigger bits (C19, register 4200).
TriggerMode.
|
noexcept |
Modbus address (C39, register 45).
|
noexcept |
The previous completed window (Modbus only; reading it may start a window, A17).
|
noexcept |
Command protocol (C43, register 56).
|
noexcept |
Read the ramp (C06, registers 524 to 525; Modbus: the raw register).
|
noexcept |
Minimum and maximum of the current or most recent window (C23).
|
noexcept |
Single-shot raw read of one ASCII command that only reads (never one that writes): one request, no retry, no decoding; the reply line (without its CR) is returned as received.
| command | A read command of the grammar table, for example Command::ReadGas. |
Unsupported over Modbus, InvalidArgument or a bus error.
|
noexcept |
Reference temperature in C (C15, register 52).
|
noexcept |
Single-shot raw read of count registers from first (Modbus function 3): one frame, no retry, no scaling. The reply is still accepted only after its CRC, address and length check.
| first | First register. |
| count | Number of registers, 1 to reg::kMaxRead. |
Unsupported over ASCII, InvalidArgument or a bus error.
|
noexcept |
The flow sensor offset (register 32, Modbus only).
|
noexcept |
Serial number (C37, registers 26 to 31).
|
noexcept |
Read the setpoint source (C04, register 516).
|
noexcept |
The current setpoint (controllers).
|
noexcept |
Status flags.
|
noexcept |
Temperature in C.
|
noexcept |
Totalizer.
|
noexcept |
Read the totalizer limit mode (C33, register 54).
|
noexcept |
Valve drive in percent (controllers).
|
noexcept |
Read the watchdog in ms (C09, register 514).
|
noexcept |
Find the instrument again after a guarded command left StateUnknown or after a lost line: poll the configured ID, else (only when Bus::DeviceCount() is one) scan A to Z or the Modbus addresses, adopt the ID that answers and run Begin(). StateUnknown ends only when that Begin() succeeds and the serial number, firmware and kind equal those learned before; on any failure the driver stays in StateUnknown and keeps its old ID.
Ok, NotInitialized, Timeout (nothing answered), VerifyMismatch (another instrument answered) or an error of Begin().
|
noexcept |
Reset the totalizer (C30, register 53).
Ok/error.
|
noexcept |
Resume closed-loop control after a hold (C12).
Ok or an error.
|
noexcept |
Read register 25 at each address of a range (function 3 only).
| first | First address, 1 to 247. |
| last | Last address, first to 247. |
|
noexcept |
Poll A to Z (26 reads at most) and report which answered.
|
noexcept |
Enable or disable autotare (C26): the zero is taken after 2 s at a zero setpoint.
| on | Enabled. |
Ok or an error.
|
noexcept |
Set the averaging time constant (C18).
| ms | 0 to 2500. |
Ok/error.
|
noexcept |
Set a batch volume (C31; the valve closes after it has flowed).
| volume | Above 0. |
|
noexcept |
Set the loop gains (C14).
| p | P gain 0 to 65535. |
| i | I gain 0 to 65535. |
Ok/error.
|
noexcept |
Select the gas (C29, register 2100).
| gas | The gas. |
Ok/error.
|
noexcept |
Set the trigger bits (C20).
| mask | 0 to 7. |
Ok/error.
|
noexcept |
Change the Modbus address (C40, register 45).
| address | 1 to 247. |
Ok, InvalidArgument, StateUnknown or an error.
|
noexcept |
Set the maximum setpoint ramp rate (C07; Modbus 524 to 525 after conversion with the full scale, A9).
| rate | Flow units per time unit, above 0. |
| unit | The time unit. |
Ok, InvalidArgument, Unsupported or a bus error.
|
noexcept |
Set the reference temperature (C16): 0 to 30.00 C (A10).
| celsius | The value. |
|
noexcept |
Set the setpoint (C03; Modbus registers 2053 to 2054).
Checked against 0 to full scale x 1.025 (M p.11). While the source is SavedDigital (or unknown) a change sooner than Config::saved_setpoint_min_interval_ms after the last one is RateLimited: the saved source wears non-volatile memory (M p.11). Read back per Config::verify_setpoint: one extra transaction.
| flow | The setpoint in the instrument's flow unit. |
StateUnknown or RateLimited. Ok, InvalidArgument, Unsupported (meter), RateLimited, VerifyMismatch or a bus error.
|
noexcept |
Set the setpoint source (C05, register 516). SavedDigital wears non-volatile memory: use UnsavedDigital for frequent changes.
| source | The source. |
Ok, InvalidArgument, Unsupported or a bus error.
|
noexcept |
Set the totalizer limit mode (C34).
| mode | The mode. |
Ok/error.
|
noexcept |
Set the communication watchdog (C10, register 514). It acts only for Modbus-set setpoints with the unsaved digital source (M p.12 to 13, A8): never rely on it with ASCII; see WatchdogProtects().
| ms | 0 to 5000; 0 disables. |
Ok, InvalidArgument, Unsupported or a bus error.
|
noexcept |
Start a measurement window (C21; Modbus register 4201 in samples of about 2.5 ms).
| duration_ms | Duration in ms. |
Ok, InvalidArgument or an error.
|
noexcept |
Switch the instrument to BASIS Protocol 1 (C44, register 56). Only with the flow units SCCM, SLPM, NCCM or NLPM (M p.17). Afterwards the driver is abandoned: every call is Unsupported until SwitchToProtocol2() or Begin().
Ok, Unsupported (unit not allowed) or an error.
|
noexcept |
Switch back to BASIS Protocol 2 (C45).
Ok/error.
|
noexcept |
Tare the flow sensor (C24; Modbus 51 and 39). Only on the pure process gas at true zero flow (M p.14). The bus stays closed for the duration.
| duration_ms | 1 to 32767. |
Ok, InvalidArgument or an error.
|
noexcept |
Tare(1000), the manual's example duration.
Ok/error.
|
inlinestaticconstexprnoexcept |
Whether the instrument's watchdog protects a setpoint (A8): only for Modbus-written setpoints with the unsaved digital source.
| protocol | The protocol the setpoint is written with. |
| source | The setpoint source. |
ModbusRtu with UnsavedDigital.