Architecture¶
How the driver is built: a serial bus that owns the line, an instrument object on top of it, and a port you write. What happens in each layer when you read a flow.
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
- Modbus RTU framing, address and baud: Modbus-RTU; Communicating Via Modbus-RTU; Changing the Baud Rate, p. 18
All of them, with the driver API for each: Datasheet map.
Figure description and sources
Top to bottom, each arrow is a call. Your application calls one object, whose public calls are listed from the umbrella header in inc/. The core turns each call into register reads and writes and hands them to the port contract (the CRTP base in inc/*_interface.hpp), which forwards them, at compile time, to the hooks of the port class you write; your port moves the bytes on the bus. The notes on the right say which layers stay the same on every MCU and which one you write. A library without a port contract has only the first two layers.
Drawn from: inc/alicat_basis2.hpp public calls; inc/alicat_basis2_uart_interface.hpp UartInterface; figure module docs/diagrams/figures/driver-layers.py.
Layers¶
| Layer | Files | Owns |
|---|---|---|
| Instrument | inc/alicat_basis2.hpp, src/alicat_basis2.ipp |
Basis2<Port>: one instrument; the typed API, learning, verification, guarded commands, scans |
| Bus | inc/alicat_basis2_uart_interface.hpp, src/alicat_basis2_uart_interface.ipp |
Bus<Port>: one serial line, one transaction at a time, timing, quarantine, stray bytes |
| Codecs | inc/alicat_basis2_ascii.hpp, inc/alicat_basis2_modbus.hpp, inc/alicat_basis2_request.hpp |
Request factories, reply grammars, CRC-16, the independent wire validators |
| Types and registers | inc/alicat_basis2_types.hpp, inc/alicat_basis2_registers.hpp |
Error, Result, Config, Decimal, Frame, the Modbus register table |
| Port contract | inc/alicat_basis2_uart_interface.hpp |
The CRTP base and the UartPort concept |
| Platform port | Your class | The UART, the clock, optionally a delay, a baud switch and logging |
| Kconfig layer | inc/alicat_basis2_kconfig.hpp |
Optional: a Config from ESP-IDF menuconfig |
Bus knows the line, not the instrument; Basis2 knows the instrument, not the timing. Several Basis2 objects share
one Bus when instruments share a line, and the bus lets one transaction run at a time.
One call through the layers¶
Figure description and sources
Participants, left to right: Your code, Basis2, Bus and Your port. The steps run from top to bottom. Your code sends ReadFlow() to Basis2. Basis2 does ascii::Make(Poll) builds and checks the bytes itself. Basis2 sends Execute(request, timing) to Bus. A note over Bus says: wait t3.5 of silence. Bus sends FlushInput(), Write("A\r") to Your port. A note over Bus and Your port says: Repeat until a CR or the deadline. Bus sends Read(buffer) to Your port. A note over Bus and Your port says: End of the repeated steps. Your port returns "A +012.30 +024.8 ... Air\r" to Bus. Bus returns Reply to Basis2. A note over Basis2 says: strict grammar, unit ID, range. Basis2 returns Result of Decimal to Your code.
Drawn from: docs/model/one-call-through-the-layers.seq.yml.
The transaction machine¶
A transaction is submitted, advanced by Poll() and taken. Execute() does the three steps and waits with DelayMs()
when the port has it, or spins on NowMs(). The states are Idle, Gap, AwaitReply and Settling.
- Gap. The line must have been silent for 3.5 character times (
35 / baudseconds at ten bits per character, at least 1 ms) since the last byte in either direction. The instrument acts on a command only after its own 3.5 character idle time following the carriage return (manual p. 10). - Send.
FlushInput(), thenWrite(). AfalsefromWrite()isError::Busand nothing is pending. - Await. Each
Poll()reads what has arrived and appends it to a 256-byte line buffer until a carriage return or the deadline: 3.5 character times plus the line time of the longest reply plusprocessing_ms, orslow_command_msfor the commands that may write non-volatile memory. - Settle. After a timeout, an overflow, a bad line or a wrong-ID reply the bus holds for at least one reply-wait and then until the line has been quiet for 3.5 character times plus 2 ms, with a hard deadline of two reply-waits. No command is sent until then, so a late reply of the failed command cannot be taken for the answer of the next one. A command with a known busy period (tare, factory restore, a timed valve hold) holds the bus for that period.
- Stray bytes. While no transaction waits, bytes that arrive are drained and counted
(
StrayLineCount()); a line that begins with@setsStreamingSuspected(). They are never used as an answer.
Retries apply to reads only. Over ASCII a read retries after bus-level failures (timeout, overflow); over Modbus it also retries a frame with a bad CRC, a wrong address or a malformed reply. A write, a guarded command or anything with a side effect is sent once.
Request, codec and validator¶
A Request has no public constructor. It is made only by ascii::Make() or the modbus::Build*() functions, which
check every argument and produce the wire bytes in one place. ascii::IsLegalRequest() and
modbus::IsLegalModbusRequest() are separate validators written as small automata over the grammar; Bus::Submit()
runs the validator on every request again and counts a refusal in WireViolations(), which must stay 0. A bug in a
builder therefore cannot put an unlisted command on the wire.
Design choices¶
- CRTP, not virtual functions. The port is a template parameter constrained by the
UartPortconcept, so every call is resolved at compile time and a missing hook is a compile error that names it. - Optional hooks by named concepts.
DelayMs,SetBaudandLogare detected byDeclares*andHas*concepts in one place. A hook that is declared with the wrong signature fails astatic_assert; a missingSetBaud()makesChangeBaud()returnUnsupported; a missingLog()logs nothing. - No I/O in the constructor. Construction cannot fail, so the driver can be a static.
- One error type.
Result<T>carries a value and anError; a failed call returns a zero-valued result. - No heap, no exceptions, no RTTI, no
std::function, noprintf. Fixed buffers, no mutable static state.
Source map¶
| You want | Read |
|---|---|
| The public API | inc/alicat_basis2.hpp |
| How a call is implemented | src/alicat_basis2.ipp |
| The transaction machine | src/alicat_basis2_uart_interface.ipp |
| ASCII commands and grammar | inc/alicat_basis2_ascii.hpp |
| Modbus registers and framing | inc/alicat_basis2_registers.hpp, inc/alicat_basis2_modbus.hpp |
Next: Contract.