domain

# 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)