signalk-chiplog 1.0.0

package/lib/places.js

@@ -0,0 +1,128 @@
+const { notFound } = require('./errors');
+
+const EARTH_RADIUS_M = 6371008.8;
+
+function toRadians(degrees) {
+  return (degrees * Math.PI) / 180;
+}
+
+function distanceBetween(a, b) {
+  const dLat = toRadians(b.lat - a.lat);
+  const dLon = toRadians(b.lon - a.lon);
+  const h =
+    Math.sin(dLat / 2) ** 2 +
+    Math.cos(toRadians(a.lat)) * Math.cos(toRadians(b.lat)) * Math.sin(dLon / 2) ** 2;
+  return 2 * EARTH_RADIUS_M * Math.asin(Math.min(1, Math.sqrt(h)));
+}
+
+function findNearestPlace(db, position, radius) {
+  const latDelta = (radius / EARTH_RADIUS_M) * (180 / Math.PI);
+  const cosLat = Math.cos(toRadians(position.lat));
+  const lonDelta = cosLat > 1e-6 ? latDelta / cosLat : 360;
+  // Near the antimeridian a longitude window would wrap; filtering on latitude
+  // alone keeps the candidate set small and the distance test stays exact.
+  const wraps = position.lon - lonDelta < -180 || position.lon + lonDelta > 180;
+
+  const candidates = wraps
+    ? db
+        .prepare('SELECT * FROM places WHERE lat BETWEEN ? AND ?')
+        .all(position.lat - latDelta, position.lat + latDelta)
+    : db
+        .prepare('SELECT * FROM places WHERE lat BETWEEN ? AND ? AND lon BETWEEN ? AND ?')
+        .all(
+          position.lat - latDelta,
+          position.lat + latDelta,
+          position.lon - lonDelta,
+          position.lon + lonDelta
+        );
+
+  let nearest = null;
+  let nearestDistance = Infinity;
+  for (const place of candidates) {
+    const distance = distanceBetween(position, place);
+    if (distance <= radius && distance < nearestDistance) {
+      nearest = place;
+      nearestDistance = distance;
+    }
+  }
+  return nearest;
+}
+
+function toPlace(row) {
+  return {
+    id: row.id,
+    name: row.name,
+    position: { lat: row.lat, lon: row.lon },
+    source: row.source,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at
+  };
+}
+
+function requirePlaceRow(db, id) {
+  const row = db.prepare('SELECT * FROM places WHERE id = ?').get(id);
+  if (!row) {
+    throw notFound('place', id);
+  }
+  return row;
+}
+
+const nameCollator = new Intl.Collator(undefined, { sensitivity: 'base', numeric: true });
+
+// Sorted in JavaScript because SQLite's NOCASE only folds ASCII and would put
+// "Île de Ré" after "Rochefort". A vessel's gazetteer stays small enough.
+function listPlaces(db, { limit, offset }) {
+  const rows = db.prepare('SELECT * FROM places').all();
+  rows.sort((a, b) => nameCollator.compare(a.name, b.name) || a.id - b.id);
+  return {
+    total: rows.length,
+    limit,
+    offset,
+    items: rows.slice(offset, offset + limit).map(toPlace)
+  };
+}
+
+// A user-supplied name becomes authoritative for its surroundings: it updates
+// the nearest known place within the radius, or creates one.
+function rememberPlaceName(db, position, name, radius, now) {
+  const nearest = findNearestPlace(db, position, radius);
+  if (nearest) {
+    db.prepare("UPDATE places SET name = ?, source = 'manual', updated_at = ? WHERE id = ?").run(
+      name,
+      now,
+      nearest.id
+    );
+    return nearest.id;
+  }
+  const { lastInsertRowid } = db
+    .prepare(
+      `INSERT INTO places (name, lat, lon, source, created_at, updated_at)
+       VALUES (?, ?, ?, 'manual', ?, ?)`
+    )
+    .run(name, position.lat, position.lon, now, now);
+  return Number(lastInsertRowid);
+}
+
+function renamePlace(db, id, name, now) {
+  requirePlaceRow(db, id);
+  db.prepare("UPDATE places SET name = ?, source = 'manual', updated_at = ? WHERE id = ?").run(
+    name,
+    now,
+    id
+  );
+  return toPlace(requirePlaceRow(db, id));
+}
+
+function deletePlace(db, id) {
+  requirePlaceRow(db, id);
+  db.prepare('DELETE FROM places WHERE id = ?').run(id);
+}
+
+module.exports = {
+  distanceBetween,
+  findNearestPlace,
+  listPlaces,
+  rememberPlaceName,
+  renamePlace,
+  deletePlace
+};

package/lib/propulsion-detector.js

@@ -0,0 +1,156 @@
+const { recomputeDurations } = require('./entries');
+
+// Engine data is published continuously: NMEA 2000 revolutions several times
+// a second, signalk-alternator-engine-on's state on every alternator reading.
+const ENGINE_DATA_MAX_AGE_MS = 2 * 60 * 1000;
+
+const PROPULSION_DEFAULTS = { defaultPropulsion: 'sail' };
+
+function iso(ms) {
+  return new Date(ms).toISOString();
+}
+
+function createPropulsionTracker({ db, readSelfPath, readFresh, settings }) {
+  let previousType = null;
+  let rpmAverage = null;
+
+  // Engine data wins over navigation.state, which signalk-autostate derives
+  // from the same sources or from its own default when it has none.
+  function sense(now, navigationState) {
+    let hasEngineData = false;
+    let running = false;
+    const rpms = [];
+
+    for (const id of Object.keys(readSelfPath('propulsion') ?? {})) {
+      const revolutions = readFresh(`propulsion.${id}.revolutions`, now, ENGINE_DATA_MAX_AGE_MS);
+      if (typeof revolutions === 'number' && Number.isFinite(revolutions)) {
+        hasEngineData = true;
+        if (revolutions > 0) {
+          running = true;
+          rpms.push(revolutions * 60);
+        }
+        continue;
+      }
+      const state = readFresh(`propulsion.${id}.state`, now, ENGINE_DATA_MAX_AGE_MS);
+      if (state === 'started' || state === 'stopped') {
+        hasEngineData = true;
+        running = running || state === 'started';
+      }
+    }
+
+    let type = settings.defaultPropulsion;
+    if (hasEngineData) {
+      type = running ? 'engine' : 'sail';
+    } else if (navigationState === 'motoring') {
+      type = 'engine';
+    } else if (navigationState === 'sailing') {
+      type = 'sail';
+    }
+    const rpm = rpms.length > 0 ? rpms.reduce((sum, value) => sum + value, 0) / rpms.length : null;
+    return { type, rpm };
+  }
+
+  function closeSegment(segment, endTime) {
+    const end = endTime < segment.start_time ? segment.start_time : endTime;
+    db.prepare('UPDATE propulsion_segments SET end_time = ? WHERE id = ?').run(end, segment.id);
+  }
+
+  function openSegment(entry, type, requestedStart, now) {
+    const { lastEnd } = db
+      .prepare('SELECT MAX(end_time) AS lastEnd FROM propulsion_segments WHERE entry_id = ?')
+      .get(entry.id);
+    let start = lastEnd === null ? entry.start_time : requestedStart;
+    if (lastEnd !== null && start < lastEnd) {
+      start = lastEnd;
+    }
+    if (start > iso(now)) {
+      start = iso(now);
+    }
+    const { lastInsertRowid } = db
+      .prepare(
+        "INSERT INTO propulsion_segments (entry_id, type, start_time, source) VALUES (?, ?, ?, 'auto')"
+      )
+      .run(entry.id, type, start);
+    return db
+      .prepare('SELECT * FROM propulsion_segments WHERE id = ?')
+      .get(Number(lastInsertRowid));
+  }
+
+  function trackRpm(segment, rpm) {
+    if (rpmAverage?.segmentId !== segment.id) {
+      rpmAverage = {
+        segmentId: segment.id,
+        sum: segment.average_rpm ?? 0,
+        count: segment.average_rpm === null ? 0 : 1
+      };
+    }
+    rpmAverage.sum += rpm;
+    rpmAverage.count += 1;
+    db.prepare('UPDATE propulsion_segments SET average_rpm = ? WHERE id = ?').run(
+      rpmAverage.sum / rpmAverage.count,
+      segment.id
+    );
+  }
+
+  // Runs inside detection's transaction, after it has updated the passage, so
+  // segment boundaries reuse the departure, stop and resume times it worked out.
+  function reconcile(now, sensed, { resumedAt = null } = {}) {
+    const entry = db.prepare("SELECT * FROM log_entries WHERE state = 'active'").get();
+    const moving = entry !== undefined && entry.stopped_since === null;
+    const touched = new Set(moving ? [entry.id] : []);
+    let current = null;
+
+    const open = db
+      .prepare(
+        `SELECT s.*, e.state AS entry_state, e.end_time AS entry_end, e.stopped_since AS entry_stopped
+         FROM propulsion_segments s JOIN log_entries e ON e.id = s.entry_id
+         WHERE s.end_time IS NULL
+         ORDER BY s.start_time`
+      )
+      .all();
+
+    for (const segment of open) {
+      let end = null;
+      if (segment.entry_state === 'closed') {
+        end = segment.entry_end;
+      } else if (segment.entry_stopped !== null) {
+        end = segment.entry_stopped;
+      } else if (current) {
+        end = iso(now);
+      } else if (segment.type !== sensed.type) {
+        // Split only when the engine actually changes state, so a manual
+        // correction of the ongoing segment holds on a boat whose sensors keep
+        // reporting the old value. After a restart, only automatic segments
+        // are brought back in line.
+        const changed = previousType !== null && sensed.type !== previousType;
+        const restarted = previousType === null && segment.source === 'auto';
+        if (changed || restarted) {
+          end = iso(now);
+        }
+      }
+
+      if (end === null) {
+        current = segment;
+      } else {
+        closeSegment(segment, end);
+        touched.add(segment.entry_id);
+      }
+    }
+
+    if (moving && !current) {
+      current = openSegment(entry, sensed.type, iso(resumedAt ?? now), now);
+    }
+    if (moving && current.type === 'engine' && sensed.rpm !== null) {
+      trackRpm(current, sensed.rpm);
+    }
+
+    for (const entryId of touched) {
+      recomputeDurations(db, entryId, iso(now));
+    }
+    previousType = sensed.type;
+  }
+
+  return { sense, reconcile };
+}
+
+module.exports = { createPropulsionTracker, PROPULSION_DEFAULTS };

package/lib/propulsion.js

@@ -0,0 +1,75 @@
+const { withTransaction } = require('./database');
+const { notFound } = require('./errors');
+const { requireEntryRow, recomputeDurations } = require('./entries');
+const { paginate } = require('./rows');
+
+function toSegment(row) {
+  return {
+    id: row.id,
+    entryId: row.entry_id,
+    type: row.type,
+    startTime: row.start_time,
+    endTime: row.end_time,
+    source: row.source,
+    averageRpm: row.average_rpm
+  };
+}
+
+function requireSegmentRow(db, id) {
+  const row = db.prepare('SELECT * FROM propulsion_segments WHERE id = ?').get(id);
+  if (!row) {
+    throw notFound('propulsion_segment', id);
+  }
+  return row;
+}
+
+function listSegments(db, entryId, { limit, offset }) {
+  requireEntryRow(db, entryId);
+  return paginate(db, {
+    table: 'propulsion_segments',
+    where: 'WHERE entry_id = ?',
+    params: [entryId],
+    orderBy: 'start_time, id',
+    limit,
+    offset,
+    map: toSegment
+  });
+}
+
+function allSegments(db, entryId) {
+  return db
+    .prepare('SELECT * FROM propulsion_segments WHERE entry_id = ? ORDER BY start_time, id')
+    .all(entryId)
+    .map(toSegment);
+}
+
+function correctSegment(db, id, { type }, { now }) {
+  return withTransaction(db, () => {
+    const row = requireSegmentRow(db, id);
+    if (row.type === type) {
+      return toSegment(row);
+    }
+
+    db.prepare("UPDATE propulsion_segments SET type = ?, source = 'manual' WHERE id = ?").run(
+      type,
+      id
+    );
+    recomputeDurations(db, row.entry_id, now);
+
+    // Placed at the segment's start so the timeline shows the correction where
+    // it applies; created_at still records when it was made.
+    db.prepare(
+      `INSERT INTO events (entry_id, time, type, subtype, payload, source, created_at)
+       VALUES (?, ?, 'manual_correction', 'propulsion', ?, 'manual', ?)`
+    ).run(
+      row.entry_id,
+      row.start_time,
+      JSON.stringify({ segmentId: id, before: { type: row.type }, after: { type } }),
+      now
+    );
+
+    return toSegment(requireSegmentRow(db, id));
+  });
+}
+
+module.exports = { listSegments, allSegments, correctSegment };

package/lib/rows.js

@@ -0,0 +1,15 @@
+function toPosition(lat, lon) {
+  return lat === null || lon === null ? null : { lat, lon };
+}
+
+// Table and ORDER BY fragments are always literals from the calling module,
+// never request input; only `params` carry user-supplied values.
+function paginate(db, { table, where = '', params = [], orderBy, limit, offset, map }) {
+  const { total } = db.prepare(`SELECT COUNT(*) AS total FROM ${table} ${where}`).get(...params);
+  const rows = db
+    .prepare(`SELECT * FROM ${table} ${where} ORDER BY ${orderBy} LIMIT ? OFFSET ?`)
+    .all(...params, limit, offset);
+  return { total, limit, offset, items: rows.map(map) };
+}
+
+module.exports = { toPosition, paginate };

package/lib/track-recorder.js

@@ -0,0 +1,149 @@
+const { withTransaction } = require('./database');
+const { MAX_REFINEMENT_AGE_MS } = require('./detection');
+const { distanceBetween } = require('./places');
+
+const METRES_PER_SECOND_PER_KNOT = 1852 / 3600;
+
+const SAMPLE_INTERVAL_MS = 1000;
+const TRACK_DEFAULTS = { trackIntervalSeconds: 15 };
+
+// Interval points are skipped until the vessel has moved this far, so a boat
+// waiting at a lock does not pile up identical points.
+const MIN_MOVE_METRES = 10;
+const HEADING_CHANGE_RAD = (15 * Math.PI) / 180;
+// Course over ground is noise at low speed; below this, a swinging boat would
+// log a turn every second.
+const MIN_HEADING_SPEED = 2 * METRES_PER_SECOND_PER_KNOT;
+const SPEED_CHANGE = 1 * METRES_PER_SECOND_PER_KNOT;
+const MIN_CHANGE_SPACING_MS = 2000;
+
+function iso(ms) {
+  return new Date(ms).toISOString();
+}
+
+function finiteOrNull(value) {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+function headingDifference(a, b) {
+  const diff = Math.abs(a - b) % (2 * Math.PI);
+  return diff > Math.PI ? 2 * Math.PI - diff : diff;
+}
+
+function createTrackRecorder({ db, readSelfPath, settings, clock = Date.now }) {
+  const intervalMs = settings.trackIntervalSeconds * 1000;
+
+  let lastFixTimestamp = null;
+  let lastSampled = null;
+  // Detection dates a departure back to when the vessel left its berth, up to
+  // MAX_REFINEMENT_AGE_MS before it opens the entry, and resumes a stopped one
+  // only after averaging. Points wait here until they have a moving passage to
+  // belong to, so the track starts where the passage does.
+  let pending = [];
+  let lastWritten = null;
+
+  function readFix(now) {
+    const node = readSelfPath('navigation.position');
+    if (!node?.timestamp || node.timestamp === lastFixTimestamp) {
+      return null;
+    }
+    lastFixTimestamp = node.timestamp;
+
+    const { value } = node;
+    if (!value || !Number.isFinite(value.latitude) || !Number.isFinite(value.longitude)) {
+      return null;
+    }
+    return {
+      time: now,
+      lat: value.latitude,
+      lon: value.longitude,
+      sog: finiteOrNull(readSelfPath('navigation.speedOverGround')?.value),
+      cog: finiteOrNull(readSelfPath('navigation.courseOverGroundTrue')?.value)
+    };
+  }
+
+  function isWorthKeeping(fix) {
+    if (!lastSampled) {
+      return true;
+    }
+    const elapsed = fix.time - lastSampled.time;
+    if (elapsed >= intervalMs && distanceBetween(lastSampled, fix) >= MIN_MOVE_METRES) {
+      return true;
+    }
+    if (elapsed < MIN_CHANGE_SPACING_MS) {
+      return false;
+    }
+    const turned =
+      fix.sog !== null &&
+      fix.sog >= MIN_HEADING_SPEED &&
+      fix.cog !== null &&
+      lastSampled.cog !== null &&
+      headingDifference(fix.cog, lastSampled.cog) >= HEADING_CHANGE_RAD;
+    const changedSpeed =
+      fix.sog !== null &&
+      lastSampled.sog !== null &&
+      Math.abs(fix.sog - lastSampled.sog) >= SPEED_CHANGE;
+    return turned || changedSpeed;
+  }
+
+  function lastPointOf(entryId) {
+    const row = db
+      .prepare(
+        'SELECT time, lat, lon FROM track_points WHERE entry_id = ? ORDER BY time DESC, id DESC LIMIT 1'
+      )
+      .get(entryId);
+    return row ? { entryId, time: Date.parse(row.time), lat: row.lat, lon: row.lon } : null;
+  }
+
+  function flush(entry, now) {
+    withTransaction(db, () => {
+      let previous = lastWritten?.entryId === entry.id ? lastWritten : lastPointOf(entry.id);
+      const startedAt = Date.parse(entry.start_time);
+      const insert = db.prepare(
+        'INSERT INTO track_points (entry_id, time, lat, lon, sog, cog) VALUES (?, ?, ?, ?, ?, ?)'
+      );
+
+      let added = 0;
+      for (const point of pending) {
+        if (point.time < startedAt || (previous && point.time <= previous.time)) {
+          continue;
+        }
+        insert.run(entry.id, iso(point.time), point.lat, point.lon, point.sog, point.cog);
+        if (previous) {
+          added += distanceBetween(previous, point);
+        }
+        previous = { entryId: entry.id, time: point.time, lat: point.lat, lon: point.lon };
+      }
+
+      if (added > 0) {
+        db.prepare(
+          'UPDATE log_entries SET distance = distance + ?, updated_at = ? WHERE id = ?'
+        ).run(added, iso(now), entry.id);
+      }
+      lastWritten = previous;
+    });
+    pending = [];
+  }
+
+  return {
+    sample() {
+      const now = clock();
+      const fix = readFix(now);
+      if (!fix || !isWorthKeeping(fix)) {
+        return;
+      }
+      lastSampled = fix;
+      pending.push(fix);
+      pending = pending.filter((point) => point.time >= now - MAX_REFINEMENT_AGE_MS);
+
+      const entry = db
+        .prepare("SELECT id, start_time, stopped_since FROM log_entries WHERE state = 'active'")
+        .get();
+      if (entry && entry.stopped_since === null) {
+        flush(entry, now);
+      }
+    }
+  };
+}
+
+module.exports = { createTrackRecorder, SAMPLE_INTERVAL_MS, TRACK_DEFAULTS };

package/lib/track.js

@@ -0,0 +1,58 @@
+const { requireEntryRow } = require('./entries');
+const { toPosition, paginate } = require('./rows');
+
+function toTrackPoint(row) {
+  return { time: row.time, lat: row.lat, lon: row.lon, sog: row.sog, cog: row.cog };
+}
+
+function toObservation(row) {
+  return {
+    id: row.id,
+    time: row.time,
+    reason: row.reason,
+    position: toPosition(row.lat, row.lon),
+    sog: row.sog,
+    cog: row.cog,
+    heading: row.heading,
+    stw: row.stw,
+    twd: row.twd,
+    tws: row.tws,
+    awa: row.awa,
+    aws: row.aws,
+    depth: row.depth,
+    pressure: row.pressure,
+    airTemp: row.air_temp,
+    waterTemp: row.water_temp,
+    tripLog: row.trip_log,
+    engineRuntime: row.engine_runtime
+  };
+}
+
+function allTrackPoints(db, entryId) {
+  return db
+    .prepare('SELECT * FROM track_points WHERE entry_id = ? ORDER BY time, id')
+    .all(entryId)
+    .map(toTrackPoint);
+}
+
+function allObservations(db, entryId) {
+  return db
+    .prepare('SELECT * FROM observations WHERE entry_id = ? ORDER BY time, id')
+    .all(entryId)
+    .map(toObservation);
+}
+
+function listObservations(db, entryId, { limit, offset }) {
+  requireEntryRow(db, entryId);
+  return paginate(db, {
+    table: 'observations',
+    where: 'WHERE entry_id = ?',
+    params: [entryId],
+    orderBy: 'time, id',
+    limit,
+    offset,
+    map: toObservation
+  });
+}
+
+module.exports = { allTrackPoints, allObservations, listObservations };