Porting¶
Run the driver on a new MCU by writing one class: the port.
Datasheet sections this page relies on
From Alicat Scientific, Inc. DOC-MANUAL-BASIS2 Rev 4:
- Connector pins and serial levels: Power and Signal Connections (pin table), p. 7
All of them, with the driver API for each: Datasheet map.
The driver never calls your SDK. It calls hooks on a class you derive from alicat_basis2::UartInterface<Self> (in
inc/alicat_basis2_uart_interface.hpp). The base uses CRTP and declares no
hook itself; the driver template is constrained by the alicat_basis2::UartPort concept, so calls are resolved at
compile time (no virtual functions, nothing to allocate) and a missing or misdeclared hook is a compile error at the
point of use.
What you implement¶
| Method | Required | Contract |
|---|---|---|
bool EnsureInitialized() noexcept |
yes | Bring the UART up on the first call; return true at once afterwards |
bool Write(const uint8_t* data, std::size_t len) noexcept |
yes | Send all len bytes; return after the last byte has left the pin |
std::size_t Read(uint8_t* data, std::size_t capacity, uint32_t timeout_ms) noexcept |
yes | Return the bytes that have arrived, up to capacity; do not wait for more |
bool FlushInput() noexcept |
yes | Drop every received byte not read yet |
uint32_t NowMs() noexcept |
yes | A monotonic millisecond clock; it may wrap |
void DelayMs(uint32_t ms) noexcept |
no | Sleep at least ms; without it blocking calls poll NowMs() |
bool SetBaud(uint32_t baud) noexcept |
no | Change the line speed; needed only by ChangeBaud() |
void Log(LogLevel, const char* message) noexcept |
no | Print one line; message is plain text, never a format string |
The port¶
class MyPort : public alicat_basis2::UartInterface<MyPort> {
public:
// Bring the UART up once; later calls return true at once.
bool EnsureInitialized() noexcept {
if (!ready_) {
ready_ = platform_uart_init();
}
return ready_;
}
bool Write(const uint8_t* data, std::size_t len) noexcept {
return platform_uart_write(data, len);
}
// Whatever has arrived, up to `capacity` bytes. The driver polls, so do not wait for a full
// frame.
std::size_t Read(uint8_t* data, std::size_t capacity, uint32_t timeout_ms) noexcept {
static_cast<void>(timeout_ms);
return platform_uart_read(data, capacity);
}
// Drop stale bytes before each request.
bool FlushInput() noexcept {
return platform_uart_flush_input();
}
// The driver times every wait against this clock.
uint32_t NowMs() noexcept {
return platform_millis();
}
private:
bool ready_ = false;
};
Rules the port must follow:
- Raw bytes only. The driver builds the lines and frames and checks them; the port does not parse, frame or retry.
Read()is partial and does not wait. It returns what has arrived. The driver polls, keeps its own time and applies its own deadlines. (This differs from the template's exact-lengthRead(): the length of an ASCII line is not known in advance.)timeout_msis advisory.Write()returns after the last byte has left the pin. The driver times the silent interval from the end of yourWrite(), and an RS-485 direction pin must not be released early.FlushInput()really flushes: the driver calls it before each request so a stale byte cannot shift a reply.- 8N1, no flow control, at the speed in
Config::baud.
Bus requirements¶
The driver states what the instrument needs from the line as constexpr values in
inc/alicat_basis2_uart_interface.hpp (handbook KB-CPP-123). Check your port
settings against them with static_assert, as both example ports do:
| Constant | Value | Meaning |
|---|---|---|
kPortDefaultBaud |
38400 | The factory baud rate, 8N1 (manual p. 10) |
kMinBaudRate, kMaxBaudRate |
4800, 115200 | The rates the instrument offers (p. 17) |
kSilentBitTimes |
35 | The idle time before the instrument acts, 3.5 characters of ten bits (p. 10) |
kTurnaroundUs |
50000 | Added to every reply wait (an assumption) |
kSupplyMinMv, kSupplyMaxMv |
12000, 24000 | The supply on pin 4 only (p. 6) |
RS-485¶
An RS-485 instrument is half duplex on one pair, and the driver knows nothing about the direction pin: the port owns it. Two rules follow.
- Switch the transceiver to transmit before the first byte and back to receive after the last byte has left the
shift register, not after it has been copied to a FIFO. On ESP-IDF that is the RS-485 half-duplex mode with
uart_wait_tx_done(); on STM32 the hardware driver-enable or the transmission-complete interrupt; on LinuxTIOCSRS485. - A transceiver whose receiver stays enabled while it sends hears its own bytes. Set
Config::echotoEchoMode::Skipand the driver drops a first reply line that equals the command it just sent.
A termination of 120 ohm at both ends of a long line and a common ground are general practice; the manual does not describe them (Hardware).
Baud switching¶
ChangeBaud() sends the baud command and then calls your SetBaud() right after the send, because the instrument's
reply arrives at the new speed (manual p. 17). Without a SetBaud() hook the call returns Unsupported. On failure the
driver sets the old speed back once and the state is StateUnknown; call Recover() after you have checked the
port's speed.
Control pins¶
None. The instrument has no reset or enable pin on its connector, and the driver sets no pin. The port is the whole platform interface.
Optional hooks¶
class FullPort : public alicat_basis2::UartInterface<FullPort> {
public:
bool EnsureInitialized() noexcept {
return platform_uart_init();
}
bool Write(const uint8_t* data, std::size_t len) noexcept {
return platform_uart_write(data, len);
}
std::size_t Read(uint8_t* data, std::size_t capacity, uint32_t timeout_ms) noexcept {
static_cast<void>(timeout_ms);
return platform_uart_read(data, capacity);
}
bool FlushInput() noexcept {
return platform_uart_flush_input();
}
uint32_t NowMs() noexcept {
return platform_millis();
}
// Optional: lets blocking calls yield instead of spinning. Without it they poll the clock.
void DelayMs(uint32_t ms) noexcept {
platform_sleep_ms(ms);
}
// Optional: needed by ChangeBaud(), which changes the line speed after the instrument has
// switched.
bool SetBaud(uint32_t baud) noexcept {
return platform_uart_set_baud(baud);
}
// Optional: one line per lifecycle event or failure. The driver never formats; the port does.
void Log(alicat_basis2::LogLevel level, const char* message) noexcept {
if (level > alicat_basis2::LogLevel::Warning) {
return;
}
platform_log(message); // plain text: never use it as a format string
}
};
A hook that is declared with the wrong signature fails a static_assert that names it: a DelayMs that takes a
uint16_t, or a SetBaud that returns void, is a compile error rather than a silently ignored hook.
Non-blocking use¶
Basis2 calls Bus::Execute(), which blocks until the transaction is over (with DelayMs() when the port has it).
If your loop left a transaction on the bus, Execute() waits for it within its deadlines (reply wait, quarantine,
hold-off) and drops its result when nobody took it, so a switch-off is never held back by it.
Bus can also be driven from your own loop:
// The non-blocking form: submit once, call Poll() from your loop, take the reply when it is no
// longer Pending. Basis2 uses Bus::Execute(), which does exactly this and waits with DelayMs() or
// the clock.
alicat_basis2::Error StartPoll(alicat_basis2::Bus<FullPort>& bus) {
const auto request = alicat_basis2::ascii::Make(alicat_basis2::Command::Poll, 'A',
alicat_basis2::ascii::Args{}, false);
if (!request) {
return request.error;
}
return bus.Submit(request.value,
alicat_basis2::Timing{}); // Busy while another transaction is not over
}
bool Step(alicat_basis2::Bus<FullPort>& bus, alicat_basis2::Result<alicat_basis2::Reply>& out) {
const alicat_basis2::PollState state = bus.Poll();
if ((state == alicat_basis2::PollState::Done) || (state == alicat_basis2::PollState::Failed)) {
out = bus.Take();
return true;
}
return false;
}
Reference implementations¶
Every port lives with its example, in examples/<platform>/; the driver has none. Platforms lists
them and how to add one.
examples/host/host_alicat_basis2_port.hpp: any PC, against a simulated instrument. Start from it for a host build or a test bench.examples/esp32/main/esp32_alicat_basis2_port.hpp: ESP-IDF, with every hook and an RS-485 mode. Start from it for any ESP-IDF target.
Check your port¶
- Build it: the ports on this page are compiled by the host CI from
tests/docs/, with the driver instantiated over them. - Call
EnsureInitialized()andBegin():Okproves that writes and reads work and that the unit ID and baud rate are right. - Call
ReadFrame()once a second and open the valve of a flow source: the flow rises. - Unplug the instrument:
Timeout, and no stray output on the line afterwards.
Threads¶
The driver is not thread-safe. Give each driver object one owner task, or guard every call with one mutex. When several chips share a bus, the port must also serialise the bus. See Contract.
Editor setup¶
The clang-format and clang-tidy configuration is in _config/, and the repository root has no copy of it. Tools
that take a path use it directly; CI does the same:
| Tool | Setting |
|---|---|
| Command line | clang-format --style=file:_config/.clang-format, clang-tidy --config-file=_config/.clang-tidy -p build |
| VS Code (C/C++ extension) | "C_Cpp.clang_format_style": "file:${workspaceFolder}/_config/.clang-format" and "C_Cpp.codeAnalysis.clangTidy.args": ["--config-file=${workspaceFolder}/_config/.clang-tidy"] |
| clangd (VS Code clangd, Neovim, Emacs), CLion | These find .clang-format and .clang-tidy only by name, from the file upwards: copy both to the root once (cp _config/.clang-format _config/.clang-tidy .). .gitignore lists the copies, so they never reach a commit; copy again after _config/ changes |
Configure with -DCMAKE_EXPORT_COMPILE_COMMANDS=ON (clangd: --compile-commands-dir=build) so the editor sees the
same flags as the build.