Protocols¶
The instrument speaks two protocols on the same line settings (38400 baud, 8N1 by default). The driver implements
both completely behind one API: Config::protocol selects one for each Basis2 object, and the calls do not change.
Datasheet sections this page relies on
From Alicat Scientific, Inc. DOC-MANUAL-BASIS2 Rev 4:
- Default serial settings and the link layer: Alicat ASCII Serial Communication, Establishing Communication, p. 10
- Data frame: Data Frame Format, p. 10
- Query specific data: Query Specific Data, p. 11
- Active gas: Active Gas, p. 15
- Modbus RTU framing, address and baud: Modbus-RTU; Communicating Via Modbus-RTU; Changing the Baud Rate, p. 18
- Modbus setpoint, watchdog and tare: Setpoint Type; Changing the Setpoint; Communication Watchdog; Taring the Instrument, p. 19
- Modbus averaging, totalizer, batch, gas table: Flow Averaging; Totalizer; Batch Dispensing; Changing the Gas, p. 20
- Modbus register tables: User, Instantaneous Data, Measurement Data and Configuration and Function Registers, p. 21
- Engineering units: Reference, Engineering Units, p. 31
All of them, with the driver API for each: Datasheet map.
| ASCII "BASIS Protocol 2" (default) | Modbus RTU | |
|---|---|---|
| Addressing | Unit ID A to Z, up to 26 instruments per line |
Address 1 to 247 |
| Framing | One text line ending in a carriage return, in both directions | Binary frames with a CRC-16, separated by 3.5 characters of silence |
| Units and decimals | Printed in the text; the flow unit is learned from the FPF reply |
Scaled integers; the flow decimals are not readable (Config::modbus_flow_decimals) |
| Gas names | Printed in the frame; the gas table is a text list | Gas numbers; names only from a gas table in firmware 3.0.5 or later |
| Functions | The 46 commands of the manual | 3 (read), 6 (write one), 16 (write several) |
| Best for | A PC or MCU on a point to point link, text logs, bring-up | A PLC style RS-485 network; a few registers exist only here |
The instrument keeps no memory of which protocol a command came from, and the manual does not say whether both can be used at once on one line (the vendor's classic line says they run in parallel). The driver uses one protocol per object and never mixes them.
ASCII¶
Every command starts with the unit ID, ends with a carriage return and gets one line in reply. The driver sends upper
case only, and no command is started before the previous reply has ended and the line has been silent for 3.5
character times. The default Config addresses unit A.
The data frame¶
A poll (A) returns the whole frame: unit ID, then temperature, flow, total, and for a controller setpoint and valve
drive, then the gas name and zero or more status flags. The parser splits on runs of spaces, accepts bracketed or bare
flags, learns the layout (three or five numbers) from the first valid frame and rejects a later frame of the other
layout. The manual shows only a controller's frame; the meter layout is an assumption.
| Flag | Meaning | In StatusFlags |
|---|---|---|
MOV |
Mass flow over range | mass_flow_over |
TOV |
Temperature over range | temperature_over |
OVR |
Totalizer over range | totalizer_over |
HLD |
Valve held by the user (an override, not a fault) | valve_hold |
VTM |
Valve thermal management (an override, not a fault) | valve_thermal |
Commands and the API¶
| Command | Does | API |
|---|---|---|
a |
Poll the full frame | ReadFrame() |
a DV n |
Read selected data items | ReadData(), ReadFlow(), ReadTemperature(), ReadTotal(), ReadValveDrive(), ReadSetpointValue(), ReadBatchRemaining(), ReadStatus() |
a S f |
Set the setpoint | SetSetpoint() |
a LSS, a LSS x |
Read or set the setpoint source (a, s, u) |
ReadSetpointSource(), SetSetpointSource() |
a SR, a SR r t, a SR 0 |
Read, set or disable the ramp | ReadRamp(), SetRamp(), DisableRamp() |
a WD, a WD t |
Read or set the watchdog | ReadWatchdog(), SetWatchdog() |
a HPUR p, a C |
Hold the valve, resume control | HoldValve(), OpenValve(), CloseValve(), ResumeControl() |
a LCG, a LCG p i |
Loop gains | ReadGains(), SetGains() |
a RT, a RT t |
Reference temperature | ReadReferenceTemperature(), SetReferenceTemperature() |
a DCA, a DCA t |
Flow averaging | ReadAveraging(), SetAveraging() |
a MT, a MT m |
Measurement trigger mode | ReadMeasurementTrigger(), SetMeasurementTrigger() |
a DVAS t, a DVAA, a DVAR |
Measurement window, averages, ranges | StartMeasurement(), ReadAverages(), ReadRanges() |
a V d |
Tare over d ms | Tare(), TareDefault() |
a ZCA, a ZCA b |
Autotare | ReadAutotare(), SetAutotare() |
a GS, a GS *, a GS n |
Read, list, set the gas | ReadGas(), ReadGasList(), SetGas() |
a T |
Reset the totalizer | ResetTotal() |
a TB v, a TB 0 |
Batch volume | SetBatch(), DisableBatch() |
a TC, a TC m |
Totalizer limit mode | ReadTotalizerLimit(), SetTotalizerLimit() |
a FPF v |
Full scale values with their units | ReadFullScale() |
a SN, a VE |
Serial number, firmware | ReadSerialNumber(), ReadFirmware() |
a MA, a NCB, a P |
Read Modbus address, baud rate, protocol | ReadModbusAddress(), ReadBaud(), ReadProtocol() |
a @=b |
Change the unit ID | ChangeUnitId() (guarded) |
a MA n |
Set the Modbus address | SetModbusAddress() (guarded) |
a NCB b |
Set the baud rate | ChangeBaud() (guarded) |
a P 1, a P2 |
Switch protocol | SwitchToProtocol1(), SwitchToProtocol2() (guarded) |
a FACTORY RESTORE |
Restore factory settings | FactoryRestore() (guarded) |
The manual documents the format of the data frame and of a few replies only. The replies to the setters, the error
reply, the DV reply with several items, the gas list, VE and SN are not shown. The driver accepts the
plausible forms and treats the ? token as Rejected. Three setters are checked: SetSetpoint() reads the value back
(not while a ramp is active), SetGas() reads register 2100 back in Modbus mode and decodes the reply in ASCII mode
(an undecodable reply is an error), and ChangeUnitId() reads the new ID back. Every other setter reports only that the
instrument accepted it: no reply is Timeout, a ? is Rejected, and a lost reply to a write is never repeated. Each
of these is an assumption recorded in the Datasheet map and
settled by one capture from an instrument.
Timing¶
One character is ten bits. The reply wait is 3.5 character times, plus the line time of the longest reply of the
command, plus processing_ms (50 ms), or slow_command_ms for commands that may write non-volatile memory.
| Baud | 3.5 characters | Poll reply wait |
|---|---|---|
| 4800 | 7.3 ms | 258 ms |
| 9600 | 3.7 ms | 154 ms |
| 19200 | 1.8 ms | 102 ms |
| 38400 | 0.9 ms | 76 ms |
| 57600 | 0.6 ms | 68 ms |
| 115200 | 0.3 ms | 60 ms |
These are derived from the character time, not measured.
Modbus RTU¶
Frames carry the address, a function code, data and a CRC-16 (polynomial 0xA001, low byte first); registers are
big-endian. The driver sends functions 3, 6 and 16 only, never to address 0 (broadcast) or above 247, never to a
read-only register, and with the two magic values only on their registers: 0xAA55 to tare or reset the totalizer
and 0x5214 to restore factory settings. A reply with a bad CRC, the wrong address or a function code with the high
bit set (an exception) is an error, and the frame is discarded as a whole.
| Quantity | Registers | Scale |
|---|---|---|
| Flow | 2103 | Signed 16 bit, decimals from Config::modbus_flow_decimals |
| Total | 2104 to 2105 | Unsigned 32 bit, same decimals |
| Temperature | 2102 | Signed, divided by 100 |
| Valve drive | 2107 | Divided by 100 |
| Status | 2101 | Bits as the flags above |
| Setpoint | 2053 to 2054 (write), 2106 (current) | Signed 32 bit divided by 1000; the write completes when 2054 is written |
| Gas | 2100 | Gas number |
| Ramp | 524 to 525 | Percent of full scale per millisecond times 10^7 |
| Watchdog | 514 | Milliseconds, 0 disables |
| Setpoint source | 516 | 0 analog, 1 digital saved, 2 digital unsaved |
| Tare | 39 (write 0xAA55), 51 (samples of about 2.5 ms) |
|
| Firmware | 25 | 256a + 16b + c |
The register table is inc/alicat_basis2_registers.hpp; each row carries the firmware that added it, and a call that
needs a newer firmware than the identity says returns FirmwareTooOld without sending (Config::firmware_gate).
Differences you will see¶
- The flow, setpoint and total depend on the decimals you configured; a wrong value is off by a power of ten.
- The setpoint verify reads registers 2053 and 2054 back. Both they and 2106 report the ramped value while a ramp runs
(M p.21), so the verify is skipped then (
VerifyPolicy::WhenNoRamp). - The ramp conversion from a rate and a time unit to percent per millisecond uses the manual's formula; the unit the ASCII command expects ("the default units of the loop control variable") is undefined in the manual, so the two protocols may differ for a ramp. Check a ramp on the bench.
- Reading register 4214 starts a measurement when trigger mode +4 is set;
ReadPreviousMeasurement()warns in its documentation.
Next: Safety notes.