BASIS 2 Driver 0.1.0
API reference
Loading...
Searching...
No Matches
alicat_basis2_uart_interface.hpp
Go to the documentation of this file.
1// clang-format off: the table below must keep one row per line.
24// clang-format on
25#ifndef ALICAT_BASIS2_UART_INTERFACE_HPP
26#define ALICAT_BASIS2_UART_INTERFACE_HPP
27
28#include <array>
29#include <concepts>
30#include <cstddef>
31#include <cstdint>
32#include <span>
33
39
40namespace alicat_basis2 {
41
50inline constexpr uint32_t kPortDefaultBaud = 38'400;
52inline constexpr uint32_t kMinBaudRate = 4'800;
54inline constexpr uint32_t kMaxBaudRate = 115'200;
57inline constexpr uint32_t kSilentBitTimes = 35;
60inline constexpr uint32_t kTurnaroundUs = 50'000;
62inline constexpr uint32_t kSupplyMinMv = 12'000;
64inline constexpr uint32_t kSupplyMaxMv = 24'000;
76template <typename Derived>
78public:
80 UartInterface(const UartInterface&) = delete;
83
84protected:
86 UartInterface() noexcept = default;
88 ~UartInterface() noexcept = default;
89};
90
96template <typename Port>
97concept UartPort = std::derived_from<Port, UartInterface<Port>> && requires {
98 detail::ExactHook<Port, bool() noexcept>::Take(&Port::EnsureInitialized);
99 detail::ExactHook<Port, bool(const uint8_t*, std::size_t) noexcept>::Take(&Port::Write);
100 detail::ExactHook<Port, std::size_t(uint8_t*, std::size_t, uint32_t) noexcept>::Take(&Port::Read);
101 detail::ExactHook<Port, bool() noexcept>::Take(&Port::FlushInput);
102 detail::ExactHook<Port, uint32_t() noexcept>::Take(&Port::NowMs);
103};
104
105namespace detail {
106
108template <typename Port>
109concept DeclaresDelayMs = requires(Port& port) { port.DelayMs(std::uint32_t{1U}); };
111template <typename Port>
112concept HasDelayMs = requires { ExactHook<Port, void(uint32_t) noexcept>::Take(&Port::DelayMs); };
114template <typename Port>
115concept DeclaresSetBaud = requires(Port& port) { port.SetBaud(std::uint32_t{1U}); };
117template <typename Port>
118concept HasSetBaud = requires { ExactHook<Port, bool(uint32_t) noexcept>::Take(&Port::SetBaud); };
120template <typename Port>
121concept DeclaresLog = requires(Port& port) { port.Log(LogLevel::Info, ""); };
123template <typename Port>
124concept HasLog =
125 requires { ExactHook<Port, void(LogLevel, const char*) noexcept>::Take(&Port::Log); };
126
127} // namespace detail
128
130struct Timing {
131 uint32_t baud{38400};
132 uint16_t processing_ms{50};
133 uint16_t slow_ms{1000};
134 EchoMode echo{EchoMode::None};
137 uint32_t switch_to_baud{0};
138};
139
141enum class PollState : uint8_t {
142 Idle = 0,
143 Pending = 1,
144 Done = 2,
145 Failed = 3,
146};
147
149enum class BusState : uint8_t {
150 Idle = 0,
151 Gap = 1,
152 AwaitReply = 2,
153 Settling = 3,
154};
155
168template <UartPort Port>
169class Bus {
170 static_assert(!detail::DeclaresDelayMs<Port> || detail::HasDelayMs<Port>,
171 "alicat_basis2: the DelayMs hook must be `void DelayMs(uint32_t ms) noexcept`");
172 static_assert(!detail::DeclaresSetBaud<Port> || detail::HasSetBaud<Port>,
173 "alicat_basis2: the SetBaud hook must be `bool SetBaud(uint32_t baud) noexcept`");
174 static_assert(
175 !detail::DeclaresLog<Port> || detail::HasLog<Port>,
176 "alicat_basis2: the Log hook must be `void Log(LogLevel, const char* message) noexcept`");
177
178public:
180 explicit Bus(Port& port) noexcept : port_(port) {}
182 Bus(const Bus&) = delete;
184 Bus& operator=(const Bus&) = delete;
185
187 Port& GetPort() & noexcept {
188 return port_;
189 }
190
192 [[nodiscard]] static constexpr bool CanSetBaud() noexcept {
193 return detail::HasSetBaud<Port>;
194 }
195
201 Result<void> ApplyBaud(uint32_t baud) noexcept;
202
211 Error Submit(const Request& request, const Timing& timing) noexcept;
212
214 PollState Poll() noexcept;
215
217 Result<Reply> Take() noexcept;
218
220 void Abort() noexcept;
221
224 void EnterQuarantine() noexcept;
225
236 Result<Reply> Execute(const Request& request, const Timing& timing) noexcept;
237
245 [[nodiscard]] uint32_t WaitBoundMs() const noexcept {
246 return busyBoundMs();
247 }
248
250 [[nodiscard]] uint32_t StrayLineCount() const noexcept {
251 return stray_lines_;
252 }
254 [[nodiscard]] bool StreamingSuspected() const noexcept {
255 return streaming_;
256 }
258 [[nodiscard]] uint32_t WireViolations() const noexcept {
259 return wire_violations_;
260 }
262 [[nodiscard]] BusState State() const noexcept {
263 return state_;
264 }
266 [[nodiscard]] uint8_t DeviceCount() const noexcept {
267 return device_count_;
268 }
271 void SetDeviceCount(uint8_t count) noexcept {
272 device_count_ = count;
273 }
274
275private:
276 void log(LogLevel level, const char* message) noexcept;
277 void sleep(uint32_t ms) noexcept;
278 void send(uint32_t now) noexcept;
279 void pollReply(uint32_t now) noexcept;
280 void feedAscii(uint8_t byte, uint32_t now) noexcept;
281 void feedModbus(uint8_t byte) noexcept;
282 void finishLine() noexcept;
283 void complete(Error error, bool quarantine, uint32_t now) noexcept;
284 void startQuarantine(uint32_t now) noexcept;
285 void settle(uint32_t now) noexcept;
286 void drainStray(uint32_t now) noexcept;
287 void strayByte(uint8_t byte) noexcept;
288 std::size_t readChunk(uint32_t now) noexcept;
289 [[nodiscard]] uint32_t gapMs() const noexcept;
290 [[nodiscard]] uint32_t replyMs() const noexcept;
291 [[nodiscard]] uint32_t lineWaitMs() const noexcept;
292 [[nodiscard]] uint32_t busyBoundMs() const noexcept;
293 void dropUntaken() noexcept;
294 [[nodiscard]] PollState pollState() const noexcept;
295
296 Port& port_;
297 BusState state_{BusState::Idle};
298 Timing timing_{};
299 Request request_;
300 std::array<uint8_t, 32> chunk_{};
301 std::array<char, kMaxLine + 1U> line_{};
302 std::size_t line_len_{0};
303 Reply reply_{};
304 Error result_{Error::Ok};
305 bool result_ready_{false};
306 bool echo_pending_{false};
307 bool have_activity_{false};
308 bool quarantine_{false};
309 bool streaming_{false};
310 uint32_t last_activity_ms_{0};
311 // Each wait is a start time and a duration, compared as an unsigned elapsed time (wrap-safe).
312 uint32_t gap_start_ms_{0};
313 uint32_t gap_limit_ms_{0};
314 bool on_wire_{false};
315 uint32_t sent_ms_{0};
316 uint32_t holdoff_ms_{0};
317 bool has_holdoff_{false};
318 uint32_t settle_start_ms_{0};
319 uint32_t settle_ms_{0};
320 uint32_t quiet_min_ms_{0};
321 uint32_t stray_lines_{0};
322 uint32_t wire_violations_{0};
323 uint32_t reply_wait_ms_{0};
324 std::size_t stray_len_{0};
325 char stray_first_{'\0'};
326 uint8_t device_count_{1};
327};
328
329} // namespace alicat_basis2
330
331// codeql::misra_deviation_next_line(MD-CPP-009)
332#include "../src/alicat_basis2_uart_interface.ipp"
333
334#endif // ALICAT_BASIS2_UART_INTERFACE_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...
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 transaction machine of one serial line, shared by every instrument on it.
Definition alicat_basis2_uart_interface.hpp:169
PollState Poll() noexcept
Advance the machine without blocking.
Bus & operator=(const Bus &)=delete
One bus per serial line.
Port & GetPort() &noexcept
Definition alicat_basis2_uart_interface.hpp:187
Error Submit(const Request &request, const Timing &timing) noexcept
Start a transaction.
Bus(Port &port) noexcept
Bind to a port; no I/O.
Definition alicat_basis2_uart_interface.hpp:180
uint8_t DeviceCount() const noexcept
Definition alicat_basis2_uart_interface.hpp:266
static constexpr bool CanSetBaud() noexcept
Definition alicat_basis2_uart_interface.hpp:192
void SetDeviceCount(uint8_t count) noexcept
Definition alicat_basis2_uart_interface.hpp:271
Result< void > ApplyBaud(uint32_t baud) noexcept
Change the port's speed through the optional hook.
BusState State() const noexcept
Definition alicat_basis2_uart_interface.hpp:262
uint32_t StrayLineCount() const noexcept
Definition alicat_basis2_uart_interface.hpp:250
uint32_t WireViolations() const noexcept
Definition alicat_basis2_uart_interface.hpp:258
Bus(const Bus &)=delete
One bus per serial line.
bool StreamingSuspected() const noexcept
Definition alicat_basis2_uart_interface.hpp:254
One validated request. Only the factories of the grammar headers make one that can be sent.
Definition alicat_basis2_request.hpp:115
CRTP base of the platform serial port.
Definition alicat_basis2_uart_interface.hpp:77
UartInterface & operator=(const UartInterface &)=delete
Ports are not copied: the bus holds a reference.
UartInterface() noexcept=default
Only the derived port is constructed.
UartInterface(const UartInterface &)=delete
Ports are not copied: the bus holds a reference.
Satisfied by a class that derives from UartInterface<Port> and implements the five required hooks wit...
Definition alicat_basis2_uart_interface.hpp:97
Error
Why a call failed. Every call of the driver returns one of these in its Result.
Definition alicat_basis2_types.hpp:37
LogLevel
Severity passed to the optional Log() hook.
Definition alicat_basis2_types.hpp:213
EchoMode
Whether a half-duplex wiring that hears its own transmission is handled.
Definition alicat_basis2_types.hpp:248
The ALICAT_BASIS2 driver: everything it declares lives here; internals in detail.
Definition alicat_basis2.hpp:39
constexpr uint32_t kPortDefaultBaud
The baud rate after a factory restore, 8 data bits, no parity, 1 stop bit (M p.10).
Definition alicat_basis2_uart_interface.hpp:50
constexpr uint32_t kSupplyMaxMv
Highest supply, millivolts (M p.6).
Definition alicat_basis2_uart_interface.hpp:64
BusState
Internal phase of the bus.
Definition alicat_basis2_uart_interface.hpp:149
@ Gap
Waiting out the idle time before a send.
@ Settling
After a transaction: hold-off or quarantine drain.
@ AwaitReply
Accumulating the reply.
constexpr uint32_t kSilentBitTimes
Definition alicat_basis2_uart_interface.hpp:57
constexpr uint32_t kSupplyMinMv
Lowest supply, millivolts, on pin 4 only (M p.6).
Definition alicat_basis2_uart_interface.hpp:62
constexpr uint32_t kTurnaroundUs
Definition alicat_basis2_uart_interface.hpp:60
PollState
State of a transaction as seen by Bus::Poll().
Definition alicat_basis2_uart_interface.hpp:141
@ Pending
Waiting for the gap, or for the reply.
@ Failed
The transaction failed: Take() returns the error.
@ Idle
Nothing pending and no result waiting.
@ Done
The result is ready: Take() returns the reply.
constexpr uint32_t kMaxBaudRate
The highest baud rate the instrument offers, firmware 2.2.2 or later (M p.17).
Definition alicat_basis2_uart_interface.hpp:54
constexpr uint32_t kMinBaudRate
The lowest baud rate the instrument offers (M p.17).
Definition alicat_basis2_uart_interface.hpp:52
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
What the bus needs to know about the instrument it talks to, per transaction.
Definition alicat_basis2_uart_interface.hpp:130