signalk-chiplog 1.0.0

package/lib/formats.js

@@ -0,0 +1,215 @@
+// Rendering for human-facing exports. This is the presentation layer the data
+// model defers unit conversion to: the database stays in Signal K SI units.
+
+const KNOTS_PER_MPS = 3600 / 1852;
+const METRES_PER_NM = 1852;
+
+function convert(value, fn, digits) {
+  return value === null || value === undefined ? null : Number(fn(value).toFixed(digits));
+}
+
+const radiansToDegrees = (rad) => (rad * 180) / Math.PI;
+const wrap360 = (degrees) => ((degrees % 360) + 360) % 360;
+
+const toKnots = (value) => convert(value, (mps) => mps * KNOTS_PER_MPS, 1);
+
+function toBearing(value) {
+  const degrees = convert(value, (rad) => wrap360(radiansToDegrees(rad)), 0);
+  return degrees === 360 ? 0 : degrees;
+}
+
+const toSignedAngle = (value) =>
+  convert(value, (rad) => wrap360(radiansToDegrees(rad) + 180) - 180, 0);
+const toHectopascals = (value) => convert(value, (pa) => pa / 100, 1);
+const toCelsius = (value) => convert(value, (k) => k - 273.15, 1);
+const toNauticalMiles = (value) => convert(value, (m) => m / METRES_PER_NM, 1);
+const toHours = (value) => convert(value, (s) => s / 3600, 1);
+const toMetres = (value) => convert(value, (m) => m, 1);
+const toCoordinate = (value) => convert(value, (deg) => deg, 6);
+
+function toGeoJson(entry, trackPoints) {
+  const coordinates = trackPoints.map((point) => [point.lon, point.lat]);
+  let geometry = null;
+  if (coordinates.length === 1) {
+    geometry = { type: 'Point', coordinates: coordinates[0] };
+  } else if (coordinates.length > 1) {
+    geometry = { type: 'LineString', coordinates };
+  }
+  return {
+    type: 'Feature',
+    geometry,
+    properties: {
+      entryId: entry.id,
+      startTime: entry.startTime,
+      endTime: entry.endTime,
+      startPlaceName: entry.startPlaceName,
+      endPlaceName: entry.endPlaceName,
+      coordTimes: trackPoints.map((point) => point.time)
+    }
+  };
+}
+
+const XML_ESCAPES = { '<': '&lt;', '>': '&gt;', '&': '&amp;', "'": '&apos;', '"': '&quot;' };
+
+function escapeXml(value) {
+  return String(value).replace(/[<>&'"]/g, (char) => XML_ESCAPES[char]);
+}
+
+function trackName(entry) {
+  const places = [entry.startPlaceName, entry.endPlaceName].filter(Boolean).join(' - ');
+  return places || `Passage of ${entry.startTime.slice(0, 10)}`;
+}
+
+function toGpx(bundles) {
+  const tracks = bundles.map(({ entry, trackPoints }) => {
+    const points = trackPoints
+      .map(
+        (point) =>
+          `      <trkpt lat="${point.lat}" lon="${point.lon}"><time>${point.time}</time></trkpt>`
+      )
+      .join('\n');
+    return [
+      '  <trk>',
+      `    <name>${escapeXml(trackName(entry))}</name>`,
+      '    <trkseg>',
+      points,
+      '    </trkseg>',
+      '  </trk>'
+    ]
+      .filter((line) => line !== '')
+      .join('\n');
+  });
+
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<gpx version="1.1" creator="signalk-chiplog" xmlns="http://www.topografix.com/GPX/1/1">',
+    ...tracks,
+    '</gpx>',
+    ''
+  ].join('\n');
+}
+
+const CSV_COLUMNS = [
+  'entry_id',
+  'time_utc',
+  'kind',
+  'type',
+  'subtype',
+  'place',
+  'lat',
+  'lon',
+  'sog_kn',
+  'cog_deg',
+  'heading_deg',
+  'stw_kn',
+  'tws_kn',
+  'twd_deg',
+  'aws_kn',
+  'awa_deg',
+  'depth_m',
+  'pressure_hpa',
+  'air_temp_c',
+  'water_temp_c',
+  'trip_log_nm',
+  'engine_runtime_h',
+  'comment'
+];
+
+const KIND_ORDER = { departure: 0, observation: 1, event: 2, arrival: 3 };
+
+function csvCell(value) {
+  if (value === null || value === undefined) {
+    return '';
+  }
+  if (typeof value !== 'string') {
+    return String(value);
+  }
+  // Spreadsheets execute cells starting with these characters as formulas;
+  // comments and place names are free text typed by the crew.
+  const text = /^[=+\-@\t\r]/.test(value) ? `'${value}` : value;
+  return /[",\r\n]/.test(text) ? `"${text.replace(/"/g, '""')}"` : text;
+}
+
+function positionColumns(position) {
+  return {
+    lat: toCoordinate(position?.lat),
+    lon: toCoordinate(position?.lon)
+  };
+}
+
+// One chronological line per departure, observation, event and arrival: the
+// shape of a paper logbook, readable without the plugin.
+function toCsv(bundles) {
+  const rows = [];
+
+  for (const { entry, observations, events } of bundles) {
+    rows.push({
+      entry_id: entry.id,
+      time_utc: entry.startTime,
+      kind: 'departure',
+      place: entry.startPlaceName,
+      ...positionColumns(entry.startPosition)
+    });
+
+    for (const observation of observations) {
+      rows.push({
+        entry_id: entry.id,
+        time_utc: observation.time,
+        kind: 'observation',
+        type: observation.reason,
+        ...positionColumns(observation.position),
+        sog_kn: toKnots(observation.sog),
+        cog_deg: toBearing(observation.cog),
+        heading_deg: toBearing(observation.heading),
+        stw_kn: toKnots(observation.stw),
+        tws_kn: toKnots(observation.tws),
+        twd_deg: toBearing(observation.twd),
+        aws_kn: toKnots(observation.aws),
+        awa_deg: toSignedAngle(observation.awa),
+        depth_m: toMetres(observation.depth),
+        pressure_hpa: toHectopascals(observation.pressure),
+        air_temp_c: toCelsius(observation.airTemp),
+        water_temp_c: toCelsius(observation.waterTemp),
+        trip_log_nm: toNauticalMiles(observation.tripLog),
+        engine_runtime_h: toHours(observation.engineRuntime)
+      });
+    }
+
+    for (const event of events) {
+      rows.push({
+        entry_id: entry.id,
+        time_utc: event.time,
+        kind: 'event',
+        type: event.type,
+        subtype: event.subtype,
+        ...positionColumns(event.position),
+        comment: event.comment
+      });
+    }
+
+    if (entry.endTime) {
+      rows.push({
+        entry_id: entry.id,
+        time_utc: entry.endTime,
+        kind: 'arrival',
+        place: entry.endPlaceName,
+        ...positionColumns(entry.endPosition)
+      });
+    }
+  }
+
+  rows.sort(
+    (a, b) =>
+      a.time_utc.localeCompare(b.time_utc) ||
+      a.entry_id - b.entry_id ||
+      KIND_ORDER[a.kind] - KIND_ORDER[b.kind]
+  );
+
+  const lines = [CSV_COLUMNS.join(',')];
+  for (const row of rows) {
+    lines.push(CSV_COLUMNS.map((column) => csvCell(row[column])).join(','));
+  }
+  return `${lines.join('\r\n')}\r\n`;
+}
+
+module.exports = { toGeoJson, toGpx, toCsv };

package/lib/manoeuvre-types.js

@@ -0,0 +1,84 @@
+const { badRequest, conflict, notFound } = require('./errors');
+const { paginate } = require('./rows');
+
+const KEY_PATTERN = /^[a-z0-9_]{1,40}$/;
+
+function toManoeuvreType(row) {
+  return {
+    key: row.key,
+    label: row.label,
+    icon: row.icon,
+    sortOrder: row.sort_order,
+    builtin: row.builtin === 1,
+    enabled: row.enabled === 1
+  };
+}
+
+function requireTypeRow(db, key) {
+  const row = db.prepare('SELECT * FROM manoeuvre_types WHERE key = ?').get(key);
+  if (!row) {
+    throw notFound('manoeuvre_type', key);
+  }
+  return row;
+}
+
+function listManoeuvreTypes(db, { limit, offset }) {
+  return paginate(db, {
+    table: 'manoeuvre_types',
+    orderBy: 'sort_order, key',
+    limit,
+    offset,
+    map: toManoeuvreType
+  });
+}
+
+function createManoeuvreType(db, { key, label, icon, sortOrder, enabled }) {
+  if (!KEY_PATTERN.test(key)) {
+    throw badRequest('key must be 1-40 characters of lowercase letters, digits or underscores');
+  }
+  if (db.prepare('SELECT 1 FROM manoeuvre_types WHERE key = ?').get(key)) {
+    throw conflict('manoeuvre_type_exists', `A manoeuvre type with key ${key} already exists`);
+  }
+
+  const order =
+    sortOrder ??
+    db.prepare('SELECT COALESCE(MAX(sort_order), 0) + 10 AS next FROM manoeuvre_types').get().next;
+  db.prepare(
+    `INSERT INTO manoeuvre_types (key, label, icon, sort_order, builtin, enabled)
+     VALUES (?, ?, ?, ?, 0, ?)`
+  ).run(key, label, icon ?? null, order, enabled === false ? 0 : 1);
+
+  return toManoeuvreType(requireTypeRow(db, key));
+}
+
+function updateManoeuvreType(db, key, patch) {
+  const row = requireTypeRow(db, key);
+  db.prepare(
+    'UPDATE manoeuvre_types SET label = ?, icon = ?, sort_order = ?, enabled = ? WHERE key = ?'
+  ).run(
+    patch.label ?? row.label,
+    patch.icon !== undefined ? patch.icon : row.icon,
+    patch.sortOrder ?? row.sort_order,
+    patch.enabled === undefined ? row.enabled : Number(patch.enabled),
+    key
+  );
+  return toManoeuvreType(requireTypeRow(db, key));
+}
+
+function deleteManoeuvreType(db, key) {
+  const row = requireTypeRow(db, key);
+  if (row.builtin === 1) {
+    throw conflict(
+      'builtin_manoeuvre_type',
+      `${key} is built in and cannot be deleted; disable it instead`
+    );
+  }
+  db.prepare('DELETE FROM manoeuvre_types WHERE key = ?').run(key);
+}
+
+module.exports = {
+  listManoeuvreTypes,
+  createManoeuvreType,
+  updateManoeuvreType,
+  deleteManoeuvreType
+};

package/lib/observation-recorder.js

@@ -0,0 +1,152 @@
+const OBSERVATION_DEFAULTS = { observationIntervalMinutes: 60 };
+
+// Navigation, wind and depth arrive several times a second; barometer and
+// temperatures can be minutes apart.
+const FAST_MAX_AGE_MS = 2 * 60 * 1000;
+const SLOW_MAX_AGE_MS = 15 * 60 * 1000;
+
+const COLUMNS = [
+  'lat',
+  'lon',
+  'sog',
+  'cog',
+  'heading',
+  'stw',
+  'twd',
+  'tws',
+  'awa',
+  'aws',
+  'depth',
+  'pressure',
+  'air_temp',
+  'water_temp',
+  'trip_log',
+  'engine_runtime'
+];
+
+function iso(ms) {
+  return new Date(ms).toISOString();
+}
+
+function finiteOrNull(value) {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+function normalizeAngle(radians) {
+  return ((radians % (2 * Math.PI)) + 2 * Math.PI) % (2 * Math.PI);
+}
+
+function createObservationRecorder({ db, readSelfPath, readFresh, settings }) {
+  const intervalMs = settings.observationIntervalMinutes * 60 * 1000;
+  let latest = {};
+
+  const fast = (path, now) => finiteOrNull(readFresh(path, now, FAST_MAX_AGE_MS));
+  const slow = (path, now) => finiteOrNull(readFresh(path, now, SLOW_MAX_AGE_MS));
+  // A counter's last value stays a true reading while it does not move: engine
+  // hours with the engine off, the trip log at anchor.
+  const counter = (path) => finiteOrNull(readSelfPath(path)?.value);
+
+  function engineRuntime() {
+    const engines = Object.keys(readSelfPath('propulsion') ?? {});
+    const ordered = engines.includes('main') ? ['main', ...engines] : engines;
+    for (const id of ordered) {
+      const runtime = counter(`propulsion.${id}.runTime`);
+      if (runtime !== null) {
+        return runtime;
+      }
+    }
+    return null;
+  }
+
+  // Called every detection cycle, not only when a snapshot is due: freshness is
+  // judged by timestamps changing between reads, so a sensor read once an hour
+  // would look current as long as it had changed at any point in that hour.
+  function sense(now) {
+    const position = readFresh('navigation.position', now, FAST_MAX_AGE_MS);
+    const headingTrue = fast('navigation.headingTrue', now);
+    const headingMagnetic = fast('navigation.headingMagnetic', now);
+    const variation = slow('navigation.magneticVariation', now);
+    const belowSurface = fast('environment.depth.belowSurface', now);
+    const belowTransducer = fast('environment.depth.belowTransducer', now);
+
+    const hasPosition =
+      position && Number.isFinite(position.latitude) && Number.isFinite(position.longitude);
+
+    latest = {
+      lat: hasPosition ? position.latitude : null,
+      lon: hasPosition ? position.longitude : null,
+      sog: fast('navigation.speedOverGround', now),
+      cog: fast('navigation.courseOverGroundTrue', now),
+      heading:
+        headingTrue ??
+        (headingMagnetic !== null && variation !== null
+          ? normalizeAngle(headingMagnetic + variation)
+          : null),
+      stw: fast('navigation.speedThroughWater', now),
+      twd: fast('environment.wind.directionTrue', now),
+      tws: fast('environment.wind.speedTrue', now),
+      awa: fast('environment.wind.angleApparent', now),
+      aws: fast('environment.wind.speedApparent', now),
+      depth: belowSurface ?? belowTransducer,
+      pressure: slow('environment.outside.pressure', now),
+      air_temp: slow('environment.outside.temperature', now),
+      water_temp: slow('environment.water.temperature', now),
+      trip_log: counter('navigation.trip.log'),
+      engine_runtime: engineRuntime()
+    };
+  }
+
+  function record(entryId, reason, time) {
+    if (COLUMNS.every((column) => latest[column] === null)) {
+      return null;
+    }
+    const { lastInsertRowid } = db
+      .prepare(
+        `INSERT INTO observations (entry_id, time, reason, ${COLUMNS.join(', ')})
+         VALUES (?, ?, ?, ${COLUMNS.map(() => '?').join(', ')})`
+      )
+      .run(entryId, time, reason, ...COLUMNS.map((column) => latest[column]));
+    return Number(lastInsertRowid);
+  }
+
+  // Periodic snapshots fall on clock boundaries — on the hour by default — as
+  // on a paper log. Any snapshot already in the slot, such as one taken for an
+  // event, stands in for the periodic one.
+  function recordPeriodic(entry, now) {
+    const { lastTime } = db
+      .prepare('SELECT MAX(time) AS lastTime FROM observations WHERE entry_id = ?')
+      .get(entry.id);
+    const lastSlot = Math.floor(Date.parse(lastTime ?? entry.start_time) / intervalMs);
+    if (Math.floor(now / intervalMs) > lastSlot) {
+      record(entry.id, 'periodic', iso(now));
+    }
+  }
+
+  return {
+    sense,
+
+    // Runs inside detection's transaction, with what this cycle did to passages.
+    afterDetection(now, { opened, closed }) {
+      if (closed && !closed.late) {
+        record(closed.id, 'entry_end', iso(now));
+      }
+      if (opened) {
+        record(opened, 'entry_start', iso(now));
+        return;
+      }
+      const entry = db
+        .prepare("SELECT id, start_time FROM log_entries WHERE state = 'active'")
+        .get();
+      if (entry) {
+        recordPeriodic(entry, now);
+      }
+    },
+
+    recordEvent(entryId, time, now) {
+      sense(now);
+      return record(entryId, 'event', time);
+    }
+  };
+}
+
+module.exports = { createObservationRecorder, OBSERVATION_DEFAULTS };

package/lib/place-names.js

@@ -0,0 +1,208 @@
+const { withTransaction } = require('./database');
+const { findNearestPlace } = require('./places');
+
+const GEOCODING_DEFAULTS = {
+  geocodingEnabled: true,
+  geocodingUrl: 'https://nominatim.openstreetmap.org'
+};
+
+const REQUEST_TIMEOUT_MS = 10 * 1000;
+// Nominatim's usage policy allows at most one request per second.
+const NEXT_LOOKUP_MS = 2 * 1000;
+const IDLE_MS = 60 * 1000;
+// Offline is the normal state at sea; retry patiently rather than hammering.
+const FIRST_RETRY_MS = 5 * 60 * 1000;
+const MAX_RETRY_MS = 60 * 60 * 1000;
+
+const HARBOUR_TYPES = new Set(['marina', 'harbour', 'port']);
+const SETTLEMENT_KEYS = [
+  'city',
+  'town',
+  'village',
+  'hamlet',
+  'isolated_dwelling',
+  'locality',
+  'island',
+  'municipality'
+];
+const DISTRICT_KEYS = ['quarter', 'suburb', 'neighbourhood', 'city_district'];
+
+function coordinatesName({ lat, lon }) {
+  const latitude = `${Math.abs(lat).toFixed(4)}${lat >= 0 ? 'N' : 'S'}`;
+  const longitude = `${Math.abs(lon).toFixed(4)}${lon >= 0 ? 'E' : 'W'}`;
+  return `${latitude} ${longitude}`;
+}
+
+// Name for a departure or arrival as it happens: a known place, or failing
+// that a name from coordinates left pending until geocoding answers.
+function initialPlaceName(db, position, radius) {
+  if (!position) {
+    return { id: null, name: null, pending: 0 };
+  }
+  const place = findNearestPlace(db, position, radius);
+  return place
+    ? { id: place.id, name: place.name, pending: 0 }
+    : { id: null, name: coordinatesName(position), pending: 1 };
+}
+
+// Near a marina Nominatim tends to answer with the quay's road, and at sea with
+// a bare administrative boundary: neither is a logbook place name. The
+// settlement, with its district when there is one, is.
+function pickName(result) {
+  if (result.name && HARBOUR_TYPES.has(result.type)) {
+    return result.name;
+  }
+  const address = result.address ?? {};
+  const settlement = SETTLEMENT_KEYS.map((key) => address[key]).find(Boolean);
+  if (!settlement) {
+    return null;
+  }
+  const district = DISTRICT_KEYS.map((key) => address[key]).find(Boolean);
+  return district && district !== settlement ? `${settlement} (${district})` : settlement;
+}
+
+function createPlaceNamer({ db, settings, userAgent, fetch = globalThis.fetch }) {
+  const stopping = new AbortController();
+  let failures = 0;
+
+  function nextPending() {
+    return db
+      .prepare(
+        `SELECT id, 'start' AS side, start_lat AS lat, start_lon AS lon FROM log_entries
+         WHERE start_place_pending = 1 AND start_lat IS NOT NULL
+         UNION ALL
+         SELECT id, 'end' AS side, end_lat AS lat, end_lon AS lon FROM log_entries
+         WHERE end_place_pending = 1 AND end_lat IS NOT NULL
+         ORDER BY id DESC, side DESC
+         LIMIT 1`
+      )
+      .get();
+  }
+
+  // Only a name still pending for the position that was looked up is replaced:
+  // a name typed, or a position corrected, while the lookup was out stays.
+  function settle({ id, side, lat, lon }, place) {
+    const prefix = side === 'start' ? 'start' : 'end';
+    const stillAsLookedUp = `id = ? AND ${prefix}_place_pending = 1 AND ${prefix}_lat = ? AND ${prefix}_lon = ?`;
+    if (place) {
+      db.prepare(
+        `UPDATE log_entries
+         SET ${prefix}_place_name = ?, ${prefix}_place_id = ?, ${prefix}_place_pending = 0
+         WHERE ${stillAsLookedUp}`
+      ).run(place.name, place.id, id, lat, lon);
+    } else {
+      db.prepare(`UPDATE log_entries SET ${prefix}_place_pending = 0 WHERE ${stillAsLookedUp}`).run(
+        id,
+        lat,
+        lon
+      );
+    }
+  }
+
+  // The places table is the geocoding cache: the next departure or arrival
+  // within the radius is named from it, with no request.
+  function rememberGeocoded(name, { lat, lon }) {
+    const now = new Date().toISOString();
+    const { lastInsertRowid } = db
+      .prepare(
+        `INSERT INTO places (name, lat, lon, source, created_at, updated_at)
+         VALUES (?, ?, ?, 'geocoding', ?, ?)`
+      )
+      .run(name, lat, lon, now, now);
+    return { id: Number(lastInsertRowid), name };
+  }
+
+  async function lookup({ lat, lon }) {
+    const base = settings.geocodingUrl.endsWith('/')
+      ? settings.geocodingUrl
+      : `${settings.geocodingUrl}/`;
+    const url = new URL('reverse', base);
+    url.searchParams.set('format', 'jsonv2');
+    url.searchParams.set('lat', String(lat));
+    url.searchParams.set('lon', String(lon));
+    url.searchParams.set('zoom', '17');
+    url.searchParams.set('addressdetails', '1');
+
+    const response = await fetch(url, {
+      headers: { 'User-Agent': userAgent, Accept: 'application/json' },
+      signal: AbortSignal.any([stopping.signal, AbortSignal.timeout(REQUEST_TIMEOUT_MS)])
+    });
+    // Rate limiting, server trouble or a refused client are worth retrying
+    // later; anything else about this position is a final answer.
+    if (
+      response.status === 401 ||
+      response.status === 403 ||
+      response.status === 429 ||
+      response.status >= 500
+    ) {
+      throw new Error(`Geocoding service answered HTTP ${response.status}`);
+    }
+    if (!response.ok) {
+      return null;
+    }
+    const result = await response.json();
+    return result.error ? null : pickName(result);
+  }
+
+  return {
+    async resolveNext() {
+      if (!settings.geocodingEnabled) {
+        return { outcome: 'disabled', retryInMs: IDLE_MS };
+      }
+      const pending = nextPending();
+      if (!pending) {
+        return { outcome: 'idle', retryInMs: IDLE_MS };
+      }
+
+      // A lookup for a nearby departure or arrival may already have named it.
+      const known = findNearestPlace(db, pending, settings.placeMatchRadius);
+      if (known) {
+        settle(pending, known);
+        return { outcome: 'known', retryInMs: 0 };
+      }
+
+      let name;
+      try {
+        name = await lookup(pending);
+      } catch (error) {
+        if (stopping.signal.aborted) {
+          return { outcome: 'stopped' };
+        }
+        failures += 1;
+        return {
+          outcome: 'failed',
+          error,
+          retryInMs: Math.min(FIRST_RETRY_MS * 2 ** (failures - 1), MAX_RETRY_MS)
+        };
+      }
+      if (stopping.signal.aborted) {
+        return { outcome: 'stopped' };
+      }
+      failures = 0;
+
+      if (!name) {
+        settle(pending, null);
+        return { outcome: 'no_result', retryInMs: NEXT_LOOKUP_MS };
+      }
+      withTransaction(db, () => {
+        const place =
+          findNearestPlace(db, pending, settings.placeMatchRadius) ??
+          rememberGeocoded(name, pending);
+        settle(pending, place);
+      });
+      return { outcome: 'resolved', name, retryInMs: NEXT_LOOKUP_MS };
+    },
+
+    stop() {
+      stopping.abort();
+    }
+  };
+}
+
+module.exports = {
+  coordinatesName,
+  initialPlaceName,
+  pickName,
+  createPlaceNamer,
+  GEOCODING_DEFAULTS
+};