{"_id":"@alikh/dwarflab-ble","_rev":"2-6cf192f2df451cf4b238ae2ea1680eb5","name":"@alikh/dwarflab-ble","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@alikh/dwarflab-ble","version":"0.1.0","keywords":["dwarflab","dwarf","telescope","bluetooth","ble","noble"],"author":{"name":"alikh31"},"license":"MIT","_id":"@alikh/dwarflab-ble@0.1.0","maintainers":[{"name":"alikh","email":"al_kh31@hotmail.com"}],"homepage":"https://github.com/alikh31/dwarflab-sdk/tree/main/packages/ble#readme","bugs":{"url":"https://github.com/alikh31/dwarflab-sdk/issues"},"dist":{"shasum":"64d9d520f17f0faf8732110d478871460b1e28a8","tarball":"https://registry.npmjs.org/@alikh/dwarflab-ble/-/dwarflab-ble-0.1.0.tgz","fileCount":9,"integrity":"sha512-c6UH2r91/FNcyEnM82fG+tahwAHCKdy01alMBSVGlAWbyBS7Ybx/hTMBIPfbXkENM+bbRglNlprWdslYupjViA==","signatures":[{"sig":"MEUCICA1kTQSjJu+bdn5G9XQ5gUaPjeTOpM7D8FJ3iRmWcC5AiEAmDCeKfQcfA5nql7FSgZ9jo0N5ME0lKoLuz6aY/uBf3I=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":107265},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.mjs","engines":{"node":">=18"},"exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.mjs"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}}},"gitHead":"482daf3f5fddeee75e6e59c790ec47311b9acf7f","scripts":{"test":"vitest run","build":"tsup","typecheck":"tsc --noEmit"},"_npmUser":{"name":"alikh","email":"al_kh31@hotmail.com"},"repository":{"url":"git+https://github.com/alikh31/dwarflab-sdk.git","type":"git","directory":"packages/ble"},"_npmVersion":"10.8.2","description":"Unofficial BLE setup package for DWARFLAB DWARF telescopes — Wi-Fi configuration and discovery (Node.js only)","directories":{},"_nodeVersion":"20.19.0","dependencies":{"@abandonware/noble":"^1.9.2-26","@alikh/dwarflab-sdk":"^0.1.0"},"publishConfig":{"access":"public","provenance":true},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/dwarflab-ble_0.1.0_1780225741015_0.7651557993306772","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@alikh/dwarflab-ble","version":"0.1.1","description":"Unofficial BLE setup package for DWARFLAB DWARF telescopes — Wi-Fi configuration and discovery (Node.js only)","type":"module","exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.mjs"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}}},"main":"./dist/index.cjs","module":"./dist/index.mjs","types":"./dist/index.d.ts","scripts":{"build":"tsup","test":"vitest run","typecheck":"tsc --noEmit"},"dependencies":{"@abandonware/noble":"^1.9.2-26","@alikh/dwarflab-sdk":"^0.1.0"},"keywords":["dwarflab","dwarf","telescope","bluetooth","ble","noble"],"license":"MIT","author":{"name":"alikh31"},"homepage":"https://github.com/alikh31/dwarflab-sdk/tree/main/packages/ble#readme","repository":{"type":"git","url":"git+https://github.com/alikh31/dwarflab-sdk.git","directory":"packages/ble"},"bugs":{"url":"https://github.com/alikh31/dwarflab-sdk/issues"},"engines":{"node":">=18"},"publishConfig":{"access":"public","provenance":true},"gitHead":"7c2ef1dae89b7964a4a3501cdcbd1f4f8c6a621b","_id":"@alikh/dwarflab-ble@0.1.1","_nodeVersion":"20.20.2","_npmVersion":"11.16.0","dist":{"integrity":"sha512-B+28Uxn9ArvMtV/PbYZOKfshhQIOqCQWngcR9thnvTyD/tJfjzSNwsEw3IqRn1JXl1uVduAzSD05t7Nch+VXZg==","shasum":"6586bcfa874b09693ce6e6bf762bdd94cc6f08b9","tarball":"https://registry.npmjs.org/@alikh/dwarflab-ble/-/dwarflab-ble-0.1.1.tgz","fileCount":9,"unpackedSize":107265,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@alikh%2fdwarflab-ble@0.1.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDdK9nX75Jw6IQuF2Uuv/5EIsQ38nhDJGI2Pb6UFOc51AIhANbDK0bAySrySBFDnLyoVVs6S/v0d6Of9n3yIwLt91tu"}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:731de7eb-a8c2-40d2-b2e0-52c700f59be5"}},"directories":{},"maintainers":[{"name":"alikh","email":"al_kh31@hotmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/dwarflab-ble_0.1.1_1780302884059_0.5227671487079308"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-31T11:09:00.876Z","modified":"2026-06-01T08:34:44.466Z","0.1.0":"2026-05-31T11:09:01.151Z","0.1.1":"2026-06-01T08:34:44.200Z"},"bugs":{"url":"https://github.com/alikh31/dwarflab-sdk/issues"},"author":{"name":"alikh31"},"license":"MIT","homepage":"https://github.com/alikh31/dwarflab-sdk/tree/main/packages/ble#readme","keywords":["dwarflab","dwarf","telescope","bluetooth","ble","noble"],"repository":{"type":"git","url":"git+https://github.com/alikh31/dwarflab-sdk.git","directory":"packages/ble"},"description":"Unofficial BLE setup package for DWARFLAB DWARF telescopes — Wi-Fi configuration and discovery (Node.js only)","maintainers":[{"name":"alikh","email":"al_kh31@hotmail.com"}],"readme":"# @alikh/dwarflab-ble\n\nBLE (Bluetooth Low Energy) communication package for DWARFLAB DWARF telescopes. Used for initial WiFi configuration and device discovery before establishing a network connection.\n\n> **Unofficial / independent project.** Not affiliated with, authorized, or\n> endorsed by DWARFLAB. \"DWARF\" and \"DWARFLAB\" are trademarks of their respective\n> owner and are used only to describe the hardware this package talks to. The\n> protocol was derived by observing a telescope's own traffic and may be incomplete\n> or change between firmware versions. Use at your own risk.\n\n**Node.js only** — uses `@abandonware/noble` for BLE access.\n\n## Installation\n\n```bash\nnpm install @alikh/dwarflab-ble\n```\n\n### Prerequisites\n\nBLE access requires platform-specific setup. See the [noble documentation](https://github.com/abandonware/noble#prerequisites) for your OS:\n\n- **macOS**: Works out of the box\n- **Linux**: Requires `libbluetooth-dev` and proper permissions (`sudo setcap cap_net_raw+eip $(eval readlink -f $(which node))`)\n- **Windows**: Requires a compatible BLE dongle and WinUSB driver\n\n## Quick Start\n\n```typescript\nimport { DwarfBle } from '@alikh/dwarflab-ble';\n\nconst ble = new DwarfBle();\n\n// Scan for nearby DWARF telescopes (filters advertisement names starting with \"DWARF\")\nconst devices = await ble.scan({ timeout: 10000 });\nconsole.log('Found:', devices);\n// [{ name: 'DWARF3_XXXX', address: 'aa:bb:cc:dd:ee:ff', rssi: -45, peripheral: ... }]\n\n// Connect to a device\nconst connection = await ble.connect(devices[0]);\n\n// Read the current device configuration\nconst config = await connection.getConfig();\nconsole.log('WiFi mode:', config.wifiMode); // number (firmware-defined mode code)\nconsole.log('Current SSID:', config.ssid);\nconsole.log('Device IP:', config.ip);\n\n// Put the telescope into STA mode (join your home WiFi).\n// The device replies with its new LAN IP — use THIS ip to reach it afterward;\n// getConfig() does not reflect the new state on current firmware.\nconst result = await connection.setStaMode({\n  ssid: 'MyHomeWiFi',\n  password: process.env.WIFI_PASSWORD!, // never hard-code a password\n});\nconsole.log('STA result code:', result.code);\nconsole.log('Connect to the telescope at:', result.ip);\n\n// Switch back to AP mode (telescope hosts its own hotspot).\n// NOTE: AP SSID/password are fixed in firmware and cannot be changed over BLE,\n// so setApMode takes no effective credentials.\nawait connection.setApMode({ ssid: '', password: '' });\n\n// Disconnect\nawait connection.disconnect();\n```\n\n## API\n\n### DwarfBle\n\nThe main entry point for BLE operations.\n\n#### `scan(options?: ScanOptions): Promise<BleDevice[]>`\n\nScans for nearby DWARF telescopes, keeping only devices whose BLE advertisement\nname starts with `DWARF` (override via `namePrefix`).\n\n```typescript\ninterface ScanOptions {\n  timeout?: number;    // Scan duration in ms (default: 10000)\n  namePrefix?: string; // Advertisement name prefix to match (default: 'DWARF')\n}\n\ninterface BleDevice {\n  name: string;\n  address: string;\n  rssi: number;\n  peripheral: unknown; // underlying noble peripheral, passed to connect()\n}\n```\n\n#### `connect(device: BleDevice): Promise<BleConnection>`\n\nEstablishes a BLE GATT connection to the specified device.\n\n### BleConnection\n\nManages the BLE connection and provides WiFi configuration methods.\n\n#### `getConfig(): Promise<DeviceConfig>`\n\nReads the current device WiFi configuration.\n\n#### `setStaMode(config: WifiConfig): Promise<StaResult>`\n\nConfigures the telescope to join an existing WiFi network (Station mode). The\ndevice responds with its assigned LAN IP. Use the returned `ip` to reach the\ntelescope afterward — `getConfig()` does not reflect the new state on current\nfirmware, so polling it will not help.\n\n#### `setApMode(config: WifiConfig): Promise<void>`\n\nSwitches the telescope to Access Point mode (it hosts its own hotspot). The AP\nSSID and password are fixed in firmware and **cannot be changed over BLE**, so the\n`WifiConfig` argument is accepted only for API symmetry and is not applied.\n\n#### `getApInfo(): Promise<{ ssid: string; password: string }>`\n\nReads the telescope's current AP SSID and password without restarting it.\n\n#### `scanWifi(): Promise<Array<{ ssid: string; signal: number; security: string }>>`\n\nAsks the telescope to scan for nearby WiFi networks.\n\n#### `disconnect(): Promise<void>`\n\nCloses the BLE connection.\n\n### Types\n\n```typescript\ninterface WifiConfig {\n  ssid: string;\n  password: string;\n}\n\ninterface DeviceConfig {\n  state: number;     // device state code\n  wifiMode: number;  // firmware-defined WiFi mode code\n  apMode: number;\n  autoStart: number;\n  ssid: string;      // current SSID\n  password: string;  // current WiFi password (do not log)\n  ip: string;        // current LAN IP\n  apCountry: string;\n}\n\ninterface StaResult {\n  code: number;  // result code from the device\n  ssid: string;\n  ip: string;    // the telescope's LAN IP after joining the network\n  password: string; // echoed credential (do not log)\n}\n```\n\n> **Never print or log a literal WiFi password.** `DeviceConfig.password` and\n> `StaResult.password` may echo a real credential — treat them as secrets.\n\n## BLE Protocol Details\n\nDWARFLAB telescopes use a single BLE service with two characteristics:\n\n| UUID | Direction | Purpose |\n|------|-----------|---------|\n| `ffe0` | Service | Main BLE service |\n| `ffe1` | Write | Send commands (ReqGetconfig, ReqSta, ReqAp) |\n| `ffe2` | Notify | Receive responses (ResGetconfig, ResSta, ResAp) |\n\nCommands are serialized as protobuf messages and written to the `ffe1` characteristic. Responses arrive as notifications on `ffe2`.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}