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
package/README-tr.md ADDED
@@ -0,0 +1,292 @@
1
+ # overlays-server
2
+
3
+ [English](README.md) · **Türkçe**
4
+
5
+ Yayıncının bilgisayarında (ya da araçtaki bir Raspberry Pi'de) çalışan küçük bir **yerel köprü sunucu**. Araç
6
+ kamerasından (şimdilik **DDPAI**) canlı GPS verisini alır, [Stream Overlays](https://overlays.ramazansancar.com.tr)
7
+ harita overlay'ine WebSocket üzerinden saniyede bir aktarır. Telefon, bulut servisi ya da RealtimeIRL gerekmez: konum
8
+ kameradan doğrudan, yerel ağdan gelir.
9
+
10
+ ```text
11
+ DDPAI kamera (Wi-Fi, 193.168.0.1:6100) ──► overlays-server (127.0.0.1:3456) ──► OBS tarayıcı kaynağı (harita)
12
+ ```
13
+
14
+ - **Canlı konum, hız, yön, rakım, uydu sayısı, GPS kalitesi** — kameranın kendi GPS'inden, 1 Hz.
15
+ - **Cihazdan alınabilen her şey** — ivme (G-sensör), hafıza kartı doluluğu, kamera sayısı, RTSP adresleri, cihaz
16
+ bilgileri, tanınmayan mesajlar ham olarak. Overlay istediğini kullanır: [docs/data.md](docs/data.md).
17
+ - **Tünelde de harita boş kalmaz** — GPS koparsa son bilinen konum kullanılır, yeniden başlatmada bile korunur.
18
+ - **Başka cihazda / VPN üzerinden** — Raspberry Pi, Tailscale/WireGuard, kendi alan adın (token + TLS ile):
19
+ [docs/remote.md](docs/remote.md).
20
+ - **Modüler sürücü yapısı** — yeni kamera / GPS cihazı tek bir modülle eklenir ([docs/drivers.md](docs/drivers.md)).
21
+ - **Kendi kendini onarır** — kamera kapanıp açılsa ya da Wi-Fi kopsa yeniden bağlanır.
22
+ - **Gizlilik öncelikli** — varsayılan olarak yalnız `127.0.0.1`'i dinler, yalnız izin verilen siteler veriyi okuyabilir.
23
+ - **Tek bağımlılık** (`ws`), Node.js 22.18+.
24
+
25
+ ## Desteklenen cihazlar
26
+
27
+ | Cihaz | Sürücü | Durum |
28
+ | --- | --- | --- |
29
+ | DDPAI N5 Pro (firmware v8.0.0.10) | `ddpai` | Sahada test edildi |
30
+ | Diğer DDPAI modelleri (TCP 6100 telemetrisi olanlar) | `ddpai` | Büyük olasılıkla çalışır, deneyip [bildir](https://github.com/ramazansancar/overlays-server/issues/new?template=device-report.yml) |
31
+ | Simülatör (cihazsız deneme) | `simulator` | — |
32
+
33
+ Cihaz ayrıntıları ve test edildiği ortamlar: [docs/devices/](docs/devices/README.md).
34
+ **Cihazın listede yok mu?** [Yeni cihaz ekleme rehberi](docs/new-device.md): tek komutla (`--probe`) cihazını
35
+ incele, raporu issue olarak gönder.
36
+
37
+ ## Kurulum
38
+
39
+ İki yol var, ikisi de aynı sunucuyu çalıştırır. **Node.js 22.18 veya üstü** gerekli ([nodejs.org](https://nodejs.org)).
40
+
41
+ ### A) npm ile (en kolay)
42
+
43
+ ```bash
44
+ npx overlays-server@latest
45
+ ```
46
+
47
+ `@latest` her açılışta npm'deki son sürümü kontrol eder (yalnız `npx overlays-server` yazarsan daha önce indirilen
48
+ sürüm kullanılabilir). Kalıcı kurmak istersen:
49
+
50
+ ```bash
51
+ npm install -g overlays-server
52
+ overlays-server
53
+ ```
54
+
55
+ **Güncelleme (kalıcı kurulum):**
56
+
57
+ ```bash
58
+ overlays-server --version # kurulu sürüm
59
+ npm outdated -g overlays-server # yeni sürüm var mı? (çıktı boşsa güncelsin)
60
+ npm install -g overlays-server@latest
61
+ ```
62
+
63
+ Kaldırmak için: `npm uninstall -g overlays-server`.
64
+
65
+ ### B) Git ile (kaynaktan)
66
+
67
+ ```bash
68
+ git clone https://github.com/ramazansancar/overlays-server.git
69
+ cd overlays-server
70
+ npm install --omit=dev # ya da: pnpm install --prod
71
+ npm start
72
+ ```
73
+
74
+ Windows'ta klasördeki **`start.cmd`** dosyasına çift tıklamak da yeterli: her açılışta önce `git pull` ile kendini
75
+ günceller, gerekirse bağımlılıkları kurar, sonra sunucuyu başlatır. İnternet yoksa uyarı verip mevcut sürümle açılır;
76
+ otomatik güncellemeyi kapatmak için `set OVERLAYS_SERVER_NO_UPDATE=1`.
77
+
78
+ **Güncelleme (git kurulumu):** `start.cmd` kullanıyorsan bir şey yapmana gerek yok. Elle:
79
+
80
+ ```bash
81
+ cd overlays-server
82
+ git pull
83
+ npm install --omit=dev # bağımlılıklar değiştiyse günceller
84
+ ```
85
+
86
+ Belirli bir sürüme geçmek için: `git fetch --tags && git checkout v0.1.0`. Değişiklikler: [CHANGELOG.md](CHANGELOG.md).
87
+
88
+ Derleme adımı yok: Node.js 22.18+ TypeScript dosyalarını doğrudan çalıştırır.
89
+
90
+ ### Çalıştığını kontrol et
91
+
92
+ Tarayıcıda **<http://127.0.0.1:3456>** adresini aç. Durum sayfası kameranın bağlı olup olmadığını ve GPS durumunu
93
+ canlı gösterir (koordinatlar varsayılan olarak gizli, yayında gösterilebilir).
94
+
95
+ ## Kullanım
96
+
97
+ 1. **Bilgisayarı kameranın Wi-Fi'ına bağla** (`DDPAI_...` ağı). İnternet Ethernet'ten (ör. Superbox) gelmeye devam
98
+ etmeli. Windows ayarı için: [docs/windows-network.md](docs/windows-network.md).
99
+ 2. **overlays-server'ı başlat** (yukarıdaki iki yoldan biri). Konsolda `ddpai: link online` ve `ddpai: gps fix` görünür.
100
+ 3. **[Overlay ayarlarında](https://overlays.ramazansancar.com.tr)** harita overlay'inin *Konum kaynağı* olarak
101
+ **Araç kamerası GPS — overlays-server [yerel]** seçeneğini seç. Altında açılan *Sunucu adresi* (`127.0.0.1`) ve
102
+ *Sunucu portu* (`3456`) varsayılan kurulumda olduğu gibi kalabilir. Sonra URL'yi OBS tarayıcı kaynağına ekle.
103
+
104
+ Kamera yoksa sistemi denemek için: `npx overlays-server@latest --simulate` (Ankara'da daire çizen sahte konum).
105
+
106
+ ### Başka bir cihazda ya da VPN üzerinden
107
+
108
+ Sunucu bir Raspberry Pi'de, başka bir bilgisayarda ya da uzakta çalışabilir; overlay (yayın bilgisayarındaki ya da
109
+ buluttaki OBS) ona yerel IP, VPN IP'si ya da alan adı/genel IP ile bağlanır. Kısaca:
110
+
111
+ | Kurulum | Sunucu | Overlay ayarı |
112
+ | --- | --- | --- |
113
+ | Aynı ağdaki Pi / VPN IP'si | `"host": "0.0.0.0"`, `"token"` | Pi'nin IP'si, port, token |
114
+ | Tailscale + HTTPS (önerilen) | `tailscale serve --https=443 http://127.0.0.1:3456`, `"allowedHosts"` | `pi.<tailnet>.ts.net`, `443`, **Güvenli bağlantı** |
115
+ | Genel IP / alan adı | `"host": "0.0.0.0"`, `"token"`, `"tls"` ya da Caddy/Nginx | alan adı, port, token, **Güvenli bağlantı** |
116
+
117
+ `127.0.0.1` dışında dinlerken **mutlaka token kullan**. Ayrıntılı rehber, systemd ve Caddy örnekleri:
118
+ [docs/remote.md](docs/remote.md).
119
+
120
+ ### Windows açılışında otomatik başlatma
121
+
122
+ `Win + R` → `shell:startup` → açılan klasöre `start.cmd`'nin (git kurulumu) ya da şu içerikte bir `.cmd` dosyasının
123
+ kısayolunu koy:
124
+
125
+ ```bat
126
+ @echo off
127
+ npx overlays-server@latest
128
+ ```
129
+
130
+ ## Ayarlar
131
+
132
+ Varsayılanlar çoğu kurulum için yeterli. Değiştirmek için bir JSON dosyası oluştur
133
+ ([config.example.json](config.example.json) örneğini kopyala). Sunucu ayar dosyasını şu sırayla arar:
134
+
135
+ 1. `--config <dosya>`
136
+ 2. `OVERLAYS_SERVER_CONFIG` ortam değişkeni
137
+ 3. Çalışma klasöründe `overlays-server.config.json`
138
+ 4. Kullanıcı klasörü: Windows `%APPDATA%\overlays-server\config.json`, Linux/macOS `~/.config/overlays-server/config.json`
139
+
140
+ | Anahtar | Varsayılan | Açıklama |
141
+ | --- | --- | --- |
142
+ | `port` | `3456` | Dinlenecek port |
143
+ | `host` | `127.0.0.1` | Dinlenecek arayüz. Başka cihazdan erişim için `0.0.0.0` (token ile) |
144
+ | `allowedOrigins` | overlay sitesi + localhost | Veriyi okuyabilecek web siteleri (`https://site`, `http://localhost:*`, `*`) |
145
+ | `token` | — | Ayarlanırsa istemciler `?token=...` göndermek zorunda |
146
+ | `allowedHosts` | `[]` | Ters vekil (Tailscale Serve, Caddy) arkasında kabul edilecek ek alan adları |
147
+ | `tls` | — | `{ "certFile", "keyFile" }`: doğrudan HTTPS / WSS sun |
148
+ | `staleAfterMs` | `5000` | Bu kadar süre GPS gelmezse durum `stale` olur |
149
+ | `gpsPriority` | `[]` | Birden fazla GPS kaynağı varsa tercih sırası (ilk sıradaki koparsa sonrakine geçer) |
150
+ | `motionMaxHz` | `10` | İstemci başına saniyedeki en fazla ivme mesajı |
151
+ | `logLevel` | `info` | `debug`, `info`, `warn`, `error`, `silent` |
152
+ | `rememberLastPosition` | `true` | Son konumu diske yaz; GPS yokken (tünel) ya da yeniden başlatmadan sonra onu göster |
153
+ | `stateFile` | kullanıcı klasöründe `last-position.json` | Son konumun saklandığı dosya |
154
+ | `sources` | `[{ "driver": "ddpai" }]` | Kaynak listesi; her biri `id`, `driver`, `enabled`, `options` |
155
+
156
+ Sürücü seçenekleri: [docs/devices/ddpai.md](docs/devices/ddpai.md#options), [docs/drivers.md](docs/drivers.md#simulator).
157
+
158
+ ### Komut satırı
159
+
160
+ ```text
161
+ overlays-server [seçenekler]
162
+ -c, --config <dosya> Ayar dosyası
163
+ -p, --port <port> Port (varsayılan 3456)
164
+ --host <adres> Dinlenecek arayüz (varsayılan 127.0.0.1)
165
+ --origin <origin> Ek izinli site (tekrarlanabilir)
166
+ --token <gizli> İstemcilerden ?token= iste
167
+ --allowed-host <ad> Ters vekil arkasındaki ek alan adı (tekrarlanabilir)
168
+ --tls-cert <dosya> HTTPS/WSS için PEM sertifika (--tls-key ile)
169
+ --tls-key <dosya> PEM özel anahtar
170
+ --ddpai-host <ip> DDPAI kamera adresi (varsayılan 193.168.0.1)
171
+ --ddpai-http-port <port> DDPAI HTTP API portu (varsayılan 80)
172
+ --simulate Kaynak yerine simülatörü kullan
173
+ --log-level <seviye> debug | info | warn | error | silent
174
+ --print-config Geçerli ayarları yazdır ve çık
175
+ --list-drivers Sürücüleri listele ve çık
176
+ --probe <adres> Cihazı incele (portlar, model, veri örnekleri), issue için rapor yazdır
177
+ --probe-ports <liste> --probe için portlar, virgülle (ör. 80,554,6100)
178
+ -v, --version / -h, --help
179
+ ```
180
+
181
+ Ortam değişkenleri: `OVERLAYS_SERVER_PORT`, `OVERLAYS_SERVER_HOST`, `OVERLAYS_SERVER_LOG_LEVEL`, `OVERLAYS_SERVER_CONFIG`.
182
+
183
+ ## Uç noktalar
184
+
185
+ | Yol | Açıklama |
186
+ | --- | --- |
187
+ | `GET /` | Durum sayfası |
188
+ | `GET /health` | Sunucu açık mı? (sürüm, kaynakların bağlantı durumu; konum yok, token istemez) |
189
+ | `GET /v1/state` | Tüm kaynakların durumu ve son konumu (JSON) |
190
+ | `WS /v1/ws` | Canlı akış (ana kanal) |
191
+ | `GET /v1/stream` | Canlı akış, Server-Sent Events (yedek) |
192
+ | `GET /v1/diagnostics` | Tanı dosyası (son ham cihaz verisi, loglar, ayarlar) |
193
+
194
+ Akış parametreleri: `source=<id|auto|*>`, `motion=1` (ivme), `events=1` (ham cihaz mesajları), `all=1`, `token=...`.
195
+ Mesaj biçimi: [docs/protocol.md](docs/protocol.md). **Hangi veriler var?** (konum, hız, yön, rakım, uydu, HDOP, ivme,
196
+ hafıza kartı, kamera sayısı, RTSP adresleri, cihaz bilgileri, ham olaylar): [docs/data.md](docs/data.md).
197
+
198
+ ## Sorun giderme
199
+
200
+ **Önce durum sayfasına bak:** <http://127.0.0.1:3456>. Kaynakların bağlantı ve GPS durumu canlı görünür; konumu
201
+ gösterip Google Maps / Yandex / OpenStreetMap'te açabilirsin.
202
+
203
+ **Hata bildirirken tanı dosyasını ekle:** durum sayfasının altındaki **Tanı verisini indir** butonu tek bir `.json`
204
+ dosyası verir: cihazdan gelen son ~2 dakikalık ham veri, son log satırları, ayarlar ve durum. Bu dosyayla sorunu
205
+ kendi bilgisayarımızda aynen tekrar oynatıp düzeltebiliyoruz. Wi-Fi şifresi, seri numarası ve MAC adresleri her zaman
206
+ gizlenir; konum yalnızca **Konumu dahil et** işaretliyse eklenir (harita/konum sorunlarında gerekli). Komut satırından:
207
+ `curl.exe -o tani.json http://127.0.0.1:3456/v1/diagnostics`. Aynı dosya overlay ayar sayfasından da (konum kaynağı
208
+ *Araç kamerası GPS — overlays-server [yerel]* seçiliyken **Tanı verisini indir**) tarihli adla indirilebilir.
209
+
210
+ **Durum sayfasında `connecting` / "is this PC connected to the camera Wi-Fi?"** — Bilgisayar kameranın Wi-Fi'ına
211
+ bağlı değil ya da Windows `193.168.0.1`'i yanlış arayüze yolluyor. [docs/windows-network.md](docs/windows-network.md).
212
+
213
+ **`gps: no_fix`** — Kamera bağlı ama uydu kilidi yok. Açık gökyüzünde birkaç dakika bekle.
214
+
215
+ **Tünel / kapalı otopark (GPS koptu)** — Harita son bilinen konumda kalır, hız 0 görünür; sinyal gelince kaldığı
216
+ yerden devam eder. OBS sahnesi ya da bilgisayar bu sırada yeniden başlasa bile son konum korunur: sunucu son konumu
217
+ `last-position.json` dosyasında saklar ve yeni bağlanan overlay'e "son bilinen konum" olarak gönderir, overlay de
218
+ tarayıcıda son konumu hatırlar. Kapatmak için `"rememberLastPosition": false`.
219
+
220
+ **Overlay bir uyarı gösteriyor** — Overlay bağlanamazsa sunucunun `/health` ucuna sorup nedenini yazar:
221
+
222
+ | Overlay'deki mesaj | Ne yapmalı |
223
+ | --- | --- |
224
+ | *Yerel sunucuya ulaşılamadı* | Sunucu kapalı, adres/port yanlış ya da overlay'i açtığın site `allowedOrigins`'te değil. Durum sayfası açılıyorsa sunucunun konsoluna bak (`refused an overlay connection`) ve aşağıdaki tarayıcı izni maddesine bak |
225
+ | *Yerel sunucu açık ama canlı bağlantıyı reddetti* | Sunucuda `token` ayarlı: overlay ayarlarındaki *Sunucu anahtarı* alanına yaz |
226
+ | *Sunucu kameraya bağlanıyor…* / *Kamera uydu arıyor* | Sunucu çalışıyor; sorun kamera tarafında (Wi-Fi, uydu) |
227
+
228
+ Sunucu reddettiği her bağlantıyı konsola yazar (`refused an overlay connection: ...`). İzin verilmeyen sitelere güvenlik
229
+ gereği hiçbir yanıt vermediği için overlay o durumu "ulaşılamadı" olarak görür.
230
+
231
+ **Durum sayfası çalışıyor ama overlay sunucuya ulaşamıyor** — Tarayıcının *Yerel Ağ Erişimi* (Local Network Access)
232
+ kısıtı:
233
+
234
+ - **OBS 33.0+**: localhost erişimine otomatik izin veriyor. OBS 33 **beta** kullandıysan eski bir ret kalıcı
235
+ kaydedilmiş olabilir: OBS'i kapat, `%APPDATA%\obs-studio\plugin_config\obs-browser` klasörünü sil, OBS'i aç.
236
+ Hâlâ olmuyorsa OBS kısayolunun sonuna `--disable-features=LocalNetworkAccessChecks` ekle.
237
+ - **Chrome / Edge** (ayar sayfası, "Pencerede aç" modu): adres çubuğunda çıkan izin isteğinde **İzin ver** de.
238
+ - **Sunucu başka cihazda / alan adıyla** erişiliyorsa `wss://` gerekir: [docs/remote.md](docs/remote.md).
239
+
240
+ **`port 3456 is already in use`** — Sunucu zaten açık (ikinci pencere?) ya da port başka programda. `--port` ile değiştir
241
+ ve overlay ayarındaki adresi de güncelle.
242
+
243
+ ## Güvenlik ve gizlilik
244
+
245
+ Canlı konum hassas bir veridir. Sunucu varsayılan olarak:
246
+
247
+ - yalnız `127.0.0.1`'i dinler (ağdaki başka cihazlar erişemez); başka bir arayüzde token'sız dinlerse uyarır,
248
+ - yalnız `allowedOrigins` listesindeki sitelerin veriyi okumasına izin verir; diğer sitelere CORS başlığı bile
249
+ göndermez (sunucunun varlığını öğrenemezler),
250
+ - DNS rebinding saldırılarına karşı `Host` başlığını kontrol eder (`127.0.0.1.saldirgan.com` gibi adlar dahil),
251
+ - kameraya **yalnız okuma** komutları gönderir, hiçbir ayarı değiştirmez,
252
+ - kameranın döndürdüğü Wi-Fi şifresini, seri numaralarını ve MAC adreslerini hiçbir yere yazmaz ya da iletmez.
253
+
254
+ Bunların hepsi otomatik testlerle doğrulanır (`test/security-e2e.test.ts`, `e2e/`). Ayrıntı ve açık bildirme:
255
+ [SECURITY.md](SECURITY.md). DDPAI kameranın **varsayılan Wi-Fi şifresini değiştir**: aynı ağa giren herkes kameranın
256
+ görüntüsüne ve ayarlarına erişebilir.
257
+
258
+ ## Geliştirme
259
+
260
+ ```bash
261
+ pnpm install
262
+ pnpm dev # kamerasız geliştirme: sahte DDPAI kamera + sunucu tek terminalde, dosya değişince yeniden başlar
263
+ pnpm dev:fake-camera # ya da iki terminal: 1) sahte kamera (bağlantıları loglar)
264
+ pnpm dev:server # 2) ona bağlanan sunucu
265
+ pnpm dev -- --no-fix --speed 90 --drop-every 20 # uydu yok / hız / bağlantı kopma senaryoları
266
+ pnpm dev -- --replay tani.json # bir yayıncının tanı dosyasını tekrar oynat
267
+ pnpm dev:camera # gerçek kamerayla (193.168.0.1), izleme modunda
268
+ pnpm check # tip kontrolü (TypeScript 7) + birim, entegrasyon ve süreç testleri
269
+ pnpm test:coverage # kapsama raporuyla
270
+ pnpm test:e2e # durum sayfası tarayıcı testleri (Playwright)
271
+ pnpm build # dist/ (npm paketi)
272
+ ```
273
+
274
+ Yerelde uçtan uca test (sahte kamera + overlay sitesi + OBS): [docs/testing-locally.md](docs/testing-locally.md).
275
+ Mimari, kod kuralları ve yeni sürücü ekleme: [CONTRIBUTING.md](CONTRIBUTING.md), [docs/architecture.md](docs/architecture.md).
276
+
277
+ ## Katkıda bulunanlar
278
+
279
+ Katkılar memnuniyetle karşılanır. Özellikle **farklı kamera modelleriyle test sonuçları** çok değerli.
280
+ [CONTRIBUTING.md](CONTRIBUTING.md) dosyasına göz at. Tüm katkıda bulunanlar:
281
+ [github.com/ramazansancar/overlays-server/graphs/contributors](https://github.com/ramazansancar/overlays-server/graphs/contributors).
282
+
283
+ ## Lisans
284
+
285
+ [GNU AGPL-3.0](LICENSE) (veya sonraki sürümleri) © 2026 Ramazan Sancar.
286
+
287
+ Kısaca: ücretsiz kullanabilir, değiştirebilir, ticari işlerde de kullanabilirsin. Ama değiştirilmiş bir sürümü
288
+ **dağıtırsan** (paket, exe, kurulum) **ya da ağ üzerinden başkalarına hizmet olarak sunarsan**, o sürümün kaynak kodunu
289
+ da aynı lisansla açmak zorundasın. Durum sayfasındaki kaynak kod linkini kendi kaynağını gösterecek şekilde koru.
290
+ Bağlayıcı olan [LICENSE](LICENSE) metnidir.
291
+
292
+ DDPAI, DDPAI Technology Co., Ltd.'nin markasıdır; bu proje onlarla bağlantılı değildir.
package/README.md CHANGED
@@ -1,3 +1,296 @@
1
- # Temporary Holding Version
1
+ # overlays-server
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ **English** · [Türkçe](README-tr.md)
4
+
5
+ A small **local bridge server** that runs on the streamer's PC (or on a Raspberry Pi in the car). It reads live GPS
6
+ from a dashcam (currently **DDPAI**) and streams it once per second over WebSocket to the
7
+ [Stream Overlays](https://overlays.ramazansancar.com.tr) map overlay. No phone, no cloud service, no RealtimeIRL: the
8
+ position comes straight from the camera over the local network.
9
+
10
+ ```text
11
+ DDPAI camera (Wi-Fi, 193.168.0.1:6100) ──► overlays-server (127.0.0.1:3456) ──► OBS browser source (map)
12
+ ```
13
+
14
+ - **Live position, speed, heading, altitude, satellites, GPS quality** — from the camera's own GPS, 1 Hz.
15
+ - **Everything the device offers** — acceleration (G-sensor), memory card usage, camera count, RTSP URLs, device
16
+ details, unknown messages passed through raw. Overlays use what they need: [docs/data.md](docs/data.md).
17
+ - **No empty map in tunnels** — when GPS drops, the last known position is used, even across restarts.
18
+ - **On another device / over a VPN** — Raspberry Pi, Tailscale/WireGuard, your own domain (with token + TLS):
19
+ [docs/remote.md](docs/remote.md).
20
+ - **Modular drivers** — a new camera / GPS device is one module ([docs/drivers.md](docs/drivers.md)).
21
+ - **Self-healing** — reconnects when the camera restarts or its Wi-Fi drops.
22
+ - **Privacy first** — listens on `127.0.0.1` by default, only allowed websites can read the data.
23
+ - **One runtime dependency** (`ws`), Node.js 22.18+.
24
+
25
+ ## Supported devices
26
+
27
+ | Device | Driver | Status |
28
+ | --- | --- | --- |
29
+ | DDPAI N5 Pro (firmware v8.0.0.10) | `ddpai` | Field tested |
30
+ | Other DDPAI models with TCP 6100 telemetry | `ddpai` | Very likely; try it and [report](https://github.com/ramazansancar/overlays-server/issues/new?template=device-report.yml) |
31
+ | Simulator (no hardware) | `simulator` | — |
32
+
33
+ Device details and tested environments: [docs/devices/](docs/devices/README.md).
34
+ **Your device is not listed?** [New device guide](docs/new-device.md): inspect it with one command (`--probe`) and
35
+ send the report as an issue.
36
+
37
+ ## Install
38
+
39
+ Two ways, both run the same server. Requires **Node.js 22.18 or newer** ([nodejs.org](https://nodejs.org)).
40
+
41
+ ### A) With npm (easiest)
42
+
43
+ ```bash
44
+ npx overlays-server@latest
45
+ ```
46
+
47
+ `@latest` checks npm for the newest version on every start (plain `npx overlays-server` may reuse an older download).
48
+ To install it permanently:
49
+
50
+ ```bash
51
+ npm install -g overlays-server
52
+ overlays-server
53
+ ```
54
+
55
+ **Updating (permanent install):**
56
+
57
+ ```bash
58
+ overlays-server --version # installed version
59
+ npm outdated -g overlays-server # is there a newer one? (no output = up to date)
60
+ npm install -g overlays-server@latest
61
+ ```
62
+
63
+ Uninstall: `npm uninstall -g overlays-server`.
64
+
65
+ ### B) With git (from source)
66
+
67
+ ```bash
68
+ git clone https://github.com/ramazansancar/overlays-server.git
69
+ cd overlays-server
70
+ npm install --omit=dev # or: pnpm install --prod
71
+ npm start
72
+ ```
73
+
74
+ On Windows, double-clicking **`start.cmd`** in the folder is enough: on every start it updates itself with `git pull`,
75
+ installs dependencies when needed, then starts the server. Without internet it warns and starts the current version;
76
+ set `OVERLAYS_SERVER_NO_UPDATE=1` to skip the update.
77
+
78
+ **Updating (git install):** nothing to do when you use `start.cmd`. By hand:
79
+
80
+ ```bash
81
+ cd overlays-server
82
+ git pull
83
+ npm install --omit=dev # updates dependencies if they changed
84
+ ```
85
+
86
+ A specific version: `git fetch --tags && git checkout v0.1.0`. Changes: [CHANGELOG.md](CHANGELOG.md).
87
+
88
+ There is no build step: Node.js 22.18+ runs the TypeScript files directly.
89
+
90
+ ### Check that it works
91
+
92
+ Open **<http://127.0.0.1:3456>** in a browser. The status page shows live whether the camera is connected and the GPS
93
+ state (coordinates are hidden by default, so it can be shown on stream).
94
+
95
+ ## Usage
96
+
97
+ 1. **Connect the PC to the camera's Wi-Fi** (`DDPAI_...` network). Internet should keep coming over Ethernet (e.g. a
98
+ 4.5G/5G router). Windows setup: [docs/windows-network.md](docs/windows-network.md).
99
+ 2. **Start overlays-server** (either way above). The console shows `ddpai: link online` and `ddpai: gps fix`.
100
+ 3. In the **[overlay settings](https://overlays.ramazansancar.com.tr)** pick **Dashcam GPS — overlays-server [local]**
101
+ as the map overlay's *Location source*. The *Server address* (`127.0.0.1`) and *Server port* (`3456`) below it can
102
+ stay as they are for the default setup. Then add the URL as an OBS browser source.
103
+
104
+ To try everything without a camera: `npx overlays-server@latest --simulate` (a fake position driving in circles in
105
+ Ankara).
106
+
107
+ ### On another device or over a VPN
108
+
109
+ The server can run on a Raspberry Pi, another computer or somewhere remote; the overlay (OBS on the streaming PC or
110
+ in the cloud) reaches it by LAN IP, VPN IP or a domain / public IP. In short:
111
+
112
+ | Setup | Server | Overlay settings |
113
+ | --- | --- | --- |
114
+ | Pi on the same LAN / VPN IP | `"host": "0.0.0.0"`, `"token"` | Pi's IP, port, token |
115
+ | Tailscale + HTTPS (recommended) | `tailscale serve --https=443 http://127.0.0.1:3456`, `"allowedHosts"` | `pi.<tailnet>.ts.net`, `443`, **Secure connection** |
116
+ | Public IP / domain | `"host": "0.0.0.0"`, `"token"`, `"tls"` or Caddy/Nginx | domain, port, token, **Secure connection** |
117
+
118
+ **Always use a token** when listening on anything other than `127.0.0.1`. Full guide with systemd and Caddy examples:
119
+ [docs/remote.md](docs/remote.md).
120
+
121
+ ### Start with Windows
122
+
123
+ `Win + R` → `shell:startup` → put a shortcut to `start.cmd` (git install) or to a `.cmd` file with this content in
124
+ that folder:
125
+
126
+ ```bat
127
+ @echo off
128
+ npx overlays-server@latest
129
+ ```
130
+
131
+ ## Configuration
132
+
133
+ The defaults fit most setups. To change them, create a JSON file (copy [config.example.json](config.example.json)).
134
+ The server looks for it in this order:
135
+
136
+ 1. `--config <file>`
137
+ 2. the `OVERLAYS_SERVER_CONFIG` environment variable
138
+ 3. `overlays-server.config.json` in the working directory
139
+ 4. the user folder: Windows `%APPDATA%\overlays-server\config.json`, Linux/macOS `~/.config/overlays-server/config.json`
140
+
141
+ | Key | Default | Description |
142
+ | --- | --- | --- |
143
+ | `port` | `3456` | Port to listen on |
144
+ | `host` | `127.0.0.1` | Interface to listen on. `0.0.0.0` for access from other devices (with a token) |
145
+ | `allowedOrigins` | overlay site + localhost | Websites allowed to read the data (`https://site`, `http://localhost:*`, `*`) |
146
+ | `token` | — | When set, clients must send `?token=...` |
147
+ | `allowedHosts` | `[]` | Extra host names accepted behind a reverse proxy (Tailscale Serve, Caddy) |
148
+ | `tls` | — | `{ "certFile", "keyFile" }`: serve HTTPS / WSS directly |
149
+ | `staleAfterMs` | `5000` | A source without GPS for this long is `stale` |
150
+ | `gpsPriority` | `[]` | Preference order with several GPS sources (falls back when the first drops) |
151
+ | `motionMaxHz` | `10` | Maximum acceleration messages per client per second |
152
+ | `logLevel` | `info` | `debug`, `info`, `warn`, `error`, `silent` |
153
+ | `rememberLastPosition` | `true` | Keep the last position on disk; show it while GPS is lost (tunnel) or after a restart |
154
+ | `stateFile` | `last-position.json` in the user folder | Where the last position is kept |
155
+ | `sources` | `[{ "driver": "ddpai" }]` | List of sources; each has `id`, `driver`, `enabled`, `options` |
156
+
157
+ Driver options: [docs/devices/ddpai.md](docs/devices/ddpai.md#options), [docs/drivers.md](docs/drivers.md#simulator).
158
+
159
+ ### Command line
160
+
161
+ ```text
162
+ overlays-server [options]
163
+ -c, --config <file> Config file
164
+ -p, --port <port> Port (default 3456)
165
+ --host <address> Interface to listen on (default 127.0.0.1)
166
+ --origin <origin> Extra allowed website (repeatable)
167
+ --token <secret> Require ?token= from clients
168
+ --allowed-host <name> Extra host name behind a reverse proxy (repeatable)
169
+ --tls-cert <file> PEM certificate for HTTPS/WSS (with --tls-key)
170
+ --tls-key <file> PEM private key
171
+ --ddpai-host <ip> DDPAI camera address (default 193.168.0.1)
172
+ --ddpai-http-port <port> DDPAI HTTP API port (default 80)
173
+ --simulate Use the simulator instead of the configured sources
174
+ --log-level <level> debug | info | warn | error | silent
175
+ --print-config Print the effective config and exit
176
+ --list-drivers List drivers and exit
177
+ --probe <address> Inspect a device (ports, model, data samples) and print a report for an issue
178
+ --probe-ports <list> Ports for --probe, comma separated (e.g. 80,554,6100)
179
+ -v, --version / -h, --help
180
+ ```
181
+
182
+ Environment variables: `OVERLAYS_SERVER_PORT`, `OVERLAYS_SERVER_HOST`, `OVERLAYS_SERVER_LOG_LEVEL`, `OVERLAYS_SERVER_CONFIG`.
183
+
184
+ ## Endpoints
185
+
186
+ | Path | Description |
187
+ | --- | --- |
188
+ | `GET /` | Status page |
189
+ | `GET /health` | Is the server up? (version, per-source state; no position, no token needed) |
190
+ | `GET /v1/state` | Every source's state and last position (JSON) |
191
+ | `WS /v1/ws` | Live stream (main channel) |
192
+ | `GET /v1/stream` | Live stream, Server-Sent Events (fallback) |
193
+ | `GET /v1/diagnostics` | Diagnostics file (recent raw device data, logs, settings) |
194
+
195
+ Stream parameters: `source=<id|auto|*>`, `motion=1` (acceleration), `events=1` (raw device messages), `all=1`,
196
+ `token=...`. Message format: [docs/protocol.md](docs/protocol.md). **What data is there?** (position, speed, heading,
197
+ altitude, satellites, HDOP, acceleration, memory card, camera count, RTSP URLs, device details, raw events):
198
+ [docs/data.md](docs/data.md).
199
+
200
+ ## Troubleshooting
201
+
202
+ **Look at the status page first:** <http://127.0.0.1:3456>. Connection and GPS state of every source are live there;
203
+ you can show the position and open it in Google Maps / Yandex / OpenStreetMap.
204
+
205
+ **Attach a diagnostics file to bug reports:** the **Download diagnostics** button at the bottom of the status page
206
+ gives one `.json` file: the last ~2 minutes of raw device data, recent log lines, settings and state. With it we can
207
+ replay the problem exactly on our machine and fix it. Wi-Fi passwords, serial numbers and MAC addresses are always
208
+ removed; the position only when **Include my position** is ticked (needed for map / position problems). From the
209
+ command line: `curl -o diagnostics.json http://127.0.0.1:3456/v1/diagnostics`. The overlay settings page offers the
210
+ same download (with the local server selected as location source), named with the date and time.
211
+
212
+ **Status page says `connecting` / "is this PC connected to the camera Wi-Fi?"** — the PC is not on the camera's Wi-Fi,
213
+ or Windows sends `193.168.0.1` to the wrong adapter. [docs/windows-network.md](docs/windows-network.md).
214
+
215
+ **`gps: no_fix`** — the camera is connected but has no satellite lock. Wait a few minutes under open sky.
216
+
217
+ **Tunnel / underground car park (GPS lost)** — the map stays at the last known position with speed 0 and continues
218
+ when the signal returns. Even if OBS or the PC restarts meanwhile, the position is kept: the server stores it in
219
+ `last-position.json` and sends it to newly connected overlays as "last known position", and the overlay also remembers
220
+ it in the browser. Turn off with `"rememberLastPosition": false`.
221
+
222
+ **The overlay shows a warning** — when it cannot connect, the overlay asks the server's `/health` and says why:
223
+
224
+ | Overlay message | What to do |
225
+ | --- | --- |
226
+ | *Cannot reach the local server* | Server not running, wrong address/port, or the site you opened the overlay from is not in `allowedOrigins`. If the status page opens, check the server console (`refused an overlay connection`) and the browser permission point below |
227
+ | *Local server is up but refused the live connection* | The server has a `token`: enter it in the overlay settings' *Server token* field |
228
+ | *Server is connecting to the camera…* / *Camera is searching satellites* | The server works; the problem is on the camera side (Wi-Fi, satellites) |
229
+
230
+ The server logs every refused connection (`refused an overlay connection: ...`). It does not answer websites that are
231
+ not allowed at all (for security), so the overlay sees that case as "cannot reach".
232
+
233
+ **Status page works but the overlay cannot reach the server** — the browser's *Local Network Access* restriction:
234
+
235
+ - **OBS 33.0+** allows localhost automatically. If you ran an OBS 33 **beta**, an old denial may be stored: close OBS,
236
+ delete `%APPDATA%\obs-studio\plugin_config\obs-browser`, start OBS. Still failing: add
237
+ `--disable-features=LocalNetworkAccessChecks` to the OBS shortcut.
238
+ - **Chrome / Edge** (settings page, "open in window" mode): click **Allow** on the permission prompt.
239
+ - **Server on another device / reached by domain:** needs `wss://`, see [docs/remote.md](docs/remote.md).
240
+
241
+ **`port 3456 is already in use`** — the server is already running (second window?) or another program uses the port.
242
+ Change it with `--port` and update the address in the overlay settings.
243
+
244
+ ## Security and privacy
245
+
246
+ A live position is sensitive. By default the server:
247
+
248
+ - listens on `127.0.0.1` only (other devices cannot reach it) and warns when it listens elsewhere without a token,
249
+ - lets only websites in `allowedOrigins` read the data and sends no CORS headers to any other site (they cannot even
250
+ detect it),
251
+ - checks the `Host` header against DNS rebinding (including names like `127.0.0.1.attacker.example`),
252
+ - sends the camera **read-only** commands and never changes its settings,
253
+ - never stores or forwards the Wi-Fi password, serial numbers or MAC addresses the camera reports.
254
+
255
+ All of this is covered by automated tests (`test/security-e2e.test.ts`, `e2e/`). Details and reporting
256
+ vulnerabilities: [SECURITY.md](SECURITY.md). **Change the DDPAI camera's default Wi-Fi password**: anyone on that
257
+ network can see the camera's video and use its settings.
258
+
259
+ ## Development
260
+
261
+ ```bash
262
+ pnpm install
263
+ pnpm dev # no camera needed: fake DDPAI camera + server in one terminal, restarts on file changes
264
+ pnpm dev:fake-camera # or two terminals: 1) fake camera (logs connections)
265
+ pnpm dev:server # 2) a server connected to it
266
+ pnpm dev -- --no-fix --speed 90 --drop-every 20 # no satellites / speed / dropped connection scenarios
267
+ pnpm dev -- --replay diagnostics.json # replay a streamer's diagnostics file
268
+ pnpm dev:camera # with the real camera (193.168.0.1), watch mode
269
+ pnpm check # typecheck (TypeScript 7) + unit, integration and process tests
270
+ pnpm test:coverage # with a coverage report
271
+ pnpm test:e2e # status page browser tests (Playwright)
272
+ pnpm build # dist/ (npm package)
273
+ ```
274
+
275
+ End-to-end testing on your machine (fake camera + overlay site + OBS): [docs/testing-locally.md](docs/testing-locally.md).
276
+ Architecture, code guidelines and adding a driver: [CONTRIBUTING.md](CONTRIBUTING.md),
277
+ [docs/architecture.md](docs/architecture.md).
278
+
279
+ ## Contributors
280
+
281
+ Contributions are welcome, especially **test reports from other camera models**. See
282
+ [CONTRIBUTING.md](CONTRIBUTING.md). Everyone who contributed:
283
+ [github.com/ramazansancar/overlays-server/graphs/contributors](https://github.com/ramazansancar/overlays-server/graphs/contributors).
284
+
285
+ Translations of this README are welcome: `README-<language>.md`, with a region where it matters
286
+ (`README-pt-BR.md`, `README-zh-TW.md`), plus a link in the language line at the top of every README.
287
+
288
+ ## License
289
+
290
+ [GNU AGPL-3.0](LICENSE) (or any later version) © 2026 Ramazan Sancar.
291
+
292
+ In short: free to use, modify and use commercially. But if you **distribute** a modified version (package, exe,
293
+ installer) **or offer it to others over a network**, you must publish its source under the same license. Keep the
294
+ status page's source link pointing to your code. The [LICENSE](LICENSE) text is binding.
295
+
296
+ DDPAI is a trademark of DDPAI Technology Co., Ltd.; this project is not affiliated with them.
@@ -0,0 +1,40 @@
1
+ {
2
+ "port": 3456,
3
+ "host": "127.0.0.1",
4
+ "allowedOrigins": [
5
+ "https://overlays.ramazansancar.com.tr",
6
+ "http://localhost:*",
7
+ "http://127.0.0.1:*"
8
+ ],
9
+ "staleAfterMs": 5000,
10
+ "motionMaxHz": 10,
11
+ "logLevel": "info",
12
+ "rememberLastPosition": true,
13
+ "gpsPriority": ["ddpai"],
14
+ "sources": [
15
+ {
16
+ "id": "ddpai",
17
+ "driver": "ddpai",
18
+ "enabled": true,
19
+ "options": {
20
+ "host": "193.168.0.1",
21
+ "telemetryPort": 6100,
22
+ "httpPort": 80,
23
+ "deviceInfo": true,
24
+ "motion": true,
25
+ "idleTimeoutMs": 6000
26
+ }
27
+ },
28
+ {
29
+ "id": "simulator",
30
+ "driver": "simulator",
31
+ "enabled": false,
32
+ "options": {
33
+ "lat": 39.92077,
34
+ "lon": 32.85411,
35
+ "radiusM": 300,
36
+ "speedKmh": 40
37
+ }
38
+ }
39
+ ]
40
+ }
package/dist/app.d.ts ADDED
@@ -0,0 +1,19 @@
1
+ import type { AppConfig } from './config.ts';
2
+ import type { AnyDriver } from './core/driver.ts';
3
+ import { Hub } from './core/hub.ts';
4
+ import { type Logger } from './lib/log.ts';
5
+ export interface StartOptions {
6
+ config: AppConfig;
7
+ /** Drivers to use; defaults to the built-in ones. Pass your own list to add third-party drivers. */
8
+ drivers?: readonly AnyDriver[];
9
+ log?: Logger;
10
+ }
11
+ export interface RunningServer {
12
+ /** Base URL, e.g. `http://127.0.0.1:3456`. */
13
+ url: string;
14
+ port: number;
15
+ hub: Hub;
16
+ close(): Promise<void>;
17
+ }
18
+ /** Builds every enabled source, starts the HTTP/WebSocket server, then starts the sources. */
19
+ export declare function startServer(options: StartOptions): Promise<RunningServer>;