The node-switchbot is a Node.js module that allows you to interact with various SwitchBot devices. You can control your SwitchBot (Bot)'s arm, operate your SwitchBot Curtain, and manage your SwitchBot Lock. Additionally, you can monitor temperature and humidity using the SwitchBot Thermometer & Hygrometer (Meter), and check the status of the SwitchBot Motion Sensor and SwitchBot Contact Sensor.

This module now supports both Bluetooth Low Energy (BLE) and the SwitchBot OpenAPI, providing more flexibility and options for interacting with your devices.

Please note that most of this module was developed by referencing the official BLE API and OpenAPI documentation. However, some functionalities were developed through trial and error, so there might be inaccuracies in the information obtained from this module.

Installation

To install the node-switchbot module within your project, use the following command:

$ npm install --save node-switchbot

BLE (Bluetooth Low Energy)

To see a breakdown of how to use the BLE functionality of this project, visit the BLE (Bluetooth Low Energy) documentation.

OpenAPI

To see a breakdown of how to use the OpenAPI functionality of this project, visit the OpenAPI documentation.

References

• SwitchBot (Official website)
• Facebook @SwitchBotRobot
• Twitter @SwitchBot

Changelog

All notable changes to this project will be documented in this file. This project uses Semantic Versioning

3.5.0 (2025-03-04)

No New Releases During Lent

What's Changed

• Fix the return value of SwitchBotOpenAPI.getDeviceStatus() method #290, Thanks @kemuridama
• Fix circular dependencies
• Housekeeping and update dependencies

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v3.4.0...v3.5.0

3.4.9 (2025-01-24)

What's Changed

• Add BLE comands for Relay Switch 1 && Relay Switch 1 PM, not yet functional
• Housekeeping and update dependencies

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v3.4.8...v3.4.9

3.4.8 (2025-01-24)

What's Changed

• Add exports for Relay Switch 1 && Relay Switch 1 PM
• Housekeeping and update dependencies

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v3.4.7...v3.4.8

3.4.7 (2025-01-24)

What's Changed

• Add Types for Relay Switch 1 && Relay Switch 1 PM
• Housekeeping and update dependencies

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v3.4.6...v3.4.7

3.4.6 (2025-01-24)

What's Changed

• Housekeeping and update dependencies

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v3.4.5...v3.4.6

3.4.5 (2025-01-23)

What's Changed

• Housekeeping and update dependencies

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v3.4.4...v3.4.5

3.4.4 (2025-01-23)

What's Changed

• Housekeeping and update dependencies

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v3.4.3...v3.4.4

3.4.3 (2024-12-22)

What's Changed

• Fixed getDeviceStatus for openAPI
• Housekeeping and update dependencies

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v3.4.2...v3.4.3

3.4.2 (2024-12-21)

What's Changed

• Housekeeping and update dependencies

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v3.4.1...v3.4.2

3.4.1 (2024-11-27)

What's Changed

• Housekeeping and update dependencies

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v3.4.0...v3.4.1

3.4.0 (2024-11-18)

What's Changed

• Add RelaySwitch1PM and RealySwitch1PLus Devices
• Handle no devices found #272, Thanks @dnicolson
• Housekeeping and update dependencies

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v3.3.0...v3.4.0

3.3.0 (2024-11-02)

What's Changed

• Add Water Leak Decector Support
• Add initial support for the Keypad Touch
• Fix timeout error handling #268, Thanks @dnicolson
• Fix characteristic notification #267, Thanks @dnicolson
• Change scanning log level #266, Thanks @dnicolson
• Housekeeping and update dependencies

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v3.2.1...v3.3.0

3.2.1 (2024-10-21)

What's Changed

• Add more Meter Pro types
• Housekeeping and update dependencies

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v3.2.0...v3.2.1

3.2.0 (2024-10-21)

What's Changed

• Add basic support for Meter Pro
• Fix Noble import issue
• Housekeeping and update dependencies

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v3.1.1...v3.2.0

3.1.1 (2024-10-11)

What's Changed

• Fix K10Pro Type, Property 'K10Pro' does not exist on type 'typeof SwitchBotModel'.

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v3.1.0...v3.1.1

3.1.0 (2024-10-11)

What's Changed

• Added support for emitting logs from this module from the SwitchBotBLE class.
• Housekeeping and update dependencies

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v3.0.1...v3.1.0

3.0.1 (2024-10-05)

What's Changed

• Hot Fix for baseURL which is used for sending OpenAPI commands
• Housekeeping and update dependencies

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v3.0.0...v3.0.1

3.0.0 (2024-10-05)

What's Changed

⚠️ Breaking Changes

• Have added OpenAPI Functionality into node-switchbot, so now it is able to handle both APIs with just one module.
  • There are now two different Classes SwitchBotBLE and SwitchBotOpenAPI that can be used interact with the two different APIs
    • SwitchBotOpenApi support emitting logs from this module.
    • You will need to update your current setup fromSwitchBot to SwitchBotBLE to be able to interact with the BLE API
• Updated the documents to explain both the BLE and the OpenAPI Functionality within node-switchbot

Other Changes

• Housekeeping and update dependencies

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v2.4.0...v3.0.0

2.4.0 (2024-09-13)

What's Changed

• Added celsius and fahrenheit as based values sent for Sensors
• Housekeeping and update dependencies

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v2.3.0...v2.4.0

2.3.0 (2024-07-21)

What's Changed

• Added humidity value based of percentage for Humidifiers
• Updated SwitchBot Lock Pro manufacturerData
• Housekeeping and update dependencies

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v2.2.0...v2.3.0

2.2.0 (2024-06-25)

What's Changed

• Add Model Friendly Name for each deviceType
• Add SwitchBot Hub 2 Support
• Add basic support for SwitchBot Lock Pro
• Housekeeping and update dependencies

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v2.1.1...v2.2.0

2.1.1 (2024-05-26)

What's Changed

• Housekeeping and update dependencies

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v2.1.0...v2.1.1

2.1.0 (2024-05-14)

What's Changed

• Add SwitchBot Lock Support #232, Thanks @brozef
• Fix TypeScript issues & warnings #239 #240 #241, Thanks @dnicolson
• Update Noble #242, Thanks @dnicolson dnicolson
• Housekeeping and update dependencies

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v2.0.3...v2.1.0

2.0.3 (2024-02-11)

What's Changed

• Add some TypeScript types #228, Thanks @dnicolson
• Remove Buffer import #229, Thanks @dnicolson
• Housekeeping and update dependencies

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v2.0.2...v2.0.3

2.0.2 (2024-02-09)

What's Changed

• Fix various 2.0.0 issues #224, Thanks @dnicolson
• Code Cleanup #225 #226, Thanks @dnicolson
• Housekeeping and update dependencies

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v2.0.1...v2.0.2

2.0.1 (2024-02-06)

What's Changed

• Fix async constructor #220, Thanks @dnicolson
• Housekeeping and update dependencies

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v2.0.0...v2.0.1

2.0.0 (2024-02-05)

What's Changed

• Rewrite into Typescript and Convert CommonJS to ES Module
• Fix Linting #216, Thanks @dnicolson
• Code Cleaup #217, Thanks @dnicolson
• Housekeeping and update dependencies

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v1.10.0...v2.0.0

1.10.0 (2024-01-05)

What's Changed

• Fix reversed bot state reporting #207, Thanks @grelca
• Add support for Curtain 3 #209, Thanks @tsia
• Housekeeping and update dependencies

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v1.9.1...v1.10.0

1.9.1 (2023-11-02)

What's Changed

• Housekeeping and update dependencies

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v1.9.0...v1.9.1

1.9.0 (2023-09-16)

What's Changed

• Add support for the Indoor/Outdoor Thermo-Hygrometer (WoIOSensorTH) #200, Thanks @moritzmhmk
• Handle noble not being "poweredOn" on init #199, Thanks @moritzmhmk
• Housekeeping and update dependencies

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v1.8.2...v1.9.0

1.8.2 (2023-07-25)

What's Changed

• Added Lint Script #195, Thanks @dnicolson
• Fixed a Linting Issues #196, Thanks @dnicolson
• Fixed 'TypeError: Assignment to constant variable' #194, Thanks @banboobee
• Fix issue of re-assigning to constant for Temperature #191, Thanks @gravity-addiction
• Housekeeping and update dependencies

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v1.8.1...v1.8.2

1.8.1 (2023-04-08)

What's Changed

• Use const keyword for immutable variables #184, Thanks @dnicolson
• Use Error object for promise rejection #181, Thanks @dnicolson
• Housekeeping and update dependencies

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v1.8.0...v1.8.1

1.8.0 (2023-01-28)

What's Changed

• Add Support for BlindTilt (Read Only)
• Use Error object for promise rejection #181, Thanks @dnicolson
• Housekeeping and update dependencies

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v1.7.3...v1.8.0

1.7.3 (2023-01-05)

What's Changed

• Improve error handling #175, Thanks @dnicolson
• Housekeeping and update dependencies

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v1.7.2...v1.7.3

1.7.2 (2022-12-26)

What's Changed

• Fix for @abandonware/nobles breaking changes that cause: TypeError: this.noble.once is not a function.

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v1.7.1...v1.7.2

1.7.1 (2022-12-20)

What's Changed

• Fix for @abandonware/nobles breaking changes that cause: TypeError: this.noble.once is not a function.

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v1.7.0...v1.7.1

1.7.0 (2022-12-08)

What's Changed

• Add Read-only Support for Smart Lock.

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v1.6.1...v1.7.0

1.6.1 (2022-10-18)

What's Changed

• Fixed Issue where node-switchbot wouldn't be found.

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v1.6.0...v1.6.1

1.6.0 (2022-10-18)

What's Changed

• Added Support for Pushing Changes to Color Bulb & Strip Light
• Housekeeping and update dependencies

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v1.5.0...v1.6.0

1.5.0 (2022-10-07)

What's Changed

• Added Support for receiving status updates from Color Bulb & Strip Light
• Fixed issue that caused excessive logging.
• Housekeeping and update dependencies

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v1.4.1...v1.5.0

1.4.1 (2022-08-27)

What's Changed

• Fix Plug Mini (US) implementation
• Housekeeping and update dependencies

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v1.4.0...v1.4.1

1.4.0 (2022-08-19)

What's Changed

• Added support for Plug Mini (j) & (g)
• Housekeeping and update dependencies

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v1.3.0...v1.4.0

1.3.0 (2022-06-25)

What's Changed

• Added more Device Types, not all supported though.
• Housekeeping and update dependencies

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v1.2.0...v1.3.0

1.2.0 (2022-03-04)

What's Changed

• Added support for SwitchBot "Contact" and "Motion"
• Fix for Curtains on Firmware v3.3 and above
• Housekeeping and update dependencies

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v1.1.2...v1.2.0

1.1.2 (2021-11-13)

What's Changed

• Housekeeping and update dependencies

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v1.1.1...v1.1.2

1.1.1 (2021-11-02)

What's Changed

• Change back from @node/noble to @abandonware/noble

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v1.1.0...v1.1.1

1.1.0 (2021-10-26)

What's Changed

• Add Contact/Motion Sensor advertisement
• Add Humidifier advertisement
• Correct Model for advertisement

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v1.0.8...v1.1.0

1.0.8 (2021-09-30)

What's Changed

• fix extra trace of old noble from @abandonware/noble

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v1.0.7...v1.0.8

1.0.7 (2021-09-24)

What's Changed

• Change from @abandonware/noble to @homebridge/noble

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v1.0.6...v1.0.7

1.0.6 (2021-08-29)

What's Changed

• Fixes FATAL ERROR: ad_id is not defined

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v1.0.5...v1.0.6

1.0.5 (2021-08-04)

What's Changed

• Adding code for Contact and Motion Sensors
  • Not Ready to be used yet though

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v1.0.4...v1.0.5

1.0.4 (2021-08-03)

What's Changed

• Support for the discover method with id on macOS

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v1.0.3...v1.0.4

1.0.3 (2021-07-30)

What's Changed

• Fixed misspelling.

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v1.0.2...v1.0.3

1.0.2 (2021-07-29)

What's Changed

• Housekeeping and update dependencies

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v1.0.1...v1.0.2

1.0.1 (2021-07-29)

What's Changed

• Fixed issue where after switching Bluetooth off and on, would not work properly.

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v1.0.0...v1.0.1

1.0.0 (2021-01-21)

What's Changed

• • fix "No device was found" in MacOS

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v0.2.0...v1.0.0

0.2.0 (2020-11-05)

What's Changed

• Modify Curtain's action command to support group and running mode #7, Thanks @SwitchBot-Wonderlabs

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v0.1.0...v0.2.0

0.1.0 (2020-10-28)

What's Changed

• Added support for SwitchBot Curtain #6, Thanks @SwitchBot-Wonderlabs
• Added support for running on the Raspberry Pi Zero W #5, Thanks @Szizi4n5

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v0.0.5...v0.1.0

0.0.5 (2020-02-19)

What's Changed

• Improved the stability of discovering the BLE characteristics #3, Thanks @dnicolson

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v0.0.4...v0.0.5

0.0.4 (2020-02-11)

What's Changed

• Fixed the bug that temperature value lower than 0 degC could not be handled #2, Thanks @musimasami

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v0.0.3...v0.0.4

0.0.3 (2020-02-10)

What's Changed

• Now the characteristic UUID 0x2a00 (Device Name) is not mandatory. Some models of Bot don't seem to support the characteristic #3, Thanks @dnicolson
• Fixed the bug that the turnOn() method returns an error if the "Press mode" is selected on the Bot.

Full Changelog: https://github.com/OpenWonderLabs/node-switchbot/compare/v0.0.2...v0.0.3

0.0.2 (2019-11-20)

What's Changed

• First public release

0.0.1 (2019-11-20)

What's Changed

• Initial commit