Examples¶
One folder per platform under examples/, each with its own port, built by CI on every pull request. The driver
itself has no platform code; Platforms lists what exists.
Host¶
examples/host/ runs the driver on any PC against a simulated BASIS 2 instrument,
through the host port host_alicat_basis2_port.hpp. No hardware:
cmake -S examples/host -B build-example && cmake --build build-example && ./build-example/alicat_basis2_host_example
It runs five scenarios, each a snippet below: read the flow ten times, ramp a controller with the unsaved source and
close the valve, tare and totalize, scan the line for unit IDs, and read over Modbus RTU. The host tests build it with
warnings as errors and run it (CTest alicat_basis2_host_example).
/// Read the flow, temperature, total and flags ten times, the way a logger at 10 Hz would.
bool ReadFlow() {
model::Instrument chip;
chip.flow_milli = 123400;
HostPort port(chip);
alicat_basis2::Bus<HostPort> bus(port);
alicat_basis2::Basis2<HostPort> meter(
bus); // 'A', 38400 baud, ASCII protocol: the factory settings
if (!Ok(meter.EnsureInitialized(), "EnsureInitialized") || !Ok(meter.Begin(), "Begin")) {
return false;
}
for (int i = 0; i < 10; ++i) {
const auto frame = meter.ReadFrame();
if (!Ok(frame, "ReadFrame")) {
return false;
}
static_cast<void>(
std::printf("%.1f %s, %.2f C, total %.1f, gas %s%s\n", frame.value.flow.ToDouble(),
meter.GetIdentity().unit_label.chars.data(), frame.value.temperature.ToDouble(),
frame.value.total.ToDouble(), frame.value.gas_name.data(),
frame.value.status.mass_flow_over ? " [MOV]" : ""));
port.DelayMs(100);
}
return true;
}
/// Step a controller through a ramp with the unsaved setpoint source, hold the valve, and close it
/// on exit.
bool ControllerRamp() {
model::Instrument chip;
HostPort port(chip);
alicat_basis2::Bus<HostPort> bus(port);
alicat_basis2::Basis2<HostPort> controller(bus);
if (!Ok(controller.EnsureInitialized(), "EnsureInitialized") ||
!Ok(controller.Begin(), "Begin")) {
return false;
}
// The unsaved source never wears the non-volatile memory; use it for anything that changes often.
bool ok = Ok(controller.SetSetpointSource(alicat_basis2::SetpointSource::UnsavedDigital),
"SetSetpointSource");
ok = ok && Ok(controller.SetRamp(50.0, alicat_basis2::TimeUnit::Second), "SetRamp");
for (const double target : {100.0, 250.0, 100.0}) {
ok = ok && Ok(controller.SetSetpoint(target), "SetSetpoint");
}
ok = ok && Ok(controller.HoldValve(40.0), "HoldValve") &&
Ok(controller.ResumeControl(), "ResumeControl");
// Leave the instrument safe: no flow, no ramp.
ok = ok && Ok(controller.DisableRamp(), "DisableRamp") &&
Ok(controller.SetSetpoint(0.0), "SetSetpoint");
return ok && Ok(controller.CloseValve(), "CloseValve");
}
/// Tare on zero flow, reset the totalizer, set a batch.
bool TareAndTotal() {
model::Instrument chip;
HostPort port(chip);
alicat_basis2::Bus<HostPort> bus(port);
alicat_basis2::Basis2<HostPort> controller(bus);
if (!Ok(controller.EnsureInitialized(), "EnsureInitialized") ||
!Ok(controller.Begin(), "Begin")) {
return false;
}
// Only tare with no flow through the instrument: it takes the present reading as zero (M p.15).
bool ok = Ok(controller.Tare(1000), "Tare") && Ok(controller.ResetTotal(), "ResetTotal");
ok = ok && Ok(controller.SetTotalizerLimit(alicat_basis2::TotalizerLimit::HoldWithError),
"SetTotalizerLimit");
return ok && Ok(controller.SetBatch(25.0), "SetBatch") &&
Ok(controller.ReadBatchRemaining(), "ReadBatchRemaining");
}
/// Find the instruments on a line: 26 polls, one per unit ID. This call blocks for the whole scan.
bool ScanBus() {
model::Instrument chip;
chip.unit_id = 'F';
HostPort port(chip);
alicat_basis2::Bus<HostPort> bus(port);
alicat_basis2::Config config;
config.unit_id = 'F';
alicat_basis2::Basis2<HostPort> meter(bus, config);
if (!Ok(meter.EnsureInitialized(), "EnsureInitialized") || !Ok(meter.Begin(), "Begin")) {
return false;
}
const auto scan = meter.ScanUnitIds();
if (!Ok(scan, "ScanUnitIds")) {
return false;
}
for (uint32_t i = 0U; i < static_cast<uint32_t>(kUnitIds.size()); ++i) {
const char id = kUnitIds[i]; // bit i of `found` is the i-th unit ID, A to Z
if ((scan.value.found & (1U << i)) != 0U) {
static_cast<void>(std::printf("instrument with unit ID %c\n", id));
}
}
return scan.value.found == (1U << static_cast<uint32_t>(kUnitIds.find('F')));
}
/// The same readout over Modbus RTU. The factory flow decimals are not readable over Modbus: say
/// them here.
bool ModbusReadout() {
model::Instrument chip;
chip.flow_milli = 12300;
HostPort port(chip);
alicat_basis2::Bus<HostPort> bus(port);
alicat_basis2::Config config;
config.protocol = alicat_basis2::Protocol::ModbusRtu;
config.modbus_address = 1;
config.modbus_flow_decimals = 1; // required: there is no default
alicat_basis2::Basis2<HostPort> meter(bus, config);
if (!Ok(meter.EnsureInitialized(), "EnsureInitialized") || !Ok(meter.Begin(), "Begin")) {
return false;
}
const auto flow = meter.ReadFlow();
if (!Ok(flow, "ReadFlow")) {
return false;
}
static_cast<void>(std::printf("Modbus: %.1f, full scale %.1f\n", flow.value.ToDouble(),
meter.GetIdentity().full_scale.ToDouble()));
return flow.value.ToMilli() == 12300;
}
ESP32¶
ESP-IDF applications that run the driver on an ESP32-C6, with pins chosen in menuconfig; the wiring is in the
example folder's README and the port in
esp32_alicat_basis2_port.hpp. The project points
EXTRA_COMPONENT_DIRS at the repository root, which is the driver's ESP-IDF component.
The apps¶
| App | What it shows | Source | CI |
|---|---|---|---|
alicat_basis2_minimal_example |
One instrument at its factory settings on UART1 at 38400 baud: poll the flow once a second | alicat_basis2_minimal_example.cpp |
yes |
alicat_basis2_full_example |
RS-485 half duplex: scan the line, identify, set a setpoint on the unsaved source, measure, map the flags | alicat_basis2_full_example.cpp |
yes |
Build and flash one (from examples/esp32, ESP-IDF environment loaded):
./scripts/build_app.sh alicat_basis2_minimal_example Release
./scripts/flash_app.sh flash_monitor alicat_basis2_minimal_example Release
Source of this table: examples/esp32/app_config.yml.
Set up once¶
git submodule update --init examples/esp32/scripts # the ESP-IDF build scripts
cd examples/esp32
. $IDF_PATH/export.sh # ESP-IDF v5.5
./scripts/build_app.sh list # every app and build type
The scripts read app_config.yml (the same file this page's table comes
from) and build each app as its own firmware image.
What to read in an example¶
| You want to | Read |
|---|---|
See the lifecycle and every Result checked |
alicat_basis2_minimal_example.cpp |
| See a scan, a setpoint on the unsaved source and a measurement window | alicat_basis2_full_example.cpp |
| Write an ESP-IDF port, with RS-485 half duplex | esp32_alicat_basis2_port.hpp |
| Choose the pins and the unit ID | main/Kconfig.projbuild |
| Use the driver's menuconfig values | alicat_basis2_kconfig.hpp and _config/Kconfig |