signalk-chiplog 1.0.0

package/lib/entries.js

@@ -0,0 +1,345 @@
+const { withTransaction } = require('./database');
+const { badRequest, conflict, notFound } = require('./errors');
+const { coordinatesName, initialPlaceName } = require('./place-names');
+const { distanceBetween, rememberPlaceName } = require('./places');
+const { toPosition, paginate } = require('./rows');
+
+const CHILD_TABLES = ['track_points', 'observations', 'propulsion_segments', 'events'];
+
+// Still this close to where the last passage ended, the vessel is at that
+// passage's destination: an alarm or a note there belongs to it.
+const STILL_AT_ARRIVAL_METRES = 1852;
+
+function toEntry(row) {
+  return {
+    id: row.id,
+    state: row.state,
+    startTime: row.start_time,
+    endTime: row.end_time,
+    stoppedSince: row.stopped_since,
+    startPosition: toPosition(row.start_lat, row.start_lon),
+    endPosition: toPosition(row.end_lat, row.end_lon),
+    startPlaceId: row.start_place_id,
+    endPlaceId: row.end_place_id,
+    startPlaceName: row.start_place_name,
+    endPlaceName: row.end_place_name,
+    startPlacePending: row.start_place_pending === 1,
+    endPlacePending: row.end_place_pending === 1,
+    distance: row.distance,
+    engineDuration: row.engine_duration,
+    sailDuration: row.sail_duration,
+    openedByEventId: row.opened_by_event_id,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at
+  };
+}
+
+function requireEntryRow(db, id) {
+  const row = db.prepare('SELECT * FROM log_entries WHERE id = ?').get(id);
+  if (!row) {
+    throw notFound('entry', id);
+  }
+  return row;
+}
+
+function listEntries(db, { from, to, limit, offset }) {
+  const conditions = [];
+  const params = [];
+  if (from !== undefined) {
+    conditions.push('start_time >= ?');
+    params.push(from);
+  }
+  if (to !== undefined) {
+    conditions.push('start_time < ?');
+    params.push(to);
+  }
+  return paginate(db, {
+    table: 'log_entries',
+    where: conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '',
+    params,
+    orderBy: 'start_time DESC, id DESC',
+    limit,
+    offset,
+    map: toEntry
+  });
+}
+
+function getEntry(db, id) {
+  const entry = toEntry(requireEntryRow(db, id));
+  const count = (table) =>
+    db.prepare(`SELECT COUNT(*) AS n FROM ${table} WHERE entry_id = ?`).get(id).n;
+  return {
+    ...entry,
+    counts: {
+      trackPoints: count('track_points'),
+      observations: count('observations'),
+      events: count('events')
+    }
+  };
+}
+
+// A segment still open counts up to `now`, so the totals of a passage in
+// progress stay current.
+function recomputeDurations(db, entryId, now) {
+  const totals = db
+    .prepare(
+      `SELECT type,
+         SUM(MAX(0, (julianday(COALESCE(end_time, ?)) - julianday(start_time)) * 86400)) AS seconds
+       FROM propulsion_segments
+       WHERE entry_id = ?
+       GROUP BY type`
+    )
+    .all(now, entryId);
+  const secondsOf = (type) => Math.round(totals.find((t) => t.type === type)?.seconds ?? 0);
+  db.prepare(
+    'UPDATE log_entries SET engine_duration = ?, sail_duration = ?, updated_at = ? WHERE id = ?'
+  ).run(secondsOf('engine'), secondsOf('sail'), now, entryId);
+}
+
+function updateEntry(db, id, patch, { placeMatchRadius, now }) {
+  return withTransaction(db, () => {
+    const row = requireEntryRow(db, id);
+    const next = { ...row };
+
+    if (patch.startTime !== undefined) {
+      next.start_time = patch.startTime;
+    }
+    if (patch.endTime !== undefined) {
+      if (row.state === 'active') {
+        throw conflict(
+          'entry_active',
+          `Entry ${id} is still in progress; close it rather than setting endTime`
+        );
+      }
+      next.end_time = patch.endTime;
+    }
+    if (next.end_time !== null && next.end_time < next.start_time) {
+      throw badRequest('endTime must not be earlier than startTime');
+    }
+
+    for (const side of ['start', 'end']) {
+      const position = patch[`${side}Position`];
+      const name = patch[`${side}PlaceName`];
+      if (position !== undefined) {
+        next[`${side}_lat`] = position ? position.lat : null;
+        next[`${side}_lon`] = position ? position.lon : null;
+        // A name still generated from coordinates follows the corrected position.
+        if (name === undefined && row[`${side}_place_pending`] === 1) {
+          next[`${side}_place_name`] = position ? coordinatesName(position) : null;
+          next[`${side}_place_pending`] = position ? 1 : 0;
+        }
+      }
+      if (name !== undefined) {
+        const at = toPosition(next[`${side}_lat`], next[`${side}_lon`]);
+        next[`${side}_place_name`] = name;
+        next[`${side}_place_pending`] = 0;
+        next[`${side}_place_id`] =
+          name !== null && at ? rememberPlaceName(db, at, name, placeMatchRadius, now) : null;
+      }
+    }
+
+    if (patch.distance !== undefined) {
+      next.distance = patch.distance;
+    }
+
+    db.prepare(
+      `UPDATE log_entries SET
+         start_time = ?, end_time = ?,
+         start_lat = ?, start_lon = ?, end_lat = ?, end_lon = ?,
+         start_place_id = ?, end_place_id = ?, start_place_name = ?, end_place_name = ?,
+         start_place_pending = ?, end_place_pending = ?,
+         distance = ?, updated_at = ?
+       WHERE id = ?`
+    ).run(
+      next.start_time,
+      next.end_time,
+      next.start_lat,
+      next.start_lon,
+      next.end_lat,
+      next.end_lon,
+      next.start_place_id,
+      next.end_place_id,
+      next.start_place_name,
+      next.end_place_name,
+      next.start_place_pending,
+      next.end_place_pending,
+      next.distance,
+      now,
+      id
+    );
+
+    return getEntry(db, id);
+  });
+}
+
+function closeEntry(db, id, { now, position, placeMatchRadius }) {
+  return withTransaction(db, () => {
+    const row = requireEntryRow(db, id);
+    if (row.state === 'closed') {
+      throw conflict('entry_already_closed', `Entry ${id} is already closed`);
+    }
+    // Closing by hand confirms an arrival: when detection has already seen the
+    // vessel stop, the passage ended then, not when someone pressed the button.
+    const stoppedAt = row.stopped_since ?? now;
+    const endTime = stoppedAt < row.start_time ? row.start_time : stoppedAt;
+    const end = toPosition(row.end_lat, row.end_lon) ?? position;
+    const place =
+      row.end_place_name === null
+        ? initialPlaceName(db, end, placeMatchRadius)
+        : { id: row.end_place_id, name: row.end_place_name, pending: row.end_place_pending };
+
+    db.prepare(
+      `UPDATE log_entries
+       SET state = 'closed', end_time = ?, stopped_since = NULL, end_lat = ?, end_lon = ?,
+           end_place_id = ?, end_place_name = ?, end_place_pending = ?, updated_at = ?
+       WHERE id = ?`
+    ).run(
+      endTime,
+      end ? end.lat : null,
+      end ? end.lon : null,
+      place.id,
+      place.name,
+      place.pending,
+      now,
+      id
+    );
+
+    return getEntry(db, id);
+  });
+}
+
+// The earlier entry survives and absorbs the later one, so the passage keeps
+// its original id and departure.
+function mergeEntries(db, id, otherId, now) {
+  if (id === otherId) {
+    throw badRequest('An entry cannot be merged with itself');
+  }
+
+  return withTransaction(db, () => {
+    const [earlier, later] = [requireEntryRow(db, id), requireEntryRow(db, otherId)].sort(
+      (a, b) => a.start_time.localeCompare(b.start_time) || a.id - b.id
+    );
+
+    if (earlier.state === 'active') {
+      throw conflict(
+        'entry_active',
+        `Entry ${earlier.id} is still in progress and cannot absorb a later entry`
+      );
+    }
+
+    const between = db
+      .prepare(
+        `SELECT COUNT(*) AS n FROM log_entries
+         WHERE id NOT IN (?, ?) AND start_time >= ? AND start_time <= ?`
+      )
+      .get(earlier.id, later.id, earlier.start_time, later.start_time).n;
+    if (between > 0) {
+      throw conflict(
+        'entries_not_consecutive',
+        `Entries ${earlier.id} and ${later.id} are not consecutive`
+      );
+    }
+
+    for (const table of CHILD_TABLES) {
+      db.prepare(`UPDATE ${table} SET entry_id = ? WHERE entry_id = ?`).run(earlier.id, later.id);
+    }
+    // Delete before reopening: if the later entry is active, the single-active
+    // index would otherwise reject the update below.
+    db.prepare('DELETE FROM log_entries WHERE id = ?').run(later.id);
+
+    db.prepare(
+      `UPDATE log_entries SET
+         state = ?, end_time = ?, stopped_since = ?,
+         end_lat = ?, end_lon = ?, end_place_id = ?, end_place_name = ?, end_place_pending = ?,
+         distance = ?, updated_at = ?
+       WHERE id = ?`
+    ).run(
+      later.state,
+      later.end_time,
+      later.stopped_since,
+      later.end_lat,
+      later.end_lon,
+      later.end_place_id,
+      later.end_place_name,
+      later.end_place_pending,
+      earlier.distance + later.distance,
+      now,
+      earlier.id
+    );
+    recomputeDurations(db, earlier.id, now);
+
+    return getEntry(db, earlier.id);
+  });
+}
+
+function activeEntryId(db) {
+  return db.prepare("SELECT id FROM log_entries WHERE state = 'active'").get()?.id ?? null;
+}
+
+// The last passage, while the vessel is still at its arrival; null otherwise.
+function entryNearArrival(db, position) {
+  if (!position) {
+    return null;
+  }
+  const last = db
+    .prepare(
+      `SELECT id, end_lat, end_lon FROM log_entries WHERE state = 'closed'
+       ORDER BY end_time DESC, id DESC LIMIT 1`
+    )
+    .get();
+  const stillThere =
+    last &&
+    last.end_lat !== null &&
+    distanceBetween(position, { lat: last.end_lat, lon: last.end_lon }) <= STILL_AT_ARRIVAL_METRES;
+  return stillThere ? last.id : null;
+}
+
+// A passage opened by the crew casting off, before detection sees the vessel
+// move. It starts stopped, so the first movement resumes it rather than opening
+// another one, and a departure that never happens closes like any long stop.
+function openEntryByHand(db, { time, position, placeMatchRadius, now }) {
+  const previousEnd = db.prepare('SELECT MAX(end_time) AS endTime FROM log_entries').get().endTime;
+  const startTime = previousEnd && time < previousEnd ? previousEnd : time;
+  const place = initialPlaceName(db, position, placeMatchRadius);
+  const { lastInsertRowid } = db
+    .prepare(
+      `INSERT INTO log_entries (
+         state, start_time, stopped_since, start_lat, start_lon, start_place_id, start_place_name,
+         start_place_pending, end_lat, end_lon, created_at, updated_at
+       ) VALUES ('active', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+    )
+    .run(
+      startTime,
+      startTime,
+      position ? position.lat : null,
+      position ? position.lon : null,
+      place.id,
+      place.name,
+      place.pending,
+      position ? position.lat : null,
+      position ? position.lon : null,
+      now,
+      now
+    );
+  return Number(lastInsertRowid);
+}
+
+function deleteEntry(db, id) {
+  requireEntryRow(db, id);
+  db.prepare('DELETE FROM log_entries WHERE id = ?').run(id);
+}
+
+module.exports = {
+  toEntry,
+  requireEntryRow,
+  listEntries,
+  getEntry,
+  updateEntry,
+  closeEntry,
+  mergeEntries,
+  deleteEntry,
+  recomputeDurations,
+  activeEntryId,
+  entryNearArrival,
+  openEntryByHand
+};

package/lib/errors.js

@@ -0,0 +1,22 @@
+class ApiError extends Error {
+  constructor(status, code, message) {
+    super(message);
+    this.status = status;
+    this.code = code;
+  }
+}
+
+function badRequest(message) {
+  return new ApiError(400, 'invalid_request', message);
+}
+
+function notFound(resource, id) {
+  const label = resource.replace(/_/g, ' ');
+  return new ApiError(404, `${resource}_not_found`, `No ${label} with id ${id}`);
+}
+
+function conflict(code, message) {
+  return new ApiError(409, code, message);
+}
+
+module.exports = { ApiError, badRequest, notFound, conflict };

package/lib/event-watcher.js

@@ -0,0 +1,332 @@
+const { createFreshnessTracker } = require('./detection');
+const { activeEntryId, entryNearArrival } = require('./entries');
+
+const METRES_PER_SECOND_PER_KNOT = 1852 / 3600;
+
+const EVENT_DEFAULTS = { windSpeedThresholds: [20, 30], pressureDropThreshold: 4 };
+
+const CHECK_INTERVAL_MS = 1000;
+
+// Any notification reaching these states is critical, whatever its path.
+const CRITICAL_STATES = new Set(['alarm', 'emergency']);
+const NOTIFICATION_METADATA_KEYS = new Set([
+  'meta',
+  'values',
+  '$source',
+  'timestamp',
+  'pgn',
+  'sentence'
+]);
+
+const DISENGAGED_AUTOPILOT_STATES = new Set(['standby', 'off']);
+
+const POSITION_MAX_AGE_MS = 2 * 60 * 1000;
+// Thresholds compare the average over this window, so a gust does not count.
+const WIND_WINDOW_MS = 2 * 60 * 1000;
+const MIN_WIND_COVERAGE_MS = 60 * 1000;
+const WIND_MAX_AGE_MS = 2 * 60 * 1000;
+const PRESSURE_WINDOW_MS = 3 * 60 * 60 * 1000;
+const PRESSURE_SAMPLE_INTERVAL_MS = 60 * 1000;
+const PRESSURE_MAX_AGE_MS = 15 * 60 * 1000;
+
+function iso(ms) {
+  return new Date(ms).toISOString();
+}
+
+function isFiniteNumber(value) {
+  return typeof value === 'number' && Number.isFinite(value);
+}
+
+function collectNotifications(node, path, found, depth = 0) {
+  if (!node || typeof node !== 'object' || depth > 12) {
+    return;
+  }
+  if ('value' in node) {
+    const { value } = node;
+    if (value === null || (typeof value === 'object' && typeof value.state === 'string')) {
+      found.set(path, value);
+    }
+    return;
+  }
+  for (const [key, child] of Object.entries(node)) {
+    if (!NOTIFICATION_METADATA_KEYS.has(key)) {
+      collectNotifications(child, `${path}.${key}`, found, depth + 1);
+    }
+  }
+}
+
+function createEventWatcher({ db, readSelfPath, settings, observe, clock = Date.now }) {
+  const readFresh = createFreshnessTracker(readSelfPath);
+
+  const seenNotifications = new Map();
+  const loggedNotifications = new Map();
+  let autopilot = null;
+  const windSamples = [];
+  const windAbove = new Map();
+  const pressureSamples = [];
+  let pressureFalling = false;
+
+  // An anchor alarm goes off between passages, at the last one's destination.
+  function entryFor(type, position) {
+    const active = activeEntryId(db);
+    if (active !== null || type === 'autopilot') {
+      return active;
+    }
+    return entryNearArrival(db, position);
+  }
+
+  function logEvent(cycle, type, subtype, { comment = null, payload, snapshot }) {
+    const entryId = entryFor(type, cycle.position);
+    if (entryId === null) {
+      return false;
+    }
+    const time = iso(cycle.now);
+    db.prepare(
+      `INSERT INTO events (entry_id, time, type, subtype, lat, lon, comment, payload, source, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'auto', ?)`
+    ).run(
+      entryId,
+      time,
+      type,
+      subtype,
+      cycle.position ? cycle.position.lat : null,
+      cycle.position ? cycle.position.lon : null,
+      comment,
+      JSON.stringify(payload),
+      time
+    );
+    if (snapshot) {
+      cycle.snapshots.add(entryId);
+    }
+    return true;
+  }
+
+  // What was last written for a notification, read from the log the first
+  // time it is seen, so a restart neither repeats an alarm nor forgets that
+  // one was open.
+  function lastLoggedState(path) {
+    if (!loggedNotifications.has(path)) {
+      const row = db
+        .prepare(
+          `SELECT payload FROM events WHERE type = 'sk_alarm' AND subtype = ?
+           ORDER BY time DESC, id DESC LIMIT 1`
+        )
+        .get(path);
+      loggedNotifications.set(path, row ? JSON.parse(row.payload).state : null);
+    }
+    return loggedNotifications.get(path);
+  }
+
+  function checkNotifications(cycle) {
+    const current = new Map();
+    collectNotifications(readSelfPath('notifications'), 'notifications', current);
+    for (const path of seenNotifications.keys()) {
+      if (!current.has(path)) {
+        current.set(path, null);
+      }
+    }
+
+    for (const [path, value] of current) {
+      const state = value?.state ?? 'normal';
+      if (seenNotifications.get(path) === state) {
+        continue;
+      }
+      seenNotifications.set(path, state);
+
+      const logged = lastLoggedState(path);
+      const critical = CRITICAL_STATES.has(state);
+      // Log a critical state not yet logged, or the end of one that was; a
+      // clearing whose alarm never made it into the log is not news.
+      const worthLogging = critical ? logged !== state : CRITICAL_STATES.has(logged);
+      if (!worthLogging) {
+        continue;
+      }
+      const message = value?.message ?? null;
+      if (
+        logEvent(cycle, 'sk_alarm', path, {
+          comment: message,
+          payload: { state, message },
+          snapshot: critical
+        })
+      ) {
+        loggedNotifications.set(path, state);
+      }
+    }
+  }
+
+  function readAutopilotTarget() {
+    const target = readSelfPath('steering.autopilot.target')?.value;
+    if (isFiniteNumber(target)) {
+      return target;
+    }
+    const byKind = {};
+    for (const kind of ['headingTrue', 'headingMagnetic', 'windAngleApparent', 'windAngleTrue']) {
+      const value = readSelfPath(`steering.autopilot.target.${kind}`)?.value;
+      if (isFiniteNumber(value)) {
+        byKind[kind] = value;
+      }
+    }
+    return Object.keys(byKind).length > 0 ? byKind : null;
+  }
+
+  // The Autopilot API publishes `engaged`; older autopilot plugins only a
+  // state such as auto, wind or standby.
+  function readAutopilot() {
+    const state = readSelfPath('steering.autopilot.state')?.value;
+    const mode = readSelfPath('steering.autopilot.mode')?.value;
+    const engagedValue = readSelfPath('steering.autopilot.engaged')?.value;
+
+    let engaged = typeof engagedValue === 'boolean' ? engagedValue : null;
+    if (engaged === null && typeof state === 'string' && state !== 'alarm') {
+      engaged = !DISENGAGED_AUTOPILOT_STATES.has(state);
+    }
+    if (engaged === null) {
+      return null;
+    }
+    return {
+      engaged,
+      mode: typeof mode === 'string' ? mode : null,
+      state: typeof state === 'string' ? state : null
+    };
+  }
+
+  function checkAutopilot(cycle) {
+    const pilot = readAutopilot();
+    if (!pilot) {
+      return;
+    }
+    const activity = pilot.mode ?? pilot.state;
+    const previous = autopilot;
+    autopilot = { engaged: pilot.engaged, activity };
+
+    let subtype = null;
+    if (previous === null) {
+      const last = db
+        .prepare(
+          "SELECT subtype FROM events WHERE type = 'autopilot' ORDER BY time DESC, id DESC LIMIT 1"
+        )
+        .get();
+      if (pilot.engaged && (!last || last.subtype === 'disengaged')) {
+        subtype = 'engaged';
+      } else if (!pilot.engaged && last && last.subtype !== 'disengaged') {
+        subtype = 'disengaged';
+      }
+    } else if (pilot.engaged !== previous.engaged) {
+      subtype = pilot.engaged ? 'engaged' : 'disengaged';
+    } else if (pilot.engaged && activity !== previous.activity) {
+      subtype = 'mode_changed';
+    }
+
+    if (subtype) {
+      // The last target lingers in the data model after disengaging.
+      const target = pilot.engaged ? readAutopilotTarget() : null;
+      logEvent(cycle, 'autopilot', subtype, {
+        payload: { mode: pilot.mode, state: pilot.state, target },
+        snapshot: false
+      });
+    }
+  }
+
+  function checkWind(cycle) {
+    const speed = readFresh('environment.wind.speedTrue', cycle.now, WIND_MAX_AGE_MS);
+    if (isFiniteNumber(speed)) {
+      windSamples.push({ time: cycle.now, speed });
+    }
+    while (windSamples.length > 0 && windSamples[0].time <= cycle.now - WIND_WINDOW_MS) {
+      windSamples.shift();
+    }
+    if (windSamples.length === 0 || cycle.now - windSamples[0].time < MIN_WIND_COVERAGE_MS) {
+      return;
+    }
+    const mean = windSamples.reduce((sum, sample) => sum + sample.speed, 0) / windSamples.length;
+
+    for (const knots of settings.windSpeedThresholds) {
+      const threshold = knots * METRES_PER_SECOND_PER_KNOT;
+      const clearsBelow = threshold - Math.max(2 * METRES_PER_SECOND_PER_KNOT, 0.1 * threshold);
+      const wasAbove = windAbove.get(knots);
+      let isAbove = wasAbove;
+      if (mean >= threshold) {
+        isAbove = true;
+      } else if (mean < clearsBelow) {
+        isAbove = false;
+      }
+      if (isAbove === undefined) {
+        continue;
+      }
+      windAbove.set(knots, isAbove);
+      // The first reading only sets where the wind stands: strong wind already
+      // blowing when the plugin starts is a condition, not a crossing.
+      if (wasAbove !== undefined && wasAbove !== isAbove) {
+        logEvent(cycle, 'weather_threshold', isAbove ? 'wind_above' : 'wind_below', {
+          payload: { threshold, windSpeed: mean },
+          snapshot: true
+        });
+      }
+    }
+  }
+
+  function checkPressure(cycle) {
+    if (!settings.pressureDropThreshold) {
+      return;
+    }
+    const pressure = readFresh('environment.outside.pressure', cycle.now, PRESSURE_MAX_AGE_MS);
+    const latest = pressureSamples.at(-1);
+    if (
+      isFiniteNumber(pressure) &&
+      (!latest || cycle.now - latest.time >= PRESSURE_SAMPLE_INTERVAL_MS)
+    ) {
+      pressureSamples.push({ time: cycle.now, pressure });
+    }
+    while (
+      pressureSamples.length > 1 &&
+      pressureSamples[1].time <= cycle.now - PRESSURE_WINDOW_MS
+    ) {
+      pressureSamples.shift();
+    }
+
+    const current = pressureSamples.at(-1);
+    const reference = pressureSamples[0];
+    if (
+      !current ||
+      cycle.now - current.time > PRESSURE_MAX_AGE_MS ||
+      current.time - reference.time < PRESSURE_WINDOW_MS
+    ) {
+      return;
+    }
+
+    const drop = reference.pressure - current.pressure;
+    const threshold = settings.pressureDropThreshold * 100;
+    if (!pressureFalling && drop >= threshold) {
+      pressureFalling = true;
+      logEvent(cycle, 'weather_threshold', 'pressure_drop', {
+        payload: { drop, over: PRESSURE_WINDOW_MS / 1000, pressure: current.pressure },
+        snapshot: true
+      });
+    } else if (pressureFalling && drop < threshold / 2) {
+      pressureFalling = false;
+    }
+  }
+
+  return {
+    check() {
+      const now = clock();
+      const fix = readFresh('navigation.position', now, POSITION_MAX_AGE_MS);
+      const position =
+        fix && Number.isFinite(fix.latitude) && Number.isFinite(fix.longitude)
+          ? { lat: fix.latitude, lon: fix.longitude }
+          : null;
+      const cycle = { now, position, snapshots: new Set() };
+
+      checkNotifications(cycle);
+      checkAutopilot(cycle);
+      checkWind(cycle);
+      checkPressure(cycle);
+
+      for (const entryId of cycle.snapshots) {
+        observe(entryId, iso(now));
+      }
+    }
+  };
+}
+
+module.exports = { createEventWatcher, EVENT_DEFAULTS, CHECK_INTERVAL_MS };