Contract¶
What the BASIS 2 driver promises, what it needs, and the rules a caller follows.
The driver inherits the Kokeb Labs driver contract; this page states only what is specific to it. A change to anything here is a breaking change, listed under Breaking in the changelog.
Datasheet sections this page relies on
From Alicat Scientific, Inc. DOC-MANUAL-BASIS2 Rev 4:
- Default serial settings and the link layer: Alicat ASCII Serial Communication, Establishing Communication, p. 10
All of them, with the driver API for each: Datasheet map.
Promises¶
- The constructors of
BusandBasis2arenoexcept, store their arguments, do no I/O and cannot fail. EnsureInitialized()brings the port up and checks the stored configuration (InvalidArgument, nothing sent).Begin()is the first call that sends: it learns the instrument with read commands only. On any failure the object stays not ready and the next call starts again from the beginning.- Every call that sends returns
Error::NotInitializedbeforeEnsureInitialized()andBegin()have succeeded where the call needs them. No call starts the instrument as a side effect. - Nothing is ever sent outside the documented grammar. A
Requestcan be made only by the factories, and every request is checked a second time by an independent validator beforeWrite()(invariant I1). - No command is sent while a transaction waits, or inside the quarantine that follows a failed one, or less than 3.5 character times after the last byte on the line (I3, I4).
- The six commands that can strand an instrument are sent only for a call with its confirmation token (I5).
- A setpoint is never negative or above 102.5 % of the full scale, a valve hold never leaves 0 to 100 percent, and a
saved setpoint is never changed faster than
Config::saved_setpoint_min_interval_ms(I6). - A failed call returns a zero-valued result: no value from a failed or partial reply is exposed (I8). A reply is used only when its first token is the unit ID addressed; a Modbus reply only when address, function and CRC match.
- Writes are never repeated. Reads are repeated at most
Config::read_retriestimes. - Every wait is bounded by a deadline computed from the baud rate and
Config;Poll()always reaches a result or a terminal state within its deadlines: one line wait for a quiet line (elseBusy, nothing sent, and a quarantine that needs only the quiet line), one reply wait for the reply, then the quarantine (I9).Execute()bounds both of its waits in time as well. The 32-bit millisecond clock may wrap and the line may stay quiet for weeks: every wait is a start time and a duration, compared as an unsigned elapsed time, so no wait depends on where the clock is (I11). A wait that is not polled for 2^32 ms (49.7 days) may be read as just begun and last its length once more; for the same reason a saved setpoint made exactly a multiple of 2^32 ms after the last one may be refused asRateLimitedfor up tosaved_setpoint_min_interval_ms(the safe direction). StateUnknownis left only by a successfulRecover()(I12), which needs a validated reply from the same instrument (serial number, firmware and kind unchanged). Only a switch-off (SetSetpoint(0),CloseValve()) is still sent while it holds.- A missing optional hook is not an error: no
DelayMs()spins onNowMs(), noSetBaud()makesChangeBaud()returnUnsupported, noLog()logs nothing. A hook declared with the wrong signature is a compile error.
The fuzz targets check I1, I3 and I5 to I16 after every call (I11 through the clock offsets and the long quiet periods of their sessions); I2 and I4 are proven by directed unit tests, and I9 and I11 by both (Testing and CI).
Depends on¶
| Dependency | Version | Why |
|---|---|---|
| A C++20 compiler | GCC 10, Clang 13 or later | Concepts constrain the port |
| CMake | 3.16 or later | Generates alicat_basis2_version.h |
| Your port | A serial line at 38400 baud 8N1 or what you configure, a millisecond clock, and for RS-485 the direction control inside Write() |
Nothing else: no RTOS, no SDK, no other repository of the organisation.
Threading¶
The driver is not thread-safe and takes no lock. Use each Bus and every Basis2 on it from one task at a time, or
guard every call with one mutex; the layer that owns the driver owns that lock. Nothing may run in an ISR. Separate
buses share no state.
Errors¶
alicat_basis2::Error inside alicat_basis2::Result<T>. Values 0 to 9 are the shared base set; values from 16 are
specific to this driver, and each is returned by some call (a test checks it).
Error |
Value | Returned when |
|---|---|---|
Ok |
0 | The call succeeded |
NotInitialized |
1 | EnsureInitialized() or Begin() has not succeeded |
InvalidArgument |
2 | An argument or a Config field is out of range; nothing was sent |
Bus |
3 | A port hook returned false |
Timeout |
4 | No complete reply within the computed time |
DeviceIdMismatch |
5 | The reply carried another unit ID or address |
Crc |
6 | Modbus CRC-16 mismatch |
Busy |
7 | The bus was not free or the line never went quiet: the transaction that met it was not sent; a writing call returns it only when its write was not sent (Safety) |
DeviceFault |
8 | Reserved: the instrument reports faults as flags, which are data, not errors |
Unsupported |
9 | Not available on this protocol, this kind, or this port |
BadReply |
16 | The line does not match the command's reply grammar |
Rejected |
17 | The instrument answered ? or with a Modbus exception |
OutOfRange |
18 | A decoded value is outside what the instrument can report |
Overflow |
19 | The reply exceeded the line buffer without a terminator |
VerifyMismatch |
20 | The read-back after a setter differs |
FirmwareTooOld |
21 | The call needs a newer firmware |
StateUnknown |
22 | A guarded command is not settled |
RateLimited |
23 | A saved setpoint came too soon |
GuardNotConfirmed |
24 | A guarded call carried the wrong token |
The API guide says what to do about each.
Memory¶
No heap, no exceptions, no RTTI, no std::function, no std::string, no printf and no static mutable state. A Bus
holds a 256-byte line buffer and a request; a Basis2 holds a Config, an Identity and the shadow state.
Platform¶
Platform-free: the same code runs on any target with a C++20 compiler, including the host tests. The ESP-IDF port in
examples/esp32 is an example, not part of the driver.
Deviations from the standard¶
- The port's
Read()is partial. It returns the number of bytes read (std::size_t), not an exact-lengthbool, because the reply length of an ASCII line is not known in advance. Documented in Porting. - The line buffer is 256 bytes, not 128, because the gas list (
GS *) reply can be that long. - The scans block.
ScanUnitIds()andScanModbusAddresses()run to the end of the scan inside one call; every other call is bounded by one reply wait. DeviceFaultis never returned. It stays in the base set, so the numeric values match the other drivers.