overlays-server 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. package/LICENSE +661 -0
  2. package/README-tr.md +292 -0
  3. package/README.md +295 -2
  4. package/config.example.json +40 -0
  5. package/dist/app.d.ts +19 -0
  6. package/dist/app.js +127 -0
  7. package/dist/cli.d.ts +2 -0
  8. package/dist/cli.js +176 -0
  9. package/dist/config.d.ts +62 -0
  10. package/dist/config.js +115 -0
  11. package/dist/core/driver.d.ts +56 -0
  12. package/dist/core/driver.js +5 -0
  13. package/dist/core/hub.d.ts +100 -0
  14. package/dist/core/hub.js +280 -0
  15. package/dist/core/last-position.d.ts +23 -0
  16. package/dist/core/last-position.js +67 -0
  17. package/dist/core/protocol.d.ts +56 -0
  18. package/dist/core/protocol.js +27 -0
  19. package/dist/core/registry.d.ts +9 -0
  20. package/dist/core/registry.js +29 -0
  21. package/dist/core/types.d.ts +83 -0
  22. package/dist/core/types.js +2 -0
  23. package/dist/drivers/ddpai/http-api.d.ts +30 -0
  24. package/dist/drivers/ddpai/http-api.js +84 -0
  25. package/dist/drivers/ddpai/index.d.ts +20 -0
  26. package/dist/drivers/ddpai/index.js +107 -0
  27. package/dist/drivers/ddpai/messages.d.ts +29 -0
  28. package/dist/drivers/ddpai/messages.js +76 -0
  29. package/dist/drivers/index.d.ts +6 -0
  30. package/dist/drivers/index.js +8 -0
  31. package/dist/drivers/simulator.d.ts +13 -0
  32. package/dist/drivers/simulator.js +64 -0
  33. package/dist/index.d.ts +26 -0
  34. package/dist/index.js +26 -0
  35. package/dist/lib/delimited.d.ts +21 -0
  36. package/dist/lib/delimited.js +51 -0
  37. package/dist/lib/log.d.ts +27 -0
  38. package/dist/lib/log.js +80 -0
  39. package/dist/lib/nmea.d.ts +57 -0
  40. package/dist/lib/nmea.js +141 -0
  41. package/dist/lib/options.d.ts +29 -0
  42. package/dist/lib/options.js +85 -0
  43. package/dist/lib/reconnecting-tcp.d.ts +35 -0
  44. package/dist/lib/reconnecting-tcp.js +91 -0
  45. package/dist/lib/redact.d.ts +10 -0
  46. package/dist/lib/redact.js +30 -0
  47. package/dist/tools/probe.d.ts +37 -0
  48. package/dist/tools/probe.js +208 -0
  49. package/dist/transports/diagnostics.d.ts +65 -0
  50. package/dist/transports/diagnostics.js +49 -0
  51. package/dist/transports/feed.d.ts +22 -0
  52. package/dist/transports/feed.js +78 -0
  53. package/dist/transports/http-server.d.ts +39 -0
  54. package/dist/transports/http-server.js +196 -0
  55. package/dist/transports/security.d.ts +15 -0
  56. package/dist/transports/security.js +78 -0
  57. package/dist/transports/status-page.d.ts +7 -0
  58. package/dist/transports/status-page.js +204 -0
  59. package/dist/version.d.ts +2 -0
  60. package/dist/version.js +4 -0
  61. package/docs/architecture.md +85 -0
  62. package/docs/data.md +87 -0
  63. package/docs/devices/README.md +29 -0
  64. package/docs/devices/ddpai.md +99 -0
  65. package/docs/drivers.md +130 -0
  66. package/docs/new-device.md +94 -0
  67. package/docs/protocol.md +160 -0
  68. package/docs/remote.md +126 -0
  69. package/docs/testing-locally.md +150 -0
  70. package/docs/windows-network.md +58 -0
  71. package/package.json +72 -4
@@ -0,0 +1,280 @@
1
+ import { silentLogger } from '../lib/log.js';
2
+ /** Below this speed (m/s, ~1.8 km/h) the course from GPS is noise: heading is left out. */
3
+ const MIN_SPEED_FOR_HEADING = 0.5;
4
+ /**
5
+ * Central state: one entry per source, the active GPS source, stale detection and fan-out.
6
+ * Sources write through their `SourceContext`, transports read snapshots and subscribe to events.
7
+ */
8
+ export class Hub {
9
+ entries = new Map();
10
+ listeners = new Set();
11
+ staleAfterMs;
12
+ rawFrameCapacity;
13
+ gpsPriority;
14
+ log;
15
+ now;
16
+ activeId;
17
+ staleTimer;
18
+ constructor(options = {}) {
19
+ this.staleAfterMs = options.staleAfterMs ?? 5000;
20
+ this.rawFrameCapacity = options.rawFrameCapacity ?? 2000;
21
+ this.gpsPriority = options.gpsPriority ?? [];
22
+ this.log = options.log ?? silentLogger;
23
+ this.now = options.now ?? Date.now;
24
+ }
25
+ /** Adds a source and returns the context its driver writes through. */
26
+ register(info, log = this.log.child(info.id)) {
27
+ if (this.entries.has(info.id))
28
+ throw new Error(`source id "${info.id}" is used twice`);
29
+ const entry = {
30
+ info,
31
+ status: { link: 'starting', gps: 'unknown', since: this.now() },
32
+ raw: [],
33
+ abort: new AbortController(),
34
+ };
35
+ this.entries.set(info.id, entry);
36
+ const id = info.id;
37
+ return {
38
+ id,
39
+ log,
40
+ signal: entry.abort.signal,
41
+ setLink: (state, message) => this.setLink(id, state, message),
42
+ setDevice: (device) => this.setDevice(id, device),
43
+ publishFix: (fix) => this.publishFix(id, fix),
44
+ publishNoFix: (detail) => this.publishNoFix(id, detail),
45
+ publishMotion: (sample) => this.publishMotion(id, sample),
46
+ publishEvent: (event) => this.publishEvent(id, event),
47
+ recordRaw: (frame) => {
48
+ if (this.rawFrameCapacity <= 0)
49
+ return;
50
+ entry.raw.push({ t: this.now(), frame });
51
+ if (entry.raw.length > this.rawFrameCapacity)
52
+ entry.raw.splice(0, entry.raw.length - this.rawFrameCapacity);
53
+ },
54
+ };
55
+ }
56
+ /** Aborts the source's signal and marks it stopped. */
57
+ unregister(id) {
58
+ const entry = this.entries.get(id);
59
+ if (!entry)
60
+ return;
61
+ entry.abort.abort();
62
+ this.setLink(id, 'stopped');
63
+ }
64
+ start() {
65
+ if (this.staleTimer)
66
+ return;
67
+ this.staleTimer = setInterval(() => this.checkStale(), Math.min(1000, Math.max(100, this.staleAfterMs / 4)));
68
+ this.staleTimer.unref();
69
+ }
70
+ stop() {
71
+ clearInterval(this.staleTimer);
72
+ this.staleTimer = undefined;
73
+ for (const id of this.entries.keys())
74
+ this.unregister(id);
75
+ }
76
+ subscribe(listener) {
77
+ this.listeners.add(listener);
78
+ return () => this.listeners.delete(listener);
79
+ }
80
+ get activeGpsSource() {
81
+ return this.activeId;
82
+ }
83
+ has(id) {
84
+ return this.entries.has(id);
85
+ }
86
+ snapshot(id) {
87
+ const entry = this.entries.get(id);
88
+ return entry && this.toSnapshot(entry);
89
+ }
90
+ snapshots() {
91
+ return [...this.entries.values()].map((e) => this.toSnapshot(e));
92
+ }
93
+ /**
94
+ * Gives a source a last known position from an earlier run (see LastPositionStore). It is served to clients as
95
+ * `lastKnown` until the device reports a live fix; the GPS state is not changed.
96
+ */
97
+ seedLastFix(id, fix, receivedAt) {
98
+ const entry = this.entries.get(id);
99
+ if (!entry || entry.lastFix)
100
+ return;
101
+ const clean = normalizeFix(fix);
102
+ if (!clean)
103
+ return;
104
+ entry.lastFix = clean;
105
+ entry.lastFixAt = receivedAt;
106
+ }
107
+ /** Recent raw device messages of a source, oldest first (for diagnostics). */
108
+ recentFrames(id) {
109
+ return [...(this.entries.get(id)?.raw ?? [])];
110
+ }
111
+ // --- writes from sources ----------------------------------------------------------------
112
+ setLink(id, link, message) {
113
+ const entry = this.entries.get(id);
114
+ if (!entry)
115
+ return;
116
+ if (entry.status.link === 'stopped' && link !== 'stopped')
117
+ return;
118
+ let gps = entry.status.gps;
119
+ if (link !== 'online')
120
+ gps = gps === 'fix' || gps === 'stale' ? 'stale' : 'unknown';
121
+ this.updateStatus(entry, { link, gps, message });
122
+ }
123
+ setDevice(id, device) {
124
+ const entry = this.entries.get(id);
125
+ if (!entry)
126
+ return;
127
+ if (JSON.stringify(entry.status.device) === JSON.stringify(device))
128
+ return;
129
+ entry.status = { ...entry.status, device };
130
+ this.emit({ kind: 'status', snapshot: this.toSnapshot(entry) });
131
+ }
132
+ publishFix(id, raw) {
133
+ const entry = this.entries.get(id);
134
+ if (!entry || entry.status.link === 'stopped')
135
+ return;
136
+ const fix = normalizeFix(raw);
137
+ if (!fix) {
138
+ this.log.debug(`${id}: dropped invalid fix`, raw);
139
+ return;
140
+ }
141
+ entry.lastFix = fix;
142
+ entry.lastFixAt = this.now();
143
+ this.updateStatus(entry, { link: 'online', gps: 'fix', message: undefined, satellites: fix.satellites });
144
+ this.emit({ kind: 'fix', source: id, fix, active: this.activeId === id });
145
+ }
146
+ publishNoFix(id, detail = {}) {
147
+ const entry = this.entries.get(id);
148
+ if (!entry || entry.status.link === 'stopped')
149
+ return;
150
+ this.updateStatus(entry, { link: 'online', gps: 'no_fix', message: undefined, satellites: detail.satellites });
151
+ }
152
+ publishMotion(id, sample) {
153
+ const entry = this.entries.get(id);
154
+ if (!entry || entry.status.link === 'stopped')
155
+ return;
156
+ if (![sample.x, sample.y, sample.z, sample.timestamp].every(Number.isFinite))
157
+ return;
158
+ entry.lastMotion = sample;
159
+ this.emit({ kind: 'motion', source: id, sample });
160
+ }
161
+ publishEvent(id, event) {
162
+ const entry = this.entries.get(id);
163
+ if (!entry || entry.status.link === 'stopped' || !event.name)
164
+ return;
165
+ this.emit({ kind: 'event', source: id, event });
166
+ }
167
+ // --- internals ----------------------------------------------------------------------------
168
+ updateStatus(entry, patch) {
169
+ const prev = entry.status;
170
+ const next = { ...prev, ...patch };
171
+ if (patch.message === undefined && 'message' in patch)
172
+ delete next.message;
173
+ if (patch.satellites === undefined && 'satellites' in patch)
174
+ delete next.satellites;
175
+ const stateChanged = next.link !== prev.link || next.gps !== prev.gps;
176
+ if (!stateChanged && next.message === prev.message && next.satellites === prev.satellites)
177
+ return;
178
+ if (stateChanged)
179
+ next.since = this.now();
180
+ entry.status = next;
181
+ if (next.link !== prev.link || next.message !== prev.message) {
182
+ const detail = next.message ? ` (${next.message})` : '';
183
+ this.log.info(`${entry.info.id}: link ${next.link}${detail}`);
184
+ }
185
+ if (next.gps !== prev.gps)
186
+ this.log.info(`${entry.info.id}: gps ${next.gps}`);
187
+ const before = this.activeId;
188
+ this.recomputeActive();
189
+ this.emit({ kind: 'status', snapshot: this.toSnapshot(entry) });
190
+ if (before !== this.activeId) {
191
+ // The other side of the switch also changed its `active` flag.
192
+ for (const id of [before, this.activeId]) {
193
+ const other = id && id !== entry.info.id ? this.entries.get(id) : undefined;
194
+ if (other)
195
+ this.emit({ kind: 'status', snapshot: this.toSnapshot(other) });
196
+ }
197
+ }
198
+ }
199
+ recomputeActive() {
200
+ const ordered = this.priorityOrder();
201
+ const withFix = ordered.find((e) => e.status.gps === 'fix');
202
+ // Without any fix keep the previous choice (or the first GPS source) so clients know whom to wait for.
203
+ const next = withFix ?? (this.activeId && this.entries.has(this.activeId) ? this.entries.get(this.activeId) : ordered[0]);
204
+ const nextId = next?.info.id;
205
+ if (nextId !== this.activeId) {
206
+ if (nextId)
207
+ this.log.info(`active GPS source: ${nextId}`);
208
+ this.activeId = nextId;
209
+ }
210
+ }
211
+ priorityOrder() {
212
+ const gpsEntries = [...this.entries.values()].filter((e) => e.info.capabilities.includes('gps') && e.status.link !== 'stopped');
213
+ const rank = (e) => {
214
+ const i = this.gpsPriority.indexOf(e.info.id);
215
+ return i === -1 ? this.gpsPriority.length : i;
216
+ };
217
+ return gpsEntries.map((e, i) => ({ e, i })).sort((a, b) => rank(a.e) - rank(b.e) || a.i - b.i).map((x) => x.e);
218
+ }
219
+ checkStale() {
220
+ const now = this.now();
221
+ for (const entry of this.entries.values()) {
222
+ if (entry.status.gps === 'fix' && entry.lastFixAt !== undefined && now - entry.lastFixAt > this.staleAfterMs) {
223
+ this.updateStatus(entry, { gps: 'stale' });
224
+ }
225
+ }
226
+ }
227
+ toSnapshot(entry) {
228
+ return {
229
+ ...entry.info,
230
+ status: entry.status,
231
+ ...(entry.lastFix && { lastFix: entry.lastFix, lastFixAt: entry.lastFixAt }),
232
+ ...(entry.lastMotion && { lastMotion: entry.lastMotion }),
233
+ active: this.activeId === entry.info.id,
234
+ };
235
+ }
236
+ emit(event) {
237
+ for (const listener of this.listeners) {
238
+ try {
239
+ listener(event);
240
+ }
241
+ catch (err) {
242
+ this.log.error('hub listener failed', err);
243
+ }
244
+ }
245
+ }
246
+ }
247
+ const round = (n, digits) => {
248
+ const f = 10 ** digits;
249
+ return Math.round(n * f) / f;
250
+ };
251
+ const finite = (n) => typeof n === 'number' && Number.isFinite(n);
252
+ /** Validates a fix and trims it to sensible precision. Returns `undefined` for impossible values. */
253
+ export function normalizeFix(fix) {
254
+ const { lat, lon } = fix;
255
+ if (!finite(lat) || !finite(lon) || Math.abs(lat) > 90 || Math.abs(lon) > 180)
256
+ return undefined;
257
+ // 0,0 is what many receivers report before their first lock.
258
+ if (lat === 0 && lon === 0)
259
+ return undefined;
260
+ const out = { lat: round(lat, 7), lon: round(lon, 7), timestamp: finite(fix.timestamp) ? fix.timestamp : Date.now() };
261
+ if (finite(fix.speed) && fix.speed >= 0)
262
+ out.speed = round(fix.speed, 2);
263
+ const moving = out.speed === undefined || out.speed >= MIN_SPEED_FOR_HEADING;
264
+ if (finite(fix.heading) && moving)
265
+ out.heading = round(((fix.heading % 360) + 360) % 360, 1);
266
+ if (finite(fix.altitude))
267
+ out.altitude = round(fix.altitude, 1);
268
+ if (finite(fix.satellites) && fix.satellites >= 0)
269
+ out.satellites = Math.round(fix.satellites);
270
+ if (finite(fix.hdop) && fix.hdop >= 0)
271
+ out.hdop = round(fix.hdop, 2);
272
+ if (finite(fix.quality) && fix.quality >= 0)
273
+ out.quality = Math.round(fix.quality);
274
+ if (finite(fix.geoidSeparation))
275
+ out.geoidSeparation = round(fix.geoidSeparation, 1);
276
+ if (typeof fix.mode === 'string' && /^[A-Z]$/.test(fix.mode))
277
+ out.mode = fix.mode;
278
+ return out;
279
+ }
280
+ //# sourceMappingURL=hub.js.map
@@ -0,0 +1,23 @@
1
+ import { type Logger } from '../lib/log.ts';
2
+ import type { GpsFix } from './types.ts';
3
+ export interface StoredPosition {
4
+ fix: GpsFix;
5
+ /** Epoch ms when it was received. */
6
+ savedAt: number;
7
+ }
8
+ export declare class LastPositionStore {
9
+ private readonly file;
10
+ private readonly log;
11
+ private readonly intervalMs;
12
+ private positions;
13
+ private dirty;
14
+ private timer;
15
+ constructor(file: string, log: Logger, intervalMs?: number);
16
+ /** Reads the file; a missing or broken file just means "nothing remembered". */
17
+ load(): Record<string, StoredPosition>;
18
+ update(id: string, fix: GpsFix, at?: number): void;
19
+ start(): void;
20
+ /** Writes now if anything changed (temp file + rename, so a crash never leaves half a file). */
21
+ flush(): void;
22
+ stop(): void;
23
+ }
@@ -0,0 +1,67 @@
1
+ /**
2
+ * Remembers each source's last position on disk, so a server (or PC) restart while GPS is lost — a tunnel, an
3
+ * underground car park — still has a position to show. Written at most every few seconds, atomically, and on close.
4
+ * It is the user's own location in their own profile folder; `rememberLastPosition: false` turns it off.
5
+ */
6
+ import fs from 'node:fs';
7
+ import path from 'node:path';
8
+ import { errorMessage } from '../lib/log.js';
9
+ export class LastPositionStore {
10
+ file;
11
+ log;
12
+ intervalMs;
13
+ positions = {};
14
+ dirty = false;
15
+ timer;
16
+ constructor(file, log, intervalMs = 10_000) {
17
+ this.file = file;
18
+ this.log = log;
19
+ this.intervalMs = intervalMs;
20
+ }
21
+ /** Reads the file; a missing or broken file just means "nothing remembered". */
22
+ load() {
23
+ try {
24
+ const data = JSON.parse(fs.readFileSync(this.file, 'utf8'));
25
+ for (const [id, p] of Object.entries(data.positions ?? {})) {
26
+ if (p && typeof p.savedAt === 'number' && Number.isFinite(p.fix?.lat) && Number.isFinite(p.fix?.lon))
27
+ this.positions[id] = p;
28
+ }
29
+ }
30
+ catch (err) {
31
+ if (err.code !== 'ENOENT')
32
+ this.log.warn(`cannot read ${this.file}: ${errorMessage(err)}`);
33
+ }
34
+ return { ...this.positions };
35
+ }
36
+ update(id, fix, at = Date.now()) {
37
+ this.positions[id] = { fix, savedAt: at };
38
+ this.dirty = true;
39
+ }
40
+ start() {
41
+ if (this.timer)
42
+ return;
43
+ this.timer = setInterval(() => this.flush(), this.intervalMs);
44
+ this.timer.unref();
45
+ }
46
+ /** Writes now if anything changed (temp file + rename, so a crash never leaves half a file). */
47
+ flush() {
48
+ if (!this.dirty)
49
+ return;
50
+ this.dirty = false;
51
+ try {
52
+ fs.mkdirSync(path.dirname(this.file), { recursive: true });
53
+ const tmp = `${this.file}.tmp`;
54
+ fs.writeFileSync(tmp, JSON.stringify({ format: 1, positions: this.positions }, null, 2));
55
+ fs.renameSync(tmp, this.file);
56
+ }
57
+ catch (err) {
58
+ this.log.warn(`cannot write ${this.file}: ${errorMessage(err)}`);
59
+ }
60
+ }
61
+ stop() {
62
+ clearInterval(this.timer);
63
+ this.timer = undefined;
64
+ this.flush();
65
+ }
66
+ }
67
+ //# sourceMappingURL=last-position.js.map
@@ -0,0 +1,56 @@
1
+ /**
2
+ * Wire protocol v1 between overlays-server and overlays (WebSocket messages and SSE events).
3
+ * Every message is a JSON object with a `type`. Clients must ignore unknown types and fields:
4
+ * new ones may be added without bumping the version; removing or changing one bumps it.
5
+ */
6
+ import type { SourceSnapshot } from './hub.ts';
7
+ import type { DeviceEvent, DeviceInfo, GpsFix, GpsState, LinkState, MotionSample } from './types.ts';
8
+ export declare const PROTOCOL_VERSION = 1;
9
+ export declare const SERVER_NAME = "overlays-server";
10
+ export interface HelloMessage {
11
+ type: 'hello';
12
+ server: typeof SERVER_NAME;
13
+ version: string;
14
+ protocol: typeof PROTOCOL_VERSION;
15
+ /** Which GPS stream this connection gets: `auto` (active source) or a source id. */
16
+ subscription: string;
17
+ /** Source currently feeding `auto`. */
18
+ activeSource?: string;
19
+ }
20
+ export interface StatusMessage {
21
+ type: 'status';
22
+ source: string;
23
+ driver: string;
24
+ /** Human readable driver name, e.g. "DDPAI dashcam". */
25
+ driverName: string;
26
+ link: LinkState;
27
+ gps: GpsState;
28
+ active: boolean;
29
+ message?: string;
30
+ satellites?: number;
31
+ device?: DeviceInfo;
32
+ /** Epoch ms of the last link/gps change. */
33
+ since: number;
34
+ }
35
+ export interface FixMessage extends GpsFix {
36
+ type: 'fix';
37
+ source: string;
38
+ /**
39
+ * Not live: the last position known before GPS was lost (tunnel, restart). Sent once when a client connects while
40
+ * the source has no fix; live fixes leave it out.
41
+ */
42
+ lastKnown?: true;
43
+ }
44
+ export interface MotionMessage extends MotionSample {
45
+ type: 'motion';
46
+ source: string;
47
+ }
48
+ export interface EventMessage extends DeviceEvent {
49
+ type: 'event';
50
+ source: string;
51
+ }
52
+ export type ServerMessage = HelloMessage | StatusMessage | FixMessage | MotionMessage | EventMessage;
53
+ export declare function statusMessage(s: SourceSnapshot): StatusMessage;
54
+ export declare function fixMessage(source: string, fix: GpsFix, lastKnown?: boolean): FixMessage;
55
+ export declare function motionMessage(source: string, sample: MotionSample): MotionMessage;
56
+ export declare function eventMessage(source: string, event: DeviceEvent): EventMessage;
@@ -0,0 +1,27 @@
1
+ export const PROTOCOL_VERSION = 1;
2
+ export const SERVER_NAME = 'overlays-server';
3
+ export function statusMessage(s) {
4
+ return {
5
+ type: 'status',
6
+ source: s.id,
7
+ driver: s.driver,
8
+ driverName: s.driverName,
9
+ link: s.status.link,
10
+ gps: s.status.gps,
11
+ active: s.active,
12
+ ...(s.status.message !== undefined && { message: s.status.message }),
13
+ ...(s.status.satellites !== undefined && { satellites: s.status.satellites }),
14
+ ...(s.status.device && { device: s.status.device }),
15
+ since: s.status.since,
16
+ };
17
+ }
18
+ export function fixMessage(source, fix, lastKnown = false) {
19
+ return { type: 'fix', source, ...fix, ...(lastKnown && { lastKnown: true }) };
20
+ }
21
+ export function motionMessage(source, sample) {
22
+ return { type: 'motion', source, ...sample };
23
+ }
24
+ export function eventMessage(source, event) {
25
+ return { type: 'event', source, ...event };
26
+ }
27
+ //# sourceMappingURL=protocol.js.map
@@ -0,0 +1,9 @@
1
+ import type { AnyDriver } from './driver.ts';
2
+ /** Known drivers by id. */
3
+ export declare class DriverRegistry {
4
+ private readonly drivers;
5
+ constructor(drivers?: Iterable<AnyDriver>);
6
+ register(driver: AnyDriver): this;
7
+ get(id: string): AnyDriver;
8
+ list(): AnyDriver[];
9
+ }
@@ -0,0 +1,29 @@
1
+ import { ConfigError } from '../lib/options.js';
2
+ const ID_PATTERN = /^[a-z][a-z0-9-]*$/;
3
+ /** Known drivers by id. */
4
+ export class DriverRegistry {
5
+ drivers = new Map();
6
+ constructor(drivers = []) {
7
+ for (const d of drivers)
8
+ this.register(d);
9
+ }
10
+ register(driver) {
11
+ if (!ID_PATTERN.test(driver.id))
12
+ throw new Error(`invalid driver id "${driver.id}"`);
13
+ if (this.drivers.has(driver.id))
14
+ throw new Error(`driver "${driver.id}" is registered twice`);
15
+ this.drivers.set(driver.id, driver);
16
+ return this;
17
+ }
18
+ get(id) {
19
+ const driver = this.drivers.get(id);
20
+ if (!driver) {
21
+ throw new ConfigError(`unknown driver "${id}". Available: ${[...this.drivers.keys()].join(', ')}`);
22
+ }
23
+ return driver;
24
+ }
25
+ list() {
26
+ return [...this.drivers.values()];
27
+ }
28
+ }
29
+ //# sourceMappingURL=registry.js.map
@@ -0,0 +1,83 @@
1
+ /**
2
+ * Data every source can produce. Field names and units match the overlay site's `Fix` type
3
+ * (src/overlays/map/location.ts in stream-overlays), so a fix can be handed over unchanged.
4
+ */
5
+ export interface GpsFix {
6
+ lat: number;
7
+ lon: number;
8
+ /** Degrees from true north, 0-360. Left out while standing still (course is noise then). */
9
+ heading?: number;
10
+ /** Meters per second. */
11
+ speed?: number;
12
+ /** Meters above mean sea level. */
13
+ altitude?: number;
14
+ satellites?: number;
15
+ hdop?: number;
16
+ /** GGA fix quality: 1 = GPS, 2 = DGPS, 4 = RTK fixed, 5 = RTK float, 6 = dead reckoning. */
17
+ quality?: number;
18
+ /** Height of the geoid above the WGS84 ellipsoid (m); altitude + this = ellipsoid height. */
19
+ geoidSeparation?: number;
20
+ /** RMC mode: A = autonomous, D = differential, E = estimated, ... */
21
+ mode?: string;
22
+ /** UTC epoch milliseconds of the fix (GPS time when the device sends it). */
23
+ timestamp: number;
24
+ }
25
+ /** Acceleration in g, device axes. */
26
+ export interface MotionSample {
27
+ x: number;
28
+ y: number;
29
+ z: number;
30
+ timestamp: number;
31
+ }
32
+ /** A live video stream the device offers (for OBS, not for the browser). */
33
+ export interface DeviceStream {
34
+ /** `front`, `rear`, ... */
35
+ name: string;
36
+ url: string;
37
+ }
38
+ /** What the device says about itself. Never put secrets (Wi-Fi passwords, serials, MACs, keys) in here. */
39
+ export interface DeviceInfo {
40
+ vendor?: string;
41
+ model?: string;
42
+ firmware?: string;
43
+ name?: string;
44
+ /** Memory card. */
45
+ storage?: {
46
+ totalBytes: number;
47
+ freeBytes: number;
48
+ };
49
+ /** Number of camera sensors (2 = front + rear). */
50
+ cameras?: number;
51
+ streams?: DeviceStream[];
52
+ /** Every other non-secret field the device reports, as is (names are device specific). */
53
+ details?: Record<string, string | number | boolean>;
54
+ /** Epoch ms when this was read. */
55
+ updatedAt?: number;
56
+ }
57
+ /** Connection to the device. */
58
+ export type LinkState = 'starting' | 'connecting' | 'online' | 'offline' | 'stopped';
59
+ /** Position quality, independent of the link. `stale`: fixes were coming but stopped. */
60
+ export type GpsState = 'unknown' | 'no_fix' | 'fix' | 'stale';
61
+ /**
62
+ * Anything else the device pushes (alerts, button presses, unknown message types), passed through untouched so
63
+ * overlays can use it before the server learns its meaning.
64
+ */
65
+ export interface DeviceEvent {
66
+ /** Device specific name, e.g. the DDPAI `msgid`. */
67
+ name: string;
68
+ data: unknown;
69
+ timestamp: number;
70
+ }
71
+ /** Kinds of data a driver can publish. */
72
+ export type Capability = 'gps' | 'motion' | 'device' | 'events';
73
+ export interface SourceStatus {
74
+ link: LinkState;
75
+ gps: GpsState;
76
+ /** Human readable detail for the current state (last error, hint). */
77
+ message?: string;
78
+ /** Satellites in use, when known (also while searching for a fix). */
79
+ satellites?: number;
80
+ device?: DeviceInfo;
81
+ /** Epoch ms of the last link/gps change. */
82
+ since: number;
83
+ }
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=types.js.map
@@ -0,0 +1,30 @@
1
+ /**
2
+ * Read-only calls to the camera's HTTP API (`/vcam/cmd.cgi?cmd=...`).
3
+ * Replies look like `{"errcode":0,"data":"<JSON string>"}`.
4
+ *
5
+ * Careful: API_GetBaseInfo also returns the camera's Wi-Fi password, serial numbers and MAC addresses in plain text.
6
+ * Those never leave this module (see SECRET_FIELD); the raw reply is never logged.
7
+ */
8
+ import type { DeviceInfo } from '../../core/types.ts';
9
+ export declare class DdpaiApiError extends Error {
10
+ name: string;
11
+ }
12
+ export declare function ddpaiCommand(host: string, port: number, cmd: string, options?: {
13
+ signal?: AbortSignal;
14
+ timeoutMs?: number;
15
+ }): Promise<unknown>;
16
+ export interface DeviceInfoOptions {
17
+ /** Camera address, for the RTSP URLs. */
18
+ host: string;
19
+ rtspPort: number;
20
+ }
21
+ /**
22
+ * Everything usable from API_GetBaseInfo: model, firmware, memory card, camera count, RTSP streams, and every other
23
+ * non-secret field under `details`.
24
+ */
25
+ export declare function pickDeviceInfo(data: unknown, options: DeviceInfoOptions, now?: number): DeviceInfo;
26
+ export declare function fetchDeviceInfo(options: DeviceInfoOptions & {
27
+ httpPort: number;
28
+ signal?: AbortSignal;
29
+ timeoutMs?: number;
30
+ }): Promise<DeviceInfo>;