Looking for step-by-step sync setup (wired, External PPS, or wireless GPS via Magpie)? See the Syncing Your Gen-2 QTFM Sensors guide.
LED Color Codes
LED visible on the sensor ECU.
| State | Description |
|---|---|
| Flashing Red | Idle (flashes every 1 s in Master mode and every 0.5 s in Slave mode) |
| Solid Yellow | Autostart in progress |
| Solid Blue | Transmitting valid magnetic field data |
| Solid Red | Bad data (high gradient or in a dead zone) |
| Solid White New in V1_43 Magpie only |
GPS wireless-sync indicator (default). When GPS Sync mode is active,
the sensor is receiving valid UTC frames (forwarded by a Magpie), and the current
measurement is good, the LED is steady white. It is held at constant brightness, so it
adds no per-second magnetic signature. (Bad data shows solid red instead.) For a
per-second multi-sensor visual sync check, switch to the rainbow with sensor command
235. See the
Syncing guide.
|
| Per-Second Rainbow cmd 235 (optional) Magpie only |
Troubleshooting sync view for GPS wireless sync (off by default). When enabled with
sensor command 235, the LED steps through a 5-color sequence (Yellow →
Green → Cyan → Blue → Purple), one color per UTC second, in lockstep
across all synced sensors —
properly synchronized sensors show the same color at the same instant.
Not the default because stepping the LED current each second radiates a small 1 Hz
magnetic signature; reverts to solid white on reboot. Red still overrides on bad data.
|
Sensor Configuration Options
Retained in internal flash memory. Configurable via the user interface software or with serial commands.
| Data Rate | 1 / 2 / 4 / 8 / 16 / 32 / 64 / 128 / 1000 / 2000 ms |
| Print Items | Sensitivity / Data drop counter / Timestamp |
| Filters | 50 or 60 Hz notch / 10 Hz low or highpass / 20 Hz low or highpass / Custom low or highpass / Off |
| Magnetic Environment Scalar | Noisy / Average / Quiet / Auto-optimize / Custom (SZC) |
| Magnetic Environment Vector | Noisy / Average / Quiet / Auto-optimize / Custom (VZC) |
| Vector Mode | Enabled / Disabled (requires add-on vector coils) |
| Vector Mode Type | Survey (default, two averaged measurements per output, requires vector-coil calibration) / Stable (single measurement, no calibration required). See Vector mode: Survey vs Stable. |
| Automatic Start-Up | Enabled / Disabled |
| Baudrate | 115200 / 230400 / 19200 bits |
| Sync Mode | Master / Slave / External PPS Sync / GPS Sync V1_43 |
More info on sensor configuration: Sensor Configuration.
Line Prefixes in the Sensor Output
The sensor labels every line it sends with a leading character so you can tell the categories
apart. If you are writing software that reads the sensor, filtering on # alone
will hide several of these.
| Prefix | Contents |
|---|---|
! | Magnetic measurement data |
# | Status, replies and messages |
+ | Auto-start progress |
| Filter status |
| | LED state |
LED state codes. The sensor sends a code on its own line the moment the LED changes, so you are told about a state change rather than having to ask. See the LED Color Codes table for what each colour means; blue is the normal running state, meaning the sensor is transmitting valid field data.
| Code | LED | Code | LED |
|---|---|---|---|
|01 | Off | |05 | Yellow |
|02 | Red | |06 | Purple |
|03 | Blue | |07 | Cyan |
|04 | Green | |08 | White |
Auto-start progress appears as +Initializing,
+Heating, +Scanning, +Cooling, +Lock On,
+Stabilizing, +Oppt_ZC and +Done. Note that
+Lock On is the laser lock, not the cell. +Done means auto-start
finished with the cell locked.
The QTFM2 UI uses these lines itself: it reads the + and | lines to
track sensor state, and sends command 34 on connect to pick up the serial
number, data rate and status.
Serial Commands
Every QTFM Gen-2 user command lives in this one table — each appears
exactly once. Commands are sent over the configured baudrate as a single ASCII character (the
ASCII column) or, for the higher-numbered sync/operation commands, as their decimal
value; some accept a numeric argument terminated by \r\n. The separator rows group
related commands (sync, filters, print/display, measurement, vector, baud); a dash in the ASCII
column marks decimal-only commands that have no printable single-character form. Step-by-step
sync setup lives in the
Syncing Your Gen-2 QTFM Sensors
guide; this page is the command dictionary.
| Decimal | ASCII | Command | Description |
|---|---|---|---|
| System & Startup | |||
| 76 | L | Autostart | Initiate Autostart process |
| 79 | O | Toggle self boot | Automatic autostart when sensor powers on. This command toggles the setting on or off |
| 101 | e | Reboot | Software sensor reboot |
| 115 | s | Startup settings | Print all startup settings |
| 34 | " | Print Sensor Info Short |
A compact status snapshot of the sensor as it is running right now. Safe to send at
any time, including mid-acquisition, and it does not change any setting. This is the
command to use when you want to know what state the sensor is in without rebooting it
or reading the start-up banner. It prints:
|
Utility & Custom Profile Tilde Commands
tilde-prefixed commands for sensor state control, scripted configuration, and
user-saveable profile slots. All tilde commands bypass the ASCII command
lock, so they keep working after ~Lock_Commands~ is enabled.
Decimal column is dashed because these commands have no equivalent single-character
form.
| |||
| — | ~ | ~Start~ | Enable autostart on power-up (writes EEPROM 269 = 1) and reboot. The sensor will begin measurements immediately after every power cycle from now on. |
| — | ~ | ~Stop~ New V1_44 | Universal abort. Drops the sensor into idle without rebooting: aborts any active autostart, cancels queued LI_Set / Reop_Heading / Warmup, disables autostart-on-power (EEPROM 269 = 0), turns off cell heater + laser heater + laser, restores Laser_SP / Laser_Max from EEPROM (so any RAM bumps clear cleanly), and resets internal state. The single command to use when something is going wrong or you want a known-clean idle. |
| — | ~ | ~apply~ New V1_44 |
Re-read EEPROM into the sensor’s live runtime variables
without rebooting. Pairs with ~ADDR,VAL~ (and the legacy
=ADDR\r\nVAL\r\n) writes so a batch of changes takes effect in one shot.
Covers the 26 settings in the
Configuration Settings Overview
plus filter coefficients (recomputes Filter_startup()) and the derived
float at address 354. Baud rate (291) still requires a reboot.
|
| — | ~ | ~Warmup~ — or — ~WU~ New V1_44 |
Background thermal pre-warmup. Turns the laser ON at present Laser_SP,
drives the cell heater at 50% of CH_Auto_time, and the laser heater at
approximately 28% above LH_mintime. Monitors PD; when PD reaches 90% of
Light_Level_Set the laser heater turns off and the cell heater holds.
Useful for cold-start workflows where you want the sensor at operating temperature
before the host triggers autostart. Cancel with ~Stop~.
|
| — | ~ | ~report~ New V1_44 |
Print every configuration setting as a three-column table: address, current EEPROM
value, and a friendly label. Closes with the supported single-address and coupled
shortcuts so the operator has the syntax in front of them. Use it to confirm sensor
state before ~apply~ or autostart.
|
| — | ~ | ~ADDR,VAL~ New V1_44 |
Direct EEPROM write shorthand. Writes integer VAL to address ADDR
(0–400). Example: ~30,1~ sets Master mode. Floats are not supported
— use the older =ADDR\r\nVAL\r\n form for the few float-valued
addresses (laser PID gains, etc.). Bypasses the ASCII command lock.
|
| — | ~ | ~ADDR,VAL,PARAM~ New V1_44 |
Coupled-write shortcut for settings split across multiple addresses. Supported
dispatches: ~285,8,fc~ (Custom Lowpass filter at fc Hz),
~315,V,N~ (VZC mode — V=0 auto /
V=1 fixed, N=count),
~353,V,S~ (Fixed Measurement Time — V=0/1,
S=1/2/3 → 100/200/300µs). Other addresses with three arguments are
rejected with a helpful message.
|
| — | ~ | ~Lock_Commands~ |
Enable the ASCII command lock. After this, single-character decimal commands print
#Commands_Locked and are ignored. Tilde commands still work. Useful for
integrators who want to harden the sensor against stray serial keystrokes.
|
| — | ~ | ~Unlock_Commands~ | Disable the ASCII command lock and restore normal command handling. |
| — | ~ | ~SaveSlotN_name~ New V1_44 |
Snapshot the sensor’s current live configuration into custom
profile slot N (1, 2, or 3) under name (up to 16 ASCII characters;
letters, digits, underscores). Replaces any previous contents of that slot. Does not
reboot. Example: ~SaveSlot1_GroundSurvey_250~.
|
| — | ~ | ~LoadSlotN~ New V1_44 |
Apply the configuration saved in custom slot N, then reboot. You can also use
the bare-name form — ~name~ — just like a built-in
profile name; built-in names take precedence if there is a collision.
|
| — | ~ | ~ListSlots~ New V1_44 |
Print the contents of all three custom profile slots. Valid slots show their saved
name; unused slots show (empty). Does not reboot.
|
| — | ~ | ~DelSlotN~ New V1_44 | Clear custom slot N. The slot becomes available for a new save. Does not reboot. |
| — | ~ | ~profile_name~ | Bare-name profile load. Looks up the name against built-in profiles first (see the Profile Configuration guide for the full catalog), then falls back to your saved custom slots. Applies the matching profile and reboots. |
| Filters | |||
| 117 | u | 60 Hz Notch Filter | Turn on 60 Hz notch filter |
| 118 | v | 50 Hz Notch Filter | Turn on 50 Hz notch filter |
| 119 | w | Highpass 10 Hz Filter | Turn on 10 Hz highpass filter |
| 120 | x | Highpass 20 Hz Filter | Turn on 20 Hz highpass filter |
| 121 | y | Lowpass 10 Hz Filter | Turn on 10 Hz lowpass filter |
| 122 | z | Lowpass 20 Hz Filter | Turn on 20 Hz lowpass filter |
| 123 | { | Filters Off | Turn off all filters |
| Print & Display Toggles on/off print items, including the onboard IMU channels (ECU V8+) | |||
| 43 | + | Print Sensitivity | Toggle on and off with the command |
| 108 | l | Print Data drop counter | Toggle on and off with the command |
| 109 | m | Print Timestamp | Toggle the millisecond timestamp print on and off. Leave this on unless you have a reason not to — it is the QTFM’s standard timestamp, from the sensor’s own jitter-free clock, and the correct time base for analysis. A Magpie or ACB adds its own microsecond timestamp, but that is for GPS correlation and drop monitoring, not measurement timing. |
| 42 | * | White LED Mode | Toggle on and off. Forces the ECU LED to be white. Useful for determining which sensor is connected to the COM port when multiple sensors are connected. |
| 82 | R | Toggle IMU Accel Print | Onboard ICM-20948 IMU accelerometer. Echoes #Print IMU Acc On / Off. Retained in flash (EEPROM address 286). |
| 83 | S | Toggle IMU Gyro Print | Echoes #Print IMU Gyro On / Off. Retained in flash (EEPROM address 287). |
| 85 | U | Toggle IMU Mag Print | Toggles the IMU’s secondary 3-axis magnetometer (AK09916) output. Echoes #Print IMU V.Mag On / Off. Retained in flash (EEPROM address 288). |
| 86 | V | Toggle IMU Temp Print | Echoes #Print IMU Temp On / Off. Retained in flash (EEPROM address 289). |
| Measurement, Environment & Zero-Crossing | |||
| 125 | } | Change Data Rate | Cycle through Data Rate settings |
| 106 | j | Environment Setting Vector | Cycle through environment settings for vector mode (change VZC) |
| 107 | k | Environment Setting Scalar | Cycle through environment settings for scalar mode (change SZC) |
| 105 | i | Set Custom ZC | Mem Add 2 (custom SZC): Mem Add 305 (custom VZC). Mem Write Int button to set address. |
| 59 | ; | Auto optimize ZC | Automatically optimizes measured zero crossings |
| 60 | < | Announce ZC | Readback of measurement zero crossings in scalar and vector mode |
| Vector Mode | |||
| 90 | Z | Toggle Vector Mode | Vector mode on/off (enable/disable the vector output entirely). Requires add-on vector coils. |
| 227 | ã | Toggle Vector Mode Type | Toggle vector mode between Survey (default, two averaged measurements per output) and Stable (single measurement, no coil calibration required). See Vector mode: Survey vs Stable. On the two 500 Hz profiles (~V_500Hz_Pro_MP~, ~V_500Hz_Robust_MP~) Stable mode is not available and this command declines with an explanation; use Survey mode at 500 Hz. |
| Baud Rate | |||
| 40 | ( | Change Baud Rate | Needs to be followed by the desired rate. Ex. (115200* |
| 41 | ) | Baud Rate Statement | Announce current baud rate |
| User Reoptimization & Calibration command-line procedures for re-tuning the sensor after long deployment, temperature drift, or hardware change. Step-by-step workflow lives in the Reoptimization guide (basic + laser-gain) and the Vector coil calibration guide (vector add-on only). | |||
| 7 | — | Print Optimization Parameters | Print all current optimization parameters (PID gains, lock setpoints, WL offsets, deltas) along with the sensor serial number and firmware version. Run before and after a reoptimization to confirm what changed. |
| 3 | — | Auto Reoptimization — Part 1 | Start the first basic-reoptimization phase (approximately 30 s, two automatic reboots). Refines the core operating parameters that drift over long deployments. |
| 4 | — | Auto Reoptimization — Part 2 | Second basic-reoptimization phase (approximately 30 s). Requires laser-lock + cell-lock + autostart-complete. Determines the WL offset and refines the lock setpoints. |
| 5 | — | Save Basic Reoptimization | Finalize the basic reoptimization by writing the new values to flash. Only takes effect when the post-reopt WL offset and WL_R_Max meet validity checks; otherwise prints a refusal so the operator re-runs the steps. |
| 224 | — | Recalculate Laser-Lock Gains (Standard) | Auto-recalculate the laser-lock PID gains into reoptimization staging slots (EEPROM addresses 326, 327, 342). Uses the standard starting P = 28. Requires laser-lock + cell-lock active. Sensor prints several unstable messages while it converges — expected. |
| 225 | — | Recalculate Laser-Lock Gains (Low Laser Power) | Same procedure as cmd 224 but starts from a lower P = 12. Use this variant when the laser power has been reduced from default — the higher-P gains from cmd 224 can fail to converge in reasonable time at lower laser power, while the lower-P gains here settle quickly. |
| 223 | — | Apply New Laser-Lock Gains | Promote the recalculated gains from staging (326, 327, 342) to the active locked-mode gain registers (271, 300, 335). Run after 224 or 225 and after verifying the sensor still locks through normal orientation changes. |
| 6 | — | Initiate Vector Coil Calibration | Start the vector-coil delta calibration (1–2 min). Sensor prints #Calibrating Coil, keep sensor still and measures Delta_X / Delta_Y / Delta_Z. Requires the vector add-on, Vector Mode enabled, laser-lock + cell-lock. |
| 9 | — | Save Vector Coil Calibration | Permanently store the measured Delta_X / Delta_Y / Delta_Z values to EEPROM (338, 339, 340). Only writes if all three deltas are > 500 (validity guard); otherwise refuses. |
| 203 | Ë | Factory Reset | Reset EEPROM to factory defaults. Two equivalent ways to send it: the decimal-203 form must be followed by the confirmation code 2023 (e.g. Ë2023 or 2032023); or send the tilde form ~Reset_EEPROM~ which performs the same reset without a separate confirmation code. Requires a full reoptimization afterward. |
| V10 ECU Diagnostics New V1_45 available on sensors with the V10 ECU; earlier ECUs continue to operate normally without these monitors | |||
| 242 | — | Coil Connectivity Check | Check the sensor’s coil connections. Run on a locked, actively measuring sensor. |
| 243 | — | Power Supply Quality Report | Run the built-in power-supply quality check and print the result. |
| 244 | — | ECU Health Monitors | Print the V10 ECU input-voltage and input-current monitors. Earlier-generation ECUs report that V10 monitors are not enabled. |
| 249 | — | ECU Hardware Identification |
Reports which ECU generation the sensor detected and the three measurements behind that
decision. The last lines are the ones that matter: #Verdict: reads either
V10 (3/3) or V9 (0/3), and #V10 features currently:
shows whether the V10 diagnostics are active. If the verdict reads AMBIGUOUS,
send the whole output to QuSpin — the sensor is telling you the three checks
disagreed, which we would want to look at. From V1_46 the same report is printed once at
boot while the ECU generation has not been stored.
|
| Sync — Modes, Operations & Trigger all sync commands grouped together: mode selection (32/33/112/113), the wired trigger (84), and the PPS/GPS operations (206–235) | |||
| 32 | space | Master Mode | Sync mode. Sensor runs on its own internal clock and pulses out a 1 Hz sync signal that downstream slaves can lock to. FPGA addr 30 = 1. |
| 33 | ! | Slave Mode | Sync mode. Sensor slaves to the external clock input on the sync line (typically driven by a Master sensor); prints #needs input clock if the input clock is missing. FPGA addr 30 = 0. |
| 112 | p | External PPS Sync Mode New FPGA v5.05+ | Sync mode. Slaves the 1 Hz cycle counter to an externally supplied PPS edge (e.g. a 1 PPS GPS pulse routed through a host ECU). No UTC time is exchanged — the shared edge keeps every sensor’s cycle boundaries aligned in lockstep. FPGA addr 30 = 2. See sync operations 231–234 below. |
| 113 | q | GPS Sync Mode New FPGA v5.05+ Magpie only | Sync mode. Same as External PPS Sync, plus the sensor accepts an 11-byte UTC time frame over UART (Serial4 on the QTFM). A Magpie with an attached GPS receiver sends the frame and the sensor realigns its internal sample counter to absolute UTC milliseconds. FPGA addr 30 = 3. Setup & frame format: Syncing guide — Wireless GPS. |
| 84 | T | Sync (wired) | Trigger a sync of all wired Master/Slave sensors chained together. |
| 206 | — | Toggle GPS Sync New |
Enable / disable the sensor’s response to incoming UTC frames. When enabled, both
GPS_Sync and GPS_Active_Sync flags are set; the sensor will
act on the next valid UTC frame. When disabled, frames are received and logged but the
sensor does not realign.
When disabled, the output reads #GPS Sync: DISABLED and notes that
incoming frames will be received but ignored.
|
| 207 | — | Toggle GPS Edge Sync New | Toggle the GPS_Edge_Sync flag directly. Normally set as a side-effect of command 209 + a valid UTC frame; manual toggling is for advanced bring-up. |
| 209 | — | Arm Edge Sync (one-shot) New |
Sets PPS_Edge_Sync_Arm = true. The next valid UTC frame will trigger a
single one-shot alignment of the sensor’s cycle counter to the PPS edge. The arm
flag clears automatically after the alignment fires; re-arm by sending the command
again.
If GPS_Sync is off when this command is sent, the output reminds the
operator to send cmd 206 first.
|
| 230 | — | Toggle Periodic Edge Re-Arm New |
Toggles a background process that automatically re-arms
PPS_Edge_Sync_Arm at a fixed interval (default 60 s). Used for
long-running deployments where the sensor’s local clock would otherwise drift out
of phase with the GPS-derived UTC time over hours. Persisted to EEPROM (address 356),
so it survives reboots and re-engages automatically after the cell locks.
PPS-loss safety. If UTC frames stop arriving (PPS lost, GPS antenna disconnected, Magpie powered off, etc.) the periodic re-arm is automatically suppressed within approximately 3 seconds, and resumes automatically when UTC frames return.
The re-arm events themselves are silent (no per-fire serial print). Visual confirmation
is the steady solid white sync LED (or, with the rainbow enabled via
cmd 235, the per-second color stepping in lockstep across all synced sensors).
|
| 231 | — | Realign on Next PPS (one-shot) New |
Arms a one-shot realignment that fires on the next valid PPS edge.
“Realign” here means: reset the sensor’s millisecond timestamp,
restart the averaging window, and re-coincide the vector Bx/By/Bz sample phases —
the same operation the wired Sensor_Sync() performs. For
External PPS Sync arrays: because every sensor wired to the same PPS
sees the same edge, broadcasting this command to all sensors within a single PPS second
makes them all realign on the same edge. One-shot — it disarms itself
after firing.
On firing: #PPS realign DONE (ms timestamp + averaging + X/Y/Z phase reset on PPS edge). |
| 232 | — | Realign After PPS Dropout (one-shot) New |
Arms a one-shot realignment driven entirely by the PPS signal — no per-sensor
command at fire time. After arming, the sensor first confirms the PPS is alive, then
waits for the operator to briefly disconnect the shared PPS; when it
resumes, the sensor realigns on the 3rd valid edge after resume
(letting the input re-stabilize), then disarms. Cutting and restoring one shared PPS
line therefore realigns an entire array together. One-shot — never auto re-arms.
|
| 233 | — | Disarm PPS Realign New | Cancels any pending realignment armed by cmd 231 or 232. Output: #PPS realign DISARMED. |
| 234 | — | Toggle External-PPS Status Debug New |
Toggles an approximately 1 Hz debug line used to confirm the sensor is actually receiving and
locking to the external PPS — run it during External PPS bring-up before relying
on the signal.
|
| 235 | — | Toggle GPS-Sync LED Style New Magpie only |
Switches the sync indicator between solid white (default) and a
per-second rainbow, for GPS wireless sync only.
#GPS sync LED: WHITE (synced + data good) or
#GPS sync LED: RAINBOW (troubleshooting). Has no effect outside GPS
wireless sync mode.
|
IMU not detected
If a sensor responds to commands 82 / 83 / 85 / 86 with
#No IMU Detected, ECU Must Be V8 Or Later, the ECU hardware does not have the
onboard ICM-20948 IMU populated; the print flag is left unchanged.
FPGA hardware requirement
Sync modes 112 (External PPS) and 113 (GPS) require the FPGA
bitstream to be at v5.05 or later. On a v5.04 or older bitstream, sending command
p or q is rejected with an informative message and the existing
sync mode is left unchanged. Confirm the active mode anytime with "
(decimal 34) — the #MS Mode: line reports the cached value of FPGA address
30. The FPGA bitstream cannot be updated remotely — sensors purchased
June 2026 or later ship with v5.05+; earlier units must be returned to QuSpin for the
upgrade. The wired Master/Slave method (modes 32/33) works on every
Gen-2 sensor regardless of FPGA version.
Vector Mode: Survey vs Stable
When Vector Mode is enabled (command Z, decimal 90), the QTFM Gen-2 can run its
vector output in one of two distinct measurement schemes. The active scheme is toggled with
command 227 and retained in flash memory across reboots.
| Mode | Description |
|---|---|
| Survey Default | Each vector output is the average of two vector measurements taken in opposite coil-bias states. This averaging cancels much of the high-frequency noise that would otherwise show up at the vector output, so Survey mode is the right choice when the magnetic environment is dynamic or RF-noisy. The trade-off is that the two-measurement scheme is sensitive to low-frequency drift in the vector coil response, so Survey mode requires a vector-coil calibration to keep the output accurate. See Vector coil calibration for the calibration procedure. |
| Stable | Each vector output is a single vector measurement. Because there is no opposite-bias averaging, Stable mode is less tolerant of high-frequency noise — the noise floor at the vector output will be higher in an RF-noisy environment. In exchange, Stable mode has extremely good long-term stability and does not require vector coil calibration, which makes it the better choice for static deployments and long-duration measurements where drift matters more than instantaneous noise. |
Switching modes
Send decimal 227 to toggle between Survey (default) and Stable. The sensor replies
with one of:
#Vector_Mode: 0, Survey(default)
#Vector_Mode: 1, Stable The new mode is written to EEPROM address 341 and applied on every subsequent boot until changed again.
Which should I use? If you operate in environments with significant RF or 60 Hz noise and can perform a vector-coil calibration every few weeks, Survey mode will give you a cleaner output. If you need set-it-and-forget-it long-term stability — especially for stationary installations — Stable mode is the better default.