Quickstart¶
Run the driver on your PC first, with no hardware; then read the flow from your MCU: wire the instrument, write a small port class, call three driver functions.
Datasheet sections this page relies on
From Alicat Scientific, Inc. DOC-MANUAL-BASIS2 Rev 4:
- Models, ranges and options: Introduction, p. 3
- Connector pins and serial levels: Power and Signal Connections (pin table), p. 7
All of them, with the driver API for each: Datasheet map.
Try it on your PC¶
examples/host/ runs the real driver against a simulated instrument, through a host
port. From the repository root, with CMake and a C++20 compiler:
cmake -S examples/host -B build-example
cmake --build build-example
./build-example/alicat_basis2_host_example
The program runs five short scenarios (read the flow, ramp a controller, tare and totalize, scan the line, read over
Modbus) and exits with 0 when every call succeeded. The calls in main.cpp are the ones
below; only the port differs on an MCU. CI builds and runs this example on every pull request.
1. Wire it¶
| MCU | Instrument connector | Notes |
|---|---|---|
| UART TX | pin 5 (RX or B) | 38400 baud, 8N1; RS-232 or RS-485 levels by model, so a level shifter or a transceiver |
| UART RX | pin 6 (TX or A) | |
| 12 to 24 V supply | pin 4 | Power on pin 4 only. Any other pin can damage the instrument |
| Ground | pin 3 | One common ground |
The Hardware page has the connector, both circuits and the warnings. Connect every pin before you switch on the supply.
2. Add the driver¶
Add the repository as a submodule and link the alicat_basis2::alicat_basis2 CMake target. Installation
covers CMake on any MCU, the installed package and ESP-IDF.
git submodule add https://github.com/kokeb-labs-drivers/driver-alicat-basis2.git external/driver-alicat-basis2
3. Write the port¶
The port is the only platform code: it brings the UART up, moves bytes and tells the time. Replace the platform_*
calls with your SDK's.
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;
};
Porting explains each method, the optional hooks and the rules for RS-485.
4. Read the flow¶
#include "alicat_basis2.hpp"
int read_flow(MyPort& port, double& flow) {
alicat_basis2::Bus<MyPort> bus(port);
alicat_basis2::Basis2<MyPort> meter(bus); // unit ID 'A', 38400 baud, ASCII: the factory settings
if (auto r = meter.EnsureInitialized(); !r) { // 1. the port comes up; no traffic yet
return static_cast<int>(r.error);
}
if (auto r = meter.Begin();
!r) { // 2. learn the instrument: Timeout means check wiring and unit ID
return static_cast<int>(r.error);
}
const auto f = meter.ReadFlow(); // 3. one poll
if (!f) {
return static_cast<int>(f.error);
}
flow = f.value.ToDouble(); // in the instrument's flow unit
return 0;
}
What each step does:
EnsureInitialized()calls your port'sEnsureInitialized(). No traffic yet.Begin()learns the instrument: its kind (meter or controller), firmware, full scale, flow unit, gas and setpoint source. It sends read commands only.ReadFlow()sends one poll and returns the flow as aDecimalin the instrument's flow unit.
The factory settings are unit ID A, 38400 baud, ASCII protocol. For another unit ID or for Modbus, change
Config. This example is built by the host CI, so it compiles against the current headers.
If it does not work¶
| Symptom | First thing to check |
|---|---|
EnsureInitialized() returns Bus |
Your port's EnsureInitialized(): the UART did not come up |
Begin() returns Timeout |
Wiring, A and B swapped (RS-485), baud rate and unit ID (Troubleshooting) |
Begin() returns DeviceIdMismatch |
Another instrument answered: two instruments with one ID |
Begin() returns InvalidArgument |
In Modbus mode modbus_flow_decimals is required: set it (Configuration) |
Next¶
- API guide: setpoints, scanning, recovery, errors.
- Protocols: ASCII and Modbus RTU side by side.
- Configuration: every
Configfield and Kconfig. - Examples: the host example and the ESP32 examples.