@esptool/mac 0.1.4 → 0.2.1

package/README.md

@@ -1,22 +1,34 @@
 # esptool.mac（@esptool/mac）
 
-MacBook 用户专用的 ESP32 主机侧工具集，发布为 `@esptool/mac`。当前提供基于 `@stoprocent/noble` 的 BLE 扫描（经本机蓝牙适配器发现周边 BLE 广播设备）。
+MacBook 用户专用的 ESP32 主机侧工具集，发布为 `@esptool/mac`。当前提供基于 `@stoprocent/noble` 的 BLE 扫描与 GATT 枚举。
 
 ## 使用（消费约定与 @esptool/cli 相同）
 
 ```bash
-npx -y @esptool/mac scan      # 扫描 10s（⏳ 待发布，发布前用下面的本地方式）
+npx -y @esptool/mac ble scan          # 扫描周边 BLE 设备 10s
+npx -y @esptool/mac ble info <id|name>  # 连接设备并枚举 GATT 服务/特征
 ```
 
 本地开发：
 
 ```bash
 bun install
-bun bin/cli.js scan -t 8     # 指定时长；-t 0 持续扫描直到 Ctrl+C
-bun bin/cli.js scan -n S3    # 按设备名过滤
-bun bin/cli.js scan -u ffff  # 按广播 service UUID 过滤（BluFi 设备指纹）
-bun bin/cli.js scan -o       # 只显示本仓库设备（规则见 OUR_SIGNATURES）
-bun bin/cli.js scan -j       # JSON 输出（不含表头与实时行，可直接管道给 jq/node）
+bun bin/cli.js ble scan -t 8     # 指定时长；-t 0 持续扫描直到 Ctrl+C
+bun bin/cli.js ble scan -n S3    # 按设备名过滤
+bun bin/cli.js ble scan -u ffff  # 按广播 service UUID 过滤（BluFi 设备指纹）
+bun bin/cli.js ble scan -o       # 只显示本仓库设备（规则见 OUR_SIGNATURES）
+bun bin/cli.js ble scan -j       # JSON 输出（不含表头与实时行，可直接管道给 jq/node）
+bun bin/cli.js ble info 85B4MT   # 连接指定设备（id 或名字），枚举服务与特征
+```
+
+## 结构
+
+```
+bin/cli.js         # 入口：命令树分发（<域> <命令>）
+src/ble.js         # noble 封装：适配器就绪等待、扫描聚合（scanDevices）
+src/scan.js        # ble scan：过滤、表格/JSON 输出
+src/info.js        # ble info：查找、连接、GATT 枚举
+src/signatures.js  # 自家设备识别签名（见 docs/2026-10-25-own-device-recognition.md）
 ```
 
 ## 说明
@@ -24,9 +36,11 @@ bun bin/cli.js scan -j       # JSON 输出（不含表头与实时行，可直
 - 运行时兼容 node 与 bun：bin 入口 `#!/usr/bin/env node`（npx 场景），本地也可 `bun bin/cli.js` 直跑。
 - macOS 下设备 id 是 CoreBluetooth 生成的随机 UUID，非真实 MAC。
 - 依赖安装时 bun 会阻止 `bluetooth-hci-socket` 的 postinstall（Linux 原生模块），macOS 无需信任，不影响使用。
-- 发布：`bun run release`（npm version patch + bun publish）。
+- 发布：`bun run release`（npm version patch + npm publish）。
 
 ## 文档
 
 - [BLE 扫描 PoC 工作报告](docs/2026-10-25-scan-poc-report.md)
 - [BLE 广播标识统一规范提案](docs/2026-10-25-ble-advertising-spec-proposal.md)
+- [自家设备识别规则](docs/2026-10-25-own-device-recognition.md)
+- [工具规划提案](docs/2026-10-25-esptool-mac-tooling-proposal.md)

package/bin/cli.js

@@ -1,158 +1,93 @@
 #!/usr/bin/env node
-import noble from '@stoprocent/noble'
+import { bleScan } from '../src/scan.js'
+import { bleInfo } from '../src/info.js'
 
 const HELP = `
-@esptool/mac — MacBook 专用主机工具（BLE 扫描等）
+@esptool/mac — MacBook 专用主机工具（BLE 扫描 / GATT 枚举等）
 
-用法: npx @esptool/mac scan [选项]
-  或: bun bin/cli.js scan [选项]
+用法: npx -y @esptool/mac <域> <命令> [选项]
 
-选项:
+BLE 命令:
+  mac ble scan [选项]          扫描周边 BLE 广播设备
+  mac ble info <id|name>       连接设备并枚举 GATT 服务/特征
+
+ble scan 选项:
   -t, --timeout <秒>     扫描时长 (默认 10, 0 = 持续扫描直到 Ctrl+C)
   -n, --name <关键字>    按设备名过滤 (大小写不敏感)
   -u, --service <uuid>   按广播 service UUID 过滤 (如 ffff, 忽略大小写与连字符)
-  -o, --our              只显示本仓库设备 (BluFi ffff 服务, 或 KDB- 名字前缀)
+  -o, --our              只显示本仓库设备 (识别规则见 docs/2026-10-25-own-device-recognition.md)
   -d, --duplicates       响应重复广播 (实时刷新 RSSI)
   -j, --json             以 JSON 输出最终结果
-  -h, --help             显示帮助
-`
-
-const normalizeUuid = (uuid) => String(uuid).replace(/-/g, '').toLowerCase()
 
-// 自家设备识别：命中任一签名即算。多条并存是为了覆盖规范落地前后各种形态，
-// 随命名规范推进逐步收紧（见 docs/2026-10-25-ble-advertising-spec-proposal.md §2/§3）。
-const OUR_SIGNATURES = [
-  { service: 'ffff' }, // BluFi 配网固件
-  { namePrefix: 'kdb-' }, // 完整格式名 KDB-<产品线>-<型号>-<标识>
-  { namePattern: /^[a-z]{2}-[0-9a-f]{2}$/ }, // 短码 <产品线2>-<MAC末1字节hex2>，如 S3-1F
-]
+ble info 选项:
+  -t, --timeout <秒>     查找设备的最长等待 (默认 10)
 
-const isOurs = (name, services) => {
-  const lowerName = name.toLowerCase()
-  return OUR_SIGNATURES.some(
-    (sig) =>
-      (sig.service && services.some((s) => s === sig.service || s.endsWith(sig.service))) ||
-      (sig.namePrefix && lowerName.startsWith(sig.namePrefix)) ||
-      (sig.namePattern && sig.namePattern.test(lowerName))
-  )
-}
+其他:
+  -h, --help             显示帮助
+`
 
-const parseArgs = (argv) => {
+const parseScanArgs = (argv) => {
   const opts = { timeout: 10, name: '', service: '', our: false, duplicates: false, json: false }
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i]
     if (a === '-t' || a === '--timeout') opts.timeout = Number(argv[++i])
     else if (a === '-n' || a === '--name') opts.name = argv[++i]
-    else if (a === '-u' || a === '--service') opts.service = normalizeUuid(argv[++i])
+    else if (a === '-u' || a === '--service') opts.service = argv[++i]
     else if (a === '-o' || a === '--our') opts.our = true
     else if (a === '-d' || a === '--duplicates') opts.duplicates = true
     else if (a === '-j' || a === '--json') opts.json = true
-    else if (a === '-h' || a === '--help') {
-      console.log(HELP)
-      process.exit(0)
-    } else {
-      console.error(`未知参数: ${a}`)
-      console.log(HELP)
-      process.exit(1)
-    }
+    else throw new Error(`未知参数: ${a}`)
   }
   return opts
 }
 
-const toHex = (buf) => (Buffer.isBuffer(buf) ? buf.toString('hex') : '')
-
-const toRecords = (devices) =>
-  [...devices.values()].sort((x, y) => y.rssi - x.rssi)
-
-const printTable = (records, elapsed) => {
-  console.log(`\n共发现 ${records.length} 台设备 (耗时 ${elapsed}s)，按信号强度排序:\n`)
-  const pad = (s, n) => (s.length > n ? `${s.slice(0, n - 1)}…` : s.padEnd(n))
-  console.log(`  ${'RSSI'.padStart(8)}  ${pad('UUID / ADDRESS', 38)}${pad('NAME', 24)}${pad('SERVICES', 10)}MFG DATA`)
-  for (const d of records) {
-    const services = d.services.join(',')
-    console.log(
-      `  ${`${d.rssi} dBm`.padStart(8)}  ${pad(d.id, 38)}${pad(d.name || '(未命名)', 24)}${pad(services, 10)}${d.mfg}`
-    )
+const parseInfoArgs = (argv) => {
+  const opts = { target: '', timeout: 10 }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '-t' || a === '--timeout') opts.timeout = Number(argv[++i])
+    else if (!a.startsWith('-')) opts.target = a
+    else throw new Error(`未知参数: ${a}`)
   }
+  if (!opts.target) throw new Error('缺少目标设备 (id 或设备名)')
+  return opts
 }
 
-const scan = async (opts) => {
-  const devices = new Map()
-  const startedAt = Date.now()
-
-  noble.on('discover', (p) => {
-    const name = p.advertisement?.localName || ''
-    if (opts.name && !name.toLowerCase().includes(opts.name.toLowerCase())) return
-
-    const services = (p.advertisement?.serviceUuids ?? []).map(normalizeUuid)
-    if (opts.service && !services.some((s) => s === opts.service || s.endsWith(opts.service))) return
-    if (opts.our && !isOurs(name, services)) return
-
-    const prev = devices.get(p.id)
-    if (prev) {
-      prev.rssi = p.rssi
-      prev.count += 1
-      if (!prev.name && name) prev.name = name
-      if (!prev.services.length && services.length) prev.services = services
-      if (!opts.duplicates) return
-    } else {
-      devices.set(p.id, {
-        id: p.id,
-        name,
-        rssi: p.rssi,
-        connectable: p.connectable ?? null,
-        mfg: toHex(p.advertisement?.manufacturerData),
-        services,
-        firstSeen: Date.now() - startedAt,
-        count: 1,
-      })
-      if (!opts.json) {
-        const elapsed = ((Date.now() - startedAt) / 1000).toFixed(1)
-        console.log(`  [${elapsed.padStart(5)}s] ${String(p.rssi).padStart(4)} dBm  ${p.id}  ${name || '(未命名)'}`)
-      }
+const route = async ([domain, cmd, ...rest]) => {
+  if (domain === 'ble') {
+    if (cmd === 'scan') {
+      await bleScan(parseScanArgs(rest))
+      return true
     }
-  })
-
-  await new Promise((resolve, reject) => {
-    const onState = (state) => (state === 'poweredOn' ? resolve() : undefined)
-    noble.on('stateChange', onState)
-    noble.on('warning', (w) => console.error(`[noble] ${w}`))
-    if (noble.state === 'poweredOn') resolve()
-    setTimeout(() => reject(new Error(`蓝牙适配器未就绪 (state: ${noble.state})`)), 5000)
-  })
-
-  if (!opts.json) {
-    console.log(`开始扫描 (${opts.timeout === 0 ? '持续模式, Ctrl+C 结束' : `${opts.timeout}s`})…\n`)
-  }
-  await noble.startScanningAsync([], opts.duplicates)
-
-  const finish = async () => {
-    noble.removeAllListeners('discover')
-    await noble.stopScanningAsync().catch(() => {})
-    const elapsed = ((Date.now() - startedAt) / 1000).toFixed(1)
-    const records = toRecords(devices)
-    if (opts.json) {
-      console.log(JSON.stringify({ elapsed: Number(elapsed), count: records.length, devices: records }, null, 2))
-    } else {
-      printTable(records, elapsed)
+    if (cmd === 'info') {
+      await bleInfo(parseInfoArgs(rest))
+      return true
     }
-    process.exit(0)
   }
-
-  process.on('SIGINT', finish)
-  if (opts.timeout > 0) setTimeout(finish, opts.timeout * 1000)
+  // 旧入口过渡: 单独的 scan 自动路由到 ble scan，下个版本移除
+  if (domain === 'scan') {
+    console.error('[提示] scan 已迁移为 ble scan，本次自动路由（旧入口将在下个版本移除）\n')
+    await bleScan(parseScanArgs([cmd, ...rest]))
+    return true
+  }
+  return false
 }
 
 const main = async () => {
-  const [cmd, ...rest] = process.argv.slice(2)
-  if (cmd !== 'scan') {
+  const argv = process.argv.slice(2)
+  if (argv[0] === '-h' || argv[0] === '--help' || !argv.length) {
     console.log(HELP)
-    process.exit(cmd ? 1 : 0)
+    return
+  }
+  if (!(await route(argv))) {
+    console.log(HELP)
+    process.exit(1)
   }
-  await scan(parseArgs(rest))
 }
 
-main().catch((err) => {
-  console.error(`错误: ${err.message}`)
-  process.exit(1)
-})
+main()
+  .then(() => process.exit(0))
+  .catch((err) => {
+    console.error(`错误: ${err.message}`)
+    process.exit(1)
+  })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esptool/mac",
-  "version": "0.1.4",
+  "version": "0.2.1",
   "description": "MacBook host-side tools for ESP32 workflow - BLE scanner and more",
   "type": "module",
   "bin": {
@@ -11,8 +11,8 @@
     "README.md"
   ],
   "scripts": {
-    "scan": "bun bin/cli.js scan",
-    "test": "node bin/cli.js scan -t 3",
+    "scan": "bun bin/cli.js ble scan",
+    "test": "node bin/cli.js ble scan -t 3",
     "release": "npm version patch && npm publish --access public"
   },
   "dependencies": {