BASIS 2 Driver 0.1.0
API reference
Loading...
Searching...
No Matches
alicat_basis2.hpp
Go to the documentation of this file.
1
20#ifndef ALICAT_BASIS2_HPP
21#define ALICAT_BASIS2_HPP
22
23#include <algorithm>
24#include <array>
25#include <cstddef>
26#include <cstdint>
27#include <span>
28#include <utility>
29
37#include "alicat_basis2_version.h"
38
39namespace alicat_basis2 {
40
63struct UnitIdScan {
64 uint32_t found{0};
65};
66
69 std::array<uint8_t, 32>
71};
72
83template <UartPort Port>
84class Basis2 {
85public:
91 explicit Basis2(Bus<Port>& bus, const Config& config = {}) noexcept
92 : bus_(bus), config_(config) {}
94 Basis2(const Basis2&) = delete;
96 Basis2& operator=(const Basis2&) = delete;
97
100
106
118 Result<void> Begin() noexcept;
119
129 Result<void> Recover() noexcept;
130
132 [[nodiscard]] bool IsInitialized() const noexcept {
133 return initialized_;
134 }
137 [[nodiscard]] bool IsReady() const noexcept {
138 return ready_ && !state_unknown_;
139 }
142 [[nodiscard]] bool IsStateUnknown() const noexcept {
143 return state_unknown_;
144 }
146 [[nodiscard]] const Config& GetConfig() const& noexcept {
147 return config_;
148 }
150 void GetConfig() const&& = delete;
152 [[nodiscard]] const Identity& GetIdentity() const& noexcept {
153 return identity_;
154 }
156 void GetIdentity() const&& = delete;
158 [[nodiscard]] uint8_t LastException() const noexcept {
159 return last_exception_;
160 }
161
169 Result<modbus::Response> ReadRegisterRaw(uint16_t first, uint16_t count) noexcept;
178 [[nodiscard]] const Reply& GetLastReply() const& noexcept {
179 return last_reply_;
180 }
182 void GetLastReply() const&& = delete;
183
187
190 Result<Frame> ReadFrame() noexcept;
197 Result<Frame> ReadData(uint8_t items) noexcept;
213 Result<Frame> ReadGas() noexcept;
214
218
232 Result<void> SetSetpoint(double flow) noexcept;
244 Result<Ramp> ReadRamp() noexcept;
252 Result<void> SetRamp(double rate, TimeUnit unit) noexcept;
254 Result<void> DisableRamp() noexcept;
256 Result<uint32_t> ReadWatchdog() noexcept;
264 Result<void> SetWatchdog(uint32_t ms) noexcept;
271 Result<void> HoldValve(double percent) noexcept;
273 Result<void> ResumeControl() noexcept;
279 Result<void> OpenValve() noexcept;
284 Result<void> CloseValve() noexcept;
285
289
291 Result<Gains> ReadGains() noexcept;
294 Result<void> SetGains(uint32_t p, uint32_t i) noexcept;
296 Result<bool> ReadAutotare() noexcept;
299 Result<void> SetAutotare(bool on) noexcept;
302 Result<uint8_t> ReadMeasurementTrigger() noexcept;
304 Result<void> SetMeasurementTrigger(uint8_t mask) noexcept;
305
309
315 Result<void> StartMeasurement(uint32_t duration_ms) noexcept;
330 Result<void> Tare(uint32_t duration_ms) noexcept;
332 Result<void> TareDefault() noexcept;
333
337
339 Result<void> SetGas(GasId gas) noexcept;
346 Result<void> ResetTotal() noexcept;
353 Result<void> SetBatch(double volume) noexcept;
355 Result<void> DisableBatch() noexcept;
357 Result<uint32_t> ReadAveraging() noexcept;
359 Result<void> SetAveraging(uint32_t ms) noexcept;
364 Result<void> SetReferenceTemperature(double celsius) noexcept;
365
369
379 Result<uint32_t> ReadModbusAddress() noexcept;
381 Result<Baud> ReadBaud() noexcept;
387 Result<uint32_t> ReadFullScaleSccm() noexcept;
390 Result<uint16_t> ReadSensorOffset() noexcept;
391
395
404 Result<void> ChangeUnitId(char new_id, ConfirmUnitIdChange /*confirm*/) noexcept;
410 Result<void> SetModbusAddress(uint8_t address, ConfirmAddressChange /*confirm*/) noexcept;
417 Result<void> ChangeBaud(Baud baud, ConfirmBaudChange /*confirm*/) noexcept;
433 Result<void> FactoryRestore(ConfirmFactoryRestore /*confirm*/) noexcept;
434
438
447 Result<AddressScan> ScanModbusAddresses(uint8_t first, uint8_t last) noexcept;
448
450
458 [[nodiscard]] static constexpr bool WatchdogProtects(Protocol protocol,
459 SetpointSource source) noexcept {
460 return (protocol == Protocol::ModbusRtu) && (source == SetpointSource::UnsavedDigital);
461 }
462
463private:
464 [[nodiscard]] Timing timing() const noexcept;
465 [[nodiscard]] ascii::FrameRules rules() const noexcept;
466 Error ready(bool needs_identity, bool switch_off = false) const noexcept;
467 bool scanAddresses(bool alone) noexcept;
468 bool scanAtSpeed(uint32_t speed, bool alone) noexcept;
469 bool scanForUnit() noexcept;
470 void afterFailedRecover(const detail::RecoverHeld& held, bool found, Error error) noexcept;
471 Error setpointAllowed(int64_t milli) const noexcept;
472 Result<SetpointSource> learnSource(SetpointSource source) noexcept;
473 Error needController() const noexcept;
474 Error needAscii() const noexcept;
475 Error needModbus() const noexcept;
476 Error gate(uint16_t min_fw) const noexcept;
477 [[nodiscard]] int64_t fullScaleMilli() const noexcept;
478 Result<Reply> run(const Request& request) noexcept;
479 Result<Reply> runOnce(const Request& request) noexcept;
480 Result<Reply> asciiRun(Command command, const ascii::Args& args) noexcept;
481 Result<void> asciiSet(Command command, const ascii::Args& args) noexcept;
482 Result<ascii::Values> asciiValues(Command command, uint8_t count) noexcept;
483 Result<modbus::Response> mbReadOnce(const Request& request, uint16_t count) noexcept;
484 Result<modbus::Response> mbRead(uint16_t first, uint16_t count) noexcept;
485 Result<void> mbWrite1(uint16_t target, uint16_t value, uint32_t extra_ms = 0U,
486 uint32_t hold_ms = 0U) noexcept;
487 Result<void> mbWrite2(uint16_t target, uint32_t value, uint32_t extra_ms = 0U) noexcept;
488 Result<void> mbWriteBuilt(const Result<Request>& built, uint32_t extra_ms,
489 uint32_t hold_ms) noexcept;
490 Result<uint32_t> readInt(Command command, uint16_t target, uint32_t hi) noexcept;
491 Result<void> setInt(Command command, uint16_t target, int64_t value) noexcept;
492 Result<Frame> asciiFrame(Command command, uint8_t items) noexcept;
493 Result<Frame> modbusFrame(uint8_t items) noexcept;
494 Result<Text> modbusText(uint16_t first, uint16_t count) noexcept;
495 Result<void> verifySetpoint(int64_t milli) noexcept;
496 Result<void> learnAscii() noexcept;
497 Result<void> learnMore() noexcept;
498 Result<void> learnFullScale() noexcept;
499 Result<void> learnControlModbus() noexcept;
500 [[nodiscard]] bool baudVerified(bool sent, uint8_t code) noexcept;
501 Result<void> learnModbus() noexcept;
502 Result<void> guardedFinish(char new_id) noexcept;
503 Result<void> guardedAscii(Command command, const ascii::Args& args) noexcept;
504 Result<void> setAddressOnBus(uint8_t address, uint16_t target) noexcept;
505 Result<void> failState(Error error) noexcept;
506 Result<void> holdValve(int64_t milli) noexcept;
507 Result<void> writeSetpoint(int64_t milli) noexcept;
508 Result<void> verifiedAfterWrite(int64_t milli) noexcept;
509 [[nodiscard]] uint32_t setpointExtraMs() const noexcept;
510 Result<void> offOnce(bool setpoint) noexcept;
511 Result<void> offInDoubt(bool setpoint) noexcept;
512 Result<void> offAt(bool setpoint, const detail::Alternatives& at, bool adopt) noexcept;
513 void invalidate() noexcept;
514
515 Bus<Port>& bus_;
516 Config config_;
517 Identity identity_{};
518 bool initialized_{false};
519 bool ready_{false};
520 bool state_unknown_{false};
521 bool line_busy_{false};
522 bool abandoned_{false};
523 bool have_setpoint_{false};
524 bool layout_known_{false};
526 uint8_t last_exception_{0};
527 Reply last_reply_{};
528 uint32_t last_setpoint_ms_{0};
529 detail::Alternatives alt_{};
530};
531
532} // namespace alicat_basis2
533
534// codeql::misra_deviation_next_line(MD-CPP-009)
535#include "../src/alicat_basis2.ipp"
536
537#endif // ALICAT_BASIS2_HPP
The ASCII grammar of "BASIS Protocol 2" (M pp.10 to 17): the command table, the encoder,...
Compile-time helpers of the ALICAT_BASIS2 driver: exact hook matching, typed register fields and enum...
The Modbus RTU codec (M pp.18 to 27): CRC-16, request builders, response parser and the second wire v...
ALICAT_BASIS2 Modbus register map, magic values, firmware gates and unit tables (M pp....
Request and Reply: the only things the driver puts on and takes off the wire, and the timing formulas...
Public types of the ALICAT_BASIS2 driver: errors, Result<T>, configuration, enumerations and the valu...
The serial port of the ALICAT_BASIS2 driver: the CRTP base, the UartPort concept and Bus<Port>,...
Driver for one instrument on a Bus.
Definition alicat_basis2.hpp:84
Result< Averages > ReadAverages() noexcept
Averages of the current or most recent window (C22).
void GetLastReply() const &&=delete
Not on a temporary.
Basis2 & operator=(const Basis2 &)=delete
One driver object per instrument.
Result< uint32_t > ReadAveraging() noexcept
Flow averaging time constant in ms (C17, register 55).
Result< uint32_t > ReadFullScaleSccm() noexcept
The full scale in SCCM (registers 35 to 36, Modbus only).
Result< void > EnsureInitialized() noexcept
Bring the port up and check the stored configuration; no instrument traffic.
Result< Ranges > ReadRanges() noexcept
Minimum and maximum of the current or most recent window (C23).
Result< Decimal > ReadTemperature() noexcept
Temperature in C.
Result< uint32_t > ReadWatchdog() noexcept
Read the watchdog in ms (C09, register 514).
Result< void > DisableRamp() noexcept
Disable ramp limiting (C08).
Result< void > TareDefault() noexcept
Tare(1000), the manual's example duration.
const Reply & GetLastReply() const &noexcept
Definition alicat_basis2.hpp:178
Result< uint8_t > ReadMeasurementTrigger() noexcept
Read the measurement trigger bits (C19, register 4200).
Result< bool > ReadAutotare() noexcept
Read autotare (C25, register 515).
bool IsReady() const noexcept
Definition alicat_basis2.hpp:137
Result< Reply > ReadRawLine(Command command) noexcept
Single-shot raw read of one ASCII command that only reads (never one that writes): one request,...
Result< void > Begin() noexcept
Learn the instrument: a poll, the firmware, serial number, full scale, gas, totalizer limit,...
Result< SetpointSource > ReadSetpointSource() noexcept
Read the setpoint source (C04, register 516).
Result< uint16_t > ReadSensorOffset() noexcept
The flow sensor offset (register 32, Modbus only).
Result< void > SetMeasurementTrigger(uint8_t mask) noexcept
Set the trigger bits (C20).
Result< TotalizerLimit > ReadTotalizerLimit() noexcept
Read the totalizer limit mode (C33, register 54).
Result< UnitIdScan > ScanUnitIds() noexcept
Poll A to Z (26 reads at most) and report which answered.
Result< Decimal > ReadSetpointValue() noexcept
The current setpoint (controllers).
Result< Baud > ReadBaud() noexcept
Baud rate (C41, register 21).
Basis2(Bus< Port > &bus, const Config &config={}) noexcept
Bind to a bus and store the configuration. No I/O, cannot fail.
Definition alicat_basis2.hpp:91
Result< PreviousMeasurement > ReadPreviousMeasurement() noexcept
The previous completed window (Modbus only; reading it may start a window, A17).
Result< Text > ReadFirmware() noexcept
Firmware version (C38, register 25).
void GetConfig() const &&=delete
Not on a temporary.
Basis2(const Basis2 &)=delete
One driver object per instrument.
Result< Decimal > ReadFlow() noexcept
Flow in the configured unit.
Result< void > Recover() noexcept
Find the instrument again after a guarded command left StateUnknown or after a lost line: poll the co...
static constexpr bool WatchdogProtects(Protocol protocol, SetpointSource source) noexcept
Whether the instrument's watchdog protects a setpoint (A8): only for Modbus-written setpoints with th...
Definition alicat_basis2.hpp:458
void GetIdentity() const &&=delete
Not on a temporary.
Result< CommandProtocol > ReadProtocol() noexcept
Command protocol (C43, register 56).
Result< AddressScan > ScanModbusAddresses(uint8_t first, uint8_t last) noexcept
Read register 25 at each address of a range (function 3 only).
const Config & GetConfig() const &noexcept
Definition alicat_basis2.hpp:146
Result< Text > ReadSerialNumber() noexcept
Serial number (C37, registers 26 to 31).
Result< Decimal > ReadTotal() noexcept
Totalizer.
Result< Gains > ReadGains() noexcept
Read the loop gains (C13, registers 519 and 520).
Result< Decimal > ReadBatchRemaining() noexcept
Batch volume remaining (controllers).
Result< GasList > ReadGasList() noexcept
The gases the instrument offers (C28, firmware 3.0.5).
bool IsStateUnknown() const noexcept
Definition alicat_basis2.hpp:142
Result< uint32_t > ReadModbusAddress() noexcept
Modbus address (C39, register 45).
const Identity & GetIdentity() const &noexcept
Definition alicat_basis2.hpp:152
Result< Ramp > ReadRamp() noexcept
Read the ramp (C06, registers 524 to 525; Modbus: the raw register).
Result< StatusFlags > ReadStatus() noexcept
Status flags.
Result< Decimal > ReadValveDrive() noexcept
Valve drive in percent (controllers).
uint8_t LastException() const noexcept
Definition alicat_basis2.hpp:158
Result< Frame > ReadGas() noexcept
The selected gas (C27).
Result< Decimal > ReadReferenceTemperature() noexcept
Reference temperature in C (C15, register 52).
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,...
Result< Frame > ReadFrame() noexcept
Poll: the full data frame (C01), or the Modbus block 2100 to 2109.
Result< void > CloseValve() noexcept
Hold the valve closed: HoldValve(0). Never refused for StateUnknown.
Result< void > OpenValve() noexcept
Hold the valve fully open: HoldValve(100) (the FlowVision "open" button is not a command,...
bool IsInitialized() const noexcept
Definition alicat_basis2.hpp:132
Result< GasTable > ReadGasTable() noexcept
The twelve-entry gas table (Modbus only, firmware 3.0.5).
Result< void > DisableBatch() noexcept
Disable the batch (C32).
Result< FlowUnit > ReadFlowUnit() noexcept
The flow unit code of register 49 (Modbus only).
Result< void > ResetTotal() noexcept
Reset the totalizer (C30, register 53).
Result< void > ResumeControl() noexcept
Resume closed-loop control after a hold (C12).
The transaction machine of one serial line, shared by every instrument on it.
Definition alicat_basis2_uart_interface.hpp:169
One validated request. Only the factories of the grammar headers make one that can be sent.
Definition alicat_basis2_request.hpp:115
Command
The 46 ASCII commands of M pp.10 to 17 (rows C01 to C46 of the coverage map), plus the Modbus kind.
Definition alicat_basis2_request.hpp:32
@ SwitchToProtocol1
C44 aP 1 (guarded).
@ SetRamp
C07 aSR r t.
@ ReadFullScale
C35 aFPF v.
@ SetSetpointSource
C05 aLSS x.
@ StartMeasurement
C21 aDVAS t.
@ SetTotalizerLimit
C34 aTC m.
@ ChangeBaud
C42 aNCB b (guarded).
@ FactoryRestore
C46 aFACTORY RESTORE (guarded).
@ SetModbusAddress
C40 aMA n (guarded).
@ HoldValve
C11 aHPUR p.
@ SetReferenceTemperature
C16 aRT t.
@ SetAveraging
C18 aDCA t.
@ SetAutotare
C26 aZCA 1 or aZCA 0.
@ ChangeUnitId
C36 a@=b (guarded).
@ SetGains
C14 aLCG p i.
Error
Why a call failed. Every call of the driver returns one of these in its Result.
Definition alicat_basis2_types.hpp:37
Baud
Serial speeds the instrument offers (NCB, Modbus 21; M p.17, p.25).
Definition alicat_basis2_types.hpp:524
TimeUnit
Time unit of the ramp command (SR r t, M p.12).
Definition alicat_basis2_types.hpp:473
FrameLayout
Which data frame layout is accepted (assumption A2: a meter's frame is not shown in the manual).
Definition alicat_basis2_types.hpp:235
Protocol
The command protocol one Basis2 object speaks.
Definition alicat_basis2_types.hpp:221
CommandProtocol
Command protocol selector (P, Modbus 56).
Definition alicat_basis2_types.hpp:534
SetpointSource
Setpoint source (LSS, Modbus 516; M p.11 to 12 and p.19).
Definition alicat_basis2_types.hpp:465
TotalizerLimit
Totalizer limit behaviour (TC, Modbus 54; M p.16).
Definition alicat_basis2_types.hpp:480
FullScaleItem
The item read by FPF (M p.16).
Definition alicat_basis2_types.hpp:488
FlowUnit
Flow units (Modbus register 49, M p.26; M p.31).
Definition alicat_basis2_types.hpp:540
@ Auto
Learn from the first valid frame, reject a later frame of the other layout.
@ ModbusRtu
Modbus RTU, functions 3, 6 and 16 (M p.18 to 27).
@ UnsavedDigital
u: recommended for frequent changes.
The ALICAT_BASIS2 driver: everything it declares lives here; internals in detail.
Definition alicat_basis2.hpp:39
The Modbus addresses that answered a scan: bit n of byte n/8 is address n.
Definition alicat_basis2.hpp:68
std::array< uint8_t, 32 > found
One bit per address 0 to 255 (only 1 to 247 are ever probed).
Definition alicat_basis2.hpp:70
Result of ReadAverages(): the current or most recent measurement window.
Definition alicat_basis2_types.hpp:640
The driver's configuration. Every default is the instrument's factory value or a documented driver ch...
Definition alicat_basis2_types.hpp:279
Confirms SwitchToProtocol1(): the instrument leaves the protocol this driver speaks.
Definition alicat_basis2.hpp:54
Confirms SetModbusAddress(): the Modbus address changes at once.
Definition alicat_basis2.hpp:50
Confirms ChangeBaud(): the reply arrives at the new speed and the port must follow.
Definition alicat_basis2.hpp:52
Confirms FactoryRestore(): unit ID, baud rate, Modbus address and protocol revert; power cycle.
Definition alicat_basis2.hpp:59
Guard token of SwitchToProtocol2.
Definition alicat_basis2.hpp:56
Confirms ChangeUnitId(): the instrument answers to the new ID afterwards; connect one instrument only...
Definition alicat_basis2.hpp:48
An exact decimal number as the instrument printed it: +0021513.0 is {215130, 1}.
Definition alicat_basis2_types.hpp:375
One data frame (A) or a DV selection; present says which fields were read.
Definition alicat_basis2_types.hpp:599
One reading of FPF: a value and its unit text.
Definition alicat_basis2_types.hpp:666
Closed-loop gains (LCG, Modbus 519 and 520).
Definition alicat_basis2_types.hpp:632
A gas number. Not a closed enumeration: the V3.0.5 gas table allows numbers up to 255 (A5).
Definition alicat_basis2_types.hpp:414
Result of ReadGasList(): the parsed pairs, or the raw text when the grammar did not match (A5).
Definition alicat_basis2_types.hpp:685
The whole gas table: twelve entries.
Definition alicat_basis2_types.hpp:679
What Begin() learned: read-only knowledge of the instrument.
Definition alicat_basis2_types.hpp:693
Result of ReadPreviousMeasurement() (Modbus only, registers 4210 to 4215).
Definition alicat_basis2_types.hpp:657
Result of ReadRamp(): rate and time unit as the instrument reported them.
Definition alicat_basis2_types.hpp:624
Result of ReadRanges().
Definition alicat_basis2_types.hpp:648
A reply as received: one ASCII line without its CR, or one Modbus frame (raw bytes as chars).
Definition alicat_basis2_request.hpp:87
The value of a call, or why there is none.
Definition alicat_basis2_types.hpp:151
Status flags of a data frame or of Modbus register 2101 (M p.10, p.21).
Definition alicat_basis2_types.hpp:565
A short text value (serial number, firmware, unit label), NUL terminated.
Definition alicat_basis2_types.hpp:618
What the bus needs to know about the instrument it talks to, per transaction.
Definition alicat_basis2_uart_interface.hpp:130
The unit IDs that answered a scan: bit 0 is A.
Definition alicat_basis2.hpp:63
uint32_t found
One bit per unit ID A to Z.
Definition alicat_basis2.hpp:64