domain

name

domain

description

IMU and seastate domain reference — quaternions, reference frames, heave estimation, significant wave height, motion metrics that matter for sailing performance analysis. TRIGGER when the user asks what a metric means, why we capture a particular report, how seastate is characterized, or how IMU motion relates to polar performance. DO NOT trigger for BNO085 register-level or install questions (use /calibrate).

IMU + seastate — domain reference

The point of this project is not "get IMU data". It's to answer: how does sea state affect boat performance, and how do we sail differently in 2 m short-chop versus 2 m long swell at the same TWS?

This skill is the glossary and the "why" for the choices in firmware.

Reference frames

See CLAUDE.md for the short version. Critical fact: we publish boat-frame data. Sensor, mount, boat, world are four distinct frames and mixing them is the single biggest source of silent bugs in IMU projects.

Quaternions, briefly

• 4-tuple (w, x, y, z) where w is the scalar part
• Unit quaternion (norm 1) represents a rotation in 3D
• q1 * q2 composes rotations; q^-1 = (w, -x, -y, -z) for unit q
• Rotate a vector v: v' = q * v * q^-1 (treating v as (0, vx, vy, vz))
• Convert to Euler (roll/pitch/yaw) only for display — never for math. Euler angles have singularities (gimbal lock) and don't compose

The BNO085 gives us a quaternion directly. That's the whole reason to use this chip instead of integrating gyro by hand.

Why Game Rotation Vector, not Rotation Vector

BNO085 exposes several fusion reports:

Report	Uses mag?	Absolute yaw?	Drift
Rotation Vector	yes	yes (north-referenced)	low if mag is good
Game Rotation Vector	no	no (arbitrary yaw origin)	slow yaw drift
Geomagnetic RV	yes, lower rate	yes	medium

A racing sailboat has a carbon mast, stainless rigging, and often a diesel. Magnetic heading from a hull-mounted IMU is unusable. We get heading from B&G via helmlog, not from this device. Game Rotation Vector gives us absolute roll and pitch (gravity-referenced) and relative yaw — which is all we need for motion analysis. Heading for correlating to TWA/VMG comes from helmlog's instrument feed.

The four channels we capture

Channel	What it's for
Quaternion (game RV)	Orientation, roll/pitch, attitude rate of change
Linear acceleration	Gravity-removed — direct input for heave integration
Gyro	Rate of turn, heel rate, pitch rate — maneuver detection
Raw accel	Sanity + debug, not used in analysis

Heave — the hard one

Heave = vertical displacement of a point on the boat due to wave motion. You cannot get heave directly from an accelerometer. You get vertical acceleration. Heave is the double integral of that — which means any DC offset or low-frequency bias becomes a runaway quadratic drift.

The classical fix is a band-pass filter before integration. Sea state lives in ~0.05–0.5 Hz (2–20 s wave period). Everything below is boat trim and SNTP drift; everything above is rig vibration and crew bouncing. The pipeline:

lin_accel_world_z  →  HPF(0.03 Hz)  →  integrate  →  HPF(0.03 Hz)  →  integrate  →  heave

Two integrations with high-pass between them. The filter cutoff is the tuning knob — too low and drift leaks through, too high and long swells are attenuated. Helmlog-side analysis, not device-side. The device just streams clean linear accel; server does the math so we can retune the filter without reflashing.

Significant wave height (H₁/₃)

Oceanographic standard: mean height (trough to crest) of the highest 1/3 of waves in a record. Computed from heave time series:

1. Identify wave cycles (zero-up-crossings of heave)
2. Measure each wave height (crest – preceding trough)
3. Sort descending, take mean of top third → H₁/₃

Alternative: spectral method (4 × √m₀ from the heave power spectrum), which is what Datawell buoys publish. Gives similar numbers in open ocean, can differ in confused seas.

Motion metrics worth capturing (helmlog-side)

Computed from stored samples over rolling windows (typical 60 s):

Metric	Definition	Why
H₁/₃	Significant wave height	Sea state magnitude
T_z	Zero-crossing period	Wave period — distinguishes chop from swell
Roll RMS	σ of roll over window	Heel variability (= sail-trim challenge)
Pitch RMS	σ of pitch over window	Fore-aft pitching (= speed loss through waves)
Slam rate	Count of |lin_accel_z| > 3g per minute	Slam count — correlates with crew fatigue and structural load
Heave RMS	σ of heave over window	Alternative sea state magnitude, less filter-sensitive than H₁/₃

The goal for correlation with polar: compute these metrics, join to existing helmlog tracks by timestamp, replot polar as surface over (TWS, TWA, H₁/₃).

Short chop vs. long swell at the same H₁/₃

Identical sig wave height can come from a 2 s period wind chop or a 12 s period ocean swell — and the boat sails them completely differently. T_z separates them, which is why period is in the metrics list above. "Sea state = H₁/₃" is the single biggest oversimplification in casual sailing analysis.

Maneuver detection (downstream idea)

Gyro-z (yaw rate) + cos(heel) gives a clean tack/gybe detector:

• Tack: yaw rate > threshold AND heel crosses through zero AND sign of heel flips
• Gybe: same, with a characteristic pitch bump during the boom swing

This isn't device firmware — it's a helmlog analysis module. But the data to do it lives in what this device sends.

What this device does NOT do

• No heading (B&G/helmlog has it)
• No speed (boat speed = B&G paddlewheel, SOG = GPS, both in helmlog)
• No dead reckoning — an IMU alone drifts unusably fast
• No on-device heave calculation — streamed raw, computed server-side where the filter can be retuned without reflashing
• No maneuver detection on device — needs joint analysis with helm angle and speed, lives in helmlog

Keep the device boring. Stream clean, labeled, frame-correct samples. All the interesting analysis lives in helmlog where it can be iterated on.

Reading list

• Kuipers, Quaternions and Rotation Sequences — quaternion math, the standard reference
• Ochi, Ocean Waves — spectral sea state analysis, H₁/₃, T_z, Pierson- Moskowitz spectrum
• BNO085 datasheet + SH-2 reference manual (Hillcrest) — report types, calibration procedure, FRS records
• Fossen, Handbook of Marine Craft Hydrodynamics and Motion Control — ship motion frames and conventions (overkill for us, but authoritative)