Boxer code will run on two incarnations of the system board: Out of Form Factor (OFF) and In Form Factor (IFF). OFF hardware will use the Arduino Mega, while IFF hardware will be a custom PCB.
Table of Contents
The command interface is via USB, but the hardware will enumerate as a virtual serial port. The port will need to be configured with these settings:
| Platform | Baud | Data bits | Stop bits | Parity checking |
|---|---|---|---|---|
| OFF | 38400 | 8 | 1 | None |
| IFF | 230400 | 8 | 1 | None |
The debug interface is via USB, but the hardware will enumerate as a virtual serial port. The port will need to be configured with these settings:
| Platform | Baud | Data bits | Stop bits | Parity checking |
|---|---|---|---|---|
| OFF | 38400 | 8 | 1 | None |
| IFF | 230400 | 8 | 1 | None |
Both the OFF and IFF hardware versions will use the Optiboot bootloader to burn new firmware into memory. Optiboot is supported by AVRDUDE, which can coordinate sending new hex files over a Virtual Comm Port (VCP). The relevant command is:
where $(avrdude) is the AVRDUDE executable, $(VCP) is the Virtual Comm Port, $(avrdude_baud) is the baud rate used by the bootloader, and $(hex_file) is the new firmware in Intel HEX format.
For Windows, VCP examples are com5, com23, etc. For Linux, VCP examples are /dev/ttyUSB0, /dev/ttyUSB1, etc. Baud rates for our two platforms are shown below.
| Platform | Baud |
|---|---|
| OFF (Arduino Mega) | 38400 |
| IFF (Whitfield – 90071) | 230400 |
Commands are not case-sensitive – the command *IDN? is the same as *idn?.
Commands always return something. If the command doesn’t have an explicit return value or string, it will return 0 (ACK). Unrecognized commands or commands causing other problems will return one of the not-acknowledged (NACK) codes shown below.
| NACK code | Condition |
|---|---|
| -1 | Command not recognized |
| -2 | System is busy |
| -3 | Command execution failed |
| -4 | Buffer overflow |
| -5 | Argument out of range |
A command may fail with the “command execution failed” code if some hardware is missing. For example, CH5.BYP.DAC 100 will fail if one of the Topaz boards isn’t plugged in.
A naked carriage return is not considered a command, and as such may be used to clear the instrument’s receive queue. The first carriage return may send garbage to the command handler and return a NACK, so the host will need to clear it’s own receive queue before sending new commands.
The controller can only handle one command at a time, and commands take a variable length of time to execute. Waiting for 500ms after sending a command is enough for all commands to produce their returns.
Returns the instrument’s identification string containing four comma-separated fields:
None
Picarro,Boxer,SN0,1.0.0
Query the system’s log message severity threshold. Pressure readings only happen at full speed (100 Hz) when the threshold is set to “error.” This level is hard-coded. Return values are isr, debug, info, warning, and error.
None
error
Initiates a system reset.
None
None
Set the instrument’s serial number to n. Query the serial number with *IDN?.
16-bit integer (0-65535) formatted as a decimal.
0
Set the manifold box’s slot ID. There can be more than one manifold box in a rack, and this will help us keep track of which rack position it was installed into. This setting is non-volatile – it will persist across power cycles.
Integers 0-9
0
Query the manifold box’s slot ID.
3
Query the system’s operational state.
standby
Put the system in standby mode. This will disable all channels and configure their bypass valves for the default flow. This command may fail if the standby state isn’t accessible from the current state.
0
Put the system in clean mode. As with standby, this will disable all channels and configure their bypass valves for the default flow. Unlike standby, this will open the clean solenoid to allow clean gas to go to the analyzers.
You can exit clean mode by enabling a sample channel or going back to standby mode.
0
Set the serial number for manifold (Topaz) board A.
Integers 0-65535
| Return | Condition |
|---|---|
0 |
Serial number set |
-1 |
Topaz A not connected |
Query the serial number for manifold (Topaz) board A.
| Return | Condition |
|---|---|
10 |
Successful return for Topaz board 10 |
-1 |
Topaz A not connected |
Set the serial number for manifold (Topaz) board B.
Integers 0-65535
| Return | Condition |
|---|---|
0 |
Serial number set |
-1 |
Topaz B not connected |
Query the serial number for manifold (Topaz) board B.
| Return | Condition |
|---|---|
10 |
Successful return for Topaz board 10 |
-1 |
Topaz A not connected |
Execute a hardware reset of manifold (Topaz) board A. This does not seem to reset the MPR pressure sensors.
0
Execute a hardware reset of manifold (Topaz) board B. This does not seem to reset the MPR pressure sensors.
0
Each manifold box (piglet) has 8 channels. Internally, there are 4 channels on two manifold (topaz) boards. Channels are arranged on boards as shown below.
Enable channel n.
Integers 1-8
0
Returns 1 if channel n is enabled, or 0 if it’s disabled.
Integers 1-8
0
Disable channel n.
Integers 1-8
0
Set the channel enable register. Each channel has a position in the enable register bitfield, starting with channel 1 and ending with channel 8. Enable a channel by setting the channel’s bit. Disable a channel by clearing the channel’s bit.
Integers 0-255
0
Query the channel enable register.
8
Query the raw digital pressure reading from one of the inlet sensors. Each channel has one inlet sensor. The raw pressure reading is a 24-bit number.
Channel number 1-8.
14799059
Query the raw digital pressure reading from one of the outlet sensors. Each manifold (Topaz) board has one outlet sensor. Outlet sensor 1 is on the board with channels 1-4, and sensor 2 is on the board with channels 5-8.
14799059
Query the pressure at inlet channel n calibrated in Pascals.
Channel number 1-8
100449
Query the pressure at the outlet pressure sensor on Topaz A (n = 1) or Topaz B (n = 2). The return value will be calibrated Pascals.
1 or 2
100449
Set the exponential moving average factor for pressure readings. See this Wikipedia page for a description of this factor. In our case, alpha values of 0-1 are represented by settings of 0-65535, where 65535 gives the least averaging, and 0 gives the most.
Integers 0-65535
0
Query the exponential averaging factor used for pressure readings.
65535
Query the successful read cycle rate for pressure sensors on either Topaz A (n = 1) or B (n = 2). The return value will be the number of times all sensors on the specified board were read in 1 second.
1 for Topaz A (channels 1-4) or 2 for Topaz B (channels 5-8).
Set the slope calibration factor n for the channel x inlet pressure sensor. There are 8 of these commands: CH1.PRS.SLP, CH2.PRS.SLP, …, CH8.PRS.SLP. The calibration factor n has units of micro Pascals per count.
0-65535
0
Query the inlet pressure sensor slope calibration factor set with one of the CHx.PRS.SLP n commands. The return will have units of micro Pascals per count.
1-8
12842
Set the offset calibration factor n for the channel x inlet pressure sensor. There are 8 of these commands: CH1.PRS.OFF, CH2.PRS.OFF, …, CH8.PRS.OFF. The calibration factor n has units of Pascals.
0-65535
0
Query the inlet pressure sensor offset calibration factor set with one of the CHx.PRS.OFF n commands. The return will have units of Pascals.
1-8
21546
Set the slope calibration factor n for the outlet pressure sensor on Topaz board A. This board handles channels 1-4. The calibration factor n has units of micro Pascals per count.
0-65535
0
Set the slope calibration factor n for the outlet pressure sensor on Topaz board B. This board handles channels 5-8. The calibration factor n has units of micro Pascals per count.
0-65535
0
Query the outlet pressure sensor offset calibration factor set with the TZA.PRS.SLP n or TZB.PRS.SLP n commands. The return will have units of micro Pascals per count. Use n = 1 for Topaz A and n = 2 for Topaz B.
1 or 2
12842
Set the offset calibration factor n for the outlet pressure sensor on Topaz board A. This board handles channels 1-4. The calibration factor n has units of Pascals.
0-65535
0
Set the offset calibration factor n for the outlet pressure sensor on Topaz board B. This board handles channels 5-8. The calibration factor n has units of Pascals.
0-65535
0
Query the outlet pressure sensor offset calibration factor set with one of the TZA.PRS.OFF n or TZB.PRS.OFFn commands. The return will have units of Pascals. Use n = 1 for Topaz A and n = 2 for Topaz B.
1 or 2
21546
Query the temperature at the surface of the Vernon (power distribution) board in Celsius. Temperatures are always positive integers.
28
Query the temperature at the surface of the Topaz A (manifold) board in Celsius. Temperatures are always positive integers.
25
Query the temperature at the surface of the Topaz B (manifold) board in Celsius. Temperatures are always positive integers.
25
Set the voltage DAC output controlling the proportional valve current source. There are 8 of these commands: CH1.BYP.DAC, CH2.BYP.DAC, …, CH8.BYP.DAC. The table below relates DAC codes to output current. For example, the revision A Topaz boards will produce 65535 * 3.4492 uA/count = 226 mA maximum.
| Hardware version | uA / count |
|---|---|
| A | 3.4492 |
0-65535
0
Query the bypass DAC setting for channel n. Returns a value in counts.
1-8
17134
Query this piglet’s required Mass Flow Controller (MFC) setting contribution. The sample lines coming from each piglet will flow through a single MFC, and the piglet firmware has no idea if other piglets are present. This number thus represents the number that needs to be added to all the other MFCVAL? outputs to form the ultimate MFC setting.
The output will be a floating-point number.
40.0
Start the channel identification process. This can only be invoked in standby mode.
0
Query the channel identification substate.
| Substate | Returned string |
|---|---|
| Ambient | ambient |
| Calculate | calculate |
| Not in identify mode | none |
none
Return a number corresponding to the active channels discovered during channel identification. Each bit in the 8-bit number corresponds to a channel, and bits are set when the channel is active.
| Active channels | ACTIVECH? |
|---|---|
| none | 0 |
| all | 255 |
| 3 | 4 |
255
This version is only for testing the bootloader, USB enumeration, and the basic command interface. The *IDN? command works to identify the device.
The SERNUM command will likely go away! You can use this command to test writing the serial number, but the command will likely change in the next version.
This version is for testing the channel enable commands with the bargraph LEDs.
Added SLOTID command and its query. This will help us keep track of where the manifold box is in the rack, and thus to number its channels.
Added default log level setting to makefile. This allows producing hex release files tagged with the log level.
The command interface will now emit a NACK (-1) when the received character buffer overflows. This may allow the rack PC to simply send characters and look for a NACK when waiting for the remote interface to be ready.
Added watchdog timer. The system will reset after 1 second if it hangs anywhere.
Added the *RST command to initiate a reset over the command interface.
Added the OPSTATE command to query the current operating state.
Added the TZA.SN and TZA.SN? commands to set and get the serial number for Topaz A. These commands, for now, simply return -1 if the board isn’t connected.
Started to add NACK codes. See the command reference for the current list. Commands without an explicit return will still simply return 0 for successful completion.
Added the PRS.IN.RAW? query for the 8 inlet pressure sensors. This is the first sensor data command. The command takes an argument (1-8) to select the inlet channel. The return is raw counts from the sensor. Revision A boards have 15 PSI sensors, while newer revisions will probably have 25 PSI sensors.
Pressures are currently sampled at a very slow rate – about once every 2 seconds. This is to make room for debug messages. I’ll increase the speed when I’m more confident.
Added the CHx.BYP.DAC n commands to set the sample bypass proportional valve positions. Note that the proportional valve current control circuit has some offset issues with revision A Topaz. The current through the proportional valves will change when solenoid valve selections change.
Pressures are now sampled at 100Hz when the log level is set to “error.”
Increased pressure sensor read frequency to 100Hz. The delay between pressure sensor triggers and reads is now 6ms. The minimum value here is 5ms, but I worry about timing variations at that level violating this 5ms limit. 100Hz is a safe reading frequency.
Hex file releases now have an extra attribute: _mega or _whitfield. Use _mega releases for the Arduino Mega, and _whitfield for Picarro’s 90071 PCBs.
This release supports two Topaz boards with the new system board – Whitfield. You’ll need to use the new 230.4k baud rate instead of the old 38.4k. The Topaz boards need to be modified to have an I2C multiplexer address of 0x71 instead of the default 0x70.
Added the TZB.SN command. Note that you can’t communicate with new Topaz boards until they have serial numbers. Getting the serial number is the system board’s way of discovering the hardware.
This firmware reads the 10 pressure sensors at about 35 Hz.
Added the clean command and support for the clean solenoid. Sending the clean command will disable all sample channels and open the clean solenoid.
Added support for the front panel PCB “Aloha.” There are no new remote commands to go with this.
This version does not read the pressure sensors. All prs.* commands will return 0. This will be an interim release while we fix the pressure sensors.
Added the MFCVAL? query to get the Mass Flow Controller (MFC) setting contribution required for a piglet.
Bypass valves for enabled channels now get set to zero.
Added the IDENTIFY command to kick off the channel identification process.
Added the IDSTATE? query to get the channel identification substate. The OPSTATE? query will return the identify parent state ID during channel identification.
Added the ACTIVECH? query to return the active channels discovered during channel identification.
standby instead of shutdown. The system will show a red communication light on the front panel while the connection is broken, but at least the light will stay on.This version adds the LOGLEV? query for the logger severity threshold. Log messages aren’t available over the command interface, but they still slow the system down. Deployed firmware applications should have this level set to error.
This version adds the VER.TMP?, TZA.TMP?, and TZB.TMP? queries for temperatures on the Vernon (power distribution) board, Topaz A (manifold A) board, and Topaz B (manifold B) board. These commands query hardware sensors on the I2C bus, and thus can be used to detect problems with I2C communication over ribbon cables.
This version adds the TZA.RST and TZB.RST commands. We tried and failed to use these commands to reset locked-up MPR pressure sensors.
This version also adds support for LEDs on the system board. The red LED will flash when the system experiences an error.
This version adds the PRS.RATE? query for successful pressure sensor cycle read rate. This can be used for health monitoring.
This version outputs an unsolicited identity string (output from *IDN?) after it boots. This lets me profile the boot time and make sure it stays below a 3s limit.
This version also adds automatic Topaz board resets after multiple pressure sensor read failures. This fixes some MPR pressure sensors that fail to reset at power-on.
This version removes the automatic Topaz board resets caused by pressure sensor read failures. The system board’s multicolor LED will still flash red on read failures, but no attempt will be made to fix the bad sensor with a reset pulse. The PRS.RATE? command is available to monitor the successful read rate.
Added the PRS.IN.PAS? n and PRS.OUT.PAS? n commands for querying input and output pressure readings calibrated in Pascals.
Added the CHx.PRS.SLP n and CHx.PRS.OFF n commands (8 of them each) for setting input pressure sensor calibration coefficients.
Added the TZA.PRS.SLP n and TZB.PRS.SLP n commands for setting output pressure sensor slope calibration coefficients. Added the TZA.PRS.OFF n and TZB.PRS.OFF n commands for setting output pressure sensor offset calibration coefficients.
Added the IN.PRS.SLP? n and IN.PRS.OFF? n queries to get input channel pressure calibration coefficients saved in non-volatile memory.
Added the OUT.PRS.SLP? n and OUT.PRS.OFF? n queries to get output sensor pressure calibration coefficients saved in non-volatile memory.