switchbot-hub2-ble
TypeScript icon, indicating that this package has built-in type declarations

2.0.0 • Public • Published

SwitchBot Hub2 BLE Decoder (TypeScript)

Build npm

This module provides a complete and reusable BLE decoder for the SwitchBot Hub2 device. It scans for BLE advertisements using @abandonware/noble, extracts environment sensor readings from the manufacturerData field, and returns a well defined TypeScript object containing temperature, humidity, and light level.

✅ Features

  • Decodes temperature (°C and °F), humidity (%), and light level (0–31)
  • Extracts MAC address from BLE data
  • Fully self-contained BLE scanner (no BLE setup required by consuming apps)
  • Can be used as a standalone module or integrated into larger IoT projects

🚀 Installation

npm install switchbot-hub2-ble

🧪 Example Usage

import { SwitchBotHub2, SwitchBotHub2Data } from 'switchbot-hub2-ble';

SwitchBotHub2.on('data', (data) => {
  console.log('Sensor Data:', data);
});
SwitchBotHub2.startScanning();

🧬 BLE Manufacturer Data Format

The SwitchBot Hub2 broadcasts sensor information using Bluetooth LE manufacturer data with the following structure:

Manufacturer Data Layout

Offset Field Description
0–1 0x69 0x09 SwitchBot Manufacturer ID (LE format)
2–7 MAC Address Device MAC in raw bytes
14 Status byte Lower 5 bits contain light level (0–31)
15–17 Sensor data Encodes temperature (Celsius), humidity

Note: The decoding offsets match pySwitchbot's process_wohub2() function. We apply an offset shift of +2 to account for the stripped 0x6909 ID bytes.

🌡️ Temperature Decoding

The temperature is encoded in 2 bytes:

  • Sign is stored in the MSB of the second byte
  • Value = (second_byte & 0x7F) + ((first_byte & 0x0F) / 10)
  • Multiply by -1 if the sign bit is set

Conversion

  • Celsius: decoded as above
  • Fahrenheit: C * 9 / 5 + 32

💧 Humidity

Stored in the 3rd byte of the tempBytes triplet:

  • Mask with 0x7F to remove reserved bit

💡 Light Level

Extracted from the status byte (offset 14):

  • status & 0x1F

📦 Output Format

interface SwitchBotHub2Data {
  temperatureC: number;
  temperatureF: number;
  humidityPercent: number;
  lightLevel: number;
  macAddress?: string;
}

🧪 Unit Test Example

const sampleManufacturerData = Buffer.from('6909c9165c55517800ff67ee84b98a048eab00', 'hex');
const result = SwitchBotHub2.decode(sampleManufacturerData);

expect(result?.temperatureC).toBeCloseTo(17.8);
expect(result?.humidityPercent).toBe(44);
expect(result?.lightLevel).toBe(12);

🙏 Credits and Sources

This module was made possible thanks to open-source contributions and reverse engineering efforts from the following:

🔒 License

MIT

Package Sidebar

Install

npm i switchbot-hub2-ble

Weekly Downloads

2

Version

2.0.0

License

MIT

Unpacked Size

18.6 kB

Total Files

12

Last publish

Collaborators

  • edabe