sk-ais-status-plugin 1.0.0

package/.prettierrc.json

@@ -0,0 +1,5 @@
+{
+  "semi": false,
+  "singleQuote": true,
+  "trailingComma": "none"
+}

package/README.md

@@ -0,0 +1,164 @@
+# Signal K AIS Status Plugin
+This plugin evaluates AIS target reporting continuity and maintains a per-target tracking state using class-specific timing thresholds. It publishes `sensors.ais.status` deltas to Signal K, enabling consuming applications to assess target validity, reliability, and reporting continuity.
+
+## About
+AIS reception is often intermittent (collisions, range, antenna shadowing), so a single position report does not necessarily mean a target is reliably tracked, and an old position may be unsafe to treat as current. The published state (`unconfirmed`, `confirmed`, `lost`, `remove`) lets clients display and filter targets appropriately and avoid “ghost” or stale tracks.
+
+### A Note About Client State Interpretation
+Client applications are free to interpret the state, but the basic intended UX is:
+
+- `unconfirmed`: show the target, but de-emphasize it (e.g. faded / dotted / “suspect”). Avoid using it for alarms until it becomes confirmed.
+- `confirmed`: show normally and treat as an active track.
+- `lost`: keep showing the last known position briefly, but clearly indicate staleness (e.g. greyed out with “age since last update”). Typically suppress CPA/guard-zone style alarms for lost targets.
+- `remove`: remove the target from display and lists.
+
+Keeping `unconfirmed` and `lost` targets visible (but styled differently) helps avoid clutter from one-off decodes while still preserving situational awareness when reception is intermittent.
+
+## Plugin AIS Target State Management
+The plugin applies standardized timing and continuity rules to manage AIS targets throughout their tracking lifecycle. Targets are created on first reception, transition to a confirmed tracking state after sufficient report continuity, and are marked as lost when expected reports are no longer received. The resulting tracking state is continuously updated and published for use by downstream consumers.
+
+### Sources (input scope)
+Subscribes to deltas with the following contexts to determine which entities/updates are tracked:
+- vessels
+- atons
+- shore.basestations
+- sar
+- aircraft
+
+### Target identity & indexing (stable identity)
+The Signal K `context` string is the primary key for in-memory tracking. One item per context. No MMSI indexing or conflict handling is performed by the plugin.
+
+### Position report rules (message quality)
+Each `navigation.position` update advances the tracking state and updates `lastPosition`.
+
+### State thresholds by class (reliability tuning)
+Class A confirms quickly and times out quickly; Class B confirms slower and times out slower, etc. See [Device Class Processing Definition](#device-class-processing-definition) for class details. 
+
+### Class resolution (source vs fallback)
+The plugin prefers `sensors.ais.class` when it is present and one of the supported values. If it is missing or unsupported, the class falls back to the target context. Unsupported values are logged at debug level.
+
+Fallback mapping:
+- `atons.*` -> `ATON`
+- `shore.basestations.*` -> `BASE`
+- `sar.*` -> `SAR`
+- `aircraft.*` -> `AIRCRAFT`
+- otherwise -> `B`
+
+### State machine (status consistency)
+*Prior to the first message, status will not exist.*
+- unconfirmed = A position has been received, but the minimum message threshold has not been met.
+- confirmed = The minimum number of messages has been received within the `confirmMaxAge` threshold.
+- lost = No messages have been received within the `lostAfter` threshold.
+- remove = No messages have been received within the `removeAfter` threshold.
+
+If not enough messages are received within `confirmMaxAge`, the confirmation process resets and the target remains `unconfirmed`. Once enough messages are received, status becomes `confirmed`. Targets become `lost` after a period of silence and `remove` after a longer period without position.
+
+```mermaid
+stateDiagram-v2
+  direction LR
+
+  [*] --> unconfirmed: first position report
+
+  unconfirmed --> unconfirmed: position report\nmsgNo < confirmAfterMsgs\n(confirmation in progress)
+  unconfirmed --> confirmed: position report\nmsgNo ≥ confirmAfterMsgs
+  unconfirmed --> unconfirmed: gap > confirmMaxAge\nreset msgCount (msgNo becomes 1)
+
+  confirmed --> confirmed: position report\nrefresh lastPosition
+
+  unconfirmed --> lost: timer\nage > lostAfter
+  confirmed --> lost: timer\nage > lostAfter
+
+  lost --> confirmed: position report\n(confirmAfterMsgs = 1)
+  lost --> unconfirmed: position report\n(confirmAfterMsgs > 1)
+
+  unconfirmed --> remove: timer\nage > removeAfter
+  confirmed --> remove: timer\nage > removeAfter
+  lost --> remove: timer\nage > removeAfter\ndelete target
+
+  remove --> confirmed: next position report\n(confirmAfterMsgs = 1)\n(new track)
+  remove --> unconfirmed: next position report\n(confirmAfterMsgs > 1)\n(new track)
+```
+
+**Trigger:** `<context>.navigation.position` received
+| Condition | Action |
+|---        |---     |
+| `msgCount` < `confirmAfterMsgs` | `status` = **'unconfirmed'** <br>`msgCount` -> increment <br>`lastPosition` = `Date.now()` |
+| (`msgCount` >= `confirmAfterMsgs`) <= `confirmMaxAge` | `status` = **'confirmed'** <br>`msgCount` -> capped at `confirmAfterMsgs` <br>`lastPosition` = `Date.now()`
+
+If the time gap between unconfirmed messages exceeds `confirmMaxAge`, `msgCount` resets to `0` before the next increment.
+
+**Trigger:** Status Interval Timer Event
+| Condition | Action |
+|---        |---     |
+| `Date.now() - lastPosition` > `lostAfter` | `status` = **'lost'** <br>`msgCount` = 0 <br>`lastPosition` -> unchanged |
+| `Date.now() - lastPosition` > `removeAfter` | `status` = **'remove'** <br>`msgCount` = 0 <br>`lastPosition` -> unchanged <br> delete target from map |
+
+### Timing & publication (resource consumption)
+The plugin emits Signal K deltas to the target context with:
+
+- Path: `sensors.ais.status`
+- Values: `unconfirmed`, `confirmed`, `lost`, `remove`
+
+There are two processes that generate delta updates:
+1. Position Update: runs when position is received and applies `unconfirmed` / `confirmed` logic.
+2. Status Check: runs on a fixed interval and applies `lostAfter` and `removeAfter` thresholds.
+
+## State Management parameters
+
+### Plugin settings
+- `confirmMaxAgeRatio` (number, default `1.1`): Multiplier applied to `confirmMaxAge` for all AIS classes. Example: `1.1` adds a 10% margin before ignoring a message in the confirmation process.
+
+### Device Class Processing Definition
+``` typescript
+const AIS_CLASS_DEFAULTS = {
+  A: {
+    confirmAfterMsgs: 2,
+    confirmMaxAge: 180000,  // ms
+    lostAfter: 360000,      // ms
+    removeAfter: 540000     // ms
+  },
+  B: {
+    confirmAfterMsgs: 3,
+    confirmMaxAge: 180000,  // ms
+    lostAfter: 360000,      // ms
+    removeAfter: 540000     // ms
+  },
+  ATON: {
+    confirmAfterMsgs: 1,
+    confirmMaxAge: 180000,  // ms
+    lostAfter: 900000,      // ms
+    removeAfter: 3600000    // ms
+  },
+  BASE: {
+    confirmAfterMsgs: 1,
+    confirmMaxAge: 10000,   // ms
+    lostAfter: 30000,       // ms
+    removeAfter: 180000     // ms
+  },
+  SAR: {
+    confirmAfterMsgs: 1,
+    confirmMaxAge: 10000,   // ms
+    lostAfter: 30000,       // ms
+    removeAfter: 180000     // ms
+  },
+  AIRCRAFT: {
+    confirmAfterMsgs: 1,
+    confirmMaxAge: 10000,   // ms
+    lostAfter: 30000,       // ms
+    removeAfter: 180000     // ms
+  }
+}
+```
+
+
+
+### Target Selection
+``` typescript
+const AIS_CONTEXT_PREFIXES = [
+  'atons.*',
+  'shore.basestations.*',
+  'vessels.*',
+  'sar.*',
+  'aircraft.*'
+];
+```

package/package.json

@@ -0,0 +1,31 @@
+{
+    "name": "sk-ais-status-plugin",
+    "version": "1.0.0",
+    "description": "AIS Status manager plugin for Signal K server.",
+    "main": "plugin/index.js",
+    "keywords": [
+        "signalk-node-server-plugin"
+    ],
+    "repository": "https://github.com/panaaj/sk-ais-status-plugin",
+    "author": "AdrianP",
+    "license": "Apache-20",
+    "scripts": {
+        "build": "tsc",
+        "build-declaration": "tsc --declaration --allowJs false",
+        "watch": "npm run build -- -w",
+        "test": "echo \"Error: no test specified\" && exit 1",
+        "start": "npm run build -- -w",
+        "format": "prettier --write src/*",
+        "prepublishOnly": "tsc"
+    },
+    "dependencies": {
+        "@signalk/server-api": "^2.10.2"
+    },
+    "devDependencies": {
+        "@types/baconjs": "^0.7.34",
+        "@types/express": "^5.0.6",
+        "prettier": "^2.5.1",
+        "typescript": "^5.9.3"
+    },
+    "signalk-plugin-enabled-by-default": true
+}

package/plugin/index.d.ts

@@ -0,0 +1 @@
+export {};

package/plugin/index.js

@@ -0,0 +1,309 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// **** Signal K flags resources ****
+const server_api_1 = require("@signalk/server-api");
+var AIS_STATUS;
+(function (AIS_STATUS) {
+    AIS_STATUS["unconfirmed"] = "unconfirmed";
+    AIS_STATUS["confirmed"] = "confirmed";
+    AIS_STATUS["lost"] = "lost";
+    AIS_STATUS["remove"] = "remove";
+})(AIS_STATUS || (AIS_STATUS = {}));
+const AIS_CLASS_DEFAULTS = {
+    A: {
+        confirmAfterMsgs: 2,
+        confirmMaxAge: 3 * 60000, // 3 min when moored, < 10 sec when moving)
+        lostAfter: 6 * 60000,
+        removeAfter: 9 * 60000
+    },
+    B: {
+        confirmAfterMsgs: 3,
+        confirmMaxAge: 3 * 60000, // 3 min when moored, < 30 sec when moving)
+        lostAfter: 6 * 60000,
+        removeAfter: 9 * 60000
+    },
+    ATON: {
+        confirmAfterMsgs: 1,
+        confirmMaxAge: 3 * 60000, // 3 min nominal
+        lostAfter: 15 * 60000, // 15 min = timeout / loss
+        removeAfter: 60 * 60000
+    },
+    BASE: {
+        confirmAfterMsgs: 1,
+        confirmMaxAge: 10000, // 10 sec nominal
+        lostAfter: 30000,
+        removeAfter: 3 * 60000
+    },
+    SAR: {
+        confirmAfterMsgs: 1,
+        confirmMaxAge: 10000, // 10 sec nominal
+        lostAfter: 30000,
+        removeAfter: 3 * 60000
+    },
+    AIRCRAFT: {
+        confirmAfterMsgs: 1,
+        confirmMaxAge: 10000, // treat similarly to SAR/BASE (fast turnover)
+        lostAfter: 30000,
+        removeAfter: 3 * 60000
+    }
+};
+const isAISClass = (value) => typeof value === 'string' &&
+    ['A', 'B', 'ATON', 'BASE', 'SAR', 'AIRCRAFT'].includes(value);
+const classFromContext = (context) => {
+    if (context.startsWith('atons.'))
+        return 'ATON';
+    if (context.startsWith('shore.basestations.'))
+        return 'BASE';
+    if (context.startsWith('sar.'))
+        return 'SAR';
+    if (context.startsWith('aircraft.'))
+        return 'AIRCRAFT';
+    return 'B';
+};
+const STATUS_CHECK_INTERVAL = 5000;
+const CONFIG_SCHEMA = {
+    properties: {
+        confirmMaxAgeRatio: {
+            type: 'number',
+            title: 'Confirmation max age margin',
+            description: 'Multiplier applied to the maximum message age threshold of the target confirmation process (e.g., 1.1 = +10%). Applied to all AIS classes.',
+            default: 1.1,
+            minimum: 0.1
+        }
+    }
+};
+const CONFIG_UISCHEMA = {};
+const DEFAULT_SETTINGS = {
+    confirmMaxAgeRatio: 1.1
+};
+module.exports = (server) => {
+    let subscriptions = []; // stream subscriptions
+    let timers = []; // interval timers
+    const plugin = {
+        id: 'sk-ais-status',
+        name: 'AIS Status Manager',
+        schema: () => CONFIG_SCHEMA,
+        uiSchema: () => CONFIG_UISCHEMA,
+        start: (options, restart) => {
+            doStartup(options);
+        },
+        stop: () => {
+            doShutdown();
+        }
+    };
+    let settings = { ...DEFAULT_SETTINGS };
+    let self = '';
+    let targets = new Map();
+    const doStartup = (options) => {
+        try {
+            server.debug(`${plugin.name} starting.......`);
+            if (options) {
+                settings = { ...DEFAULT_SETTINGS, ...options };
+            }
+            else {
+                // save defaults if no options loaded
+                server.savePluginOptions(settings, () => {
+                    server.debug(`Default configuration applied...`);
+                });
+            }
+            server.debug(`Applied configuration: ${JSON.stringify(settings)}`);
+            server.setPluginStatus(`Started`);
+            // initialize plugin
+            initialize();
+        }
+        catch (error) {
+            const msg = `Started with errors!`;
+            server.setPluginError(msg);
+            server.error('error: ' + error);
+        }
+    };
+    const doShutdown = () => {
+        server.debug(`${plugin.name} stopping.......`);
+        server.debug('** Un-registering Update Handler(s) **');
+        subscriptions.forEach((b) => b());
+        subscriptions = [];
+        server.debug('** Stopping Timer(s) **');
+        timers.forEach((t) => clearInterval(t));
+        timers = [];
+        const msg = 'Stopped.';
+        server.setPluginStatus(msg);
+    };
+    /**
+     * initialize plugin
+     */
+    const initialize = () => {
+        server.debug('Initializing ....');
+        // setup subscriptions
+        initSubscriptions();
+        self = server.getPath('self');
+        timers.push(setInterval(() => checkStatus(), STATUS_CHECK_INTERVAL));
+    };
+    // register DELTA stream message handler
+    const initSubscriptions = () => {
+        const subDef = [
+            {
+                path: 'navigation.position',
+                period: 500
+            }
+        ];
+        const subs = [
+            {
+                context: 'vessels.*',
+                subscribe: subDef
+            },
+            {
+                context: 'atons.*',
+                subscribe: subDef
+            },
+            {
+                context: 'shore.basestations.*',
+                subscribe: subDef
+            },
+            {
+                context: 'sar.*',
+                subscribe: subDef
+            },
+            {
+                context: 'aircraft.*',
+                subscribe: subDef
+            }
+        ];
+        server.debug(`Subscribing to contexts: ${subs.map((s) => s.context).join(', ')}`);
+        server.debug(`With paths: ${subDef
+            .map((s) => `${s.path} (${s.period} ms)`)
+            .join(', ')}`);
+        subs.forEach((s) => {
+            server.subscriptionmanager.subscribe(s, subscriptions, onError, onMessage);
+        });
+    };
+    /**
+     * Delta message handler
+     * @param delta Delta message
+     */
+    const onMessage = (delta) => {
+        if (!delta.updates) {
+            return;
+        }
+        if (delta.context === self) {
+            return;
+        }
+        delta.updates.forEach((u) => {
+            if (!(0, server_api_1.hasValues)(u)) {
+                return;
+            }
+            u.values.forEach((v) => {
+                if (v.path === 'navigation.position') {
+                    if (!targets.has(delta.context)) {
+                        targets.set(delta.context, {
+                            lastPosition: 0,
+                            msgCount: 0
+                        });
+                    }
+                    processTarget(delta.context);
+                }
+            });
+        });
+    };
+    /** Handle subscription error */
+    const onError = (error) => {
+        server.error(`${plugin.id} Error: ${error}`);
+    };
+    /** Process target after position message */
+    const processTarget = (context) => {
+        const target = targets.get(context);
+        if (!target)
+            return;
+        const aisClass = getAisClass(context);
+        const confirmMaxAge = getConfirmMaxAge(aisClass);
+        const now = Date.now();
+        if (target.msgCount > 0 &&
+            target.msgCount < AIS_CLASS_DEFAULTS[aisClass].confirmAfterMsgs) {
+            const elapse = now - target.lastPosition;
+            if (elapse > confirmMaxAge) {
+                server.debug(`*** Confirm max age exceeded (${elapse} ms > ${confirmMaxAge} ms) -> reset confirmation`, context, aisClass);
+                target.msgCount = 0;
+            }
+        }
+        const msgNo = target.msgCount + 1;
+        target.lastPosition = now;
+        // confirmMsg threshold met?
+        if (msgNo < AIS_CLASS_DEFAULTS[aisClass].confirmAfterMsgs) {
+            target.msgCount = msgNo;
+            if (emitAisStatus(context, AIS_STATUS.unconfirmed)) {
+                server.debug(`*** Threshold not met (${msgNo}/${AIS_CLASS_DEFAULTS[aisClass].confirmAfterMsgs}) -> unconfirmed`, context, aisClass);
+            }
+        }
+        else {
+            target.msgCount = AIS_CLASS_DEFAULTS[aisClass].confirmAfterMsgs;
+            if (emitAisStatus(context, AIS_STATUS.confirmed)) {
+                server.debug(`*** Threshold met (${msgNo}/${AIS_CLASS_DEFAULTS[aisClass].confirmAfterMsgs}) -> confirmed`, context, aisClass);
+            }
+        }
+        targets.set(context, target);
+    };
+    /**
+     * Return AIS Class of supplied Context
+     * @param context Signal K context
+     * @returns AIS class (falls back to context-derived class)
+     */
+    const getAisClass = (context) => {
+        const aisClass = server.getPath(`${context}.sensors.ais.class`)?.value;
+        if (isAISClass(aisClass)) {
+            return aisClass;
+        }
+        return classFromContext(context);
+    };
+    const getConfirmMaxAge = (aisClass) => {
+        const ratio = Number(settings.confirmMaxAgeRatio);
+        if (!Number.isFinite(ratio) || ratio <= 0) {
+            return AIS_CLASS_DEFAULTS[aisClass].confirmMaxAge;
+        }
+        return Math.round(AIS_CLASS_DEFAULTS[aisClass].confirmMaxAge * ratio);
+    };
+    /**
+     * Check and update AIS target(s) status
+     */
+    const checkStatus = () => {
+        targets.forEach((v, k) => {
+            const aisClass = getAisClass(k);
+            const tDiff = Date.now() - v.lastPosition;
+            if (tDiff >= AIS_CLASS_DEFAULTS[aisClass].removeAfter) {
+                if (emitAisStatus(k, AIS_STATUS.remove)) {
+                    server.debug('*** Remove threshold met -> remove', k, aisClass);
+                }
+                targets.delete(k);
+            }
+            else if (tDiff >= AIS_CLASS_DEFAULTS[aisClass].lostAfter) {
+                v.msgCount = 0;
+                if (emitAisStatus(k, AIS_STATUS.lost)) {
+                    server.debug('*** Lost threshold met -> lost', k, aisClass);
+                }
+            }
+        });
+    };
+    /**
+     * Emits sensors.ais.status delta
+     * @param context Signal K context
+     */
+    const emitAisStatus = (context, status) => {
+        let currStatus = server.getPath(`${context}.sensors.ais.status`);
+        if (status === currStatus?.value) {
+            return false;
+        }
+        server.handleMessage(plugin.id, {
+            context: context,
+            updates: [
+                {
+                    values: [
+                        {
+                            path: 'sensors.ais.status',
+                            value: status
+                        }
+                    ]
+                }
+            ]
+        }, server_api_1.SKVersion.v1);
+        return true;
+    };
+    return plugin;
+};

package/plugin/openApi.json

@@ -0,0 +1,175 @@
+{
+    "openapi": "3.0.0",
+    "info": {
+        "version": "2.5.0",
+        "title": "Signal K Flags API",
+        "description": "API endpoints exposed by `signalk-flags` plugin for displaying flags based on MMSI or country code.",
+        "termsOfService": "http://signalk.org/terms/",
+        "license": {
+            "name": "Apache 2.0",
+            "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
+        }
+    },
+    "externalDocs": {
+        "url": "http://signalk.org/specification/",
+        "description": "Signal K specification."
+    },
+    "servers": [
+        {
+            "url": "/"
+        }
+    ],
+    "tags": [
+        {
+            "name": "Flags",
+            "description": "Endpoints for retrieving country flags."
+        }
+    ],
+    "components": {
+        "schemas": {},
+        "responses": {
+            "200OKResponse": {
+                "description": "Successful operation",
+                "content": {
+                    "application/json": {
+                        "schema": {
+                            "type": "object",
+                            "description": "Request success response",
+                            "properties": {
+                                "state": {
+                                    "type": "string",
+                                    "enum": ["COMPLETED"]
+                                },
+                                "statusCode": {
+                                    "type": "number",
+                                    "enum": [200]
+                                }
+                            },
+                            "required": ["state", "statusCode"]
+                        }
+                    }
+                }
+            },
+            "ErrorResponse": {
+                "description": "Failed operation",
+                "content": {
+                    "application/json": {
+                        "schema": {
+                            "type": "object",
+                            "description": "Request error response",
+                            "properties": {
+                                "state": {
+                                    "type": "string",
+                                    "enum": ["FAILED"]
+                                },
+                                "statusCode": {
+                                    "type": "number",
+                                    "enum": [404]
+                                },
+                                "message": {
+                                    "type": "string"
+                                }
+                            },
+                            "required": ["state", "statusCode", "message"]
+                        }
+                    }
+                }
+            }
+        },
+        "parameters": {
+            "mmsi": {
+                "in": "path",
+                "required": true,
+                "name": "mmsi",
+                "description": "Maritime Mobile Service Identity (MMSI).",
+                "schema": {
+                    "type": "number",
+                    "minLength": 9,
+                    "maxLength": 9,
+                    "example": 520345561
+                }
+            },
+            "countryCode": {
+                "in": "path",
+                "required": true,
+                "name": "code",
+                "description": "Two letter country code.",
+                "schema": {
+                    "type": "string",
+                    "minLength": 2,
+                    "maxLength": 2,
+                    "example": "al"
+                }
+            },
+            "aspect": {
+                "in": "query",
+                "required": false,
+                "name": "aspect",
+                "description": "Aspect of flag image to return. 4x3 (default)",
+                "schema": {
+                    "type": "string",
+                    "enum": ["4x3", "1x1"]
+                }
+            }
+        },
+        "securitySchemes": {
+            "bearerAuth": {
+                "type": "http",
+                "scheme": "bearer",
+                "bearerFormat": "JWT"
+            },
+            "cookieAuth": {
+                "type": "apiKey",
+                "in": "cookie",
+                "name": "JAUTHENTICATION"
+            }
+        }
+    },
+    "security": [{ "cookieAuth": [] }, { "bearerAuth": [] }],
+    "paths": {
+        "/signalk/v2/api/resources/flags/mmsi/{mmsi}": {
+            "parameters": [
+                {
+                    "$ref": "#/components/parameters/mmsi"
+                },
+                {
+                    "$ref": "#/components/parameters/aspect"
+                }
+            ],
+            "get": {
+                "tags": ["Flags"],
+                "summary": "Returns flag for supplied MMSI.",
+                "responses": {
+                    "default": {
+                        "description": "Return SVG content for flag derived from the supplied MMSI.",
+                        "content": {
+                            "image/svg+xml": {}
+                        }
+                    }
+                }
+            }
+        },
+        "/signalk/v2/api/resources/flags/country/{code}": {
+            "parameters": [
+                {
+                    "$ref": "#/components/parameters/countryCode"
+                },
+                {
+                    "$ref": "#/components/parameters/aspect"
+                }
+            ],
+            "get": {
+                "tags": ["Flags"],
+                "summary": "Returns flag for supplied country code.",
+                "responses": {
+                    "default": {
+                        "description": "Return SVG content for flag derived from the supplied country code.",
+                        "content": {
+                            "image/svg+xml": {}
+                        }
+                    }
+                }
+            }
+        }
+    }
+}