capacitor-motioncal 0.0.3 → 0.0.5

package/README.md

@@ -1,126 +1,372 @@
 # Capacitor MotionCal Plugin
 
-A Capacitor plugin for motion/magnetometer calibration using native C libraries.
+A Capacitor plugin for real-time magnetometer calibration using the Freescale/NXP MotionCal algorithm (ported from [PaulStoffregen/MotionCal](https://github.com/PaulStoffregen/MotionCal)). The plugin accepts raw IMU sensor readings and computes hard-iron offset, soft-iron matrix, and geomagnetic field magnitude — the three values needed to correct a magnetometer heading.
+
+## How it works
+
+```
+Ionic app (sensor events)
+        │
+        ▼  rawData({ data: [9 int16 counts] })         — every sensor sample
+  MotionCal plugin  ──►  C calibration engine
+        │
+        ▼  isSendCalAvailable()                        — poll until quality is good
+        │
+        ▼  sendCalibration()                           — finalise
+        │
+        ▼  getHardIronOffset() / getSoftIronMatrix()   — apply to compass readings
+```
+
+The calibration engine accumulates magnetic field samples in a sphere-fitting buffer. Once the sphere is well-covered (quality metrics below threshold), `isSendCalAvailable()` returns `1` and you can call `sendCalibration()` to lock in the result.
+
+---
 
 ## Installation
 
-Install directly from GitHub:
+### From npm (after publish)
+
+```bash
+npm install capacitor-motioncal
+npx cap sync
+```
+
+### From GitHub
 
 ```bash
 npm install github:denizak/motioncal-capacitor
 npx cap sync
 ```
 
-Or clone and install locally:
+### Local path install (for testing before publish — see [Testing](#testing-locally-before-publishing))
 
 ```bash
-git clone https://github.com/denizak/motioncal-capacitor.git capacitor-motioncal
-npm install ./capacitor-motioncal
+npm install ../path/to/Capacitor-MotionCal
 npx cap sync
 ```
 
-## API
+---
 
-### updateBValue(options)
+## Ionic / Angular Integration
 
-Update the B (magnetic field magnitude) value.
+### 1. Install and sync
+
+```bash
+npm install capacitor-motioncal
+npx cap sync
+```
+
+### 2. Create a calibration service
+
+Create `src/app/services/motioncal.service.ts`:
 
 ```typescript
+import { Injectable } from '@angular/core';
 import { MotionCalibration } from 'capacitor-motioncal';
 
-await MotionCalibration.updateBValue({ value: 45.0 });
+export interface CalibrationResult {
+  hardIronOffset: number[];   // [x, y, z] in µT
+  softIronMatrix: number[][]; // 3×3 correction matrix
+  fieldMagnitude: number;     // geomagnetic field strength in µT
+  drawPoints: number[][];     // collected sphere points for visualisation
+}
+
+@Injectable({ providedIn: 'root' })
+export class MotionCalService {
+
+  /** Feed one IMU sample into the calibration engine.
+   *
+   *  All values must be converted to int16 raw counts using:
+   *    Accelerometer:  multiply g       × 8192  (G_PER_COUNT      = 1/8192)
+   *    Gyroscope:      multiply deg/s   × 16    (DEG_PER_SEC_PER_COUNT = 1/16)
+   *    Magnetometer:   multiply µT      × 10    (UT_PER_COUNT     = 0.1)
+   */
+  async feedSample(
+    ax: number, ay: number, az: number,   // accelerometer in g
+    gx: number, gy: number, gz: number,   // gyroscope in deg/s
+    mx: number, my: number, mz: number,   // magnetometer in µT
+  ): Promise<void> {
+    await MotionCalibration.rawData({
+      data: [
+        Math.round(ax * 8192), Math.round(ay * 8192), Math.round(az * 8192),
+        Math.round(gx * 16),   Math.round(gy * 16),   Math.round(gz * 16),
+        Math.round(mx * 10),   Math.round(my * 10),   Math.round(mz * 10),
+      ],
+    });
+  }
+
+  /** Returns true when the algorithm has enough data for a good calibration. */
+  async isReady(): Promise<boolean> {
+    const { available } = await MotionCalibration.isSendCalAvailable();
+    return available === 1;
+  }
+
+  /** Returns quality error values — lower is better.
+   *  isSendCalAvailable() already gates on these, but you can surface them in UI. */
+  async getQuality() {
+    const [gap, variance, wobble, fit] = await Promise.all([
+      MotionCalibration.getQualitySurfaceGapError(),
+      MotionCalibration.getQualityMagnitudeVarianceError(),
+      MotionCalibration.getQualityWobbleError(),
+      MotionCalibration.getQualitySphericalFitError(),
+    ]);
+    return {
+      surfaceGap:        gap.error,
+      magnitudeVariance: variance.error,
+      wobble:            wobble.error,
+      sphericalFit:      fit.error,
+    };
+  }
+
+  /** Finalise calibration and return all results. Call only after isReady() === true. */
+  async finalise(): Promise<CalibrationResult> {
+    await MotionCalibration.sendCalibration();
+
+    const [offset, matrix, magnitude, points] = await Promise.all([
+      MotionCalibration.getHardIronOffset(),
+      MotionCalibration.getSoftIronMatrix(),
+      MotionCalibration.getGeomagneticFieldMagnitude(),
+      MotionCalibration.getDrawPoints(),
+    ]);
+
+    return {
+      hardIronOffset: offset.offset,
+      softIronMatrix: matrix.matrix,
+      fieldMagnitude: magnitude.magnitude,
+      drawPoints:     points.points,
+    };
+  }
+
+  /** Reset the engine to start a new calibration session. */
+  async reset(): Promise<void> {
+    await MotionCalibration.resetRawData();
+    await MotionCalibration.clearDrawPoints();
+  }
+}
 ```
 
-### getBValue()
+### 3. Use the service in a component
 
-Get the current B value.
+```typescript
+import { Component, OnDestroy } from '@angular/core';
+import { MotionCalService, CalibrationResult } from '../services/motioncal.service';
+
+// Use @capacitor/motion or the Web DeviceMotion API to obtain sensor events.
+// The plugin also integrates with @awesome-cordova-plugins/device-motion if needed.
+
+@Component({
+  selector: 'app-calibration',
+  template: `
+    <ion-content>
+      <ion-button (click)="start()" [disabled]="running">Start Calibration</ion-button>
+      <ion-button (click)="stop()"  [disabled]="!running">Stop</ion-button>
+
+      <div *ngIf="running">
+        <p>Quality — gap: {{ quality?.surfaceGap | number:'1.3-3' }}
+                    wobble: {{ quality?.wobble | number:'1.3-3' }}</p>
+        <p *ngIf="ready">✓ Ready — tap Stop to finalise</p>
+      </div>
+
+      <div *ngIf="result">
+        <h3>Calibration Complete</h3>
+        <p>Hard iron offset: {{ result.hardIronOffset | json }}</p>
+        <p>Field magnitude: {{ result.fieldMagnitude | number:'1.2-2' }} µT</p>
+      </div>
+    </ion-content>
+  `,
+})
+export class CalibrationPage implements OnDestroy {
+  running = false;
+  ready   = false;
+  quality: Awaited<ReturnType<MotionCalService['getQuality']>> | null = null;
+  result: CalibrationResult | null = null;
+
+  private intervalId: ReturnType<typeof setInterval> | null = null;
+
+  constructor(private cal: MotionCalService) {}
+
+  async start() {
+    await this.cal.reset();
+    this.running = true;
+    this.result  = null;
+
+    // Subscribe to your sensor source here.
+    // Example using window.addEventListener for DeviceMotion + DeviceOrientation:
+    window.addEventListener('devicemotion',      this.onMotion);
+    window.addEventListener('deviceorientation', this.onOrientation);
+
+    // Poll quality every 500 ms for UI feedback.
+    this.intervalId = setInterval(async () => {
+      this.quality = await this.cal.getQuality();
+      this.ready   = await this.cal.isReady();
+    }, 500);
+  }
+
+  async stop() {
+    this.running = false;
+    window.removeEventListener('devicemotion',      this.onMotion);
+    window.removeEventListener('deviceorientation', this.onOrientation);
+    if (this.intervalId) clearInterval(this.intervalId);
+
+    if (this.ready) {
+      this.result = await this.cal.finalise();
+    }
+  }
+
+  // Replace with actual sensor values from your sensor plugin/service.
+  private onMotion = async (e: DeviceMotionEvent) => {
+    const a = e.accelerationIncludingGravity;
+    const r = e.rotationRate;
+    if (!a || !r) return;
+    // Magnetometer must come from a separate sensor source (e.g. @capacitor/motion
+    // does not expose magnetometer — use a dedicated plugin or native bridge).
+    // Here mx/my/mz are placeholders; replace with real values.
+    await this.cal.feedSample(
+      a.x ?? 0, a.y ?? 0, a.z ?? 0,
+      r.alpha ?? 0, r.beta ?? 0, r.gamma ?? 0,
+      0, 0, 0, // ← replace with real magnetometer µT values
+    );
+  };
+
+  private onOrientation = (_e: DeviceOrientationEvent) => { /* optional */ };
+
+  ngOnDestroy() { this.stop(); }
+}
+```
+
+### 4. Apply calibration to compass readings
 
 ```typescript
-const result = await MotionCalibration.getBValue();
-console.log('B value:', result.value);
+// After calibration is done, correct raw magnetometer readings before computing heading:
+function applyCalibration(
+  rawMag: [number, number, number],
+  hardIron: number[],
+  softIron: number[][],
+): [number, number, number] {
+  // Step 1: subtract hard-iron offset
+  const hx = rawMag[0] - hardIron[0];
+  const hy = rawMag[1] - hardIron[1];
+  const hz = rawMag[2] - hardIron[2];
+
+  // Step 2: multiply by soft-iron matrix
+  return [
+    softIron[0][0]*hx + softIron[0][1]*hy + softIron[0][2]*hz,
+    softIron[1][0]*hx + softIron[1][1]*hy + softIron[1][2]*hz,
+    softIron[2][0]*hx + softIron[2][1]*hy + softIron[2][2]*hz,
+  ];
+}
+
+function headingDegrees(mx: number, my: number): number {
+  return (Math.atan2(my, mx) * 180 / Math.PI + 360) % 360;
+}
 ```
 
-### readDataFromFile(options)
+---
 
-Read calibration data from a file.
+## Testing Locally Before Publishing
 
-```typescript
-const result = await MotionCalibration.readDataFromFile({ filename: 'magdata.bin' });
-console.log('Read result:', result.result);
+### Step 1 — Build the plugin
+
+```bash
+cd /path/to/Capacitor-MotionCal
+npm run build
 ```
 
-### sendCalibration()
+Verify `dist/` was generated with no TypeScript errors.
 
-Send/process the calibration data.
+### Step 2 — Install into the Ionic app via local path
 
-```typescript
-const result = await MotionCalibration.sendCalibration();
-console.log('Calibration result:', result.result);
+In your Ionic app directory:
+
+```bash
+npm install /path/to/Capacitor-MotionCal
+npx cap sync
 ```
 
-### Quality Metrics
+This installs the exact local build. You can iterate on the plugin and re-run `npm run build` + `npx cap sync` to pick up changes without publishing.
 
-```typescript
-const gapError = await MotionCalibration.getQualitySurfaceGapError();
-const varianceError = await MotionCalibration.getQualityMagnitudeVarianceError();
-const wobbleError = await MotionCalibration.getQualityWobbleError();
-const fitError = await MotionCalibration.getQualitySphericalFitError();
+### Step 3 — Verify the iOS build compiles
+
+Back in the plugin directory:
+
+```bash
+npm run verify:ios
 ```
 
-### Calibration Results
+This runs `pod install` + `xcodebuild` for the iOS target. Fix any Swift/C compile errors before proceeding.
 
-```typescript
-// Get hard iron offset [x, y, z]
-const offset = await MotionCalibration.getHardIronOffset();
-console.log('Hard iron offset:', offset.offset);
+### Step 4 — Verify the Android build compiles
+
+```bash
+npm run verify:android
+```
+
+Runs `./gradlew clean build test`. Requires the Android SDK in your `$PATH` / `$ANDROID_HOME`.
+
+### Step 5 — Smoke test on a real device
 
-// Get soft iron matrix (3x3)
-const matrix = await MotionCalibration.getSoftIronMatrix();
-console.log('Soft iron matrix:', matrix.matrix);
+1. Open the Ionic app in Xcode (`npx cap open ios`) or Android Studio (`npx cap open android`).
+2. Run on a physical device (simulators have no magnetometer).
+3. With the app open, wave/rotate the device in a figure-8 pattern to ensure `rawData` calls are being accepted and `isSendCalAvailable` eventually returns `1`.
+4. Call `sendCalibration()` and log the results — `hardIronOffset` should be non-zero and `fieldMagnitude` should be in the range 20–80 µT (typical for Earth's field).
 
-// Get geomagnetic field magnitude
-const magnitude = await MotionCalibration.getGeomagneticFieldMagnitude();
-console.log('Field magnitude:', magnitude.magnitude);
+### Step 6 — Pack and inspect what will be published
+
+```bash
+npm pack --dry-run
 ```
 
-### Visualization
+This lists all files that will be included in the npm package. Verify:
+- `dist/` is present
+- `android/src/main/` is present
+- `ios/Sources/` is present
+- `common/` (C source files) is present
+- No test files, node_modules, or local config bleed in
 
-```typescript
-// Get points for 3D visualization
-const points = await MotionCalibration.getDrawPoints();
-console.log('Draw points:', points.points);
+To create the actual tarball for manual inspection:
 
-// Clear points
-await MotionCalibration.clearDrawPoints();
+```bash
+npm pack
+# creates capacitor-motioncal-x.x.x.tgz
+tar -tzf capacitor-motioncal-*.tgz | sort
 ```
 
-### Reset
+### Step 7 — Publish
 
-```typescript
-await MotionCalibration.resetRawData();
+```bash
+npm login          # one-time
+npm publish
 ```
 
+For a scoped package use `npm publish --access public`.
+
+---
+
 ## Full API Reference
 
-| Method | Parameters | Returns |
-|--------|------------|---------|
-| `updateBValue` | `{ value: number }` | `Promise<void>` |
-| `getBValue` | - | `Promise<{ value: number }>` |
-| `isSendCalAvailable` | - | `Promise<{ available: number }>` |
-| `readDataFromFile` | `{ filename: string }` | `Promise<{ result: number }>` |
-| `setResultFilename` | `{ filename: string }` | `Promise<void>` |
-| `sendCalibration` | - | `Promise<{ result: number }>` |
-| `getQualitySurfaceGapError` | - | `Promise<{ error: number }>` |
-| `getQualityMagnitudeVarianceError` | - | `Promise<{ error: number }>` |
-| `getQualityWobbleError` | - | `Promise<{ error: number }>` |
-| `getQualitySphericalFitError` | - | `Promise<{ error: number }>` |
-| `displayCallback` | - | `Promise<void>` |
-| `getCalibrationData` | - | `Promise<{ data: string }>` |
-| `getDrawPoints` | - | `Promise<{ points: number[][] }>` |
-| `resetRawData` | - | `Promise<void>` |
-| `getHardIronOffset` | - | `Promise<{ offset: number[] }>` |
-| `getSoftIronMatrix` | - | `Promise<{ matrix: number[][] }>` |
-| `getGeomagneticFieldMagnitude` | - | `Promise<{ magnitude: number }>` |
-| `clearDrawPoints` | - | `Promise<void>` |
+| Method | Parameters | Returns | Notes |
+|--------|------------|---------|-------|
+| `rawData` | `{ data: number[] }` | `Promise<void>` | 9 int16 counts; call every sensor sample |
+| `isSendCalAvailable` | — | `Promise<{ available: number }>` | `1` = ready to finalise |
+| `sendCalibration` | — | `Promise<{ result: number }>` | Finalises calibration; call after `isSendCalAvailable` |
+| `getHardIronOffset` | — | `Promise<{ offset: number[] }>` | [x, y, z] bias in µT |
+| `getSoftIronMatrix` | — | `Promise<{ matrix: number[][] }>` | 3×3 scaling/rotation matrix |
+| `getGeomagneticFieldMagnitude` | — | `Promise<{ magnitude: number }>` | Earth field strength in µT |
+| `getCalibrationData` | — | `Promise<{ data: string }>` | Raw 68-byte calibration packet as base64 |
+| `getQualitySurfaceGapError` | — | `Promise<{ error: number }>` | Lower is better |
+| `getQualityMagnitudeVarianceError` | — | `Promise<{ error: number }>` | Lower is better |
+| `getQualityWobbleError` | — | `Promise<{ error: number }>` | Lower is better |
+| `getQualitySphericalFitError` | — | `Promise<{ error: number }>` | Lower is better |
+| `displayCallback` | — | `Promise<void>` | Triggers internal visualisation update |
+| `getDrawPoints` | — | `Promise<{ points: number[][] }>` | Sphere surface points for 3D display |
+| `clearDrawPoints` | — | `Promise<void>` | Clears the visualisation buffer |
+| `resetRawData` | — | `Promise<void>` | Resets entire calibration state |
+
+### int16 conversion factors
+
+| Sensor | Unit | Multiply by | Constant |
+|--------|------|-------------|----------|
+| Accelerometer | g | 8192 | `G_PER_COUNT = 1/8192` |
+| Gyroscope | deg/s | 16 | `DEG_PER_SEC_PER_COUNT = 1/16` |
+| Magnetometer | µT | 10 | `UT_PER_COUNT = 0.1` |
 
 

package/android/CMakeLists.txt

@@ -0,0 +1,29 @@
+cmake_minimum_required(VERSION 3.22.1)
+project("motioncalibration" C)
+
+# Suppress warnings from upstream C code (Freescale/NXP algorithm, not authored here).
+set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -std=c99 -w")
+
+add_library(
+    motioncalibration
+    SHARED
+
+    # JNI bridge (Java ↔ C)
+    src/main/jni/jni_bridge.c
+
+    # Algorithm sources (shared with iOS via common/)
+    ../common/rawdata.c
+    ../common/serialdata.c
+    ../common/visualize.c
+    ../common/magcal.c
+    ../common/mahony.c
+    ../common/matrix.c
+    ../common/quality.c
+)
+
+# Make imuread.h and other common/ headers visible to all C files.
+target_include_directories(motioncalibration PRIVATE ../common)
+
+# Android system libraries
+find_library(log-lib log)
+target_link_libraries(motioncalibration ${log-lib} m)

package/android/build.gradle

@@ -44,10 +44,10 @@ android {
         sourceCompatibility JavaVersion.VERSION_17
         targetCompatibility JavaVersion.VERSION_17
     }
-    
-    sourceSets {
-        main {
-            jniLibs.srcDirs = ['src/main/jniLibs']
+
+    externalNativeBuild {
+        cmake {
+            path "CMakeLists.txt"
         }
     }
 }

package/android/src/main/java/com/denizak/motioncalibration/{MotionCalibrationPlugin.java → MotionCalibration.java}

@@ -13,7 +13,7 @@ import org.json.JSONArray;
 import org.json.JSONException;
 
 @CapacitorPlugin(name = "MotionCalibration")
-public class MotionCalibrationPlugin extends Plugin {
+public class MotionCalibration extends Plugin {
 
     // Load the native library
     static {
@@ -21,11 +21,8 @@ public class MotionCalibrationPlugin extends Plugin {
     }
 
     // Native method declarations
-    private native void updateBValueNative(float bValue);
-    private native float getBValueNative();
     private native short isSendCalAvailableNative();
-    private native int readDataFromFileNative(String filename);
-    private native void setResultFilenameNative(String filename);
+    private native void rawDataNative(short[] data);
     private native int sendCalibrationNative();
     private native float getQualitySurfaceGapErrorNative();
     private native float getQualityMagnitudeVarianceErrorNative();
@@ -40,25 +37,6 @@ public class MotionCalibrationPlugin extends Plugin {
     private native float getGeomagneticFieldMagnitudeNative();
     private native void clearDrawPointsNative();
 
-    @PluginMethod
-    public void updateBValue(PluginCall call) {
-        Float value = call.getFloat("value");
-        if (value == null) {
-            call.reject("Value is required");
-            return;
-        }
-        updateBValueNative(value);
-        call.resolve();
-    }
-
-    @PluginMethod
-    public void getBValue(PluginCall call) {
-        float result = getBValueNative();
-        JSObject ret = new JSObject();
-        ret.put("value", result);
-        call.resolve(ret);
-    }
-
     @PluginMethod
     public void isSendCalAvailable(PluginCall call) {
         short isAvailable = isSendCalAvailableNative();
@@ -68,29 +46,22 @@ public class MotionCalibrationPlugin extends Plugin {
     }
 
     @PluginMethod
-    public void readDataFromFile(PluginCall call) {
-        String filename = call.getString("filename");
-        if (filename == null) {
-            call.reject("Filename is required");
+    public void rawData(PluginCall call) {
+        JSArray dataArray = call.getArray("data");
+        if (dataArray == null || dataArray.length() != 9) {
+            call.reject("Expected array of 9 numbers");
             return;
         }
-        String fullPath = getContext().getFilesDir().getAbsolutePath() + "/" + filename;
-        int result = readDataFromFileNative(fullPath);
-        JSObject ret = new JSObject();
-        ret.put("result", result);
-        call.resolve(ret);
-    }
-
-    @PluginMethod
-    public void setResultFilename(PluginCall call) {
-        String filename = call.getString("filename");
-        if (filename == null) {
-            call.reject("Filename is required");
-            return;
+        try {
+            short[] data = new short[9];
+            for (int i = 0; i < 9; i++) {
+                data[i] = (short) dataArray.getInt(i);
+            }
+            rawDataNative(data);
+            call.resolve();
+        } catch (Exception e) {
+            call.reject("Failed to process raw data: " + e.getMessage());
         }
-        String fullPath = getContext().getFilesDir().getAbsolutePath() + "/" + filename;
-        setResultFilenameNative(fullPath);
-        call.resolve();
     }
 
     @PluginMethod
@@ -245,4 +216,4 @@ public class MotionCalibrationPlugin extends Plugin {
         clearDrawPointsNative();
         call.resolve();
     }
-}
+}