rm3100/README.md

RM3100 logging over a CH347 USB-I2C adapter

Logs a PNI RM3100 geomagnetic sensor connected to the I2C pins of a Waveshare USB to UART/I2C/SPI/JTAG adapter (CH347, USB 1a86:55db).

Reference: RM3100 & RM2100 Sensor Suite User Manual, Doc 1017252 R07 (PNI Sensor - RM3100-Sensor-Suite-User-Manual-R07-1.pdf in this directory). Section numbers below refer to it.

Hardware

Waveshare adapter in Mode 1 (UART1 + I2C + SPI), voltage selector at 3V3. The RM3100 is on a breakout board.

3V3 is required, though 3.0v would be ideal for the analog side.

Wiring

All connections below are confirmed working — this exact wiring produces valid data.

Adapter	RM3100	Notes
I2C VCC (3V3)	DVDD	digital supply
I2C VCC (3V3)	VDD (= AVDD)	analog supply — required for measurements
I2C VCC (3V3)	I2CEN	required to select I2C over SPI
I2C GND	DVSS	digital ground
I2C SCL	SCK/SCL	pin 27, shared with SPI SCLK
I2C SDA	SI/SDA	pin 1, shared with SPI MOSI

All three 3V3 connections share the adapter's single I2C VCC pin. Current draw is negligible — ~260 µA per axis at 24 Hz (Table 3-1).

The two supply pins and I2CEN are the non-obvious ones; both are explained below, because omitting either produces a failure that is easy to misdiagnose.

I2CEN (pin 22) must be tied HIGH

HIGH = I2C, LOW = SPI (§4.3.1). The RM3100's SDA/SCL pins are shared with the SPI MOSI/SCLK pins, and I2CEN is what selects between the two interfaces. Left floating or low, the chip stays in SPI mode and never ACKs its I2C address — the bus scan finds nothing at all, even though the adapter is perfectly healthy.

At DVDD = 3.3 V it needs at least VIH = 0.7 × DVDD = 2.31 V, so tie it directly to 3V3.

AVDD/AVSS (pins 4, 5) must be powered to take measurements

§4.3.1: "AVDD can be turned off when not making a measurement to conserve power, since all other operations are supported with DVDD."

So with only DVDD connected, the part is half alive in a way that is easy to misread as working: the I2C address responds, REVID reads back 0x22, and registers write and read back correctly — but the analog section that drives the sensor coils is dead, so DRDY never asserts and the measurement registers stay at zero. BIST reports XOK=YOK=ZOK=0 (see Diagnostics below), which is the unambiguous tell.

Both rails are needed — AVDD is not a substitute for DVDD. Two constraints (§4.3.1, Table 3-5):

• DVDD must come up before or at the same time as AVDD, never after. Moving the supply from DVDD to AVDD instead of adding it violates this.
• AVDD must stay within 0.1 V of DVDD while on — sharing one 3V3 rail satisfies this for free.

Power quality

The manual specifies very little here, but what it does specify is firm.

Parameter	Limit	Source
Ripple on AVDD or DVDD	50 mV peak-to-peak	Table 3-5, VDD_ripple
DVDD − AVDD while running	±0.1 V	Table 3-5, ΔVDD_OP
Supply range	2.0–3.6 V (typ 3.0)	Table 3-5
Absolute maximum	3.7 V	Table 3-4

The ripple limit carries no frequency qualifier — it is stated flat, so switching noise and mains hum are not distinguished.

Reference decoupling (Figures 4-1 and 4-2) is a 10 µF bulk capacitor in parallel with 0.1 µF ceramic, rail to ground. One rail feeds AVDD, both DVDD pins, and I2CEN. That is the entire filtering specification — no ferrite, no split analog/digital rails, no LDO requirement. §4.2.3 adds a placement rule: "Keep capacitors, especially tantalum capacitors, far away from the sensor coils" — a magnetic concern (ferromagnetic packaging), not an electrical one.

The manual gives no transfer function from ripple to field error — no µT-per-mV, no PSRR, no ripple-vs-noise curve. Only the 50 mV limit.

Slow drift should matter less than fast ripple. §4.1 describes the output as "the difference in the time to complete the measurement for each bias" — a differential measurement across forward and reverse coil bias — and §2 claims measurements are "stable over temperature and inherently free from offset drift." Anything common to both half-measurements largely cancels, so supply variation slower than one measurement cycle is rejected far better than noise near the ~180 kHz LR oscillation. (That last step is inference from the described architecture, not an explicit claim in the manual.)

This rig runs at 3.3 V, but every number in Table 3-1 is quoted at 3.0 V. Footnote 1: "Other bias resistors, external timing resistors and operating voltages may be used, but performance will differ from the values listed." 3.3 V is comfortably in range, but the 75 LSB/µT gain this driver uses is strictly a 3.0 V figure — a candidate scale-factor error the manual does not quantify. Unverified here: whether the breakout carries local decoupling, and what the CH347's 3V3 rail ripple actually measures against the 50 mV limit.

SA0 / SA1 set the I2C address

The top 5 address bits are fixed at 0b01000; SA0 (pin 3) and SA1 (pin 28) set the low two, giving 0x20–0x23 (§4.5). On this breakout both are strapped high, so the sensor answers at 0x23. These pins are shared with SPI SSN and MISO, so a breakout may label them SSN/SA0 and MISO/SA1.

logger.py scans all four addresses, so no configuration is needed.

DRDY (pin 23) is not connected

Not required. The driver polls the STATUS register instead (§5.4.1), which the manual explicitly offers as an alternative.

Setup

./setup.sh

Idempotent. It installs a udev rule, creates .venv, and installs pyusb. It needs sudo for the udev rule only.

The rule is needed because the CH347's USB node defaults to root:root 0664. It grants the plugdev group access:

SUBSYSTEM=="usb", ATTRS{idVendor}=="1a86", ATTRS{idProduct}=="55db", GROUP="plugdev", MODE="0660"

Python 3.14 here is PEP 668 externally-managed, hence the venv rather than a system-wide pip install.

Usage

./.venv/bin/python logger.py --duration 10      # log for 10 s
./.venv/bin/python logger.py                    # log until Ctrl-C
./.venv/bin/python logger.py --scan-only        # bus scan only, for wiring checks

Flag	Default	Meaning
--cycle-count	200	gain/resolution vs. speed; 200 → 75 LSB/µT
--tmrc	0x96	continuous-mode rate; 0x92 (~600 Hz) to 0x9D (~0.3 Hz)
--duration	0	seconds, 0 = until Ctrl-C
--output	timestamped	CSV path
--address	autodetect	skip the scan
--scan-only	—	scan and exit

CSV columns: timestamp_iso, elapsed_s, x_raw, y_raw, z_raw, x_uT, y_uT, z_uT, magnitude_uT.

./.venv/bin/python plot.py capture_60s.csv          # -> capture_60s.png
./.venv/bin/python plot.py capture.csv --smooth 0   # raw only, no moving average

Sample rate

Cycle count, not TMRC, sets the ceiling. Measured with --bus-speed 400:

Cycle count	Measured (polled)	Table 3-1 predicts	Noise (Table 3-1)
200	152 Hz	147 Hz	15 nT
100	297 Hz	283 Hz	20 nT
50	538 Hz	533 Hz	30 nT

The manual contradicts itself here and Table 3-1 is the correct one. The §5.2.1 note claims cycle count 200 allows a "~430 Hz" 3-axis update rate; Table 3-1 gives 440 Hz single-axis and says to divide by 3, i.e. ~147 Hz. Measurement backs Table 3-1 at all three cycle counts.

Bus speed matters less than expected: 400 kHz measured best (538 Hz), 100 kHz gave 444 Hz, and 750 kHz was slightly worse than 400 kHz at 515 Hz. Use 400.

Skipping the DRDY poll and free-running reads reaches 1100–1460 Hz, but 62–87% of those samples are duplicates, so it buys nothing real.

Threading

The sampling loop does I2C and nothing else — it pushes raw counts onto a queue, and a writer thread does unit conversion, CSV formatting, flushing and the console display. Wall-clock timestamps are reconstructed in the writer from one start time plus each sample's monotonic offset, rather than calling datetime.now() per sample; that is both cheaper and immune to an NTP step mid-capture.

This is worth roughly 28%: the same 60 s capture yielded 22,558 samples (376 Hz) with inline writing and 28,864 (481 Hz) with the writer split off. The queue is bounded, and any drop is counted and reported rather than silently losing data.

Files

File	Role
setup.sh	udev rule, venv, pyusb
ch347.py	CH347 I2C transport — USB only, knows nothing about the sensor
rm3100.py	RM3100 driver — registers and decoding, knows nothing about USB
logger.py	CLI: scan → identify → configure → log
plot.py	four-panel plot of a capture: X, Y, Z and the norm
diagnose.py	walks USB → bus → identity → registers → BIST → live read, stopping at the first failure

The adapter/sensor split is deliberate: ch347.py is a general I2C master usable with any device, and rm3100.py needs only a bus object exposing write(addr, data) and read(addr, count).

Implementation notes

Things that cost time to work out, recorded so they don't have to be again.

CH347 access

The adapter presents three USB interfaces. Interfaces 0 and 1 are CDC-ACM and the kernel binds them as /dev/ttyACM0 (the UART). Interface 2 is vendor-class and carries I2C/SPI/JTAG with no kernel driver bound, so libusb can claim it directly with nothing to detach.

ch347.py deliberately never calls set_configuration() — the device is already configured, and re-setting it would disturb the CDC-ACM interfaces driving the UART.

There is no usable off-the-shelf option: no CH347 kernel driver exists (the in-tree spi-ch341 is for 1a86:5512, a different chip); the PyPI ch347 package wraps a Windows DLL; and ch347api supports only HID mode (55dc), not this vendor-bulk mode 1. The framing in ch347.py follows the aystarik/ch347-i2c-spi-gpio Linux driver, whose id-table entry USB_DEVICE_INTERFACE_NUMBER(0x1a86, 0x55db, 0x02) matches this device exactly.

Wire format — bulk OUT 0x06, bulk IN 0x86, max 63 bytes per transfer:

Purpose	Bytes out	Bytes back
Set speed	AA 6<speed> 00	0
Write n	AA 74 (80|n+1) (addr<<1) <data> 75 00	n+1
Read n	AA 74 81 ((addr<<1)|1) [C0|(n-1)] C0 75 00	n+1
Probe	AA 74 81 (addr<<1) 75 00	1

Every returned byte must be 1 — that is the per-byte ACK. On a read, byte 0 is the address ACK and the rest is payload.

RM3100 quirks

• Register reads use the plain address, not |0x80. §5 describes the SPI convention of adding 0x80, but the I2C diagram in §5.8.4 writes 0x24 literally. Only 7 bits are decoded, so both work; the plain form is used here.
• A read is STOP-then-START, not a repeated START (§4.5.2, §5.8.4), which is exactly what two separate CH347 transactions produce. No special handling.
• CMM = 0x79 for all three axes. Table 5-1 describes bit 3 as reserved-zero, but the manual's own examples (§5.7.2, §5.8.3) set it. The examples win.
• HSHAKE is set to 0x0A (DRC0=0, DRC1=1) during init. The 0x1B default has DRC0=1, meaning any register write clears DRDY — including the pointer write that reading STATUS itself requires, so polling could never observe DRDY set. With DRC0=0, DRDY clears only on a results read.
• Gain is 0.3671 × cycle_count + 1.5 LSB/µT, a linear fit to Table 3-1 (50→20, 100→38, 200→75; reproduces all three within a count).
• Measurements are three 24-bit big-endian two's-complement values, read as 9 bytes from 0x24 using the sensor's register auto-increment.

Diagnostics

Symptoms map cleanly onto causes, so work down this list.

Symptom	Cause
Cannot claim CH347 interface 2: Access denied	udev rule missing — run ./setup.sh
No CH347 adapter found	not plugged in, or not in Mode 1
Adapter opens, --scan-only finds nothing	I2CEN not tied high (most likely), or SDA/SCL swapped, or no bus pull-ups
Found at 0x23, REVID 0x22, registers fine, but DRDY never sets and results are all zero	AVDD/VDD not powered — confirm with BIST; both of these were hit during bring-up
Cycle-count read-back mismatch	bus integrity — try a lower speed

BIST is the definitive test for the analog side (§5.6.1). Write 0x8F to BIST (STE=1, max timeout and periods), write 0x70 to POLL, wait, then read BIST back: bits 4/5/6 are XOK/YOK/ZOK, and 1 means that axis's LR oscillator ran. All zeros means the coils are not oscillating, which points at AVDD or the REXT timing resistor rather than anything on the I2C side.

A healthy total field magnitude is roughly 25–65 µT (Earth's field). Near zero, railed, or wildly out of range means the decode or gain is wrong rather than merely "data arrived".

Observed performance

First working capture, 10 s at TMRC 0x96, cycle count 200, sensor stationary on a desk next to a PC:

349 samples over 10.02 s -> 34.8 Hz
  X: mean  +6.473 uT   sd 177 nT
  Y: mean +50.914 uT   sd 106 nT
  Z: mean +18.944 uT   sd 396 nT
  |B|: mean 54.709 uT  sd 245 nT
  sample interval: 28.78 ms, sd 1.52 ms

• Rate. 34.8 Hz against a nominal ~37 Hz is in spec: §5.2.1 quotes roughly 7% one-standard-deviation tolerance on the update rate.
• Magnitude. 54.7 µT sits in the expected 25–65 µT band for Earth's field, which is the real confirmation that gain and the int24 decode are right.
• Noise is well above the 15 nT that Table 3-1 quotes for cycle count 200, and is not a driver problem. Most likely proximity to a PC and the USB adapter; a secondary candidate is ripple on the CH347's 3V3 rail against the 50 mV limit (see Power quality above), which has not been measured. Expect far better readings away from mains wiring and switching supplies.
• Drift. All three axes drifted monotonically down over the 10 s (Z most, by about 1.3 µT), so |B| fell from 55.5 to 54.3. Consistent with thermal settling after AVDD is first powered — coil DC resistance moves 0.4 %/°C (Table 3-3). Worth allowing a warm-up period before trusting absolute values.

None of this is calibrated: the figures are raw sensor output with no hard- or soft-iron correction, so the individual axis values reflect local distortion as much as Earth's field.

60 s capture at maximum rate

capture_60s.csv / capture_60s.png — 28,864 samples, 481 Hz, cycle count 50, 400 kHz bus. The sensor was nudged by hand at t ≈ 41 s, so statistics are split around that to keep the noise figures honest:

Axis	sd, 0–40 s	sd, 47–60 s	step across the event
X	84 nT	85 nT	+280 nT
Y	388 nT	376 nT	+217 nT
Z	187 nT	198 nT	+232 nT
|B|	369 nT	358 nT	+313 nT

Three things worth noting:

• The t ≈ 41 s step was the sensor being physically moved, confirmed at the time — not an electrical artefact. Note that a norm shift does not by itself imply an external source changed: |B| is preserved under rotation in a uniform field, but a translation through a field gradient samples a different local field and changes the magnitude. Near a PC the gradients are steep (§4.2.2: field falls off as 1/distance³), so a few centimetres is ample to produce the +313 nT seen here. Treat |B| changes as "not a pure rotation", nothing more.
• Noise is strongly axis-dependent — Y is 4.6× X (388 vs 84 nT), and stable across the event, so it is not a consequence of the disturbance. The coils are nominally identical, so this asymmetry points at orientation relative to a local noise source rather than a sensor fault. X at 84 nT is within ~3× of the 30 nT Table 3-1 quotes for cycle count 50; Y is ~13×.
• Sample timing is jittery: intervals average 2.08 ms (481 Hz) with sd 1.09 ms and a 19.6 ms worst case. Fine for logging, but the irregular spacing makes this data unsuitable for spectral analysis without resampling.

Status

• udev rule and venv setup
• CH347 vendor protocol — verified byte-for-byte against the kernel driver
• I2C bus scan — sensor found at 0x23
• Sensor identified — REVID 0x22
• Register write/read verified — cycle counts written and read back
• Analog section verified — BIST reports XOK=YOK=ZOK=1
• Live measurements logging to CSV at ~35 Hz

Initial communication is complete. A proper Python API is planned; these modules are the initial-communication milestone, deliberately kept simple.