alicat_basis2.hpp

Go to the documentation of this file.

 
#pragma once
 
#include "alicat_basis2_modbus.hpp"
#include "alicat_basis2_registers.hpp"
#include "alicat_basis2_types.hpp"
#include "alicat_basis2_uart_interface.hpp"
#include "alicat_basis2_version.h"
 
#include <array>
#include <cstdint>
#include <cstddef>
#include <cstring>
 
namespace alicat_basis2 {
 
inline const char* GetDriverVersion() noexcept {
    return HF_ALICAT_BASIS2_VERSION_STRING;
}
 
template <typename UartT>
class Driver {
public:
    Driver(UartT& uart, uint8_t address,
           uint16_t timeout_ms = kDefaultTimeoutMs) noexcept
        : uart_(uart), address_(address), timeout_ms_(timeout_ms) {}
 
    Driver(const Driver&) = delete;
    Driver& operator=(const Driver&) = delete;
 
    void SetTimeoutMs(uint16_t ms) noexcept { timeout_ms_ = ms; }
    uint16_t GetTimeoutMs() const noexcept  { return timeout_ms_; }
 
    void SetBusBaudRate(uint32_t bps) noexcept {
      bus_bps_ = bps;
    }
    uint32_t GetBusBaudRate() const noexcept {
      return bus_bps_;
    }
    uint32_t GetInterFrameGapUs() const noexcept {
      return modbus::InterFrameGapUs(bus_bps_);
    }
 
    void SetAddress(uint8_t addr) noexcept { address_ = addr; }
    uint8_t GetAddress() const noexcept    { return address_; }
 
    //==========================================================================
    // INSTANTANEOUS DATA — single Modbus burst
    //==========================================================================
 
    DriverResult<InstantaneousData> ReadInstantaneous(uint8_t flow_decimals = 3) noexcept {
        std::array<uint16_t, 10> regs{};
        const auto rc = ReadHoldingRegisters(reg::SelectedGas, regs.data(),
                                             static_cast<uint8_t>(regs.size()));
        if (rc != DriverError::None) return DriverResult<InstantaneousData>::failure(rc);
 
        InstantaneousData out{};
        out.gas = static_cast<Gas>(regs[0] & 0xFFU);
 
        const uint16_t status = regs[1];
        out.mass_flow_overrange      = (status & 0x0001U) != 0;
        out.temperature_overrange    = (status & 0x0002U) != 0;
        out.totalizer_overrange      = (status & 0x0004U) != 0;
        out.valve_held               = (status & 0x0008U) != 0;
        out.valve_thermal_management = (status & 0x0010U) != 0;
 
        out.raw_temp_2102 = static_cast<int16_t>(regs[2]);
        out.temperature_c = static_cast<float>(out.raw_temp_2102) * 0.01f;
 
        out.raw_flow_2103 = static_cast<int16_t>(regs[3]);
        out.flow = ScaleFlow(out.raw_flow_2103, flow_decimals);
 
        out.raw_total_volume_2104_2105 =
            (static_cast<uint32_t>(regs[4]) << 16) | regs[5];
        out.total_volume = ScaleFlow(static_cast<int32_t>(out.raw_total_volume_2104_2105),
                                     flow_decimals);
 
        out.raw_setpoint_2053_2054 = static_cast<int16_t>(regs[6]);
        out.setpoint = ScaleFlow(out.raw_setpoint_2053_2054, flow_decimals);
 
        out.valve_drive_pct = static_cast<float>(static_cast<int16_t>(regs[7])) * 0.01f;
 
        out.raw_batch_remaining_2108_2109 =
            (static_cast<uint32_t>(regs[8]) << 16) | regs[9];
        out.batch_remaining = ScaleFlow(static_cast<int32_t>(out.raw_batch_remaining_2108_2109),
                                        flow_decimals);
 
        return DriverResult<InstantaneousData>::success(out);
    }
 
    //==========================================================================
    // INSTRUMENT IDENTITY (slow registers; read once at init)
    //==========================================================================
 
    DriverResult<InstrumentIdentity> ReadIdentity() noexcept {
        InstrumentIdentity id{};
 
        // Firmware version
        std::array<uint16_t, 1> fw{};
        if (auto rc = ReadHoldingRegisters(reg::FirmwareVersion, fw.data(), 1);
            rc != DriverError::None) {
            return DriverResult<InstrumentIdentity>::failure(rc);
        }
        id.firmware_version_raw = fw[0];
        id.fw_major = static_cast<uint8_t>((fw[0] >> 8) & 0xFFU);
        id.fw_minor = static_cast<uint8_t>((fw[0] >> 4) & 0x0FU);
        id.fw_patch = static_cast<uint8_t>(fw[0] & 0x0FU);
 
        // Serial number
        std::array<uint16_t, reg::SerialNumberCount> sn{};
        if (auto rc = ReadHoldingRegisters(reg::SerialNumberStart, sn.data(),
                                           reg::SerialNumberCount);
            rc != DriverError::None) {
            return DriverResult<InstrumentIdentity>::failure(rc);
        }
        for (std::size_t i = 0; i < reg::SerialNumberCount; ++i) {
            id.serial_number[i * 2]     = static_cast<char>((sn[i] >> 8) & 0xFFU);
            id.serial_number[i * 2 + 1] = static_cast<char>(sn[i] & 0xFFU);
        }
        id.serial_number[12] = '\0';
 
        // Address + unit id + flow units
        std::array<uint16_t, 5> tail{};  // 45..49
        if (auto rc = ReadHoldingRegisters(reg::ModbusAddress, tail.data(),
                                           static_cast<uint8_t>(tail.size()));
            rc != DriverError::None) {
            return DriverResult<InstrumentIdentity>::failure(rc);
        }
        id.modbus_address = static_cast<uint8_t>(tail[0] & 0xFFU);
        id.ascii_unit_id  = static_cast<char>(tail[1] & 0xFFU);
        id.full_scale_flow_raw =
            (static_cast<uint32_t>(tail[2]) << 16) | tail[3];
        id.flow_units = static_cast<FlowUnits>(tail[4] & 0xFFU);
        return DriverResult<InstrumentIdentity>::success(id);
    }
 
    //==========================================================================
    // SETPOINT (controllers only)
    //==========================================================================
 
    DriverResult<void> SetSetpoint(float value_in_user_units, uint8_t flow_decimals = 3) noexcept {
        const int32_t scaled = static_cast<int32_t>(
            value_in_user_units * Pow10(flow_decimals + 0));  // datasheet: × 1000 always
        // The datasheet specifies value/1000 for the scaled register regardless of decimals.
        const int32_t raw = static_cast<int32_t>(value_in_user_units * 1000.0f);
        std::array<uint16_t, 2> regs = {
            static_cast<uint16_t>((raw >> 16) & 0xFFFFU),
            static_cast<uint16_t>(raw & 0xFFFFU),
        };
        (void)scaled;
        return WriteMultipleRegisters(reg::SetpointCommand, regs.data(), 2);
    }
 
    DriverResult<void> SetSetpointSource(SetpointSource src) noexcept {
        return WriteSingleRegister(reg::SetpointSource, static_cast<uint16_t>(src));
    }
 
    DriverResult<void> SetCommWatchdogMs(uint16_t ms) noexcept {
        if (ms > 5000) return DriverResult<void>::failure(DriverError::InvalidParameter);
        return WriteSingleRegister(reg::CommWatchdogMs, ms);
    }
 
    DriverResult<void> SetMaxSetpointRamp(uint32_t pct_per_ms_x_10e7) noexcept {
        std::array<uint16_t, 2> regs = {
            static_cast<uint16_t>((pct_per_ms_x_10e7 >> 16) & 0xFFFFU),
            static_cast<uint16_t>(pct_per_ms_x_10e7 & 0xFFFFU),
        };
        return WriteMultipleRegisters(reg::MaxSetpointRamp, regs.data(), 2);
    }
 
    //==========================================================================
    // TARING / AUTOTARE
    //==========================================================================
 
    DriverResult<void> Tare() noexcept {
        return WriteSingleRegister(reg::TareCommand, kMagicTare);
    }
 
    DriverResult<void> SetAutotareEnabled(bool enabled) noexcept {
        return WriteSingleRegister(reg::AutotareEnable, enabled ? 1U : 0U);
    }
 
    //==========================================================================
    // GAS SELECTION
    //==========================================================================
 
    DriverResult<void> SetGas(Gas g) noexcept {
        return WriteSingleRegister(reg::SelectedGas, static_cast<uint16_t>(g));
    }
 
    //==========================================================================
    // TOTALIZER
    //==========================================================================
 
    DriverResult<void> ResetTotalizer() noexcept {
        return WriteSingleRegister(reg::TotalizerResetCommand, kMagicTare);
    }
 
    DriverResult<void> SetTotalizerLimitMode(TotalizerLimitMode mode) noexcept {
        return WriteSingleRegister(reg::TotalizerLimitMode, static_cast<uint16_t>(mode));
    }
 
    DriverResult<void> SetTotalizerBatch(uint32_t value_scaled) noexcept {
        std::array<uint16_t, 2> regs = {
            static_cast<uint16_t>((value_scaled >> 16) & 0xFFFFU),
            static_cast<uint16_t>(value_scaled & 0xFFFFU),
        };
        return WriteMultipleRegisters(reg::TotalizerBatchVolume, regs.data(), 2);
    }
 
    //==========================================================================
    // FLOW PROCESSING
    //==========================================================================
 
    DriverResult<void> SetFlowAveragingMs(uint16_t ms) noexcept {
        if (ms > 2500) return DriverResult<void>::failure(DriverError::InvalidParameter);
        return WriteSingleRegister(reg::FlowAveragingMs, ms);
    }
 
    DriverResult<void> SetReferenceTemperatureC(float c) noexcept {
        if (c < 0.0f || c > 30.0f) return DriverResult<void>::failure(DriverError::InvalidParameter);
        const uint16_t raw = static_cast<uint16_t>(c * 100.0f);
        return WriteSingleRegister(reg::ReferenceTemperature, raw);
    }
 
    //==========================================================================
    // MEASUREMENT WINDOW (datasheet "Configure Measurement Triggering")
    //==========================================================================
 
    DriverResult<void> ConfigureMeasurementTrigger(uint16_t trigger_bits) noexcept {
        return WriteSingleRegister(reg::MeasurementTriggerMode, trigger_bits);
    }
 
    DriverResult<void> StartMeasurementSamples(uint16_t num_samples) noexcept {
        return WriteSingleRegister(reg::MeasurementSampleCount, num_samples);
    }
 
    DriverResult<MeasurementData> ReadMeasurement(uint8_t flow_decimals = 3) noexcept {
      constexpr uint16_t kFirst = reg::MeasurementSampleCount;                             // 4201
      constexpr uint16_t kLast = reg::MeasurementPrevAvgFlow + reg::kPrevAvgFlowCount - 1; // 4215
      std::array<uint16_t, kLast - kFirst + 1> regs{};
      const auto rc = ReadHoldingRegisters(kFirst, regs.data(), static_cast<uint8_t>(regs.size()));
      if (rc != DriverError::None)
        return DriverResult<MeasurementData>::failure(rc);
      const auto at = [&regs](uint16_t r) { return regs[r - kFirst]; };
 
      MeasurementData out{};
      out.num_samples_requested = at(reg::MeasurementSampleCount);
      out.num_samples_collected = at(reg::MeasurementSamplesAveraged);
      out.min_temperature_raw = static_cast<int16_t>(at(reg::MeasurementMinTemp));
      out.max_temperature_raw = static_cast<int16_t>(at(reg::MeasurementMaxTemp));
      out.min_flow_raw = static_cast<int16_t>(at(reg::MeasurementMinFlow));
      out.max_flow_raw = static_cast<int16_t>(at(reg::MeasurementMaxFlow));
      out.avg_temperature_raw = static_cast<int16_t>(at(reg::MeasurementAvgTemp));
      out.avg_flow_raw = static_cast<int16_t>(at(reg::MeasurementAvgFlow));
      out.prev_avg_flow_raw =
          static_cast<int32_t>((static_cast<uint32_t>(at(reg::MeasurementPrevAvgFlow)) << 16) |
                               at(reg::MeasurementPrevAvgFlow + 1));
      out.min_temperature_c = static_cast<float>(out.min_temperature_raw) * 0.01f;
      out.max_temperature_c = static_cast<float>(out.max_temperature_raw) * 0.01f;
      out.avg_temperature_c = static_cast<float>(out.avg_temperature_raw) * 0.01f;
      out.avg_flow = ScaleFlow(out.avg_flow_raw, flow_decimals);
      return DriverResult<MeasurementData>::success(out);
    }
 
    //==========================================================================
    // BUS / IDENTITY RECONFIGURATION
    //==========================================================================
 
    DriverResult<void> SetModbusAddress(uint8_t new_address) noexcept {
        if (new_address < 1 || new_address > kMaxModbusAddress) {
            return DriverResult<void>::failure(DriverError::InvalidAddress);
        }
        const auto rc = WriteSingleRegister(reg::ModbusAddress, new_address);
        if (rc.ok()) address_ = new_address;
        return rc;
    }
 
    DriverResult<void> SetAsciiUnitId(char id) noexcept {
        if (id < 'A' || id > 'Z') {
            return DriverResult<void>::failure(DriverError::InvalidParameter);
        }
        return WriteSingleRegister(reg::AsciiUnitId, static_cast<uint16_t>(id));
    }
 
    DriverResult<void> SetBaudRate(BaudRate br) noexcept {
      const auto rc = WriteSingleRegister(reg::BaudRate, static_cast<uint16_t>(br));
      bus_bps_ = BaudRateToBps(br);
      return rc;
    }
 
    DriverResult<void> FactoryRestore() noexcept {
        return WriteSingleRegister(reg::FactoryRestoreCommand, kMagicFactoryRestore);
    }
 
    //==========================================================================
    // BUS DISCOVERY
    //==========================================================================
 
    DriverResult<uint8_t> DiscoverPresentAddresses(uint8_t* present_bitmap,
                                                   std::size_t bitmap_bytes,
                                                   uint16_t probe_timeout_ms = 30,
                                                   uint8_t  first_addr = 1,
                                                   uint8_t  last_addr  = kMaxModbusAddress) noexcept {
        if (!present_bitmap || bitmap_bytes < 32) {
            return DriverResult<uint8_t>::failure(DriverError::BufferTooSmall);
        }
        std::memset(present_bitmap, 0, bitmap_bytes);
 
        const uint8_t saved_addr     = address_;
        const uint16_t saved_timeout = timeout_ms_;
        timeout_ms_ = probe_timeout_ms;
        quiet_ = true; // silent addresses are expected: do not log each timeout
 
        uint8_t found = 0;
        for (uint16_t a = first_addr; a <= last_addr; ++a) {
            address_ = static_cast<uint8_t>(a);
            std::array<uint16_t, 1> dummy{};
            if (ReadHoldingRegisters(reg::FirmwareVersion, dummy.data(), 1) ==
                DriverError::None) {
                present_bitmap[a / 8] |= static_cast<uint8_t>(1U << (a % 8));
                ++found;
            }
        }
 
        address_    = saved_addr;
        timeout_ms_ = saved_timeout;
        quiet_ = false;
        return DriverResult<uint8_t>::success(found);
    }
 
    //==========================================================================
    // RAW MODBUS PRIMITIVES
    //==========================================================================
 
    DriverError ReadHoldingRegisters(uint16_t reg_addr, uint16_t* out, uint8_t count) noexcept {
        if (!out || count == 0 || count > 125) return DriverError::InvalidParameter;
        std::array<uint8_t, 8> tx{};
        const std::size_t tx_len = modbus::BuildReadHolding(address_, reg_addr, count,
                                                            tx.data(), tx.size());
        if (tx_len == 0) return DriverError::BufferTooSmall;
 
        // Expected response: addr(1) + fn(1) + bytecount(1) + payload(2*count) + crc(2)
        const std::size_t need = 5 + 2U * count;
        std::array<uint8_t, 5 + 2 * 32> rx{};  // up to 32 regs per call
        if (need > rx.size()) return DriverError::BufferTooSmall;
 
        SendRequest(tx.data(), tx_len);
        std::size_t got = 0;
        DriverError rc = ReceiveReply(reg::fn::ReadHolding, rx.data(), need, got);
        if (rc == DriverError::None) {
          rc = modbus::ParseReadHolding(rx.data(), got, address_, count, out);
        }
        return LogFailure(rc, reg::fn::ReadHolding, reg_addr);
    }
 
    DriverResult<void> WriteSingleRegister(uint16_t reg_addr, uint16_t value) noexcept {
        std::array<uint8_t, 8> tx{};
        const std::size_t tx_len = modbus::BuildWriteSingle(address_, reg_addr, value,
                                                            tx.data(), tx.size());
        if (tx_len == 0) return DriverResult<void>::failure(DriverError::BufferTooSmall);
 
        SendRequest(tx.data(), tx_len);
 
        // Broadcast → no response.
        if (address_ == kBroadcastAddress) return DriverResult<void>::success();
 
        std::array<uint8_t, 8> rx{};
        std::size_t got = 0;
        DriverError rc = ReceiveReply(reg::fn::WriteSingle, rx.data(), rx.size(), got);
        if (rc == DriverError::None) {
          rc = modbus::ParseWriteSingleEcho(rx.data(), got, tx.data(), tx_len);
        }
        return DriverResult<void>{LogFailure(rc, reg::fn::WriteSingle, reg_addr)};
    }
 
    DriverResult<void> WriteMultipleRegisters(uint16_t reg_addr,
                                              const uint16_t* regs, uint8_t count) noexcept {
        if (!regs || count == 0 || count > 32) {
            return DriverResult<void>::failure(DriverError::InvalidParameter);
        }
        std::array<uint8_t, 9 + 32 * 2> tx{};
        const std::size_t tx_len = modbus::BuildWriteMultiple(address_, reg_addr, regs, count,
                                                              tx.data(), tx.size());
        if (tx_len == 0) return DriverResult<void>::failure(DriverError::BufferTooSmall);
 
        SendRequest(tx.data(), tx_len);
 
        if (address_ == kBroadcastAddress) return DriverResult<void>::success();
 
        std::array<uint8_t, 8> rx{};
        std::size_t got = 0;
        DriverError rc = ReceiveReply(reg::fn::WriteMultiple, rx.data(), rx.size(), got);
        if (rc == DriverError::None) {
          rc = modbus::ParseWriteMultipleEcho(rx.data(), got, address_, reg_addr, count);
        }
        return DriverResult<void>{LogFailure(rc, reg::fn::WriteMultiple, reg_addr)};
    }
 
    ModbusExceptionCode GetLastException() const noexcept {
      return last_exception_;
    }
 
private:
  static constexpr const char* kLogTag = "alicat_basis2";
 
  DriverError LogFailure(DriverError rc, uint8_t fn, uint16_t reg_addr) noexcept {
    if (rc == DriverError::None || quiet_) {
      return rc;
    }
    if (rc == DriverError::ModbusException) {
      uart_.log(kLogTag, "addr %u fn 0x%02X reg %u: ModbusException %s",
                static_cast<unsigned>(address_), static_cast<unsigned>(fn),
                static_cast<unsigned>(reg_addr), ToString(last_exception_).data());
    } else {
      uart_.log(kLogTag, "addr %u fn 0x%02X reg %u: %s", static_cast<unsigned>(address_),
                static_cast<unsigned>(fn), static_cast<unsigned>(reg_addr), ToString(rc).data());
    }
    return rc;
  }
 
  void SendRequest(const uint8_t* tx, std::size_t tx_len) noexcept {
    last_exception_ = ModbusExceptionCode::None;
    uart_.delay_ms(modbus::InterFrameGapMs(bus_bps_));
    uart_.flush_rx();
    uart_.write(tx, tx_len);
  }
 
  DriverError ReceiveReply(uint8_t fn, uint8_t* rx, std::size_t expected_len,
                           std::size_t& got) noexcept {
    got = uart_.read(rx, modbus::kReplyHeaderLength, timeout_ms_);
    if (got == 0)
      return DriverError::Timeout;
    if (got < modbus::kReplyHeaderLength)
      return DriverError::InvalidFrame;
    if (modbus::IsExceptionReply(rx, got)) {
      got += uart_.read(rx + got, modbus::kExceptionFrameLength - got, timeout_ms_);
      uint8_t code = 0;
      const DriverError rc = modbus::ParseException(rx, got, address_, fn, &code);
      if (rc == DriverError::ModbusException) {
        last_exception_ = static_cast<ModbusExceptionCode>(code);
      }
      return rc;
    }
    got += uart_.read(rx + got, expected_len - got, timeout_ms_);
    return DriverError::None;
  }
 
    static float Pow10(int n) noexcept {
        float v = 1.0f;
        for (int i = 0; i < n; ++i) v *= 10.0f;
        return v;
    }
 
    static float ScaleFlow(int32_t raw, uint8_t decimals) noexcept {
        return static_cast<float>(raw) / Pow10(decimals);
    }
 
    UartT&    uart_;
    uint8_t   address_;
    uint16_t  timeout_ms_;
    ModbusExceptionCode last_exception_{ModbusExceptionCode::None};
    bool quiet_{false}; 
    uint32_t bus_bps_{kDefaultBusBaudBps}; 
};
 
}  // namespace alicat_basis2