@home-network-agent/core

Agent kecil yang jalan di laptop/PC di dalam jaringan rumah dan melapor ke CCTV radar API:

• Wi-Fi scan — BSSID + RSSI + channel di sekitar device → zone/floor tracking
• LAN discovery — ping sweep + ARP neighbors → presence, vendor, fingerprint
• Fingerprint calibration — sampling RSSI per ruangan/zone untuk k-NN
• WS mode — koneksi persistent, server bisa kirim command (remote calibrate)

Zero runtime dependencies. Node ≥22 (atau Bun).

Setup sekali

# 1. Set key yang SAMA di .env API server (VPS) dan agent
#    apps/api/.env  →  RADAR_INGEST_KEY=secret-bebas-panjang

# 2. Build agent (dari packages/agent)
bun build src/cli.ts --outdir dist --target node

Tanpa build juga bisa langsung jalan:

bun src/cli.ts --api https://api.example.com --key <RADAR_INGEST_KEY>

Cara pakai per skenario

# A. Track laptop (Wi-Fi zone) — jalanin di laptop yang mau di-track
node dist/cli.js --api https://api.example.com --key <KEY>

# B. LAN discovery dari PC/server wired — detect semua device di subnet
node dist/cli.js --api https://api.example.com --key <KEY> --lan --no-wifi

# C. Calibrate zone — berdiri di dapur selama 60 detik
node dist/cli.js --api ... --key ... --zone kitchen --floor <floorPlanId> --calibrate-for 60

# D. WS mode — koneksi persistent, dashboard bisa remote-calibrate (tombol ▶ di badge zone)
node dist/cli.js --api ... --key ... --ws --lan

Konfigurasi — 3 cara

Semua opsi configurable. Precedence (yang terakhir menang):

defaults → agent.config.json → env vars (RADAR_*) → CLI flags

1. Config file — copy agent.config.example.json → agent.config.json di folder tempat kamu run, lalu cukup node dist/cli.js. Custom path: --config D:\conf\agent.json.

{
  "api": "https://api.example.com",
  "key": "secret-bebas-panjang",
  "device": "laptop-budi",
  "intervalSec": 10,
  "wifi": true,
  "lan": true,
  "lanIntervalSec": 60,
  "ws": true,
  "subnets": [],
  "zone": "",
  "floorId": "",
  "calibrateSec": 0
}

2. Env vars — semua field punya padanan RADAR_*:

| Env | Field | |----------------------|-------------------| | RADAR_API | api | | RADAR_INGEST_KEY | key | | RADAR_DEVICE | device | | RADAR_INTERVAL | intervalSec | | RADAR_LAN | lan | | RADAR_LAN_INTERVAL | lanIntervalSec | | RADAR_WIFI | wifi | | RADAR_ZONE | zone | | RADAR_FLOOR_ID | floorId | | RADAR_CALIBRATE_SEC| calibrateSec | | RADAR_WS | ws | | RADAR_SUBNETS | subnets (comma) | | RADAR_PING_TIMEOUT_MS | pingTimeoutMs |

3. CLI flags — menang paling akhir, buat override cepat:

node dist/cli.js --config agent.config.json --interval 5 --subnet 192.168.1

Referensi lengkap:

--config PATH        file config (default ./agent.config.json)
--api URL            API base URL
--key KEY            ingest key
--device NAME        identitas device (default: hostname)
--interval SEC       interval report Wi-Fi (default 10)
--lan                aktifkan LAN discovery
--lan-interval SEC   interval LAN scan (default 60)
--subnet A.B.C       /24 yang di-sweep; repeatable (default: auto-detect semua interface)
--ping-timeout MS    timeout ping per host (default 150)
--no-wifi            matikan Wi-Fi scan (PC wired)
--ws                 WebSocket transport (remote calibrate aktif)
--zone NAME          mode calibrate ke zone
--floor ID           floorPlanId untuk zone baru
--calibrate-for SEC  durasi calibrate lalu stop

Mode-mode

1. Tracking Wi-Fi (laptop yang mau di-track)

network-agent --api ... --key ...

Tiap --interval detik scan netsh/nmcli, kirim {bssid, rssi} → server hitung floor/zone via mapping AP + fingerprint k-NN.

2. LAN discovery (PC/server mana pun dalam subnet — kabel boleh)

network-agent --api ... --key ... --lan --no-wifi

Ping-sweep /24 semua interface lalu baca ARP table → IP/MAC/hostname tiap device. Detect new/online/offline devices. Subnet bisa di-override:

network-agent --api ... --key ... --lan --subnet 192.168.1 --subnet 10.0.0

3. Fingerprint calibration

# berdiri di ruangan "kitchen", jalanin 60 detik:
network-agent --api ... --key ... --zone kitchen --floor <floorPlanId> --calibrate-for 60

Atau remote-trigger dari dashboard (butuh --ws): klik ▶ di badge zone pada halaman radar → agent mulai sampling sendiri.

4. Pull mode (--serve) — VPS yang manggil agent

Berguna dengan Tailscale/subnet router: agent pasang listener, server fetch on-demand.

network-agent --api ... --key ... --serve --serve-port 8080 --serve-host 100.x.y.z --serve-key <SECRET>

Endpoints: GET /health · GET /wifi · GET /lan · GET /scan (gabungan). Server pull via POST /api/radar/pull { url, key } — di dashboard ada field "Pull agent" + tombol Scan now.

Bind ke tailscale IP (--serve-host 100.x.y.z) biar listener cuma reachable dari tailnet; --serve-key wajibkan header x-agent-key / Authorization: Bearer.

5. --ws vs HTTP

| | HTTP (default) | --ws | |---|---|---| | Koneksi | POST per report | persistent /api/ws | | Remote command (calibrate) | ❌ | ✅ | | Reconnect | n/a | auto |

Publish ke npm

Package ini siap publish (files: ["dist"], publishConfig.public, prepublishOnly auto-build):

# sekali: login npm
npm login

# bump version + build + publish (release-it, git tag/commit dimatikan)
bun run release

Setelah publish, user cukup:

npx @home-network-agent/core --api https://api.example.com --key <KEY>

Autostart

Windows (Task Scheduler):

schtasks /create /tn "network-agent" /sc onlogon /rl highest `
  /tr "node C:\path\to\agent\dist\cli.js --config C:\path\to\agent.config.json"

Linux (systemd user):

# ~/.config/systemd/user/network-agent.service
[Service]
ExecStart=/usr/bin/node /opt/agent/dist/cli.js --config /opt/agent/agent.config.json
Restart=always

Catatan OS

• Windows: Wi-Fi scan pakai netsh — butuh adapter Wi-Fi + service WlanSvc jalan. PC tanpa Wi-Fi pakai --no-wifi.
• Linux: Wi-Fi scan pakai nmcli (NetworkManager). iw scan butuh sudo — tidak dipakai.
• macOS: Wi-Fi scan belum supported (wdutil butuh sudo) — LAN scan tetap jalan.
• LAN scan tidak butuh privilege apa pun — pakai ping + arp bawaan OS.

Troubleshooting

| Gejala | Penyebab umum | |---|---| | wifi: 0 BSSID(s) terus | nggak ada adapter Wi-Fi / WlanSvc mati → pakai --no-wifi | | lan: 0 device(s) | firewall block ping → devices tetap muncul kalau ada di ARP table; coba --ping-timeout 500 | | send failed: HTTP 401 | RADAR_INGEST_KEY salah / belum diset di API | | Device "Unknown" kind | OUI prefix belum ada di map server → edit apps/api/src/shared/net/oui.ts |