Skip to content

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
/// 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;
}
Ramp a controller and leave it safe
/// 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 and totalize
/// 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");
}
Scan the line
/// 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 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