API guide¶
The API by task. Every call returns Result<T> (a value and an Error) or a bare Error; every call is noexcept.
The code blocks are compiled by the host build. For every class and member see the API reference.
Datasheet sections this page relies on
From Alicat Scientific, Inc. DOC-MANUAL-BASIS2 Rev 4:
- Data frame: Data Frame Format, p. 10
- Query specific data: Query Specific Data, p. 11
- Setpoint, setpoint source and ramp: Setpoint; Setpoint Source; Maximum Setpoint Ramp Rate, p. 11
- Communication watchdog: Communication Watchdog, p. 12
- Hold valve, gains, reference temperature, averaging: Hold Valve Position; Loop Control Gains; Reference Temperature; Readings Averaging, p. 13
- Measurement triggering, averages and ranges: Configure Measurement Triggering; Start a Measurement; Measurement Averages and Ranges, p. 13
- Tare and autotare: Taring the Instrument; Using Ground to Tare; Autotare, p. 14
- Active gas: Active Gas, p. 15
- Totalizer and batch: Totalizer Reset; Totalizer Batch; Totalizer Configuration, p. 15
- Full scale flow, serial number, firmware: Full Scale Flow; Unit ID; Version Number, p. 16
- Unit ID: Unit ID, p. 16
- Modbus address, baud rate, command protocol: Modbus Address; Serial Baud Rate; Command Protocol, p. 17
- Engineering units: Reference, Engineering Units, p. 31
All of them, with the driver API for each: Datasheet map.
Objects¶
A Bus<Port> owns one serial line and runs one transaction at a time. A Basis2<Port> is one instrument on a bus,
described by a Config. Neither does any I/O when constructed.
alicat_basis2::Bus<MyPort> bus(port);
alicat_basis2::Basis2<MyPort> meter(bus); // unit ID 'A', 38400 baud, ASCII
Several Basis2 objects with different unit IDs (or Modbus addresses) can share one bus. Call
bus.SetDeviceCount(n) when more than one instrument is connected, so that a unit ID change is refused.
Start up¶
EnsureInitialized() brings the port up (nothing is sent). Begin() learns the instrument and is the first call that
sends. Both can be repeated; after a failure they start from the beginning, and once Begin() has succeeded every
other call may be used.
alicat_basis2::Error BringUp(Meter& meter) {
// EnsureInitialized() starts the port; Begin() learns the instrument (identity, full scale,
// firmware). Both can be called again: after a failure they start from the beginning.
auto r = meter.EnsureInitialized();
if (r) {
r = meter.Begin();
}
if (!r) {
std::printf("BASIS 2 start-up: %s\n", alicat_basis2::ToString(r.error));
}
return r.error;
}
Begin() reads the serial number, firmware, full scale and its unit, the gas, the setpoint source and the ramp
(read commands only), and checks the first data frame. After it, GetIdentity() returns an Identity: the kind
(meter or controller), firmware, full scale, flow unit and label, gas and source. IsReady() is false while the
state is unknown, and IsStateUnknown() tells that case apart.
Read¶
| Call | Returns |
|---|---|
ReadFrame() |
The whole frame: flow, temperature, total, for a controller setpoint and valve drive, gas and flags |
ReadFlow(), ReadTemperature(), ReadTotal() |
One Decimal |
ReadValveDrive(), ReadSetpointValue(), ReadBatchRemaining() |
One Decimal (controllers) |
ReadStatus() |
StatusFlags: mass_flow_over, temperature_over, totalizer_over, valve_hold, valve_thermal |
ReadData(items) |
A frame with only the items you ask for (a DataItem mask) |
A Decimal is an integer mantissa and a count of decimals, so nothing is lost to floating point; ToDouble() and
ToMilli() convert. Values are in the instrument's own flow unit, which GetIdentity().unit_label prints. A flow
beyond Config::flow_margin_permille of the full scale, or a temperature outside the plausibility limits, is
OutOfRange and no value is returned.
Reads are retried up to Config::read_retries times after a failed transaction; nothing that changes the instrument is
ever retried.
Set a setpoint¶
alicat_basis2::Error RampTo(Meter& meter, double flow) {
// The unsaved source never wears the non-volatile memory; the saved one is rate limited.
if (auto r = meter.SetSetpointSource(alicat_basis2::SetpointSource::UnsavedDigital); !r) {
return r.error;
}
return meter.SetSetpoint(flow).error; // read back and compared when no ramp is active
}
The setpoint is checked against 0 to 2.5 % over full scale before anything is sent, and read back unless a ramp is
active. A meter returns Unsupported. While the source is saved a change sooner than three minutes after the last
is RateLimited. Read Safety notes before you move a valve.
Other tasks¶
| Task | Calls |
|---|---|
| Hold or release the valve | HoldValve(), OpenValve(), CloseValve(), ResumeControl() (ASCII only) |
| Ramp | SetRamp(rate, unit), DisableRamp(), ReadRamp() |
| Tare | Tare(duration_ms), TareDefault(), SetAutotare() |
| Gas | SetGas(), ReadGas(), ReadGasList() (GasName() names the nine gases) |
| Totalizer and batch | ResetTotal(), SetTotalizerLimit(), SetBatch(), DisableBatch() |
| Reference temperature, averaging | SetReferenceTemperature(), SetAveraging() |
| Measurement window | SetMeasurementTrigger(), StartMeasurement(), ReadAverages(), ReadRanges() |
| Identify | ReadSerialNumber(), ReadFirmware(), ReadFullScale() |
| Scan | ScanUnitIds() (ASCII), ScanModbusAddresses() (Modbus) |
| Raw access, for diagnostics | ReadRegisterRaw() (Modbus), ReadRawLine() (ASCII), GetLastReply() (no I/O) |
The raw reads send one request and never retry; a reply is still accepted only after its CRC, address and length (or
unit ID) check. GetLastReply() returns the last reply any call accepted, without touching the bus.
ScanUnitIds() and ScanModbusAddresses() block for the whole scan: 26 polls, each up to a reply wait, or one
read per address. Run them from a task that may wait, and not from a loop with a deadline.
Guarded commands¶
alicat_basis2::Error MoveToUnit(Meter& meter) {
// Commands that can strand the instrument need a token that names the consequence.
return meter.ChangeUnitId('B', alicat_basis2::ConfirmUnitIdChange{}).error;
}
The six guarded commands are listed with their tokens in Safety notes.
Recover¶
void Resynchronise(Meter& meter) {
// After an unexplained failure: find the instrument again (scans unit IDs or Modbus addresses).
if (auto r = meter.Recover(); !r) {
std::printf("BASIS 2 recover: %s\n", alicat_basis2::ToString(r.error));
}
}
Recover() finds the instrument again after a guarded command that was not confirmed or an unexplained failure: it
polls the configured ID or address and, when the bus declares one instrument, scans the unit IDs over ASCII or the
Modbus addresses over Modbus. It then relearns the identity and compares the serial number, firmware and kind with the
earlier ones: another instrument is VerifyMismatch. The state stays unknown (IsStateUnknown()) until all of that
succeeds.
Handle errors¶
Error values 0 to 9 are the base set shared by every driver of the organisation; values from 16 are this driver's.
const char* Describe(alicat_basis2::Error e) {
switch (e) {
case alicat_basis2::Error::Timeout:
return "no reply: check wiring, unit ID, baud rate and RS-485 direction control";
case alicat_basis2::Error::DeviceIdMismatch:
return "another unit answered: check the unit ID or Modbus address";
case alicat_basis2::Error::Crc:
return "line noise: check cabling and termination";
default:
return alicat_basis2::ToString(e);
}
}
Error |
Meaning | What to do |
|---|---|---|
Bus |
Write() returned false |
Check your port |
Timeout |
No complete reply in time | Wiring, A and B, baud rate, unit ID, direction pin: Troubleshooting |
DeviceIdMismatch |
Another unit answered | Two instruments with one ID |
Crc |
Modbus CRC-16 mismatch | Line noise, termination |
BadReply, Overflow |
The line does not match the grammar, or has no end | A wrong protocol, a wrong baud rate, noise |
Rejected |
The instrument answered ? or a Modbus exception |
The command is not valid in this state or on this model |
OutOfRange |
A decoded value is impossible | Check the unit and the decimals |
VerifyMismatch |
The read-back differs from what was set | A ramp, a clamp, or an analog source |
FirmwareTooOld |
The call needs a newer firmware | Update or FirmwareGate::Ignore |
RateLimited |
A saved setpoint came too soon | Use the unsaved source |
StateUnknown, GuardNotConfirmed |
A guarded command is not settled, or the token is wrong | Recover() |
Busy |
The bus was not free, or the line never went quiet: the transaction that met it was not sent. A writing call returns it only when its write was not sent | Wait, retry; find the peer that talks |
Unsupported |
Not on this protocol, this kind, or this port | Check the table above |
Not blocking¶
Bus can also be driven without blocking: Submit() a request, call Poll() from your loop and Take() the result.
Basis2 itself calls Execute(), which waits. Take every result before the next Basis2 call: Execute() drops a
result nobody took (its transaction is over) and waits at most as long as the transaction on the bus can still take.
See Porting.
Next: Configuration.