node-switchbot 4.0.0-beta.9 → 4.0.1

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 (417) hide show
  1. package/BLE.md +215 -838
  2. package/CHANGELOG.md +163 -1438
  3. package/OpenAPI.md +169 -135
  4. package/README.md +1 -1
  5. package/dist/ble.d.ts +14 -1
  6. package/dist/ble.d.ts.map +1 -1
  7. package/dist/ble.js +241 -39
  8. package/dist/ble.js.map +1 -1
  9. package/dist/devices/base.d.ts +97 -1
  10. package/dist/devices/base.d.ts.map +1 -1
  11. package/dist/devices/base.js +204 -2
  12. package/dist/devices/base.js.map +1 -1
  13. package/dist/devices/device-override-state-during-connection.d.ts +27 -0
  14. package/dist/devices/device-override-state-during-connection.d.ts.map +1 -0
  15. package/dist/devices/device-override-state-during-connection.js +45 -0
  16. package/dist/devices/device-override-state-during-connection.js.map +1 -0
  17. package/dist/devices/index.d.ts +36 -0
  18. package/dist/devices/index.d.ts.map +1 -1
  19. package/dist/devices/index.js +36 -0
  20. package/dist/devices/index.js.map +1 -1
  21. package/dist/devices/sequence-device.d.ts +52 -0
  22. package/dist/devices/sequence-device.d.ts.map +1 -0
  23. package/dist/devices/sequence-device.js +91 -0
  24. package/dist/devices/sequence-device.js.map +1 -0
  25. package/dist/devices/wo-ai-hub.d.ts +9 -0
  26. package/dist/devices/wo-ai-hub.d.ts.map +1 -0
  27. package/dist/devices/wo-ai-hub.js +25 -0
  28. package/dist/devices/wo-ai-hub.js.map +1 -0
  29. package/dist/devices/wo-air-purifier-pm25.d.ts +29 -0
  30. package/dist/devices/wo-air-purifier-pm25.d.ts.map +1 -0
  31. package/dist/devices/wo-air-purifier-pm25.js +144 -0
  32. package/dist/devices/wo-air-purifier-pm25.js.map +1 -0
  33. package/dist/devices/wo-air-purifier.d.ts +21 -4
  34. package/dist/devices/wo-air-purifier.d.ts.map +1 -1
  35. package/dist/devices/wo-air-purifier.js +111 -61
  36. package/dist/devices/wo-air-purifier.js.map +1 -1
  37. package/dist/devices/wo-art-frame.d.ts +8 -0
  38. package/dist/devices/wo-art-frame.d.ts.map +1 -0
  39. package/dist/devices/wo-art-frame.js +12 -0
  40. package/dist/devices/wo-art-frame.js.map +1 -0
  41. package/dist/devices/wo-blind-tilt.d.ts +2 -16
  42. package/dist/devices/wo-blind-tilt.d.ts.map +1 -1
  43. package/dist/devices/wo-blind-tilt.js +135 -62
  44. package/dist/devices/wo-blind-tilt.js.map +1 -1
  45. package/dist/devices/wo-bulb.d.ts +37 -1
  46. package/dist/devices/wo-bulb.d.ts.map +1 -1
  47. package/dist/devices/wo-bulb.js +196 -51
  48. package/dist/devices/wo-bulb.js.map +1 -1
  49. package/dist/devices/wo-candle-warmer-lamp.d.ts +25 -0
  50. package/dist/devices/wo-candle-warmer-lamp.d.ts.map +1 -0
  51. package/dist/devices/wo-candle-warmer-lamp.js +81 -0
  52. package/dist/devices/wo-candle-warmer-lamp.js.map +1 -0
  53. package/dist/devices/wo-circulator-fan.d.ts +8 -0
  54. package/dist/devices/wo-circulator-fan.d.ts.map +1 -0
  55. package/dist/devices/wo-circulator-fan.js +12 -0
  56. package/dist/devices/wo-circulator-fan.js.map +1 -0
  57. package/dist/devices/wo-climate-panel.d.ts +8 -0
  58. package/dist/devices/wo-climate-panel.d.ts.map +1 -0
  59. package/dist/devices/wo-climate-panel.js +12 -0
  60. package/dist/devices/wo-climate-panel.js.map +1 -0
  61. package/dist/devices/wo-contact.d.ts +1 -1
  62. package/dist/devices/wo-contact.d.ts.map +1 -1
  63. package/dist/devices/wo-contact.js +19 -35
  64. package/dist/devices/wo-contact.js.map +1 -1
  65. package/dist/devices/wo-curtain.d.ts +17 -1
  66. package/dist/devices/wo-curtain.d.ts.map +1 -1
  67. package/dist/devices/wo-curtain.js +119 -27
  68. package/dist/devices/wo-curtain.js.map +1 -1
  69. package/dist/devices/wo-floor-lamp.d.ts +8 -0
  70. package/dist/devices/wo-floor-lamp.d.ts.map +1 -0
  71. package/dist/devices/wo-floor-lamp.js +12 -0
  72. package/dist/devices/wo-floor-lamp.js.map +1 -0
  73. package/dist/devices/wo-garage-door-opener.d.ts +8 -0
  74. package/dist/devices/wo-garage-door-opener.d.ts.map +1 -0
  75. package/dist/devices/wo-garage-door-opener.js +12 -0
  76. package/dist/devices/wo-garage-door-opener.js.map +1 -0
  77. package/dist/devices/wo-hand.d.ts +22 -6
  78. package/dist/devices/wo-hand.d.ts.map +1 -1
  79. package/dist/devices/wo-hand.js +55 -39
  80. package/dist/devices/wo-hand.js.map +1 -1
  81. package/dist/devices/wo-hub2.d.ts +1 -1
  82. package/dist/devices/wo-hub2.d.ts.map +1 -1
  83. package/dist/devices/wo-hub2.js +17 -33
  84. package/dist/devices/wo-hub2.js.map +1 -1
  85. package/dist/devices/wo-hubmini-matter.d.ts +8 -0
  86. package/dist/devices/wo-hubmini-matter.d.ts.map +1 -0
  87. package/dist/devices/wo-hubmini-matter.js +12 -0
  88. package/dist/devices/wo-hubmini-matter.js.map +1 -0
  89. package/dist/devices/wo-humi.d.ts +18 -2
  90. package/dist/devices/wo-humi.d.ts.map +1 -1
  91. package/dist/devices/wo-humi.js +60 -36
  92. package/dist/devices/wo-humi.js.map +1 -1
  93. package/dist/devices/wo-humi2.d.ts.map +1 -1
  94. package/dist/devices/wo-humi2.js.map +1 -1
  95. package/dist/devices/wo-keypad-vision-pro.d.ts +18 -0
  96. package/dist/devices/wo-keypad-vision-pro.d.ts.map +1 -0
  97. package/dist/devices/wo-keypad-vision-pro.js +15 -0
  98. package/dist/devices/wo-keypad-vision-pro.js.map +1 -0
  99. package/dist/devices/wo-keypad-vision.d.ts +8 -0
  100. package/dist/devices/wo-keypad-vision.d.ts.map +1 -0
  101. package/dist/devices/wo-keypad-vision.js +12 -0
  102. package/dist/devices/wo-keypad-vision.js.map +1 -0
  103. package/dist/devices/wo-keypad.d.ts +1 -1
  104. package/dist/devices/wo-keypad.d.ts.map +1 -1
  105. package/dist/devices/wo-keypad.js +14 -30
  106. package/dist/devices/wo-keypad.js.map +1 -1
  107. package/dist/devices/wo-leak.d.ts +1 -1
  108. package/dist/devices/wo-leak.d.ts.map +1 -1
  109. package/dist/devices/wo-leak.js +15 -31
  110. package/dist/devices/wo-leak.js.map +1 -1
  111. package/dist/devices/wo-lock-lite.d.ts +7 -0
  112. package/dist/devices/wo-lock-lite.d.ts.map +1 -0
  113. package/dist/devices/wo-lock-lite.js +11 -0
  114. package/dist/devices/wo-lock-lite.js.map +1 -0
  115. package/dist/devices/wo-lock-pro-wifi.d.ts +7 -0
  116. package/dist/devices/wo-lock-pro-wifi.d.ts.map +1 -0
  117. package/dist/devices/wo-lock-pro-wifi.js +11 -0
  118. package/dist/devices/wo-lock-pro-wifi.js.map +1 -0
  119. package/dist/devices/wo-lock-pro.d.ts +12 -3
  120. package/dist/devices/wo-lock-pro.d.ts.map +1 -1
  121. package/dist/devices/wo-lock-pro.js +83 -37
  122. package/dist/devices/wo-lock-pro.js.map +1 -1
  123. package/dist/devices/wo-lock-vision-pro.d.ts +7 -0
  124. package/dist/devices/wo-lock-vision-pro.d.ts.map +1 -0
  125. package/dist/devices/wo-lock-vision-pro.js +11 -0
  126. package/dist/devices/wo-lock-vision-pro.js.map +1 -0
  127. package/dist/devices/wo-lock-vision.d.ts +7 -0
  128. package/dist/devices/wo-lock-vision.d.ts.map +1 -0
  129. package/dist/devices/wo-lock-vision.js +11 -0
  130. package/dist/devices/wo-lock-vision.js.map +1 -0
  131. package/dist/devices/wo-lock.d.ts +8 -3
  132. package/dist/devices/wo-lock.d.ts.map +1 -1
  133. package/dist/devices/wo-lock.js +75 -36
  134. package/dist/devices/wo-lock.js.map +1 -1
  135. package/dist/devices/wo-pan-tilt-cam-plus-3k.d.ts +21 -0
  136. package/dist/devices/wo-pan-tilt-cam-plus-3k.d.ts.map +1 -0
  137. package/dist/devices/wo-pan-tilt-cam-plus-3k.js +87 -0
  138. package/dist/devices/wo-pan-tilt-cam-plus-3k.js.map +1 -0
  139. package/dist/devices/wo-plug-mini-us.d.ts +3 -3
  140. package/dist/devices/wo-plug-mini-us.d.ts.map +1 -1
  141. package/dist/devices/wo-plug-mini-us.js +25 -35
  142. package/dist/devices/wo-plug-mini-us.js.map +1 -1
  143. package/dist/devices/wo-presence.d.ts +1 -1
  144. package/dist/devices/wo-presence.d.ts.map +1 -1
  145. package/dist/devices/wo-presence.js +17 -33
  146. package/dist/devices/wo-presence.js.map +1 -1
  147. package/dist/devices/wo-relay-switch-1.d.ts +19 -3
  148. package/dist/devices/wo-relay-switch-1.d.ts.map +1 -1
  149. package/dist/devices/wo-relay-switch-1.js +90 -42
  150. package/dist/devices/wo-relay-switch-1.js.map +1 -1
  151. package/dist/devices/wo-relay-switch-2pm.d.ts +21 -0
  152. package/dist/devices/wo-relay-switch-2pm.d.ts.map +1 -0
  153. package/dist/devices/wo-relay-switch-2pm.js +37 -0
  154. package/dist/devices/wo-relay-switch-2pm.js.map +1 -0
  155. package/dist/devices/wo-remote-with-screen.d.ts +9 -0
  156. package/dist/devices/wo-remote-with-screen.d.ts.map +1 -0
  157. package/dist/devices/wo-remote-with-screen.js +22 -0
  158. package/dist/devices/wo-remote-with-screen.js.map +1 -0
  159. package/dist/devices/wo-remote.d.ts +1 -1
  160. package/dist/devices/wo-remote.d.ts.map +1 -1
  161. package/dist/devices/wo-remote.js +13 -29
  162. package/dist/devices/wo-remote.js.map +1 -1
  163. package/dist/devices/wo-rgbic-bulb.d.ts +29 -0
  164. package/dist/devices/wo-rgbic-bulb.d.ts.map +1 -0
  165. package/dist/devices/wo-rgbic-bulb.js +84 -0
  166. package/dist/devices/wo-rgbic-bulb.js.map +1 -0
  167. package/dist/devices/wo-rgbic-neon-wire-rope-light.d.ts +29 -0
  168. package/dist/devices/wo-rgbic-neon-wire-rope-light.d.ts.map +1 -0
  169. package/dist/devices/wo-rgbic-neon-wire-rope-light.js +113 -0
  170. package/dist/devices/wo-rgbic-neon-wire-rope-light.js.map +1 -0
  171. package/dist/devices/wo-rgbicww-floor-lamp.d.ts +8 -0
  172. package/dist/devices/wo-rgbicww-floor-lamp.d.ts.map +1 -0
  173. package/dist/devices/wo-rgbicww-floor-lamp.js +12 -0
  174. package/dist/devices/wo-rgbicww-floor-lamp.js.map +1 -0
  175. package/dist/devices/wo-rgbicww-strip-light.d.ts +8 -0
  176. package/dist/devices/wo-rgbicww-strip-light.d.ts.map +1 -0
  177. package/dist/devices/wo-rgbicww-strip-light.js +12 -0
  178. package/dist/devices/wo-rgbicww-strip-light.js.map +1 -0
  179. package/dist/devices/wo-roller-shade.d.ts +8 -0
  180. package/dist/devices/wo-roller-shade.d.ts.map +1 -0
  181. package/dist/devices/wo-roller-shade.js +12 -0
  182. package/dist/devices/wo-roller-shade.js.map +1 -0
  183. package/dist/devices/wo-sensor-th.d.ts +1 -1
  184. package/dist/devices/wo-sensor-th.d.ts.map +1 -1
  185. package/dist/devices/wo-sensor-th.js +18 -34
  186. package/dist/devices/wo-sensor-th.js.map +1 -1
  187. package/dist/devices/wo-smart-thermostat-radiator.d.ts +8 -0
  188. package/dist/devices/wo-smart-thermostat-radiator.d.ts.map +1 -0
  189. package/dist/devices/wo-smart-thermostat-radiator.js +12 -0
  190. package/dist/devices/wo-smart-thermostat-radiator.js.map +1 -0
  191. package/dist/devices/wo-strip-light-3.d.ts +8 -0
  192. package/dist/devices/wo-strip-light-3.d.ts.map +1 -0
  193. package/dist/devices/wo-strip-light-3.js +12 -0
  194. package/dist/devices/wo-strip-light-3.js.map +1 -0
  195. package/dist/devices/wo-vacuum-k10-plus.d.ts +7 -0
  196. package/dist/devices/wo-vacuum-k10-plus.d.ts.map +1 -0
  197. package/dist/devices/wo-vacuum-k10-plus.js +11 -0
  198. package/dist/devices/wo-vacuum-k10-plus.js.map +1 -0
  199. package/dist/devices/wo-vacuum-k10-pro-combo.d.ts +7 -0
  200. package/dist/devices/wo-vacuum-k10-pro-combo.d.ts.map +1 -0
  201. package/dist/devices/wo-vacuum-k10-pro-combo.js +11 -0
  202. package/dist/devices/wo-vacuum-k10-pro-combo.js.map +1 -0
  203. package/dist/devices/wo-vacuum-k10-pro.d.ts +7 -0
  204. package/dist/devices/wo-vacuum-k10-pro.d.ts.map +1 -0
  205. package/dist/devices/wo-vacuum-k10-pro.js +11 -0
  206. package/dist/devices/wo-vacuum-k10-pro.js.map +1 -0
  207. package/dist/devices/wo-vacuum-k11-plus.d.ts +7 -0
  208. package/dist/devices/wo-vacuum-k11-plus.d.ts.map +1 -0
  209. package/dist/devices/wo-vacuum-k11-plus.js +11 -0
  210. package/dist/devices/wo-vacuum-k11-plus.js.map +1 -0
  211. package/dist/devices/wo-vacuum-k20.d.ts +7 -0
  212. package/dist/devices/wo-vacuum-k20.d.ts.map +1 -0
  213. package/dist/devices/wo-vacuum-k20.js +11 -0
  214. package/dist/devices/wo-vacuum-k20.js.map +1 -0
  215. package/dist/devices/wo-vacuum-s10.d.ts +7 -0
  216. package/dist/devices/wo-vacuum-s10.d.ts.map +1 -0
  217. package/dist/devices/wo-vacuum-s10.js +11 -0
  218. package/dist/devices/wo-vacuum-s10.js.map +1 -0
  219. package/dist/devices/wo-vacuum-s20.d.ts +7 -0
  220. package/dist/devices/wo-vacuum-s20.d.ts.map +1 -0
  221. package/dist/devices/wo-vacuum-s20.js +11 -0
  222. package/dist/devices/wo-vacuum-s20.js.map +1 -0
  223. package/dist/devices/wo-vacuum.d.ts +44 -0
  224. package/dist/devices/wo-vacuum.d.ts.map +1 -0
  225. package/dist/devices/wo-vacuum.js +143 -0
  226. package/dist/devices/wo-vacuum.js.map +1 -0
  227. package/dist/devices/wo-water-detector.d.ts +9 -0
  228. package/dist/devices/wo-water-detector.d.ts.map +1 -0
  229. package/dist/devices/wo-water-detector.js +20 -0
  230. package/dist/devices/wo-water-detector.js.map +1 -0
  231. package/dist/errors.d.ts +20 -0
  232. package/dist/errors.d.ts.map +1 -1
  233. package/dist/errors.js +31 -1
  234. package/dist/errors.js.map +1 -1
  235. package/dist/index.d.ts +4 -2
  236. package/dist/index.d.ts.map +1 -1
  237. package/dist/index.js +3 -1
  238. package/dist/index.js.map +1 -1
  239. package/dist/settings.d.ts +25 -0
  240. package/dist/settings.d.ts.map +1 -1
  241. package/dist/settings.js +86 -6
  242. package/dist/settings.js.map +1 -1
  243. package/dist/switchbot.d.ts +1 -0
  244. package/dist/switchbot.d.ts.map +1 -1
  245. package/dist/switchbot.js +152 -34
  246. package/dist/switchbot.js.map +1 -1
  247. package/dist/types/ble.d.ts +6 -0
  248. package/dist/types/ble.d.ts.map +1 -1
  249. package/dist/types/ble.js.map +1 -1
  250. package/dist/types/device.d.ts +81 -2
  251. package/dist/types/device.d.ts.map +1 -1
  252. package/dist/types/index.d.ts +18 -0
  253. package/dist/types/index.d.ts.map +1 -1
  254. package/dist/types/index.js.map +1 -1
  255. package/dist/utils/fallback-handler.js +0 -1
  256. package/dist/utils/fallback-handler.js.map +1 -1
  257. package/dist/utils/index.d.ts +21 -1
  258. package/dist/utils/index.d.ts.map +1 -1
  259. package/dist/utils/index.js +49 -0
  260. package/dist/utils/index.js.map +1 -1
  261. package/dist/utils/relay-encryption.d.ts +10 -0
  262. package/dist/utils/relay-encryption.d.ts.map +1 -0
  263. package/dist/utils/relay-encryption.js +23 -0
  264. package/dist/utils/relay-encryption.js.map +1 -0
  265. package/dist/utils/retry.d.ts.map +1 -1
  266. package/dist/utils/retry.js +49 -6
  267. package/dist/utils/retry.js.map +1 -1
  268. package/package.json +32 -16
  269. package/.gitattributes +0 -2
  270. package/.github/copilot-instructions.md +0 -179
  271. package/.github/dependabot.yml +0 -17
  272. package/.github/labeler.yml +0 -38
  273. package/.github/npm-version-script-esm.js +0 -97
  274. package/.github/workflows/beta-release.yml +0 -52
  275. package/.github/workflows/release.yml +0 -71
  276. package/.github/workflows/stale.yml +0 -12
  277. package/branding/Node_x_SwitchBot.svg +0 -8
  278. package/branding/icon.png +0 -0
  279. package/branding/switchbot.png +0 -0
  280. package/docs/.nojekyll +0 -1
  281. package/docs/assets/hierarchy.js +0 -1
  282. package/docs/assets/highlight.css +0 -85
  283. package/docs/assets/icons.js +0 -18
  284. package/docs/assets/icons.svg +0 -1
  285. package/docs/assets/main.js +0 -60
  286. package/docs/assets/navigation.js +0 -1
  287. package/docs/assets/search.js +0 -1
  288. package/docs/assets/style.css +0 -1633
  289. package/docs/classes/APIError.html +0 -6
  290. package/docs/classes/APINotAvailableError.html +0 -4
  291. package/docs/classes/BLEConnection.html +0 -21
  292. package/docs/classes/BLENotAvailableError.html +0 -4
  293. package/docs/classes/BLEScanner.html +0 -17
  294. package/docs/classes/CommandFailedError.html +0 -6
  295. package/docs/classes/ConnectionTimeoutError.html +0 -5
  296. package/docs/classes/DeviceManager.html +0 -25
  297. package/docs/classes/DeviceNotFoundError.html +0 -4
  298. package/docs/classes/DiscoveryError.html +0 -5
  299. package/docs/classes/OpenAPIClient.html +0 -66
  300. package/docs/classes/SwitchBot.html +0 -22
  301. package/docs/classes/SwitchBotDevice.html +0 -56
  302. package/docs/classes/SwitchBotError.html +0 -4
  303. package/docs/classes/ValidationError.html +0 -5
  304. package/docs/classes/WoAirPurifier.html +0 -63
  305. package/docs/classes/WoAirPurifierTable.html +0 -64
  306. package/docs/classes/WoBlindTilt.html +0 -67
  307. package/docs/classes/WoBulb.html +0 -65
  308. package/docs/classes/WoCeilingLight.html +0 -66
  309. package/docs/classes/WoContact.html +0 -55
  310. package/docs/classes/WoCurtain.html +0 -63
  311. package/docs/classes/WoHand.html +0 -69
  312. package/docs/classes/WoHub2.html +0 -55
  313. package/docs/classes/WoHub3.html +0 -56
  314. package/docs/classes/WoHumi.html +0 -63
  315. package/docs/classes/WoHumi2.html +0 -64
  316. package/docs/classes/WoIOSensorTH.html +0 -56
  317. package/docs/classes/WoKeypad.html +0 -56
  318. package/docs/classes/WoLeak.html +0 -55
  319. package/docs/classes/WoPlugMiniJP.html +0 -62
  320. package/docs/classes/WoPlugMiniUS.html +0 -61
  321. package/docs/classes/WoPresence.html +0 -55
  322. package/docs/classes/WoRelaySwitch1.html +0 -61
  323. package/docs/classes/WoRelaySwitch1PM.html +0 -62
  324. package/docs/classes/WoRemote.html +0 -56
  325. package/docs/classes/WoSensorTH.html +0 -55
  326. package/docs/classes/WoSensorTHPlus.html +0 -56
  327. package/docs/classes/WoSensorTHPro.html +0 -56
  328. package/docs/classes/WoSensorTHProCO2.html +0 -56
  329. package/docs/classes/WoSmartLock.html +0 -59
  330. package/docs/classes/WoSmartLockPro.html +0 -61
  331. package/docs/classes/WoStrip.html +0 -66
  332. package/docs/enums/LogLevel.html +0 -7
  333. package/docs/enums/SwitchBotBLEModel.html +0 -40
  334. package/docs/enums/SwitchBotBLEModelName.html +0 -40
  335. package/docs/functions/updateBaseURL.html +0 -3
  336. package/docs/hierarchy.html +0 -1
  337. package/docs/index.html +0 -55
  338. package/docs/interfaces/APICommandRequest.html +0 -5
  339. package/docs/interfaces/APICommandResponse.html +0 -5
  340. package/docs/interfaces/APIDevice.html +0 -18
  341. package/docs/interfaces/APIDeviceStatus.html +0 -36
  342. package/docs/interfaces/APIErrorResponse.html +0 -5
  343. package/docs/interfaces/APIResponse.html +0 -5
  344. package/docs/interfaces/AirPurifierCommands.html +0 -5
  345. package/docs/interfaces/AirPurifierServiceData.html +0 -29
  346. package/docs/interfaces/AirPurifierStatus.html +0 -17
  347. package/docs/interfaces/BLEAdvertisement.html +0 -7
  348. package/docs/interfaces/BLEScanOptions.html +0 -10
  349. package/docs/interfaces/BLEServiceData.html +0 -27
  350. package/docs/interfaces/BlindTiltCommands.html +0 -7
  351. package/docs/interfaces/BlindTiltServiceData.html +0 -30
  352. package/docs/interfaces/BlindTiltStatus.html +0 -15
  353. package/docs/interfaces/BotCommands.html +0 -4
  354. package/docs/interfaces/BotServiceData.html +0 -27
  355. package/docs/interfaces/BotStatus.html +0 -14
  356. package/docs/interfaces/BulbCommands.html +0 -6
  357. package/docs/interfaces/BulbServiceData.html +0 -35
  358. package/docs/interfaces/BulbStatus.html +0 -16
  359. package/docs/interfaces/CeilingLightCommands.html +0 -6
  360. package/docs/interfaces/CeilingLightServiceData.html +0 -35
  361. package/docs/interfaces/CeilingLightStatus.html +0 -16
  362. package/docs/interfaces/CommandResult.html +0 -12
  363. package/docs/interfaces/ContactServiceData.html +0 -30
  364. package/docs/interfaces/ContactStatus.html +0 -15
  365. package/docs/interfaces/CurtainCommands.html +0 -5
  366. package/docs/interfaces/CurtainServiceData.html +0 -31
  367. package/docs/interfaces/CurtainStatus.html +0 -17
  368. package/docs/interfaces/DeviceInfo.html +0 -36
  369. package/docs/interfaces/DeviceListResponse.html +0 -4
  370. package/docs/interfaces/DeviceStatus.html +0 -12
  371. package/docs/interfaces/DiscoveryOptions.html +0 -14
  372. package/docs/interfaces/HubServiceData.html +0 -31
  373. package/docs/interfaces/HubStatus.html +0 -15
  374. package/docs/interfaces/HumidifierCommands.html +0 -5
  375. package/docs/interfaces/HumidifierServiceData.html +0 -31
  376. package/docs/interfaces/HumidifierStatus.html +0 -18
  377. package/docs/interfaces/KeypadStatus.html +0 -13
  378. package/docs/interfaces/LeakServiceData.html +0 -28
  379. package/docs/interfaces/LeakStatus.html +0 -13
  380. package/docs/interfaces/LockCommands.html +0 -3
  381. package/docs/interfaces/LockServiceData.html +0 -29
  382. package/docs/interfaces/LockStatus.html +0 -15
  383. package/docs/interfaces/MeterServiceData.html +0 -30
  384. package/docs/interfaces/MeterStatus.html +0 -15
  385. package/docs/interfaces/MotionServiceData.html +0 -30
  386. package/docs/interfaces/MotionStatus.html +0 -14
  387. package/docs/interfaces/PlugCommands.html +0 -4
  388. package/docs/interfaces/PlugServiceData.html +0 -33
  389. package/docs/interfaces/PlugStatus.html +0 -16
  390. package/docs/interfaces/PresenceServiceData.html +0 -29
  391. package/docs/interfaces/PresenceStatus.html +0 -14
  392. package/docs/interfaces/RelaySwitchCommands.html +0 -4
  393. package/docs/interfaces/RelaySwitchServiceData.html +0 -30
  394. package/docs/interfaces/RelaySwitchStatus.html +0 -16
  395. package/docs/interfaces/RemoteStatus.html +0 -12
  396. package/docs/interfaces/SceneListResponse.html +0 -3
  397. package/docs/interfaces/StripCommands.html +0 -6
  398. package/docs/interfaces/StripServiceData.html +0 -35
  399. package/docs/interfaces/StripStatus.html +0 -16
  400. package/docs/interfaces/SwitchBotConfig.html +0 -30
  401. package/docs/interfaces/WebhookConfig.html +0 -4
  402. package/docs/interfaces/WebhookDetails.html +0 -7
  403. package/docs/interfaces/WebhookQueryResponse.html +0 -5
  404. package/docs/interfaces/WebhookSetupResponse.html +0 -5
  405. package/docs/media/BLE.md +0 -1259
  406. package/docs/media/OpenAPI.md +0 -186
  407. package/docs/modules.html +0 -1
  408. package/docs/types/ConnectionType.html +0 -2
  409. package/docs/types/PhysicalDeviceType.html +0 -2
  410. package/docs/types/VirtualDeviceType.html +0 -2
  411. package/docs/variables/urls.html +0 -1
  412. package/tmp-switchbot-scan.mjs +0 -79
  413. package/todo/PYSWITCHBOT_COMPARISON.md +0 -484
  414. package/todo/README.md +0 -68
  415. package/todo/completed.md +0 -65
  416. package/todo/todo.md +0 -369
  417. package/tsconfig.build.json +0 -17
package/BLE.md CHANGED
@@ -6,948 +6,325 @@ The `SwitchBot` class allows you to interact with SwitchBot devices using the Sw
6
6
 
7
7
  - [BLE (Bluetooth Low Energy)](#ble-bluetooth-low-energy)
8
8
  - [Supported OS](#supported-os)
9
- - [Dependencies](#dependencies)
10
- - [Importing and Setting Up](#importing-and-setting-up)
11
- - [`SwitchBotBLE` Object](#switchbot-object)
12
- - [`discover()` method](#discover-method)
13
- - [`ondiscover` event handler](#ondiscover-event-handler)
14
- - [`startScan()` method](#startscan-method)
15
- - [`onadvertisement` event handler](#onadvertisement-event-handler)
16
- - [`stopScan()` method](#stopscan-method)
17
- - [`wait()` method](#wait-method)
18
- - [`SwitchBotDevice` Object](#switchbotdevice-object)
19
- - [Properties](#properties)
20
- - [`getDeviceName()` method](#getdevicename-method)
21
- - [`setDeviceName()` method](#setdevicename-method)
22
- - [`connect()` method](#connect-method)
23
- - [`disconnect()` method](#disconnect-method)
24
- - [`onconnect` event handler](#onconnect-event-handler)
25
- - [`ondisconnect` event handler](#ondisconnect-event-handler)
26
- - [`WoHand` Object](#wohand-object)
27
- - [`press()` method](#press-method)
28
- - [`turnOn()` method](#turnon-method)
29
- - [`turnOff()` method](#turnoff-method)
30
- - [`down()` method](#down-method)
31
- - [`up()` method](#up-method)
32
- - [`WoCurtain` object](#wocurtain-object)
33
- - [`open()` method](#open-method)
34
- - [`close()` method](#close-method)
35
- - [`pause()` method](#pause-method)
36
- - [`runToPos()` method](#runtopos-method)
37
- - [`WoPlugMini` object](#woplugmini-object)
38
- - [`turnOn()` method](#turnon-method)
39
- - [`turnOff()` method](#turnoff-method)
40
- - [`toggle()` method](#toggle-method)
41
- - [`WoSmartLock` object](#wosmartlock-object)
42
- - [`lock()` method](#lock-method)
43
- - [`unlock()` method](#unlock-method)
44
- - [`unlock_no_unlatch()` method](#unlock_no_unlatch-method)
45
- - [`info()` method](#info-method)
46
- - [Advertisement data](#advertisement-data)
47
- - [Bot (WoHand)](#bot-wohand)
48
- - [Meter (WoSensorTH)](#meter-wosensorth)
49
- - [Curtain (WoCurtain)](#curtain-wocurtain)
50
- - [Contact (WoContact)](#contact-wocontact)
51
- - [Motion (WoMotion)](#motion-womotion)
52
- - [PlugMini (WoPlugMini)](#plugmini-woplugmini)
53
- - [Supported Devices](#supported-devices)
54
- - [Advertisement Data](#advertisement-data)
55
- - [Control Device](#control-device)
56
- - [Summary](#summary)
57
-
58
- ## BLE (Bluetooth Low Energy)
59
-
60
- ### Supported OS
61
-
62
- The node-switchbot supports Linux-based OSes (such as Raspbian, Ubuntu) and macOS. Windows is not currently supported. BLE functionality requires [@stoprocent/noble](https://github.com/stoprocent/noble#readme) which works natively on Linux and macOS.
63
-
64
- ### Dependencies
65
-
66
- - [Node.js](https://nodejs.org/en/): ^20 || ^22 || ^24
67
- - [@stoprocent/noble](https://github.com/stoprocent/noble) - Included as a dependency
68
-
69
- ### Prerequisites
70
-
71
- #### macOS
72
-
73
- - **Xcode**: Install from the App Store
74
- - **Bluetooth Permissions**: On newer versions of macOS, allow Bluetooth access for your terminal app:
75
- 1. Open "System Preferences" → "Security & Privacy" → "Privacy" → "Bluetooth"
76
- 2. Add and enable your terminal application (Terminal.app, iTerm.app, etc.)
77
-
78
- #### Linux (Ubuntu, Debian, Raspbian)
79
-
80
- - **Kernel**: Version 3.6 or above
81
- - **Required Packages**:
9
+ # SwitchBot BLE Documentation
82
10
 
83
- ```bash
84
- sudo apt-get install bluetooth bluez libbluetooth-dev libudev-dev
85
- ```
86
-
87
- - **Node Path**: Ensure `node` is on your PATH
88
-
89
- ```bash
90
- # If needed, symlink nodejs to node
91
- sudo ln -s /usr/bin/nodejs /usr/bin/node
92
- ```
93
-
94
- - **Running without sudo** (Recommended):
95
-
96
- ```bash
97
- sudo setcap cap_net_raw+eip $(eval readlink -f `which node`)
98
- ```
99
-
100
- This grants the `node` binary `cap_net_raw` privileges for BLE operations.
101
-
102
- Required package: `sudo apt-get install libcap2-bin`
103
-
104
- - **Raspberry Pi Specific**: If having trouble connecting to BLE devices, disable the `pnat` plugin by adding this line to `/etc/bluetooth/main.conf`:
105
- ```
106
- DisablePlugins=pnat
107
- ```
108
- Then restart the system.
11
+ BLE support in `node-switchbot` is part of the v4 unified architecture. The primary API is the `SwitchBot` class, which can use BLE directly, OpenAPI directly, or both together with automatic fallback.
109
12
 
110
- #### Linux (Fedora and RPM-based)
13
+ This document covers:
111
14
 
112
- ```bash
113
- sudo yum install bluez bluez-libs bluez-libs-devel
114
- ```
115
-
116
- See [@stoprocent/noble prerequisites](https://github.com/stoprocent/noble?tab=readme-ov-file#prerequisites) for more detailed platform-specific instructions.
117
-
118
- ### Importing and Setting Up
15
+ - BLE support and prerequisites on macOS and Linux
16
+ - BLE-first usage through the unified `SwitchBot` class
17
+ - Bot password protection over BLE
18
+ - Low-level BLE helpers for advanced use: `BLEScanner` and `BLEConnection`
119
19
 
120
- To use the `SwitchBotBLE` class in `node-switchbot`, you need to import it and create an instance.
121
-
122
- ```typescript
123
- import { SwitchBotBLE } from 'node-switchbot'
124
-
125
- // Example usage
126
- const switchBotBLE = new SwitchBotBLE()
127
-
128
- try {
129
- await switchBotBLE.startScan()
130
- } catch (e: any) {
131
- console.error(`Failed to start BLE scanning, Error: ${e.message ?? e}`)
132
- }
133
- ```
20
+ ## v4 BLE Model
134
21
 
135
- ### `SwitchBotBLE` Object
136
-
137
- The `SwitchBotBLE` constructor takes an argument optionally. It must be a hash object containing the properties as follows:
138
-
139
- | Property | Type | Required | Description |
140
- | :------- | :---- | :------- | :-------------------------------------------------------------------------------------- |
141
- | `noble` | Noble | option | a Noble object of the [`@stoprocent/noble`](https://github.com/stoprocent/noble) module |
142
-
143
- The node-switchbot module uses the [`@stoprocent/noble`](https://github.com/stoprocent/noble) module in order to interact with BLE devices. If you want to interact other BLE devices using the `@stoprocent/noble` module, you can create an `Noble` object by yourself, then pass it to this module. If you don't specify a `Noble` object to the `noble` property, this module automatically create a `Noble` object internally.
144
-
145
- The sample code below shows how to pass a `Noble` object to the `Switchbot` constructor.
146
-
147
- ```Typescript
148
- // Create a Noble object
149
- const noble = require('@stoprocent/noble');
150
-
151
- const switchBotBLE = new SwitchBotBLE({ 'noble': Noble })
152
- ```
22
+ In v4.0.0, BLE is no longer a separate top-level workflow that you have to adopt in isolation. Instead:
153
23
 
154
- In the code snippet above, the variable `switchbot` is an `SwitchBotBLE` object. The `SwitchBotBLE` object has a lot of methods as described in sections below.
24
+ - `SwitchBot` is the main public entry point
25
+ - BLE is used when `enableBLE: true`
26
+ - OpenAPI can be used as fallback when credentials are present
27
+ - Devices are accessed through `switchbot.devices`
28
+ - Per-device commands automatically choose the best available connection path
155
29
 
156
- #### `discover()` method
30
+ ## Supported Platforms
157
31
 
158
- The `discover` method finds devices. This method returns a `Promise` object. This method takes an argument which is a hash object containing parameters as follows:
159
-
160
- | Property | Type | Required | Description |
161
- | :--------- | :------ | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
162
- | `duration` | Integer | Optional | Duration for discovery process (msec). The default value is 5000 (msec). |
163
- | `model` | String | Optional | `"H"`, `"T"` or `"c"`. If `"H"` is specified, this method will discover only Bots. If `"T"` is specified, this method will discover only Meters. If `"c"` is specified, this method will discover only Curtains. |
164
- | `id` | String | Optional | If this value is set, this method will discover only a device whose ID is as same as this value. The ID is identical to the MAC address. This parameter is case-insensitive, and colons are ignored. |
165
- | `quick` | Boolean | Optional | If this value is `true`, this method finishes the discovery process when the first device is found, then calls the `resolve()` function without waiting the specified `duration`. The default value is `false`. |
166
-
167
- In the code snippet below, no parameter is passed to the method:
168
-
169
- ```Typescript
170
- switchBotBLE.discover().then((device_list) => {
171
- // Do something...
172
- }).catch((error) => {
173
- console.error(error);
174
- });
175
- ```
176
-
177
- If no parameter is passed to the method as the code above, an `Array` object will be passed to the `resolve()` function in 5 seconds. The `Array` object contains [`SwitchbotDevice`](#SwitchbotDevice-object) objects representing the found devices. See the section "[`SwitchbotDevice`](#SwitchbotDevice-object) objects" for more details.
178
-
179
- If you want a quick response, you can set the `quick` property to `true`.
180
-
181
- ```Typescript
182
- switchBotBLE.discover({
183
- duration: 5000,
184
- quick: true
185
- }).then((device_list) => {
186
- // Do something...
187
- }).catch((error) => {
188
- console.error(error);
189
- });
190
- ```
191
-
192
- As the `quick` property is set to `true`, the `resolve()` function will be called immediately after a device is found regardless the value of the `duration` property.
193
-
194
- #### `ondiscover` event handler
195
-
196
- The `ondiscover` property on the [`Switchbot`](#Switchbot-object) object is an event handler called whenever a device is newly found in the discovery process. A [`SwitchbotDevice`](#SwitchbotDevice-object) object is passed to the callback function set to the `ondiscover` property.
197
-
198
- ```Typescript
199
- switchBotBLE.ondiscover = (device) => {
200
- console.log(device.id + ' (' + device.modelName + ')');
201
- };
202
-
203
- switchBotBLE.discover().then(() => {
204
- console.log('The discovery process was finished.');
205
- }).catch((error) => {
206
- console.error(error);
207
- });
208
- ```
209
-
210
- The code snippet above will output the result as follows:
211
-
212
- ```
213
- cb4eb903c96d (WoSensorTH)
214
- c12e453e2008 (WoHand)
215
- The discovery process was finished.
216
- ```
217
-
218
- #### `startScan()` method
219
-
220
- The `startScan()` method starts to scan advertising packets coming from devices. This method takes an argument which is a hash object containing the parameters as follows:
221
-
222
- | Property | Type | Required | Description |
223
- | :------- | :----- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
224
- | `model` | String | Optional | `"H"`, `"T"`, `"c"`, `"g"` or `"j"`. If `"H"` is specified, this method will discover only Bots. If `"T"` is specified, this method will discover only Meters. If `"c"` is specified, this method will discover only Curtains. If `"g"` or `"j"` is specified, this method will discover only (US/JP) Plug Minis. |
225
- | `id` | String | Optional | If this value is set, this method will discover only a device whose ID is as same as this value. The ID is identical to the MAC address. This value is case-insensitive, and colons are ignored. |
226
-
227
- Whenever a packet is received, the callback function set to the [`onadvertisement`](#Switchbot-onadvertisement-event-handler) property of the [`Switchbot`](#Switchbot-object) object will be called. When a packet is received, a hash object representing the packet will be passed to the callback function.
228
-
229
- ```Typescript
230
- // Set a callback function called when a packet is received
231
- switchBotBLE.onadvertisement = (ad) => {
232
- console.log(ad);
233
- };
234
-
235
- // Start to scan advertising packets
236
- switchBotBLE.startScan({
237
- id: 'cb:4e:b9:03:c9:6d',
238
- }).then(() => {
239
- // Wait for 30 seconds
240
- return switchBotBLE.wait(30000);
241
- }).then(() => {
242
- // Stop to scan
243
- switchBotBLE.stopScan();
244
- process.exit();
245
- }).catch((error) => {
246
- console.error(error);
247
- });
248
- ```
249
-
250
- The code snippet above will output the result as follows:
251
-
252
- ```
253
- {
254
- id: 'cb4eb903c96d',
255
- address: 'cb:4e:b9:03:c9:6d',
256
- rssi: -65,
257
- serviceData: {
258
- model: 'T',
259
- modelName: 'WoSensorTH',
260
- celsius: 25.8,
261
- fahrenheit: 78.4,
262
- fahrenheit_mode: false,
263
- humidity: 43,
264
- battery: 100
265
- }
266
- }
267
- ...
268
- ```
269
-
270
- The `serviceData` property depends on the model of the device. See the section "[Advertisement data](#Advertisement-data)" for the details of the data format.
271
-
272
- #### `onadvertisement` event handler
273
-
274
- If a callback function is set to the `onadvertisement` property, the callback function will be called whenever an advertising packet is received from a device during the scan is active (from the moment when the [`startScan()`](#startscan-method) method is called, to the moment when the [`stopScan()`](#Switchbot-stopScan-method) method is called).
275
-
276
- ```typescript
277
- switchBotBLE.onadvertisement = async (ad: any) => {
278
- try {
279
- this.bleEventHandler[ad.address]?.(ad.serviceData)
280
- } catch (e: any) {
281
- await this.errorLog(`Failed to handle BLE event, Error: ${e.message ?? e}`)
282
- }
283
- }
284
- ```
285
-
286
- See the section "[`startScan()` method](#startscan-method)" for details.
287
-
288
- #### `stopScan()` method
289
-
290
- The `stopScan()` method stops to scan advertising packets coming from devices. This method returns nothing. Note that this method is _not_ asynchronous but synchronous unlike the other methods. See the section "[`startScan()` method](#startscan-method)" for details.
291
-
292
- ```typescript
293
- try {
294
- switchBotBLE.stopScan()
295
- console.log('Stopped BLE scanning to close listening.')
296
- } catch (e: any) {
297
- console.error(`Failed to stop BLE scanning, Error: ${e.message ?? e}`)
298
- }
299
- ```
300
-
301
- #### `wait()` method
302
-
303
- The `wait()` method waits for the specified milliseconds. This method takes an integer representing the duration (millisecond). This method returns a `Promise` object.
304
-
305
- This method has nothing to do with Switchbot devices. It's just a utility method. See the section "[Quick Start](#Quick-Start)" for details of the usage of this method.
306
-
307
- ```typescript
308
- await switchBotBLE.wait(1000)
309
- ```
310
-
311
- ### `SwitchBotDevice` Object
312
-
313
- The `SwitchbotDevice` object represents a Switchbot device (Bot, Meter, Curtain, Contact or Motion), which is created through the discovery process triggered by the [`switchBotBLE.discover()`](#discover-method) method.
314
-
315
- Actually, the `SwitchbotDevice` object is a super class of the [`WoHand`](#SwitchbotDeviceWoHand-object) and `WoSensorTH` objects. The [`WoHand`](#SwitchbotDeviceWoHand-object) object represents a Bot, the `WoSensorTH` object represents a Meter.
316
-
317
- You can use the properties and methods described in this section on Bot, Meter, Curtain, Contact and Motion. See the section "[`WoHand` object](#SwitchbotDeviceWoHand-object)" for the details of the functionalities available only on Bot. For now, `WoSensorTH` object has no additional functionality.
318
-
319
- #### Properties
320
-
321
- The `SwitchbotDevice` object supports the properties as follows:
322
-
323
- | Property | Type | Description |
324
- | :---------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |
325
- | `id` | String | ID of the device. (e.g., `"cb4eb903c96d"`) |
326
- | `address` | String | MAC address of the device. Basically it is as same as the value of the `id` except that this value includes `:` in the string. (e.g., `"cb:4e:b9:03:c9:6d"`) |
327
- | `model` | String | This value is `"H"` "Bot (WoHand)", `"T"` "Meter (WoSensorTH)", `"c"` "Curtain (WoCurtain)", `"d"` "Contact (WoContact)" or `"s"` "Motion (WoMotion)". |
328
- | `modelName` | String | This value is `"WoHand"`, `"WoSensorTH"`, `WoCurtain`, `WoContect` or `WoMotion`. |
329
- | `connectionState` | String | This value indicates the BLE connection state. `"connecting"`, `"connected"`, `"disconnecting"`, or `"disconnected"`. |
330
- | `onconnect` | Function | See the section "[`onconnect` event handler](#SwitchbotDevice-onconnect-event-handler)" for details. |
331
- | `ondisconnect` | Function | See the section "[`ondisconnect` event handler](#SwitchbotDevice-ondisconnect-event-handler)" for details. |
332
-
333
- #### `getDeviceName()` method
334
-
335
- The `getDeviceName()` method fetches the device name saved in the device. This method returns a `Promise` object.
336
-
337
- If no connection is established with the device, this method automatically establishes a connection with the device, then finally closes the connection. You don't have to call the [`connect()`](#SwitchbotDevice-connect-method) method in advance.
338
-
339
- If the device name is fetched successfully, the device name will be passed to the `resolve()`.
340
-
341
- ```Typescript
342
- switchbot
343
- .discover({ model: "H", quick: true })
344
- .then((device_list) => {
345
- return device_list[0].getDeviceName();
346
- })
347
- .then((name) => {
348
- console.log(name);
349
- process.exit();
350
- })
351
- .catch((error) => {
352
- console.error(error);
353
- process.exit();
354
- });
355
- ```
356
-
357
- The code above will output the result as follows:
358
-
359
- ```Typescript
360
- WoHand;
361
- ```
362
-
363
- #### `setDeviceName()` method
364
-
365
- The `setDeviceName()` method update the device name saved in the device with the name specified as the first argument. This method returns a `Promise` object. Nothing will be passed to the `resolve()` function.
366
-
367
- If no connection is established with the device, this method automatically establishes a connection with the device, then finally closes the connection. You don't have to call the [`connect()`](#SwitchbotDevice-connect-method) method in advance.
368
-
369
- The character set of the device name saved in the device is UTF-8. The byte length of the name must be less than or equal to 20 bytes. If the name consists of only ASCII characters, up to 20 characters would be allowed. But if the name consists of multibyte characters, the upper limit of characters would be fewer than half. For example, Japanese characters could be saved at most 6 characters because most of Japanese characters consume 3 byte per each character.
370
-
371
- ```Typescript
372
- switchbot
373
- .discover({ model: "H", quick: true })
374
- .then((device_list) => {
375
- return device_list[0].setDeviceName("Bot in kitchen");
376
- })
377
- .then(() => {
378
- console.log("Done.");
379
- process.exit();
380
- })
381
- .catch((error) => {
382
- console.error(error);
383
- process.exit();
384
- });
385
- ```
386
-
387
- #### `connect()` method
388
-
389
- The `connect()` method establishes a connection with the device (i.e., pairing). This method returns a `Promise` object. If the device has already been connected, this method does nothing and calls the `resolve()` function immediately.
390
-
391
- Most of the methods implemented in the `SwitchbotDevice` object automatically connect and disconnect the device. But this mechanism would be absolutely inefficient if you want to manipulate the device repeatedly in the short time.
392
-
393
- The connection established using the `connect()` method is not disconnected automatically unless the [`disconnect()`](#SwitchbotDevice-disconnect-method) method is explicitly called.
394
-
395
- The code snippet below establishes a connection with the Bot using the `connect()` method, then puts the Bot's arm down, then waits for 5 seconds, then puts the arm down, finally disconnects the device using the [`disconnect()`](#SwitchbotDevice-disconnect-method) method:
396
-
397
- ```Typescript
398
- let device = null;
399
-
400
- switchbot
401
- .discover({ model: "H", quick: true })
402
- .then((device_list) => {
403
- device = device_list[0];
404
- if (!device) {
405
- console.log("No device was found.");
406
- process.exit();
407
- }
408
- console.log(device.modelName + " (" + device.address + ") was found.");
409
- console.log("Connecting...");
410
- return device.connect();
411
- })
412
- .then(() => {
413
- console.log("Putting the arm down...");
414
- return device.down();
415
- })
416
- .then(() => {
417
- console.log("Waiting for 5 seconds...");
418
- return switchBotBLE.wait(5000);
419
- })
420
- .then(() => {
421
- console.log("Putting the arm up...");
422
- return device.up();
423
- })
424
- .then(() => {
425
- console.log("Disconnecting...");
426
- return device.disconnect();
427
- })
428
- .then(() => {
429
- console.log("Done.");
430
- process.exit();
431
- })
432
- .catch((error) => {
433
- console.error(error);
434
- process.exit();
435
- });
436
- ```
32
+ BLE is supported on:
437
33
 
438
- The result will be as follows:
34
+ - macOS
35
+ - Linux, including Ubuntu, Debian, Raspbian, and similar distributions
439
36
 
440
- ```
441
- WoHand (c1:2e:45:3e:20:08) was found.
442
- Connecting...
443
- Putting the arm down...
444
- Waiting for 5 seconds...
445
- Putting the arm up...
446
- Disconnecting...
447
- Done.
448
- ```
37
+ BLE is not supported on Windows in this package. On Windows, use API-only mode through the unified `SwitchBot` class.
449
38
 
450
- #### `disconnect()` method
39
+ ## Requirements
451
40
 
452
- The `disconnect()` method disconnects the device. This method returns a `Promise` object. If the device has already been disconnected, this method does nothing and calls the `resolve()` function immediately.
41
+ - Node.js `^20 || ^22 || ^24`
42
+ - `@stoprocent/noble` is included as a dependency
453
43
 
454
- See the [previous section](#SwitchbotDevice-connect-method) for more details.
44
+ ## Prerequisites
455
45
 
456
- #### `onconnect` event handler
46
+ ### macOS
457
47
 
458
- The `onconnect` event handler will be called when the connection with the device is established. Nothing will be passed to the handler.
48
+ - Install Xcode from the App Store
49
+ - Allow Bluetooth access for your terminal application in System Settings or System Preferences
459
50
 
460
- The code below calls the [`press()`](#SwitchbotDeviceWoHand-press-method) method, while callback functions are attached to the `onconnect` and `ondisconnect`.
51
+ ### Linux (Ubuntu, Debian, Raspbian)
461
52
 
462
- ```Typescript
463
- switchbot
464
- .discover({ model: "H", quick: true })
465
- .then((device_list) => {
466
- const device = device_list[0];
467
- if (!device) {
468
- console.log("No device was found.");
469
- process.exit();
470
- }
471
- console.log(device.modelName + " (" + device.address + ") was found.");
472
-
473
- // Set event handers
474
- device.onconnect = () => {
475
- console.log("Connected.");
476
- };
477
- device.ondisconnect = () => {
478
- console.log("Disconnected.");
479
- };
480
-
481
- console.log("Pressing the switch...");
482
- return device.press();
483
- })
484
- .then(() => {
485
- console.log("Done.");
486
- process.exit();
487
- })
488
- .catch((error) => {
489
- console.error(error);
490
- process.exit();
491
- });
492
- ```
53
+ Install required packages:
493
54
 
494
- The code above will output the result as follows:
55
+ ```bash
56
+ sudo apt-get install bluetooth bluez libbluetooth-dev libudev-dev
57
+ ```
495
58
 
496
- ```
497
- WoHand (c1:2e:45:3e:20:08) was found.
498
- Pressing the switch...
499
- Connected.
500
- Disconnected.
501
- Done.
502
- ```
59
+ For non-root access, also install `libcap2-bin` and grant raw socket capability to `node`:
503
60
 
504
- Seeing the result, you would find the [`press()`](#SwitchbotDeviceWoHand-press-method) method automatically connects and disconnects the device.
61
+ ```bash
62
+ sudo apt-get install libcap2-bin
63
+ sudo setcap cap_net_raw+eip $(eval readlink -f `which node`)
64
+ ```
505
65
 
506
- #### `ondisconnect` event handler
66
+ On Raspberry Pi, if BLE connections are unstable, you may need to disable the `pnat` plugin in `/etc/bluetooth/main.conf` and restart Bluetooth or reboot.
507
67
 
508
- The `ondisconnect` event handler will be called when the connection with the device is closed. Nothing will be passed to the handler. See the previous section "[`onconnect` event handler](#SwitchbotDevice-onconnect-event-handler)" for more details.
68
+ ### Fedora and Other RPM-Based Linux
509
69
 
510
- ### `WoHand` Object
70
+ ```bash
71
+ sudo yum install bluez bluez-libs bluez-libs-devel
72
+ ```
511
73
 
512
- The `WoHand` object represents a Bot, which is created through the discovery process triggered by the [`switchBotBLE.discover()`](#discover-method) method.
74
+ For more platform details, see the `@stoprocent/noble` prerequisites documentation.
513
75
 
514
- Actually, the `WoHand` is an object inherited from the [`SwitchbotDevice`](#SwitchbotDevice-object). You can use not only the method described in this section but also the properties and methods implemented in the [`SwitchbotDevice`](#SwitchbotDevice-object) object.
76
+ ## Unified BLE Usage
515
77
 
516
- #### `press()` method
78
+ ### BLE-Only Mode
517
79
 
518
- The `press()` method sends a press command to the Bot. This method returns a `Promise` object. Nothing will be passed to the `resove()`.
80
+ Use BLE without OpenAPI credentials:
519
81
 
520
- If no connection is established with the device, this method automatically establishes a connection with the device, then finally closes the connection. You don't have to call the [`connect()`](#SwitchbotDevice-connect-method) method in advance.
82
+ ```typescript
83
+ import { LogLevel, SwitchBot } from 'node-switchbot'
521
84
 
522
- ```Typescript
523
- switchbot
524
- .discover({ model: "H", quick: true })
525
- .then((device_list) => {
526
- return device_list[0].press();
527
- })
528
- .then(() => {
529
- console.log("Done.");
85
+ const switchbot = new SwitchBot({
86
+ enableBLE: true,
87
+ enableFallback: false,
88
+ logLevel: LogLevel.INFO,
530
89
  })
531
- .catch((error) => {
532
- console.error(error);
533
- });
534
- ```
535
-
536
- When the Bot receives this command, the Bot's arm will be put down (stretched), then put up (retracted) in a few seconds.
537
-
538
- #### `turnOn()` method
539
-
540
- The `turnOn()` method sends a turn-on command to the Bot. This method returns a `Promise` object. Nothing will be passed to the `resove()`.
541
-
542
- If no connection is established with the device, this method automatically establishes a connection with the device, then finally closes the connection. You don't have to call the [`connect()`](#SwitchbotDevice-connect-method) method in advance.
543
-
544
- When the Bot receives this command, the Bot's arm will be put down (stretched) or put up (retracted) depending on the mode setting.
545
90
 
546
- | Mode | Inverse the on/off direction | Physical position of the arm |
547
- | :---------- | :--------------------------- | :------------------------------------ |
548
- | Press mode | N/A | Down (stretched), then Up (retracted) |
549
- | Switch mode | Disabled | Down (stretched) |
550
- |   | Enabled | Up (retracted) |
551
-
552
- ```Typescript
553
- switchbot
554
- .discover({ model: "H", quick: true })
555
- .then((device_list) => {
556
- return device_list[0].turnOn();
91
+ const devices = await switchbot.discover({
92
+ scanBLE: true,
93
+ fetchAPI: false,
94
+ timeout: 10_000,
557
95
  })
558
- .then(() => {
559
- console.log("Done.");
560
- })
561
- .catch((error) => {
562
- console.error(error);
563
- });
564
- ```
565
-
566
- #### `turnOff()` method
567
-
568
- The `turnOff()` method sends a turn-off command to the Bot. This method returns a `Promise` object. Nothing will be passed to the `resove()`.
569
-
570
- If no connection is established with the device, this method automatically establishes a connection with the device, then finally closes the connection. You don't have to call the [`connect()`](#SwitchbotDevice-connect-method) method in advance.
571
-
572
- When the Bot receives this command, the Bot's arm will be put down (stretched) or put up (retracted) depending on the mode setting.
573
96
 
574
- | Mode | Inverse the on/off direction | Physical position of the arm |
575
- | :---------- | :--------------------------- | :------------------------------------ |
576
- | Press mode | N/A | Down (stretched), then Up (retracted) |
577
- | Switch mode | Disabled | Up (retracted) |
578
- |   | Enabled | Down (stretched) |
97
+ console.log(`Found ${devices.length} BLE device(s)`)
579
98
 
580
- ```Typescript
581
- switchbot
582
- .discover({ model: "H", quick: true })
583
- .then((device_list) => {
584
- return device_list[0].turnOff();
585
- })
586
- .then(() => {
587
- console.log("Done.");
588
- })
589
- .catch((error) => {
590
- console.error(error);
591
- });
592
- ```
99
+ const bot = switchbot.devices.get('YOUR_DEVICE_ID')
100
+ if (bot) {
101
+ await bot.press()
102
+ }
593
103
 
594
- #### `down()` method
104
+ await switchbot.cleanup()
105
+ ```
595
106
 
596
- The `down()` method sends a down command to the Bot. This method returns a `Promise` object. Nothing will be passed to the `resove()`.
107
+ ### Hybrid BLE + API Mode
597
108
 
598
- If no connection is established with the device, this method automatically establishes a connection with the device, then finally closes the connection. You don't have to call the [`connect()`](#SwitchbotDevice-connect-method) method in advance.
109
+ Use BLE first, with automatic API fallback when needed:
599
110
 
600
- When the Bot receives this command, the Bot's arm will be put down (stretched) regardless of the mode setting.
111
+ ```typescript
112
+ import { LogLevel, SwitchBot } from 'node-switchbot'
601
113
 
602
- ```Typescript
603
- switchbot
604
- .discover({ model: "H", quick: true })
605
- .then((device_list) => {
606
- return device_list[0].down();
114
+ const switchbot = new SwitchBot({
115
+ token: 'YOUR_TOKEN',
116
+ secret: 'YOUR_SECRET',
117
+ enableBLE: true,
118
+ enableFallback: true,
119
+ enableConnectionIntelligence: true,
120
+ enableCircuitBreaker: true,
121
+ enableRetry: true,
122
+ logLevel: LogLevel.INFO,
607
123
  })
608
- .then(() => {
609
- console.log("Done.");
610
- })
611
- .catch((error) => {
612
- console.error(error);
613
- });
614
- ```
615
124
 
616
- #### `up()` method
617
-
618
- The `up()` method sends an up command to the Bot. This method returns a `Promise` object. Nothing will be passed to the `resove()`.
619
-
620
- If no connection is established with the device, this method automatically establishes a connection with the device, then finally closes the connection. You don't have to call the [`connect()`](#SwitchbotDevice-connect-method) method in advance.
621
-
622
- When the Bot receives this command, the Bot's arm will be put up (retracted) regardless of the mode setting.
623
-
624
- ```Typescript
625
- switchbot
626
- .discover({ model: "H", quick: true })
627
- .then((device_list) => {
628
- return device_list[0].up();
629
- })
630
- .then(() => {
631
- console.log("Done.");
125
+ await switchbot.discover({
126
+ scanBLE: true,
127
+ fetchAPI: true,
128
+ timeout: 10_000,
632
129
  })
633
- .catch((error) => {
634
- console.error(error);
635
- });
636
- ```
637
-
638
- #### Password Protection
639
130
 
640
- The Bot (WoHand) supports password protection via BLE to prevent unauthorized control. When a password is set, all BLE commands (press, turnOn, turnOff, up, down) will be automatically encrypted.
131
+ const curtain = switchbot.devices.get('YOUR_CURTAIN_ID')
132
+ if (curtain) {
133
+ await curtain.open()
134
+ const status = await curtain.getStatus()
135
+ console.log(status)
136
+ }
641
137
 
642
- **Password Requirements:**
138
+ await switchbot.cleanup()
139
+ ```
643
140
 
644
- - Exactly 4 characters
645
- - Alphanumeric only (letters and numbers)
646
- - Case-sensitive
141
+ ## Discovery Options
647
142
 
648
- **Setting a Password:**
143
+ `switchbot.discover()` accepts the following v4 options:
649
144
 
650
- ```typescript
651
- // Using device options during construction
652
- const bot = new WoHand({
653
- id: 'c1:2e:45:3e:20:08',
654
- password: 'A1b2' // Your 4-character password
655
- })
145
+ | Property | Type | Description |
146
+ | :-- | :-- | :-- |
147
+ | `scanBLE` | `boolean` | Enable BLE discovery for this call |
148
+ | `fetchAPI` | `boolean` | Fetch devices from OpenAPI for this call |
149
+ | `timeout` | `number` | Discovery timeout in milliseconds |
150
+ | `deviceId` | `string` | Filter by SwitchBot device ID |
151
+ | `mac` | `string` | Filter by MAC address |
152
+ | `deviceType` | `string` | Filter by device type |
656
153
 
657
- // Or set/change password on existing device
658
- await bot.setPassword('A1b2')
659
- ```
154
+ ## Device Access Pattern
660
155
 
661
- **Clearing a Password:**
156
+ After discovery, use the device manager:
662
157
 
663
- ```typescript
664
- // Remove password protection
665
- await bot.clearPassword()
666
- ```
158
+ ```typescript
159
+ const devices = switchbot.devices.list()
160
+ const bot = switchbot.devices.get('YOUR_DEVICE_ID')
161
+ const curtains = switchbot.devices.getByType('WoCurtain')
162
+ ```
667
163
 
668
- **Checking Password Status:**
164
+ Common device helpers include:
669
165
 
670
- ```typescript
671
- // Check if device has password configured
672
- if (bot.hasPassword()) {
673
- console.log('Device is password protected')
674
- }
675
- ```
166
+ - `getInfo()`
167
+ - `getName()`
168
+ - `getDeviceType()`
169
+ - `getStatus()`
676
170
 
677
- **Example with Password:**
171
+ Commands vary by device class. Examples:
678
172
 
679
- ```typescript
680
- switchbot
681
- .discover({ model: 'H', quick: true })
682
- .then((device_list) => {
683
- const bot = device_list[0]
684
- // Set password for protected Bot
685
- bot.setPassword('MyP4')
686
- return bot.press()
687
- })
688
- .then(() => {
689
- console.log('Password-protected Bot pressed successfully')
690
- })
691
- .catch((error) => {
692
- console.error(error)
693
- })
694
- ```
173
+ - Bot: `press()`, `turnOn()`, `turnOff()`, `handUp()`, `handDown()`
174
+ - Curtain: `open()`, `close()`, `pause()`, `setPosition()`
175
+ - Plug: `turnOn()`, `turnOff()`, `toggle()`
695
176
 
696
- **Notes:**
177
+ ## Bot Password Protection
697
178
 
698
- - Password encryption uses CRC32 checksums for secure command transmission
699
- - All control methods (press, turnOn, turnOff, up, down) automatically use encrypted commands when password is set
700
- - Password is stored in memory only and must be set each time the application starts
701
- - If the wrong password is configured, BLE commands will fail silently (Bot will not respond)
179
+ Bot (`WoHand`) devices support password-protected BLE commands in v4.
702
180
 
703
- ### `WoCurtain` Object
181
+ ### What It Adds
704
182
 
705
- The `WoCurtain` object represents a Curtain, which is created through the discovery process triggered by the [`switchBotBLE.discover()`](#discover-method) method.
183
+ - Password validation for exactly 4 alphanumeric characters
184
+ - CRC32-based encrypted BLE command construction
185
+ - Automatic encrypted command execution when a password is configured
186
+ - Runtime helpers: `setPassword()`, `clearPassword()`, `hasPassword()`
706
187
 
707
- Actually, the `WoCurtain` is an object inherited from the [`SwitchbotDevice`](#SwitchbotDevice-object). You can use not only the method described in this section but also the properties and methods implemented in the [`SwitchbotDevice`](#SwitchbotDevice-object) object.
188
+ ### Supported Commands
708
189
 
709
- #### `open()` method
190
+ When a password is set, these BLE Bot commands use the encrypted flow:
710
191
 
711
- The `open()` method sends an open command to the Curtain. This method returns a `Promise` object. Nothing will be passed to the `resove()`.
192
+ - `press()`
193
+ - `turnOn()`
194
+ - `turnOff()`
195
+ - `handUp()`
196
+ - `handDown()`
712
197
 
713
- If no connection is established with the device, this method automatically establishes a connection with the device, then finally closes the connection. You don't have to call the [`connect()`](#SwitchbotDevice-connect-method) method in advance.
198
+ ### Example
714
199
 
715
- When the Curtain receives this command, the Curtain will open the curtain (0% position). If not calibrated, the Curtain does not move.
200
+ ```typescript
201
+ import { LogLevel, SwitchBot, WoHand } from 'node-switchbot'
716
202
 
717
- The `open()` method receives an optional `mode` parameter. (See [`runToPos()`](#runtopos-method))
718
-
719
- ```Typescript
720
- switchbot
721
- .discover({ model: "c", quick: true })
722
- .then((device_list) => {
723
- return device_list[0].open();
724
- })
725
- .then(() => {
726
- console.log("Done.");
203
+ const switchbot = new SwitchBot({
204
+ enableBLE: true,
205
+ enableFallback: false,
206
+ logLevel: LogLevel.INFO,
727
207
  })
728
- .catch((error) => {
729
- console.error(error);
730
- });
731
- ```
732
-
733
- #### `close()` method
734
208
 
735
- The `close()` method sends a close command to the Curtain. This method returns a `Promise` object. Nothing will be passed to the `resove()`.
209
+ await switchbot.discover({ scanBLE: true, fetchAPI: false })
736
210
 
737
- If no connection is established with the device, this method automatically establishes a connection with the device, then finally closes the connection. You don't have to call the [`connect()`](#SwitchbotDevice-connect-method) method in advance.
211
+ const bot = switchbot.devices.get('YOUR_DEVICE_ID') as WoHand | undefined
212
+ if (bot) {
213
+ bot.setPassword('A1b2')
738
214
 
739
- When the Curtain receives this command, the Curtain will close the curtain (100% position). If not calibrated, the Curtain does not move.
740
-
741
- The `close()` method receives an optional `mode` parameter. (See [`runToPos()`](#runtopos-method))
215
+ if (bot.hasPassword()) {
216
+ await bot.press()
217
+ }
742
218
 
743
- ```Typescript
744
- switchbot
745
- .discover({ model: "c", quick: true })
746
- .then((device_list) => {
747
- return device_list[0].close();
748
- })
749
- .then(() => {
750
- console.log("Done.");
751
- })
752
- .catch((error) => {
753
- console.error(error);
754
- });
755
- ```
219
+ bot.clearPassword()
220
+ }
756
221
 
757
- #### `pause()` method
222
+ await switchbot.cleanup()
223
+ ```
758
224
 
759
- The `pause()` method sends a pause command to the Curtain. This method returns a `Promise` object. Nothing will be passed to the `resove()`.
225
+ Notes:
760
226
 
761
- If no connection is established with the device, this method automatically establishes a connection with the device, then finally closes the connection. You don't have to call the [`connect()`](#SwitchbotDevice-connect-method) method in advance.
227
+ - Passwords are stored in memory only
228
+ - The password must be configured again when your application starts
229
+ - Password-protected Bot commands require BLE and do not use OpenAPI fallback for the encrypted write path
762
230
 
763
- When the Curtain receives this command, the Curtain will pause.
231
+ ## Reliability Features in BLE Workflows
764
232
 
765
- ```Typescript
766
- switchbot
767
- .discover({ model: "c", quick: true })
768
- .then((device_list) => {
769
- return device_list[0].pause();
770
- })
771
- .then(() => {
772
- console.log("Done.");
773
- })
774
- .catch((error) => {
775
- console.error(error);
776
- });
777
- ```
233
+ The v4 BLE path includes the resilience features introduced in the 4.0.0 release:
778
234
 
779
- #### `runToPos()` method
235
+ - Automatic retry with exponential backoff and jitter
236
+ - Circuit breaker state management to avoid repeated failing connections
237
+ - Connection intelligence that can prefer the more reliable path over time
238
+ - Fallback hooks for custom logging, metrics, or alerting
780
239
 
781
- The `runToPos()` method sends a position command to the Curtain. This method returns a `Promise` object. Nothing will be passed to the `resove()`.
240
+ These behaviors are primarily exposed through the unified `SwitchBot` and `SwitchBotDevice` flow rather than through manual low-level BLE orchestration.
782
241
 
783
- If no connection is established with the device, this method automatically establishes a connection with the device, then finally closes the connection. You don't have to call the [`connect()`](#SwitchbotDevice-connect-method) method in advance.
242
+ ## Low-Level BLE APIs
784
243
 
785
- When the Curtain receives this command, the Curtain will run to the percentage position. If not calibrated, the Curtain does not move.
244
+ If you need raw scanning or connection control, v4 exports `BLEScanner` and `BLEConnection` directly.
786
245
 
787
- The `open()` method sends an open command to the Curtain. This method returns a `Promise` object. Nothing will be passed to the `resove()`.
246
+ ### `BLEScanner`
788
247
 
789
- If no connection is established with the device, this method automatically establishes a connection with the device, then finally closes the connection. You don't have to call the [`connect()`](#SwitchbotDevice-connect-method) method in advance.
248
+ Use this for advertisement scanning and device discovery without going through `SwitchBot`.
790
249
 
791
- When the Curtain receives this command, the Curtain will open the curtain (0% position). If not calibrated, the Curtain does not move.
250
+ ```typescript
251
+ import { BLEScanner } from 'node-switchbot'
792
252
 
793
- | Property | Type | Required | Description |
794
- | :-------- | :------ | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------- |
795
- | `percent` | Integer | Required | The percentage of target position (`0-100`). (e.g., `50`) |
796
- | `mode` | Integer | Optional | The running mode of Curtain. <br/>`0x00` - Performance mode.<br/> `0x01` - Silent mode. <br/>`0xff` - Default. Unspecified, from Curtain's settings. |
253
+ const scanner = new BLEScanner()
797
254
 
798
- ```Typescript
799
- switchbot
800
- .discover({ model: "c", quick: true })
801
- .then((device_list) => {
802
- return device_list[0].runToPos(50);
803
- })
804
- .then(() => {
805
- console.log("Done.");
255
+ scanner.on('discover', (advertisement) => {
256
+ console.log(advertisement)
806
257
  })
807
- .catch((error) => {
808
- console.error(error);
809
- });
810
- ```
811
-
812
- ### `WoPlugMini` Object
813
-
814
- The `WoPlugMini ` object represents a PlugMini, which is created through the discovery process triggered by the [`switchBotBLE.discover()`](#discover-method) method.
815
-
816
- Actually, the `WoPlugMini ` is an object inherited from the [`SwitchbotDevice`](#SwitchbotDevice-object). You can use not only the method described in this section but also the properties and methods implemented in the [`SwitchbotDevice`](#SwitchbotDevice-object) object.
817
-
818
- #### `turnOn()` method
819
-
820
- The `turnOn()` method sends a turn-on command to the PlugMini. This method returns a `Promise` object. A `boolean` value indicating whether the PlugMini is on (`true`), is passed to the `resolve()` method of the Promise.
821
-
822
- If no connection is established with the device, this method automatically establishes a connection with the device, then finally closes the connection. You don't have to call the [`connect()`](#SwitchbotDevice-connect-method) method in advance.
823
-
824
- #### `turnOff()` method
825
-
826
- The `turnOff()` method sends a turn-off command to the PlugMini. This method returns a `Promise` object. A `boolean` value indicating whether the PlugMini is off (`false`), is passed to the `resolve()` method of the Promise.
827
-
828
- If no connection is established with the device, this method automatically establishes a connection with the device, then finally closes the connection. You don't have to call the [`connect()`](#SwitchbotDevice-connect-method) method in advance.
829
-
830
- #### `toggle()` method
831
-
832
- The `toggle()` method sends a toggle command to the PlugMini, toggling between the on and off state. This method returns a `Promise` object. A `boolean` value indicating whether the PlugMini is on (`true`) or off (`false`), is passed to the `resolve()` method of the Promise.
833
-
834
- If no connection is established with the device, this method automatically establishes a connection with the device, then finally closes the connection. You don't have to call the [`connect()`](#SwitchbotDevice-connect-method) method in advance.
835
-
836
- ### `WoSmartLock` Object
837
258
 
838
- The `WoSmartLock ` object represents a SmartLock, which is created through the discovery process triggered by the [`switchBotBLE.discover()`](#discover-method) method.
839
-
840
- Actually, the `WoSmartLock ` is an object inherited from the [`SwitchbotDevice`](#SwitchbotDevice-object). You can use not only the method described in this section but also the properties and methods implemented in the [`SwitchbotDevice`](#SwitchbotDevice-object) object.
841
-
842
- #### `setKey()` method
843
-
844
- The `setKey()` method initialises the key information required for encrypted communication with the SmartLock
845
-
846
- This must be set before any control commands are sent to the device. To obtain the key information you will need to use an external tool - see [`pySwitchbot`](https://github.com/Danielhiversen/pySwitchbot/tree/master?tab=readme-ov-file#obtaining-locks-encryption-key) project for an example script.
847
- Or, use [`switchbot-get-encryption-key`](https://www.npmjs.com/package/switchbot-get-encryption-key) npm script.
848
-
849
- | Property | Type | Description |
850
- | :-------------- | :----- | :----------------------------------------------------------------------------------------------- |
851
- | `keyId` | String | unique2 character ID for the key. (e.g., `"ff"`) returned from the SwitchBot api for your device |
852
- | `encryptionKey` | String | the unique encryption key returned from the SwitchBot api for your device |
853
-
854
- #### `lock()` method
855
-
856
- The `lock()` method sends a lock command to the SmartLock. This method returns a `Promise` object. A `boolean` value indicating whether the SmartLock is locked (`true`), is passed to the `resolve()` method of the Promise.
857
-
858
- If no connection is established with the device, this method automatically establishes a connection with the device, then finally closes the connection. You don't have to call the [`connect()`](#SwitchbotDevice-connect-method) method in advance.
859
-
860
- #### `unlock()` method
861
-
862
- The `unlock()` method sends an unlock command to the SmartLock. This method returns a `Promise` object. A `boolean` value indicating whether the SmartLock is locked (`false`), is passed to the `resolve()` method of the Promise.
259
+ await scanner.startScan({ duration: 10_000, active: true })
260
+ ```
863
261
 
864
- If no connection is established with the device, this method automatically establishes a connection with the device, then finally closes the connection. You don't have to call the [`connect()`](#SwitchbotDevice-connect-method) method in advance.
262
+ Public methods:
865
263
 
866
- #### `unlockNoUnlatch()` method
264
+ - `startScan(options?)`
265
+ - `stopScan()`
266
+ - `getDiscoveredDevices()`
267
+ - `getDevice(mac, bleId?)`
268
+ - `waitForDevice(mac, timeoutMs?, bleId?)`
269
+ - `destroy()`
867
270
 
868
- The `unlockNoUnlatch()` method sends a partial unlock command to the SmartLock, unlocking without the full unlatch.
271
+ Events:
869
272
 
870
- If no connection is established with the device, this method automatically establishes a connection with the device, then finally closes the connection. You don't have to call the [`connect()`](#SwitchbotDevice-connect-method) method in advance.
273
+ - `ready`
274
+ - `state-change`
275
+ - `scan-start`
276
+ - `scan-stop`
277
+ - `discover`
871
278
 
872
- #### `info()` method
279
+ ### `BLEConnection`
873
280
 
874
- The `info()` method retreieves state information from the SmartLock, This method returns a `Promise` object. An `object` value indicating with the state infor, is passed to the `resolve()` method of the Promise.
281
+ Use this for low-level connection, write, and notification handling.
875
282
 
876
- If no connection is established with the device, this method automatically establishes a connection with the device, then finally closes the connection. You don't have to call the [`connect()`](#SwitchbotDevice-connect-method) method in advance.
283
+ ```typescript
284
+ import { BLEConnection } from 'node-switchbot'
285
+ import { Buffer } from 'node:buffer'
877
286
 
878
- ### Advertisement Data
287
+ const connection = new BLEConnection()
879
288
 
880
- After the [`startScan()`](#startscan-method) method is invoked, the [`onadvertisement`](#Switchbot-onadvertisement-event-handler) event handler will be called whenever an advertising packet comes from the switchbot devices.
289
+ await connection.connect('AA:BB:CC:DD:EE:FF')
290
+ await connection.write('AA:BB:CC:DD:EE:FF', Buffer.from([0x57, 0x01, 0x00]))
291
+ const response = await connection.read('AA:BB:CC:DD:EE:FF')
881
292
 
882
- ```Typescript
883
- // Load the node-switchbot and get a `Switchbot` constructor object
884
- import { SwitchBotBLE } from 'node-switchbot';
885
- // Create a `Switchbot` object
886
- const switchBotBLE = new SwitchBotBLE();
293
+ console.log(response)
887
294
 
888
- (async () => {
889
- // Start to monitor advertisement packets
890
- await switchBotBLE.startScan();
891
- // Set an event handler
892
- switchBotBLE.onadvertisement = (ad) => {
893
- console.log(JSON.stringify(ad, null, ' '));
894
- };
895
- // Wait 10 seconds
896
- await switchBotBLE.wait(10000);
897
- // Stop to monitor
898
- switchBotBLE.stopScan();
899
- process.exit();
900
- })();
901
- ```
902
-
903
- An object containing the properties as follows will be passed to the event handler:
904
-
905
- | Property | Type | Description |
906
- | :------------ | :------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |
907
- | `id` | String | ID of the device. (e.g., `"cb4eb903c96d"`) |
908
- | `address` | String | MAC address of the device. Basically it is as same as the value of the `id` except that this value includes `:` in the string. (e.g., `"cb:4e:b9:03:c9:6d"`) |
909
- | `rssi` | Integer | RSSI. (e.g., `-62`) |
910
- | `serviceData` | Object | An object including the device-specific data. |
911
-
912
- The structures of the `serviceData` are described in the following sections.
295
+ await connection.disconnectAll()
296
+ ```
913
297
 
914
- #### Bot (WoHand)
298
+ Key public methods:
915
299
 
916
- Example of the advertisement data:
300
+ - `connect(mac)`
301
+ - `write(mac, data)`
302
+ - `read(mac)`
303
+ - `disconnectAll()`
304
+ - `setPersistentConnectionTimeout(timeoutMs)`
305
+ - `setEncryption(mac, keyHex, ivHex, mode?)`
306
+ - `clearEncryption(mac)`
917
307
 
918
- ```json
919
- {
920
- "id": "c12e453e2008",
921
- "address": "c1:2e:45:3e:20:08",
922
- "rssi": -61,
923
- "serviceData": {
924
- "model": "H",
925
- "modelName": "WoHand",
926
- "mode": true,
927
- "state": false,
928
- "battery": 100
929
- }
930
- }
931
- ```
308
+ ## BLE-Supported Device Families
932
309
 
933
- Structure of the `serviceData`:
310
+ v4 BLE support includes, among others:
934
311
 
935
- | Property | Type | Description |
936
- | :---------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------- |
937
- | `model` | String | This value is always `"H"`, which means "Bot (WoHand)". |
938
- | `modelName` | String | This value is always `"WoHand"`, which means "Bot". |
939
- | `mode` | Boolean | This indicates the mode setting. When the mode is "Switch mode", this value is `true`. When the mode is "Press mode", this value is `false`. |
940
- | `state` | Boolean | This value indicates whether the switch status is ON or OFF. |
941
- | `battery` | Integer | (**experimental**) This value indicates the battery level (`%`). |
312
+ - Bot
313
+ - Curtain and Roller Shade
314
+ - Blind Tilt
315
+ - Meter family
316
+ - Plug Mini family
317
+ - Lock family
318
+ - Humidifier family
319
+ - Bulb and light families
320
+ - Leak, contact, and presence sensors
321
+ - Relay switch family
942
322
 
943
- The `mode` can be changed only using the official smartphone app. The node-switchbot does not support changing the mode because the BLE protocol is non-public.
323
+ Exact per-device behavior still depends on what the physical device exposes over BLE.
944
324
 
945
- If the `mode` is `false`, which means the "Press mode" is selected, the `state` is always `false`. If the `mode` is `true`, which means the "Switch mode" is selected, the `state` represents the logical state (ON or OFF). Note that it does _not_ mean the physical arm position. The physical arm position depends on the setting "Inverse the on/off direction" on the official smartphone app.
325
+ ## Summary
946
326
 
947
- | "Inverse the on/off direction" | Value of the `state` | Logical state | Physical arm position |
948
- | :----------------------------- | :------------------- | :------------ | :-------------------- |
949
- | disabled | `true` | OFF | Up (retracted) |
950
- | &nbsp; | `false` | ON | Down (stretched) |
327
+ Use `SwitchBot` for almost all v4 BLE workflows. Reach for `BLEScanner` and `BLEConnection` only when you need direct advertisement scanning or manual low-level BLE control.
951
328
  | enabled | `true` | OFF | Down (stretched) |
952
329
  | &nbsp; | `false` | ON | Up (retracted) |
953
330