Class APIError
Hierarchy (View Summary)
- SwitchBotError
- APIError
Index
Constructors
Properties
Constructors
constructor
Parameters
- message: string
OptionalstatusCode: numberOptionalstatusMessage: string
Returns APIError
Class APINotAvailableError
Error thrown when API is not available or credentials are missing
+Hierarchy (View Summary)
- SwitchBotError
- APINotAvailableError
Index
Constructors
Properties
Constructors
constructor
Parameters
- message: string = 'API not available or credentials not provided'
Returns APINotAvailableError
Class Advertising
Represents the advertising data parser for SwitchBot devices.
-Index
Constructors
Methods
Constructors
constructor
Returns Advertising
Methods
Staticparse
- parse(
peripheral: Peripheral,
emitLog: (level: string, message: string) => void,
): Promise<null | ad>Parses the advertisement data coming from SwitchBot device.
-This function processes advertising packets received from SwitchBot devices -and extracts relevant information based on the device type.
-Parameters
- peripheral: Peripheral
The peripheral device object from noble.
- - emitLog: (level: string, message: string) => void
The function to emit log messages.
-
Returns Promise<null | ad>
-
-
- An object containing parsed data specific to the SwitchBot device type, or
nullif the device is not recognized.
-
- peripheral: Peripheral
Staticparse
- parseServiceData(
model: string,
serviceData: Buffer,
manufacturerData: Buffer,
emitLog: (level: string, message: string) => void,
): Promise<any>Parses the service data based on the device model.
-Parameters
- model: string
The device model.
- - serviceData: Buffer
The service data buffer.
- - manufacturerData: Buffer
The manufacturer data buffer.
- - emitLog: (level: string, message: string) => void
The function to emit log messages.
-
Returns Promise<any>
-
-
- The parsed service data. -
- model: string
Class BLEConnection
BLE Connection for communicating with SwitchBot devices
+Index
Constructors
constructor
Parameters
- options: { logger?: Logger; logLevel?: number; noble?: any } = {}
Returns BLEConnection
Methods
clear
Parameters
- mac: string
Returns void
connect
Connect to a device
+Parameters
- mac: string
Returns Promise<void>
disconnect
Disconnect from a device
+Parameters
- mac: string
Returns Promise<void>
disconnect
Disconnect all devices
+Returns Promise<void>
get
Get connected device count
+Returns number
is
Check if connected to device
+Parameters
- mac: string
Returns boolean
mark
Mark the next disconnect for this MAC as expected
+Parameters
- mac: string
Returns void
read
Read data from device
+Parameters
- mac: string
Returns Promise<Buffer<ArrayBufferLike>>
send
- sendCommand(
mac: string,
data: Buffer,
options?: {
expectNotification?: boolean;
expectResponse?: boolean;
notificationTimeoutMs?: number;
responseTimeoutMs?: number;
validateResponse?: boolean;
},
): Promise<Buffer<ArrayBufferLike> | undefined>Parameters
- mac: string
- data: Buffer
- options: {
expectNotification?: boolean;
expectResponse?: boolean;
notificationTimeoutMs?: number;
responseTimeoutMs?: number;
validateResponse?: boolean;
} = {}
Returns Promise<Buffer<ArrayBufferLike> | undefined>
set
Parameters
- mac: string
- keyHex: string
- ivHex: string
- mode: "auto" | "ctr" | "gcm" = 'auto'
Returns void
set
Parameters
- timeoutMs: number
Returns void
subscribe
Parameters
- mac: string
- handler: (payload: Buffer) => void
Returns Promise<void>
unsubscribe
Parameters
- mac: string
- handler: (payload: Buffer) => void
Returns void
write
Write data to device
+Parameters
- mac: string
- data: Buffer
Returns Promise<void>
Class BLENotAvailableError
Error thrown when BLE is not available or supported
+Hierarchy (View Summary)
- SwitchBotError
- BLENotAvailableError
Index
Constructors
Properties
Constructors
constructor
Parameters
- message: string = 'BLE not available on this platform or device'
Returns BLENotAvailableError
Class BLEScanner
BLE Scanner for discovering SwitchBot devices
+Hierarchy
- EventEmitter
- BLEScanner
Index
Constructors
Methods
Constructors
constructor
Parameters
- options: { logLevel?: number; noble?: any } = {}
Returns BLEScanner
Methods
destroy
Cleanup all resources
+Returns void
get
Get discovered device by MAC or BLE ID
+Parameters
- mac: string
OptionalbleId: string
Returns BLEAdvertisement | undefined
get
Get all discovered devices
+Returns BLEAdvertisement[]
is
Check if currently scanning
+Returns boolean
start
stop
Stop scanning
+Returns void
wait
Wait for specific device
+Parameters
- mac: string
- timeoutMs: number = BLE_SCAN_TIMEOUT
OptionalbleId: string
Returns Promise<BLEAdvertisement>
Class CommandFailedError
Error thrown when a command fails
+Hierarchy (View Summary)
- SwitchBotError
- CommandFailedError
Index
Constructors
Properties
Constructors
constructor
- new CommandFailedError(
message: string,
connectionType?: "ble" | "api",
originalError?: Error,
): CommandFailedErrorParameters
- message: string
OptionalconnectionType: "ble" | "api"OptionaloriginalError: Error
Returns CommandFailedError
Class ConnectionTimeoutError
Error thrown when a connection timeout occurs
+Hierarchy (View Summary)
- SwitchBotError
- ConnectionTimeoutError
Index
Constructors
Properties
Constructors
constructor
Parameters
- message: string = 'Connection timeout'
OptionaltimeoutMs: number
Returns ConnectionTimeoutError
Class DeviceManager
Device Manager for managing multiple devices
+Hierarchy
- EventEmitter
- DeviceManager
Constructors
constructor
Parameters
OptionallogLevel: number
Returns DeviceManager
Methods
add
clear
Clear all devices
+Returns void
count
Get device count
+Returns number
get
get
get
get
Get all device IDs
+Returns string[]
has
Check if device exists
+Parameters
- deviceId: string
Returns boolean
list
Get all devices
+Returns SwitchBotDevice[]
remove
Remove a device from the manager
+Parameters
- deviceId: string
Returns boolean
to
Get devices as an object keyed by ID
+Returns Record<string, SwitchBotDevice>
Class DeviceNotFoundError
Error thrown when a device is not found
+Hierarchy (View Summary)
- SwitchBotError
- DeviceNotFoundError
Index
Constructors
Properties
Constructors
constructor
Parameters
- deviceId: string
Returns DeviceNotFoundError
Class DeviceOverrideStateDuringConnectionAbstract
Base class for devices that should ignore advertisement state while connected. +Prevents stale BLE advertisement data from overriding active connection state.
+Hierarchy (View Summary)
- SwitchBotDevice
- DeviceOverrideStateDuringConnection
Index
Constructors
Accessors
Methods
Constructors
constructor
- new DeviceOverrideStateDuringConnection(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): DeviceOverrideStateDuringConnectionParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns DeviceOverrideStateDuringConnection
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
Abstractget
Returns Promise<DeviceStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Class DiscoveryError
Error thrown when device discovery fails
+Hierarchy (View Summary)
- SwitchBotError
- DiscoveryError
Index
Constructors
Properties
Constructors
constructor
Parameters
- message: string
OptionaloriginalError: Error
Returns DiscoveryError
Class ErrorUtils
Enhanced error handling utilities.
-Index
Constructors
Methods
Constructors
constructor
Returns ErrorUtils
Methods
Staticcreate
Creates a command error with context.
-Parameters
- command: string
The command that failed
- - deviceId: string
The device ID
- Optionalcause: ErrorThe underlying cause
-
Returns Error
A descriptive command error
-- command: string
Staticcreate
Creates a connection error with context.
-Parameters
- deviceId: string
The device ID that failed to connect
- Optionalcause: ErrorThe underlying cause of the connection failure
-
Returns Error
A descriptive connection error
-- deviceId: string
Staticcreate
Creates a timeout error with context.
-Parameters
- operation: string
The operation that timed out
- - timeoutMs: number
The timeout duration in milliseconds
-
Returns Error
A descriptive timeout error
-- operation: string
Staticwith
Wraps an async operation with timeout and enhanced error handling.
-Type Parameters
- T
Parameters
- operation: Promise<T>
The async operation to wrap
- - timeoutMs: number
Timeout in milliseconds
- - operationName: string
Name of the operation for error messages
-
Returns Promise<T>
Promise that resolves with the operation result or rejects with timeout
-
Class OpenAPIClient
OpenAPI Client for SwitchBot API v1.1
+Index
Constructors
Methods
Constructors
constructor
- new OpenAPIClient(
token: string,
secret: string,
baseURL?: string,
logLevel?: number,
): OpenAPIClientParameters
- token: string
- secret: string
- baseURL: string = urls.base
OptionallogLevel: number
Returns OpenAPIClient
Methods
air
Parameters
- deviceId: string
- speed: number
Returns Promise<APICommandResponse>
air
- airPurifierSetMode(
deviceId: string,
mode: "auto" | "manual" | "sleep",
): Promise<APICommandResponse>Parameters
- deviceId: string
- mode: "auto" | "manual" | "sleep"
Returns Promise<APICommandResponse>
air
Parameters
- deviceId: string
Returns Promise<APICommandResponse>
air
blind
Parameters
- deviceId: string
Returns Promise<APICommandResponse>
blind
blind
Parameters
- deviceId: string
- position: number
Returns Promise<APICommandResponse>
bot
bot
Parameters
- deviceId: string
Returns Promise<APICommandResponse>
bot
Parameters
- deviceId: string
Returns Promise<APICommandResponse>
curtain
Parameters
- deviceId: string
- speed: number = 255
Returns Promise<APICommandResponse>
curtain
Curtain-specific commands
+Parameters
- deviceId: string
- speed: number = 255
Returns Promise<APICommandResponse>
curtain
Parameters
- deviceId: string
Returns Promise<APICommandResponse>
curtain
- curtainSetPosition(
deviceId: string,
position: number,
speed?: number,
): Promise<APICommandResponse>Parameters
- deviceId: string
- position: number
- speed: number = 255
Returns Promise<APICommandResponse>
delete
Delete webhook
+Parameters
- url: string
Returns Promise<void>
execute
Execute a scene
+Parameters
- sceneId: string
Returns Promise<void>
get
Get client configuration
+Returns { baseURL: string; token: string }
get
get
Get all devices
+Returns Promise<DeviceListResponse>
get
get
Get all scenes
+Returns Promise<SceneListResponse>
get
humidifier
Parameters
- deviceId: string
- mode: "auto" | "manual"
Returns Promise<APICommandResponse>
humidifier
Parameters
- deviceId: string
Returns Promise<APICommandResponse>
humidifier
is
Check if device has cloud service enabled
+Parameters
- deviceId: string
Returns Promise<boolean>
light
Parameters
- deviceId: string
- brightness: number
Returns Promise<APICommandResponse>
light
- lightSetColor(
deviceId: string,
red: number,
green: number,
blue: number,
): Promise<APICommandResponse>Parameters
- deviceId: string
- red: number
- green: number
- blue: number
Returns Promise<APICommandResponse>
light
Parameters
- deviceId: string
- temperature: number
Returns Promise<APICommandResponse>
light
Parameters
- deviceId: string
Returns Promise<APICommandResponse>
light
lock
lock
Parameters
- deviceId: string
Returns Promise<APICommandResponse>
plug
Parameters
- deviceId: string
Returns Promise<APICommandResponse>
plug
Parameters
- deviceId: string
Returns Promise<APICommandResponse>
plug
query
send
Send command to device
+Parameters
- deviceId: string
- command: string
Optionalparameter: any
Returns Promise<APICommandResponse>
set
Update base URL
+Parameters
- newBaseURL: string
Returns void
setup
update
Class ParameterChecker
Hierarchy
- EventEmitter
- ParameterChecker
Index
Constructors
constructor
Parameters
Optionaloptions: EventEmitterOptions
Returns ParameterChecker
Accessors
error
Gets the current error object.
-Returns null | ErrorObject
-
-
- The current error object or null if no error. -
Methods
check
- check(
obj: Record<string, unknown>,
rules: Record<string, Rule>,
required?: boolean,
): Promise<boolean>Checks if the specified object contains valid values based on the provided rules.
-Parameters
- obj: Record<string, unknown>
Object including parameters you want to check.
- - rules: Record<string, Rule>
Object including rules for the parameters.
- Optionalrequired: boolean = falseFlag whether the
-objis required or not.
Returns Promise<boolean>
-
-
- Resolves to true if the value is valid, false otherwise. -
- obj: Record<string, unknown>
is
Checks if the value is an array.
-Parameters
- value: unknown
The value to check.
- - rule: Rule
The rule object containing validation criteria.
- Optionalname: string = 'value'The parameter name.
-
Returns Promise<boolean>
-
-
- Resolves to true if the value is valid, false otherwise. -
- value: unknown
is
Checks if the value is a boolean.
-Parameters
- value: unknown
The value to check.
- - rule: Rule
The rule object containing validation criteria.
- Optionalname: string = 'value'The parameter name.
-
Returns Promise<boolean>
-
-
- Resolves to true if the value is valid, false otherwise. -
- value: unknown
is
Checks if the value is a float.
-Parameters
- value: unknown
The value to check.
- - rule: Rule
The rule object containing validation criteria.
- Optionalname: string = 'value'The parameter name.
-
Returns Promise<boolean>
-
-
- Resolves to true if the value is valid, false otherwise. -
- value: unknown
is
Checks if the value is an integer.
-Parameters
- value: unknown
The value to check.
- - rule: Rule
The rule object containing validation criteria.
- Optionalname: string = 'value'The parameter name.
-
Returns Promise<boolean>
-
-
- Resolves to true if the value is valid, false otherwise. -
- value: unknown
is
Checks if the value is an object.
-Parameters
- value: unknown
The value to check.
- - rule: Rule
The rule object containing validation criteria.
- Optionalname: string = 'value'The parameter name.
-
Returns Promise<boolean>
-
-
- Resolves to true if the value is valid, false otherwise. -
- value: unknown
is
Checks if the value is specified (not undefined).
-Parameters
- value: unknown
The value to check.
-
Returns boolean
-
-
- True if the value is specified, false otherwise. -
- value: unknown
is
Checks if the value is a string.
-Parameters
- value: unknown
The value to check.
- - rule: Rule
The rule object containing validation criteria.
- Optionalname: string = 'value'The parameter name.
-
Returns Promise<boolean>
-
-
- Resolves to true if the value is valid, false otherwise. -
- value: unknown
Class SequenceDeviceAbstract
Base class for devices that expose an advertisement sequence number. +Automatically triggers a status refresh when the sequence number changes.
+BLE-first, API-fallback Status Pattern
+Subclasses should implement their getStatus() using the centralized
+getStatusWithFallback() method from SwitchBotDevice for robust BLE-first,
+API-fallback logic. See SwitchBotDevice for details.
Example:
+async getStatus(): Promise<DeviceStatus> {
return this.getStatusWithFallback(
bleData => ({ ... }),
apiData => ({ ... })
)
}
+Hierarchy (View Summary)
Index
Constructors
Accessors
Methods
Constructors
constructor
- new SequenceDevice(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): SequenceDeviceParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns SequenceDevice
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
Abstractget
Returns Promise<DeviceStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Refresh status for this device. Called automatically after sequence changes.
+Returns Promise<DeviceStatus>
update
Update device information and react to sequence number changes.
+Parameters
- newInfo: Partial<DeviceInfo>
Returns void
Class SwitchBot
Main SwitchBot class - Hybrid BLE/API with automatic fallback
+Hierarchy
- EventEmitter
- SwitchBot
Index
Constructors
constructor
Parameters
- config: SwitchBotConfig = {}
Returns SwitchBot
Accessors
devices
Get device manager (for accessing devices)
+Returns DeviceManager
Methods
cleanup
Cleanup and disconnect
+Returns Promise<void>
discover
Discover devices (BLE + OpenAPI) +BLE discovery runs first, then API discovery to enable proper device matching
+Parameters
- options: DiscoveryOptions = {}
Returns Promise<SwitchBotDevice[]>
get
Get API client (if available)
+Returns OpenAPIClient | undefined
get
Get BLE scanner (if available)
+Returns BLEScanner | undefined
get
Get configuration
+Returns Required<SwitchBotConfig>
is
Check if API is available
+Returns boolean
is
Check if BLE is available
+Returns boolean
set
Class SwitchBotBLE
SwitchBotBLE class to interact with SwitchBot devices.
-Hierarchy
- EventEmitter
- SwitchBotBLE
Index
Constructors
Properties
Methods
Properties
noble
noble
Optionalonadvertisement
Optionalondiscover
Methods
discover
Discovers Switchbot devices with enhanced error handling and logging.
-Parameters
- params: Params = {}
The discovery parameters.
-
Returns Promise<SwitchbotDevice[]>
A Promise that resolves with an array of discovered Switchbot devices.
-- params: Params = {}
log
start
Starts scanning for SwitchBot devices.
-Parameters
Optionalparams: Params = {}Optional parameters.
-
Returns Promise<void>
-
-
- Resolves when scanning starts successfully. -
stop
Stops scanning for SwitchBot devices.
-Returns Promise<void>
-
-
- Resolves when scanning stops successfully. -
validate
Validates the parameters.
-Parameters
- params: Params
The parameters to validate.
- - schema: Record<string, unknown>
The schema to validate against.
-
Returns Promise<void>
-
-
- Resolves if parameters are valid, otherwise throws an error. -
- params: Params
wait
Waits for the specified time.
-Parameters
- msec: number
The time to wait in milliseconds.
-
Returns Promise<void>
-
-
- Resolves after the specified time. -
- msec: number
Class SwitchBotError
Base error class for SwitchBot errors
+Hierarchy (View Summary)
Index
Constructors
Properties
Constructors
constructor
Parameters
- message: string
Optionalcode: string
Returns SwitchBotError
Class SwitchBotOpenAPI
The SwitchBotOpenAPI class provides methods to interact with the SwitchBot OpenAPI.
-It allows you to retrieve device information, control devices, and manage webhooks.
Example
const switchBotAPI = new SwitchBotOpenAPI('your-token', 'your-secret');
// Get devices
switchBotAPI.getDevices().then(response => {
console.log(response);
}).catch(error => {
console.error(error);
});
// Control a device
switchBotAPI.controlDevice('device-id', 'turnOn', 'default').then(response => {
console.log(response);
}).catch(error => {
console.error(error);
});
// Setup webhook
switchBotAPI.setupWebhook('http://your-webhook-url').then(() => {
console.log('Webhook setup successfully');
}).catch(error => {
console.error(error);
});
-Hierarchy
- EventEmitter
- SwitchBotOpenAPI
Index
Constructors
Properties
Methods
Constructors
constructor
Creates an instance of the SwitchBot OpenAPI client.
-Parameters
- token: string
The API token used for authentication.
- - secret: string
The secret key used for signing requests.
- Optionalhostname: string
Returns SwitchBotOpenAPI
- token: string
Properties
Optionalwebhook
| null
| Server<typeof IncomingMessage, typeof ServerResponse> = null
Methods
control
- controlDevice(
deviceId: string,
command: string,
parameter: string,
commandType?: commandType,
token?: string,
secret?: string,
): Promise<{ response: pushResponseBody; statusCode: number }>Controls a device by sending a command to the SwitchBot API.
-Parameters
- deviceId: string
The ID of the device to control.
- - command: string
The command to send to the device.
- - parameter: string
The parameter for the command.
- - commandType: commandType = 'command'
The type of the command (default is 'command').
- Optionaltoken: string(Optional) The token used for authentication. If not provided, the instance token will be used.
-Optionalsecret: string(Optional) The secret used for authentication. If not provided, the instance secret will be used.
-
Returns Promise<{ response: pushResponseBody; statusCode: number }>
A promise that resolves to an object containing the response body and status code.
- - deviceId: string
delete
Deletes a webhook by sending a request to the specified URL.
-Parameters
- url: string
The URL of the webhook to be deleted.
- Optionaltoken: string(Optional) The token used for authentication. If not provided, the instance token will be used.
-Optionalsecret: string(Optional) The secret used for authentication. If not provided, the instance secret will be used.
-
Returns Promise<void>
A promise that resolves when the webhook is successfully deleted.
-- url: string
get
Retrieves the list of devices from the SwitchBot OpenAPI.
-Parameters
Optionaltoken: string(Optional) The token used for authentication. If not provided, the instance token will be used.
-Optionalsecret: string(Optional) The secret used for authentication. If not provided, the instance secret will be used.
-
Returns Promise<{ response: devices; statusCode: number }>
A promise that resolves to an object containing the API response.
-
get
- getDeviceStatus(
deviceId: string,
token?: string,
secret?: string,
): Promise<{ response: deviceStatus; statusCode: number }>Retrieves the status of a specific device.
-Parameters
- deviceId: string
The unique identifier of the device.
- Optionaltoken: string(Optional) The token used for authentication. If not provided, the instance token will be used.
-Optionalsecret: string(Optional) The secret used for authentication. If not provided, the instance secret will be used.
-
Returns Promise<{ response: deviceStatus; statusCode: number }>
A promise that resolves to an object containing the device status and the status code of the request.
- - deviceId: string
setup
Sets up a webhook listener and configures the webhook on the server.
-This method performs the following steps:
--
-
- Creates a local server to listen for incoming webhook events. -
- Sends a request to set up the webhook with the provided URL. -
- Sends a request to update the webhook configuration. -
- Sends a request to query the current webhook URL. -
Parameters
- url: string
The URL to which the webhook events will be sent.
- Optionaltoken: string(Optional) The token used for authentication. If not provided, the instance token will be used.
-Optionalsecret: string(Optional) The secret used for authentication. If not provided, the instance secret will be used.
-
Returns Promise<void>
A promise that resolves when the webhook setup is complete.
-
Class SwitchbotDevice
Represents a Switchbot Device.
-Hierarchy (View Summary)
- EventEmitter
- SwitchbotDevice
Index
Constructors
Accessors
Class SwitchBotDeviceAbstract
Base class for all SwitchBot devices
+BLE-first, API-fallback Logic
+This class provides a centralized, robust hybrid connection strategy for all SwitchBot devices:
+-
+
- BLE-first, API-fallback: By default, status and command methods attempt BLE first (if available), then fall back to OpenAPI if BLE fails or is unavailable. This is controlled by
preferredConnectionandenableFallback.
+ - Centralized Fallback: The
getStatusWithFallback()andsendCommand()methods implement this logic. Device subclasses should call these methods and provide normalization/mapping as needed.
+ - Connection Intelligence: Tracks connection health and performance, automatically preferring the most reliable connection if enabled. +
- Circuit Breaker & Retry: Both BLE and API commands are protected by circuit breaker and retry logic to handle transient failures gracefully. +
Usage in Subclasses
+-
+
- For status: Call
await this.getStatusWithFallback(normalizeBLE, normalizeAPI)in yourgetStatus()implementation.
+ - For commands: Use
await this.sendCommand(bleCommand, apiCommand, apiParameter)to automatically select the best connection and handle fallback.
+ - For custom logic: You may override or extend these methods, but should preserve the fallback and error-handling patterns for consistency. +
Example (in a device subclass)
+async getStatus(): Promise<DeviceStatus> {
return this.getStatusWithFallback(
bleData => ({ ... }), // normalize BLE data
apiData => ({ ... }), // normalize API data
)
}
async turnOn(): Promise<boolean> {
const result = await this.sendCommand([0x57, 0x01, 0x01], 'turnOn')
return result.success
}
+Configuration
+-
+
preferredConnection: 'ble' | 'api' (default: 'ble')
+enableFallback: boolean (default: true)
+enableConnectionIntelligence: boolean (default: true)
+enableCircuitBreaker: boolean (default: true)
+enableRetry: boolean (default: true)
+
See Also
+-
+
getStatusWithFallback()
+sendCommand()
+hasBLE(),hasAPI()
+setPreferredConnection(),setFallbackEnabled()
+
This pattern ensures all device classes benefit from robust, testable, and consistent connection logic.
+Hierarchy (View Summary)
Index
Constructors
Accessors
Methods
Constructors
constructor
Initializes a new instance of the SwitchbotDevice class.
-Parameters
- peripheral: Peripheral
The peripheral object from noble.
- - noble: Noble
The Noble object.
-
Returns SwitchbotDevice
- peripheral: Peripheral
Accessors
address
- get address(): string
Returns string
connection
- get connectionState(): string
Returns string
friendly
Returns SwitchBotBLEModelFriendlyName
id
- get id(): string
Returns string
model
Returns SwitchBotBLEModel
model
Returns SwitchBotBLEModelName
on
- get onConnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onConnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
on
- get onDisconnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onDisconnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
Methods
command
Sends a command to the device and awaits a response.
-Parameters
- reqBuf: Buffer
The command buffer.
-
Returns Promise<Buffer<ArrayBufferLike>>
A Promise that resolves with the response buffer.
-- reqBuf: Buffer
connect
Connects to the device.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
disconnect
Disconnects from the device.
-Returns Promise<void>
A Promise that resolves when the disconnection is complete.
-
discover
Discovers the device services.
-Returns Promise<Service[]>
A Promise that resolves with the list of services.
-
get
Retrieves the device characteristics.
-Returns Promise<Chars>
A Promise that resolves with the device characteristics.
-
get
Retrieves the device name.
-Returns Promise<string>
A Promise that resolves with the device name.
-
internal
Internal method to handle the connection process.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
log
Logs a message with the specified log level.
-Parameters
- level: string
The severity level of the log (e.g., 'info', 'warn', 'error').
- - message: string
The log message to be emitted.
-
Returns Promise<void>
- level: string
set
Sets the device name.
-Parameters
- name: string
The new device name.
-
Returns Promise<void>
A Promise that resolves when the name is set.
-- name: string
unsubscribe
Unsubscribes from the notify characteristic.
-Returns Promise<void>
A Promise that resolves when the unsubscription is complete.
-
Methods
Constructors
constructor
- new SwitchBotDevice(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): SwitchBotDeviceParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns SwitchBotDevice
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
Abstractget
Returns Promise<DeviceStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Class ValidationError
Error thrown when invalid parameters are provided
+Hierarchy (View Summary)
- SwitchBotError
- ValidationError
Index
Constructors
Properties
Constructors
constructor
Parameters
- message: string
Optionalparameter: string
Returns ValidationError
Class ValidationUtils
Utility class for comprehensive input validation with improved error messages.
-Index
Constructors
Methods
Constructors
constructor
Returns ValidationUtils
Methods
Staticvalidate
- validateBuffer(
buffer: any,
expectedLength?: number,
paramName?: string,
): asserts buffer is Buffer<ArrayBufferLike>Validates buffer and throws descriptive error.
-Parameters
- buffer: any
The buffer to validate
- OptionalexpectedLength: numberOptional expected length
-- paramName: string = 'buffer'
The parameter name for error reporting
-
Returns asserts buffer is Buffer<ArrayBufferLike>
- buffer: any
Staticvalidate
Staticvalidate
Staticvalidate
Staticvalidate
- validateRange(
value: number,
min: number,
max: number,
paramName?: string,
mustBeInteger?: boolean,
): voidValidates numeric range with enhanced checks.
-Parameters
- value: number
The value to validate
- - min: number
Minimum allowed value
- - max: number
Maximum allowed value
- - paramName: string = 'value'
The parameter name for error reporting
- - mustBeInteger: boolean = false
Whether the value must be an integer
-
Returns void
- value: number
Staticvalidate
Staticvalidate
- validateString(
value: any,
paramName?: string,
minLength?: number,
maxLength?: number,
): asserts value is stringValidates string input with comprehensive checks.
-Parameters
- value: any
The value to validate
- - paramName: string = 'value'
The parameter name for error reporting
- - minLength: number = 1
Minimum required length
- OptionalmaxLength: numberOptional maximum length
-
Returns asserts value is string
- value: any
Class WoAIHub
Base class for all SwitchBot devices
+BLE-first, API-fallback Logic
+This class provides a centralized, robust hybrid connection strategy for all SwitchBot devices:
+-
+
- BLE-first, API-fallback: By default, status and command methods attempt BLE first (if available), then fall back to OpenAPI if BLE fails or is unavailable. This is controlled by
preferredConnectionandenableFallback.
+ - Centralized Fallback: The
getStatusWithFallback()andsendCommand()methods implement this logic. Device subclasses should call these methods and provide normalization/mapping as needed.
+ - Connection Intelligence: Tracks connection health and performance, automatically preferring the most reliable connection if enabled. +
- Circuit Breaker & Retry: Both BLE and API commands are protected by circuit breaker and retry logic to handle transient failures gracefully. +
Usage in Subclasses
+-
+
- For status: Call
await this.getStatusWithFallback(normalizeBLE, normalizeAPI)in yourgetStatus()implementation.
+ - For commands: Use
await this.sendCommand(bleCommand, apiCommand, apiParameter)to automatically select the best connection and handle fallback.
+ - For custom logic: You may override or extend these methods, but should preserve the fallback and error-handling patterns for consistency. +
Example (in a device subclass)
+async getStatus(): Promise<DeviceStatus> {
return this.getStatusWithFallback(
bleData => ({ ... }), // normalize BLE data
apiData => ({ ... }), // normalize API data
)
}
async turnOn(): Promise<boolean> {
const result = await this.sendCommand([0x57, 0x01, 0x01], 'turnOn')
return result.success
}
+Configuration
+-
+
preferredConnection: 'ble' | 'api' (default: 'ble')
+enableFallback: boolean (default: true)
+enableConnectionIntelligence: boolean (default: true)
+enableCircuitBreaker: boolean (default: true)
+enableRetry: boolean (default: true)
+
See Also
+-
+
getStatusWithFallback()
+sendCommand()
+hasBLE(),hasAPI()
+setPreferredConnection(),setFallbackEnabled()
+
This pattern ensures all device classes benefit from robust, testable, and consistent connection logic.
+Hierarchy (View Summary)
- SwitchBotDevice
- WoAIHub
Index
Constructors
Accessors
Methods
Constructors
constructor
- new WoAIHub(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoAIHubParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoAIHub
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get device status (BLE-first, API-fallback)
+Returns Promise<HubStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Class WoAirPurifier
Class representing a SwitchBot Air Purifier device.
-Hierarchy (View Summary)
- SwitchbotDevice
- WoAirPurifier
Index
Constructors
Accessors
Class WoAirPurifier
Air Purifier Device
+Hierarchy (View Summary)
Implements
Index
Constructors
Accessors
Methods
Methods
Constructors
constructor
Initializes a new instance of the SwitchbotDevice class.
-Parameters
- peripheral: Peripheral
The peripheral object from noble.
- - noble: Noble
The Noble object.
-
Returns WoAirPurifier
- peripheral: Peripheral
Accessors
address
- get address(): string
Returns string
connection
- get connectionState(): string
Returns string
friendly
Returns SwitchBotBLEModelFriendlyName
id
- get id(): string
Returns string
model
Returns SwitchBotBLEModel
model
Returns SwitchBotBLEModelName
on
- get onConnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onConnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
on
- get onDisconnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onDisconnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
Methods
command
Sends a command to the device and awaits a response.
-Parameters
- reqBuf: Buffer
The command buffer.
-
Returns Promise<Buffer<ArrayBufferLike>>
A Promise that resolves with the response buffer.
-- reqBuf: Buffer
connect
Connects to the device.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
disconnect
Disconnects from the device.
-Returns Promise<void>
A Promise that resolves when the disconnection is complete.
-
discover
Discovers the device services.
-Returns Promise<Service[]>
A Promise that resolves with the list of services.
-
get
Retrieves the device characteristics.
-Returns Promise<Chars>
A Promise that resolves with the device characteristics.
-
get
Retrieves the device name.
-Returns Promise<string>
A Promise that resolves with the device name.
-
internal
Internal method to handle the connection process.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
log
Logs a message with the specified log level.
-Parameters
- level: string
The severity level of the log (e.g., 'info', 'warn', 'error').
- - message: string
The log message to be emitted.
-
Returns Promise<void>
- level: string
operate
Operates the air purifier with the given byte array.
-Parameters
- bytes: number[]
The byte array to send.
-
Returns Promise<boolean>
-
-
- Resolves with true if the operation was successful. -
- bytes: number[]
set
Sets the device name.
-Parameters
- name: string
The new device name.
-
Returns Promise<void>
A Promise that resolves when the name is set.
-- name: string
set
Sets the mode of the air purifier.
-Parameters
- mode: number
The mode value (1-4).
-
Returns Promise<boolean>
-
-
- Resolves with true if the operation was successful. -
- mode: number
set
Sets the speed of the air purifier.
-Parameters
- speed: number
The speed value (0-100).
-
Returns Promise<boolean>
-
-
- Resolves with true if the operation was successful. -
- speed: number
turn
Turns the air purifier off.
-Returns Promise<boolean>
-
-
- Resolves with true if the air purifier is turned off. -
turn
Turns the air purifier on.
-Returns Promise<boolean>
-
-
- Resolves with true if the air purifier is turned on. -
unsubscribe
Unsubscribes from the notify characteristic.
-Returns Promise<void>
A Promise that resolves when the unsubscription is complete.
-
Staticparse
- parseServiceData(
serviceData: null | Buffer<ArrayBufferLike>,
manufacturerData: null | Buffer<ArrayBufferLike>,
emitLog?: (level: string, message: string) => void,
): null | airPurifierServiceDataParses service data for air purifier devices.
-Parameters
- serviceData: null | Buffer<ArrayBufferLike>
The service data buffer.
- - manufacturerData: null | Buffer<ArrayBufferLike>
The manufacturer data buffer.
- OptionalemitLog: (level: string, message: string) => voidThe function to emit log messages.
-
Returns null | airPurifierServiceData
-
-
- The parsed service data or null. -
- serviceData: null | Buffer<ArrayBufferLike>
Constructors
constructor
- new WoAirPurifier(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoAirPurifierParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoAirPurifier
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get device status (BLE-first, API-fallback)
+Returns Promise<AirPurifierStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Set fan speed (1-4)
+Parameters
- speed: number
Returns Promise<boolean>
set
set
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
turn
Turn off
+Returns Promise<boolean>
turn
Turn on
+Returns Promise<boolean>
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Refresh status for this device. Called automatically after sequence changes.
+Returns Promise<DeviceStatus>
update
Update device information and react to sequence number changes.
+Parameters
- newInfo: Partial<DeviceInfo>
Returns void
verify
Verifies the BLE encryption key by attempting a status read with encryption. +Throws an error if the key is invalid or the device rejects the command.
+Returns Promise<boolean>
Class WoAirPurifierPM25
Base class for all SwitchBot devices
+BLE-first, API-fallback Logic
+This class provides a centralized, robust hybrid connection strategy for all SwitchBot devices:
+-
+
- BLE-first, API-fallback: By default, status and command methods attempt BLE first (if available), then fall back to OpenAPI if BLE fails or is unavailable. This is controlled by
preferredConnectionandenableFallback.
+ - Centralized Fallback: The
getStatusWithFallback()andsendCommand()methods implement this logic. Device subclasses should call these methods and provide normalization/mapping as needed.
+ - Connection Intelligence: Tracks connection health and performance, automatically preferring the most reliable connection if enabled. +
- Circuit Breaker & Retry: Both BLE and API commands are protected by circuit breaker and retry logic to handle transient failures gracefully. +
Usage in Subclasses
+-
+
- For status: Call
await this.getStatusWithFallback(normalizeBLE, normalizeAPI)in yourgetStatus()implementation.
+ - For commands: Use
await this.sendCommand(bleCommand, apiCommand, apiParameter)to automatically select the best connection and handle fallback.
+ - For custom logic: You may override or extend these methods, but should preserve the fallback and error-handling patterns for consistency. +
Example (in a device subclass)
+async getStatus(): Promise<DeviceStatus> {
return this.getStatusWithFallback(
bleData => ({ ... }), // normalize BLE data
apiData => ({ ... }), // normalize API data
)
}
async turnOn(): Promise<boolean> {
const result = await this.sendCommand([0x57, 0x01, 0x01], 'turnOn')
return result.success
}
+Configuration
+-
+
preferredConnection: 'ble' | 'api' (default: 'ble')
+enableFallback: boolean (default: true)
+enableConnectionIntelligence: boolean (default: true)
+enableCircuitBreaker: boolean (default: true)
+enableRetry: boolean (default: true)
+
See Also
+-
+
getStatusWithFallback()
+sendCommand()
+hasBLE(),hasAPI()
+setPreferredConnection(),setFallbackEnabled()
+
This pattern ensures all device classes benefit from robust, testable, and consistent connection logic.
+Hierarchy (View Summary)
- SwitchBotDevice
- WoAirPurifierPM25
Index
Constructors
Accessors
Methods
Constructors
constructor
- new WoAirPurifierPM25(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoAirPurifierPM25Parameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoAirPurifierPM25
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get device status (BLE-first, API-fallback)
+Returns Promise<AirPurifierStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Set fan speed (1-4)
+Parameters
- speed: number
Returns Promise<boolean>
set
Set mode (auto/manual/sleep)
+Parameters
- mode: "auto" | "manual" | "sleep"
Returns Promise<CommandResult>
set
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
turn
Turn off
+Returns Promise<boolean>
turn
Turn on
+Returns Promise<boolean>
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Class WoAirPurifierTable
Class representing a SwitchBot Air Purifier Table device.
-Hierarchy (View Summary)
- SwitchbotDevice
- WoAirPurifierTable
Index
Constructors
Accessors
Class WoAirPurifierTable
Air Purifier Table Device +Uses same logic as standard Air Purifier
+Hierarchy (View Summary)
- WoAirPurifier
- WoAirPurifierTable
Index
Constructors
Accessors
Methods
Constructors
constructor
Initializes a new instance of the SwitchbotDevice class.
-Parameters
- peripheral: Peripheral
The peripheral object from noble.
- - noble: Noble
The Noble object.
-
Returns WoAirPurifierTable
- peripheral: Peripheral
Accessors
address
- get address(): string
Returns string
connection
- get connectionState(): string
Returns string
friendly
Returns SwitchBotBLEModelFriendlyName
id
- get id(): string
Returns string
model
Returns SwitchBotBLEModel
model
Returns SwitchBotBLEModelName
on
- get onConnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onConnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
on
- get onDisconnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onDisconnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
Methods
command
Sends a command to the device and awaits a response.
-Parameters
- reqBuf: Buffer
The command buffer.
-
Returns Promise<Buffer<ArrayBufferLike>>
A Promise that resolves with the response buffer.
-- reqBuf: Buffer
connect
Connects to the device.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
disconnect
Disconnects from the device.
-Returns Promise<void>
A Promise that resolves when the disconnection is complete.
-
discover
Discovers the device services.
-Returns Promise<Service[]>
A Promise that resolves with the list of services.
-
get
Retrieves the device characteristics.
-Returns Promise<Chars>
A Promise that resolves with the device characteristics.
-
get
Retrieves the device name.
-Returns Promise<string>
A Promise that resolves with the device name.
-
internal
Internal method to handle the connection process.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
log
Logs a message with the specified log level.
-Parameters
- level: string
The severity level of the log (e.g., 'info', 'warn', 'error').
- - message: string
The log message to be emitted.
-
Returns Promise<void>
- level: string
operate
Operates the air purifier table with the given byte array.
-Parameters
- bytes: number[]
The byte array to send.
-
Returns Promise<boolean>
-
-
- Resolves with true if the operation was successful. -
- bytes: number[]
set
Sets the device name.
-Parameters
- name: string
The new device name.
-
Returns Promise<void>
A Promise that resolves when the name is set.
-- name: string
set
Sets the mode of the air purifier table.
-Parameters
- mode: number
The mode value (1-4).
-
Returns Promise<boolean>
-
-
- Resolves with true if the operation was successful. -
- mode: number
set
Sets the speed of the air purifier table.
-Parameters
- speed: number
The speed value (0-100).
-
Returns Promise<boolean>
-
-
- Resolves with true if the operation was successful. -
- speed: number
turn
Turns the air purifier table off.
-Returns Promise<boolean>
-
-
- Resolves with true if the air purifier table is turned off. -
turn
Turns the air purifier table on.
-Returns Promise<boolean>
-
-
- Resolves with true if the air purifier table is turned on. -
unsubscribe
Unsubscribes from the notify characteristic.
-Returns Promise<void>
A Promise that resolves when the unsubscription is complete.
-
Staticparse
- parseServiceData(
serviceData: null | Buffer<ArrayBufferLike>,
manufacturerData: null | Buffer<ArrayBufferLike>,
emitLog?: (level: string, message: string) => void,
): null | airPurifierTableServiceDataParses service data for air purifier table devices.
-Parameters
- serviceData: null | Buffer<ArrayBufferLike>
The service data buffer.
- - manufacturerData: null | Buffer<ArrayBufferLike>
The manufacturer data buffer.
- OptionalemitLog: (level: string, message: string) => voidThe function to emit log messages.
-
Returns null | airPurifierTableServiceData
-
-
- The parsed service data or null. -
- serviceData: null | Buffer<ArrayBufferLike>
Methods
Constructors
constructor
- new WoAirPurifierTable(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoAirPurifierTableParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoAirPurifierTable
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get device status (BLE-first, API-fallback)
+Returns Promise<AirPurifierStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Set fan speed (1-4)
+Parameters
- speed: number
Returns Promise<boolean>
set
set
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
turn
Turn off
+Returns Promise<boolean>
turn
Turn on
+Returns Promise<boolean>
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Refresh status for this device. Called automatically after sequence changes.
+Returns Promise<DeviceStatus>
update
Update device information and react to sequence number changes.
+Parameters
- newInfo: Partial<DeviceInfo>
Returns void
verify
Verifies the BLE encryption key by attempting a status read with encryption. +Throws an error if the key is invalid or the device rejects the command.
+Returns Promise<boolean>
Class WoArtFrame
Art Frame Device +Uses same logic as Color Bulb
+Hierarchy (View Summary)
- WoBulb
- WoArtFrame
Index
Constructors
Properties
Accessors
Methods
Constructors
constructor
- new WoArtFrame(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoArtFrameParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoArtFrame
Properties
StaticEFFECTS
Preset effect name to effect ID mapping
+Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get device status (BLE-first/API-fallback, centralized)
+Returns Promise<BulbStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Strip Light 3 and complex light patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex light patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Set brightness (0-100)
+Parameters
- brightness: number
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Set RGB color
+Parameters
- red: number
- green: number
- blue: number
Returns Promise<boolean>
set
Set color temperature with min/max bounds +For advanced bulbs that support color temperature range control
+Parameters
- minTemp: number
- maxTemp: number
- temp: number
Returns Promise<boolean>
set
Set color temperature (2700-6500K)
+Parameters
- temperature: number
Returns Promise<boolean>
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Set preset light effect
+Parameters
- effectName: string
- speed: number = 100
Returns Promise<boolean>
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
turn
Turn off
+Returns Promise<boolean>
turn
Turn on
+Returns Promise<boolean>
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
verify
Verifies the BLE encryption key by attempting a status read with encryption. +Throws an error if the key is invalid or the device rejects the command.
+Returns Promise<boolean>
Class WoBlindTilt
Class representing a WoBlindTilt device.
-Hierarchy (View Summary)
- SwitchbotDevice
- WoBlindTilt
Index
Constructors
Accessors
Class WoBlindTilt
Blind Tilt Device
+Hierarchy (View Summary)
- SwitchBotDevice
- WoBlindTilt
Implements
Index
Constructors
Accessors
Methods
Constructors
constructor
Parameters
- peripheral: Peripheral
- noble: Noble
Returns WoBlindTilt
Accessors
address
- get address(): string
Returns string
connection
- get connectionState(): string
Returns string
friendly
Returns SwitchBotBLEModelFriendlyName
id
- get id(): string
Returns string
model
Returns SwitchBotBLEModel
model
Returns SwitchBotBLEModelName
on
- get onConnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onConnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
on
- get onDisconnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onDisconnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
Methods
close
Closes the blind tilt to the nearest endpoint.
-Returns Promise<void>
close
Closes the blind tilt down to the nearest endpoint.
-Returns Promise<void>
close
Closes the blind tilt up to the nearest endpoint.
-Returns Promise<void>
command
Sends a command to the device and awaits a response.
-Parameters
- reqBuf: Buffer
The command buffer.
-
Returns Promise<Buffer<ArrayBufferLike>>
A Promise that resolves with the response buffer.
-- reqBuf: Buffer
connect
Connects to the device.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
disconnect
Disconnects from the device.
-Returns Promise<void>
A Promise that resolves when the disconnection is complete.
-
discover
Discovers the device services.
-Returns Promise<Service[]>
A Promise that resolves with the list of services.
-
get
Retrieves the basic information of the blind tilt.
-Returns Promise<null | object>
-
-
- A promise that resolves to an object containing the basic information of the blind tilt. -
get
Retrieves the device characteristics.
-Returns Promise<Chars>
A Promise that resolves with the device characteristics.
-
get
Retrieves the device name.
-Returns Promise<string>
A Promise that resolves with the device name.
-
get
Retrieves the current position of the blind tilt.
-Returns Promise<number>
-
-
- The current position of the blind tilt (0-100). -
internal
Internal method to handle the connection process.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
log
Logs a message with the specified log level.
-Parameters
- level: string
The severity level of the log (e.g., 'info', 'warn', 'error').
- - message: string
The log message to be emitted.
-
Returns Promise<void>
- level: string
open
Opens the blind tilt to the fully open position.
-Returns Promise<void>
pause
Pauses the blind tilt operation.
-Returns Promise<void>
run
Runs the blind tilt to the specified position.
-Parameters
- percent: number
The target position percentage (0-100).
- - mode: number
The running mode (0 or 1).
-
Returns Promise<void>
- percent: number
set
Sets the device name.
-Parameters
- name: string
The new device name.
-
Returns Promise<void>
A Promise that resolves when the name is set.
-- name: string
unsubscribe
Unsubscribes from the notify characteristic.
-Returns Promise<void>
A Promise that resolves when the unsubscription is complete.
-
Staticparse
- parseServiceData(
serviceData: Buffer,
manufacturerData: Buffer,
emitLog: (level: string, message: string) => void,
reverse?: boolean,
): Promise<null | blindTiltServiceData>Parses the service data and manufacturer data for the WoBlindTilt device.
-Parameters
- serviceData: Buffer
The service data buffer.
- - manufacturerData: Buffer
The manufacturer data buffer.
- - emitLog: (level: string, message: string) => void
The function to emit log messages.
- Optionalreverse: boolean = falseWhether to reverse the tilt percentage.
-
Returns Promise<null | blindTiltServiceData>
-
-
- The parsed data object or null if the data is invalid. -
- serviceData: Buffer
Constructors
constructor
- new WoBlindTilt(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoBlindTiltParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoBlindTilt
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
close
Returns Promise<boolean>
close
Returns Promise<boolean>
close
Close blind up (position 100%)
+Returns Promise<boolean>
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Returns Promise<BlindTiltStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
open
Open blind (position 50%)
+Returns Promise<boolean>
pause
Returns Promise<boolean>
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
Parameters
- position: number
Returns Promise<boolean>
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Class WoBulb
Class representing a WoBulb device.
-Hierarchy (View Summary)
- SwitchbotDevice
- WoBulb
Index
Constructors
Accessors
Class WoBulb
Color Bulb Device
+Hierarchy (View Summary)
Implements
Index
Constructors
Properties
Accessors
Methods
Methods
Constructors
constructor
Parameters
- peripheral: Peripheral
- noble: Noble
Returns WoBulb
Accessors
address
- get address(): string
Returns string
connection
- get connectionState(): string
Returns string
friendly
Returns SwitchBotBLEModelFriendlyName
id
- get id(): string
Returns string
model
Returns SwitchBotBLEModel
model
Returns SwitchBotBLEModelName
on
- get onConnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onConnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
on
- get onDisconnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onDisconnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
Methods
command
Sends a command to the device and awaits a response.
-Parameters
- reqBuf: Buffer
The command buffer.
-
Returns Promise<Buffer<ArrayBufferLike>>
A Promise that resolves with the response buffer.
-- reqBuf: Buffer
connect
Connects to the device.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
disconnect
Disconnects from the device.
-Returns Promise<void>
A Promise that resolves when the disconnection is complete.
-
discover
Discovers the device services.
-Returns Promise<Service[]>
A Promise that resolves with the list of services.
-
get
Retrieves the device characteristics.
-Returns Promise<Chars>
A Promise that resolves with the device characteristics.
-
get
Retrieves the device name.
-Returns Promise<string>
A Promise that resolves with the device name.
-
internal
Internal method to handle the connection process.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
log
Logs a message with the specified log level.
-Parameters
- level: string
The severity level of the log (e.g., 'info', 'warn', 'error').
- - message: string
The log message to be emitted.
-
Returns Promise<void>
- level: string
read
Reads the state of the bulb.
-Returns Promise<boolean>
-
-
- Resolves with a boolean indicating whether the bulb is ON (true) or OFF (false). -
set
Sets the brightness of the bulb.
-Parameters
- brightness: number
The brightness percentage (0-100).
-
Returns Promise<boolean>
-
-
- Resolves with a boolean indicating whether the operation was successful. -
- brightness: number
set
Sets the color temperature of the bulb.
-Parameters
- color_temperature: number
The color temperature percentage (0-100).
-
Returns Promise<boolean>
-
-
- Resolves with a boolean indicating whether the operation was successful. -
- color_temperature: number
set
Sets the device name.
-Parameters
- name: string
The new device name.
-
Returns Promise<void>
A Promise that resolves when the name is set.
-- name: string
set
Sets the RGB color of the bulb.
-Parameters
- brightness: number
The brightness percentage (0-100).
- - red: number
The red color value (0-255).
- - green: number
The green color value (0-255).
- - blue: number
The blue color value (0-255).
-
Returns Promise<boolean>
-
-
- Resolves with a boolean indicating whether the operation was successful. -
- brightness: number
turn
Turns off the bulb.
-Returns Promise<boolean>
-
-
- Resolves with a boolean indicating whether the bulb is OFF (false). -
turn
Turns on the bulb.
-Returns Promise<boolean>
-
-
- Resolves with a boolean indicating whether the bulb is ON (true). -
unsubscribe
Unsubscribes from the notify characteristic.
-Returns Promise<void>
A Promise that resolves when the unsubscription is complete.
-
Staticparse
- parseServiceData(
serviceData: Buffer,
manufacturerData: Buffer,
emitLog: (level: string, message: string) => void,
): Promise<null | colorBulbServiceData>Parses the service data for WoBulb.
-Parameters
- serviceData: Buffer
The service data buffer.
- - manufacturerData: Buffer
The manufacturer data buffer.
- - emitLog: (level: string, message: string) => void
The function to emit log messages.
-
Returns Promise<null | colorBulbServiceData>
-
-
- Parsed service data or null if invalid. -
- serviceData: Buffer
Constructors
constructor
- new WoBulb(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoBulbParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoBulb
Properties
StaticEFFECTS
Preset effect name to effect ID mapping
+Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get device status (BLE-first/API-fallback, centralized)
+Returns Promise<BulbStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Strip Light 3 and complex light patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex light patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Set brightness (0-100)
+Parameters
- brightness: number
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Set RGB color
+Parameters
- red: number
- green: number
- blue: number
Returns Promise<boolean>
set
Set color temperature with min/max bounds +For advanced bulbs that support color temperature range control
+Parameters
- minTemp: number
- maxTemp: number
- temp: number
Returns Promise<boolean>
set
Set color temperature (2700-6500K)
+Parameters
- temperature: number
Returns Promise<boolean>
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Set preset light effect
+Parameters
- effectName: string
- speed: number = 100
Returns Promise<boolean>
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
turn
Turn off
+Returns Promise<boolean>
turn
Turn on
+Returns Promise<boolean>
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
verify
Verifies the BLE encryption key by attempting a status read with encryption. +Throws an error if the key is invalid or the device rejects the command.
+Returns Promise<boolean>
Class WoCandleWarmerLamp
Base class for all SwitchBot devices
+BLE-first, API-fallback Logic
+This class provides a centralized, robust hybrid connection strategy for all SwitchBot devices:
+-
+
- BLE-first, API-fallback: By default, status and command methods attempt BLE first (if available), then fall back to OpenAPI if BLE fails or is unavailable. This is controlled by
preferredConnectionandenableFallback.
+ - Centralized Fallback: The
getStatusWithFallback()andsendCommand()methods implement this logic. Device subclasses should call these methods and provide normalization/mapping as needed.
+ - Connection Intelligence: Tracks connection health and performance, automatically preferring the most reliable connection if enabled. +
- Circuit Breaker & Retry: Both BLE and API commands are protected by circuit breaker and retry logic to handle transient failures gracefully. +
Usage in Subclasses
+-
+
- For status: Call
await this.getStatusWithFallback(normalizeBLE, normalizeAPI)in yourgetStatus()implementation.
+ - For commands: Use
await this.sendCommand(bleCommand, apiCommand, apiParameter)to automatically select the best connection and handle fallback.
+ - For custom logic: You may override or extend these methods, but should preserve the fallback and error-handling patterns for consistency. +
Example (in a device subclass)
+async getStatus(): Promise<DeviceStatus> {
return this.getStatusWithFallback(
bleData => ({ ... }), // normalize BLE data
apiData => ({ ... }), // normalize API data
)
}
async turnOn(): Promise<boolean> {
const result = await this.sendCommand([0x57, 0x01, 0x01], 'turnOn')
return result.success
}
+Configuration
+-
+
preferredConnection: 'ble' | 'api' (default: 'ble')
+enableFallback: boolean (default: true)
+enableConnectionIntelligence: boolean (default: true)
+enableCircuitBreaker: boolean (default: true)
+enableRetry: boolean (default: true)
+
See Also
+-
+
getStatusWithFallback()
+sendCommand()
+hasBLE(),hasAPI()
+setPreferredConnection(),setFallbackEnabled()
+
This pattern ensures all device classes benefit from robust, testable, and consistent connection logic.
+Hierarchy (View Summary)
- SwitchBotDevice
- WoCandleWarmerLamp
Index
Constructors
Accessors
Methods
Constructors
constructor
- new WoCandleWarmerLamp(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoCandleWarmerLampParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoCandleWarmerLamp
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get device status (BLE-first, API-fallback)
+Returns Promise<CandleWarmerLampStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Set brightness (1-100)
+Parameters
- level: number
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
turn
Turn off the candle warmer lamp
+Returns Promise<boolean>
turn
Turn on the candle warmer lamp
+Returns Promise<boolean>
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Class WoCeilingLight
Class representing a WoCeilingLight device.
-Hierarchy (View Summary)
- SwitchbotDevice
- WoCeilingLight
Index
Constructors
Accessors
Class WoCeilingLight
Ceiling Light Device +Uses same logic as Color Bulb
+Hierarchy (View Summary)
- WoBulb
- WoCeilingLight
Index
Constructors
constructor
Parameters
- peripheral: Peripheral
- noble: Noble
Returns WoCeilingLight
Accessors
address
- get address(): string
Returns string
connection
- get connectionState(): string
Returns string
friendly
Returns SwitchBotBLEModelFriendlyName
id
- get id(): string
Returns string
model
Returns SwitchBotBLEModel
model
Returns SwitchBotBLEModelName
on
- get onConnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onConnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
on
- get onDisconnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onDisconnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
Methods
command
Sends a command to the device and awaits a response.
-Parameters
- reqBuf: Buffer
The command buffer.
-
Returns Promise<Buffer<ArrayBufferLike>>
A Promise that resolves with the response buffer.
-- reqBuf: Buffer
connect
Connects to the device.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
disconnect
Disconnects from the device.
-Returns Promise<void>
A Promise that resolves when the disconnection is complete.
-
discover
Discovers the device services.
-Returns Promise<Service[]>
A Promise that resolves with the list of services.
-
get
Retrieves the device characteristics.
-Returns Promise<Chars>
A Promise that resolves with the device characteristics.
-
get
Retrieves the device name.
-Returns Promise<string>
A Promise that resolves with the device name.
-
internal
Internal method to handle the connection process.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
log
Logs a message with the specified log level.
-Parameters
- level: string
The severity level of the log (e.g., 'info', 'warn', 'error').
- - message: string
The log message to be emitted.
-
Returns Promise<void>
- level: string
operate
Sends a command to the ceiling light.
-Parameters
- bytes: number[]
The command bytes.
-
Returns Promise<boolean>
-
-
- Resolves with a boolean indicating whether the operation was successful. -
- bytes: number[]
read
Reads the state of the ceiling light.
-Returns Promise<boolean>
-
-
- Resolves with a boolean indicating whether the light is ON (true) or OFF (false). -
set
Sets the brightness of the ceiling light.
-Parameters
- brightness: number
The brightness percentage (0-100).
-
Returns Promise<boolean>
-
-
- Resolves with a boolean indicating whether the operation was successful. -
- brightness: number
set
Sets the color temperature of the ceiling light.
-Parameters
- color_temperature: number
The color temperature percentage (0-100).
-
Returns Promise<boolean>
-
-
- Resolves with a boolean indicating whether the operation was successful. -
- color_temperature: number
set
Sets the device name.
-Parameters
- name: string
The new device name.
-
Returns Promise<void>
A Promise that resolves when the name is set.
-- name: string
set
Sets the RGB color of the ceiling light.
-Parameters
- brightness: number
The brightness percentage (0-100).
- - red: number
The red color value (0-255).
- - green: number
The green color value (0-255).
- - blue: number
The blue color value (0-255).
-
Returns Promise<boolean>
-
-
- Resolves with a boolean indicating whether the operation was successful. -
- brightness: number
set
Sets the state of the ceiling light.
-Parameters
- reqByteArray: number[]
The request byte array.
-
Returns Promise<boolean>
-
-
- Resolves with a boolean indicating whether the operation was successful. -
- reqByteArray: number[]
turn
Turns off the ceiling light.
-Returns Promise<boolean>
-
-
- Resolves with a boolean indicating whether the light is OFF (false). -
turn
Turns on the ceiling light.
-Returns Promise<boolean>
-
-
- Resolves with a boolean indicating whether the light is ON (true). -
unsubscribe
Unsubscribes from the notify characteristic.
-Returns Promise<void>
A Promise that resolves when the unsubscription is complete.
-
Staticparse
- parseServiceData(
manufacturerData: Buffer,
emitLog: (level: string, message: string) => void,
): Promise<null | ceilingLightServiceData>Parses the service data for WoCeilingLight.
-Parameters
- manufacturerData: Buffer
The manufacturer data buffer.
- - emitLog: (level: string, message: string) => void
The function to emit log messages.
-
Returns Promise<null | ceilingLightServiceData>
-
-
- Parsed service data or null if invalid. -
- manufacturerData: Buffer
Staticparse
- parseServiceData_Pro(
manufacturerData: Buffer,
emitLog: (level: string, message: string) => void,
): Promise<null | ceilingLightProServiceData>Parses the service data for WoCeilingLight Pro.
-Parameters
- manufacturerData: Buffer
The manufacturer data buffer.
- - emitLog: (level: string, message: string) => void
The function to emit log messages.
-
Returns Promise<null | ceilingLightProServiceData>
-
-
- Parsed service data or null if invalid. -
- manufacturerData: Buffer
Methods
Constructors
constructor
- new WoCeilingLight(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoCeilingLightParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoCeilingLight
Properties
StaticEFFECTS
Preset effect name to effect ID mapping
+Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get device status (BLE-first/API-fallback, centralized)
+Returns Promise<BulbStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Strip Light 3 and complex light patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex light patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Set brightness (0-100)
+Parameters
- brightness: number
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Set RGB color
+Parameters
- red: number
- green: number
- blue: number
Returns Promise<boolean>
set
Set color temperature with min/max bounds +For advanced bulbs that support color temperature range control
+Parameters
- minTemp: number
- maxTemp: number
- temp: number
Returns Promise<boolean>
set
Set color temperature (2700-6500K)
+Parameters
- temperature: number
Returns Promise<boolean>
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Set preset light effect
+Parameters
- effectName: string
- speed: number = 100
Returns Promise<boolean>
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
turn
Turn off
+Returns Promise<boolean>
turn
Turn on
+Returns Promise<boolean>
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
verify
Verifies the BLE encryption key by attempting a status read with encryption. +Throws an error if the key is invalid or the device rejects the command.
+Returns Promise<boolean>
Class WoCirculatorFan
Circulator Fan Device (Battery/USB) +Reuses air purifier fan-speed control and status behavior.
+Hierarchy (View Summary)
- WoAirPurifier
- WoCirculatorFan
Index
Constructors
Accessors
Methods
Constructors
constructor
- new WoCirculatorFan(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoCirculatorFanParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoCirculatorFan
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get device status (BLE-first, API-fallback)
+Returns Promise<AirPurifierStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Set fan speed (1-4)
+Parameters
- speed: number
Returns Promise<boolean>
set
set
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
turn
Turn off
+Returns Promise<boolean>
turn
Turn on
+Returns Promise<boolean>
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Refresh status for this device. Called automatically after sequence changes.
+Returns Promise<DeviceStatus>
update
Update device information and react to sequence number changes.
+Parameters
- newInfo: Partial<DeviceInfo>
Returns void
verify
Verifies the BLE encryption key by attempting a status read with encryption. +Throws an error if the key is invalid or the device rejects the command.
+Returns Promise<boolean>
Class WoClimatePanel
Climate Panel Device +Reuses climate control behavior for power, mode, and fan-speed style control.
+Hierarchy (View Summary)
- WoAirPurifier
- WoClimatePanel
Index
Constructors
Accessors
Methods
Constructors
constructor
- new WoClimatePanel(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoClimatePanelParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoClimatePanel
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get device status (BLE-first, API-fallback)
+Returns Promise<AirPurifierStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Set fan speed (1-4)
+Parameters
- speed: number
Returns Promise<boolean>
set
set
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
turn
Turn off
+Returns Promise<boolean>
turn
Turn on
+Returns Promise<boolean>
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Refresh status for this device. Called automatically after sequence changes.
+Returns Promise<DeviceStatus>
update
Update device information and react to sequence number changes.
+Parameters
- newInfo: Partial<DeviceInfo>
Returns void
verify
Verifies the BLE encryption key by attempting a status read with encryption. +Throws an error if the key is invalid or the device rejects the command.
+Returns Promise<boolean>
Class WoContact
Class representing a WoContact device.
-Hierarchy (View Summary)
- SwitchbotDevice
- WoContact
Index
Constructors
Accessors
Class WoContact
Contact Sensor (Door/Window Sensor)
+Hierarchy (View Summary)
- SwitchBotDevice
- WoContact
Index
Constructors
Accessors
Methods
Constructors
constructor
Parameters
- peripheral: Peripheral
- noble: Noble
Returns WoContact
Accessors
address
- get address(): string
Returns string
connection
- get connectionState(): string
Returns string
friendly
Returns SwitchBotBLEModelFriendlyName
id
- get id(): string
Returns string
model
Returns SwitchBotBLEModel
model
Returns SwitchBotBLEModelName
on
- get onConnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onConnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
on
- get onDisconnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onDisconnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
Methods
command
Sends a command to the device and awaits a response.
-Parameters
- reqBuf: Buffer
The command buffer.
-
Returns Promise<Buffer<ArrayBufferLike>>
A Promise that resolves with the response buffer.
-- reqBuf: Buffer
connect
Connects to the device.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
disconnect
Disconnects from the device.
-Returns Promise<void>
A Promise that resolves when the disconnection is complete.
-
discover
Discovers the device services.
-Returns Promise<Service[]>
A Promise that resolves with the list of services.
-
get
Retrieves the device characteristics.
-Returns Promise<Chars>
A Promise that resolves with the device characteristics.
-
get
Retrieves the device name.
-Returns Promise<string>
A Promise that resolves with the device name.
-
internal
Internal method to handle the connection process.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
log
Logs a message with the specified log level.
-Parameters
- level: string
The severity level of the log (e.g., 'info', 'warn', 'error').
- - message: string
The log message to be emitted.
-
Returns Promise<void>
- level: string
set
Sets the device name.
-Parameters
- name: string
The new device name.
-
Returns Promise<void>
A Promise that resolves when the name is set.
-- name: string
unsubscribe
Unsubscribes from the notify characteristic.
-Returns Promise<void>
A Promise that resolves when the unsubscription is complete.
-
Staticparse
- parseServiceData(
serviceData: Buffer,
emitLog: (level: string, message: string) => void,
): Promise<null | contactSensorServiceData>Parses the service data for WoContact.
-Parameters
- serviceData: Buffer
The service data buffer.
- - emitLog: (level: string, message: string) => void
The function to emit log messages.
-
Returns Promise<null | contactSensorServiceData>
-
-
- Parsed service data or null if invalid. -
- serviceData: Buffer
Methods
Constructors
constructor
- new WoContact(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoContactParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoContact
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get device status (BLE-first, API-fallback)
+Returns Promise<ContactStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Class WoCurtain
Class representing a WoCurtain device.
-Hierarchy (View Summary)
- SwitchbotDevice
- WoCurtain
Index
Constructors
Accessors
Class WoCurtain
Curtain Device - Smart curtain controller
+Hierarchy (View Summary)
- SwitchBotDevice
- WoCurtain
Implements
Index
Constructors
Properties
Accessors
Methods
Constructors
constructor
Parameters
- peripheral: Peripheral
- noble: Noble
Returns WoCurtain
Accessors
address
- get address(): string
Returns string
connection
- get connectionState(): string
Returns string
friendly
Returns SwitchBotBLEModelFriendlyName
id
- get id(): string
Returns string
model
Returns SwitchBotBLEModel
model
Returns SwitchBotBLEModelName
on
- get onConnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onConnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
on
- get onDisconnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onDisconnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
Methods
close
Closes the curtain.
-Parameters
Optionalmode: number = 0xFFRunning mode (0x01 = QuietDrift, 0xFF = Default).
-
Returns Promise<void>
command
Sends a command to the device and awaits a response.
-Parameters
- reqBuf: Buffer
The command buffer.
-
Returns Promise<Buffer<ArrayBufferLike>>
A Promise that resolves with the response buffer.
-- reqBuf: Buffer
connect
Connects to the device.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
disconnect
Disconnects from the device.
-Returns Promise<void>
A Promise that resolves when the disconnection is complete.
-
discover
Discovers the device services.
-Returns Promise<Service[]>
A Promise that resolves with the list of services.
-
get
Retrieves the device characteristics.
-Returns Promise<Chars>
A Promise that resolves with the device characteristics.
-
get
Retrieves the device name.
-Returns Promise<string>
A Promise that resolves with the device name.
-
internal
Internal method to handle the connection process.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
log
Logs a message with the specified log level.
-Parameters
- level: string
The severity level of the log (e.g., 'info', 'warn', 'error').
- - message: string
The log message to be emitted.
-
Returns Promise<void>
- level: string
open
Opens the curtain.
-Parameters
Optionalmode: number = 0xFFRunning mode (0x01 = QuietDrift, 0xFF = Default).
-
Returns Promise<void>
operate
Sends a command to the curtain.
-Parameters
- bytes: number[]
The command bytes.
-
Returns Promise<void>
- bytes: number[]
pause
Pauses the curtain.
-Returns Promise<void>
run
Runs the curtain to the target position.
-Parameters
- percent: number
The percentage of the target position.
- Optionalmode: number = 0xFFRunning mode (0x01 = QuietDrift, 0xFF = Default).
-
Returns Promise<void>
- percent: number
set
Sets the device name.
-Parameters
- name: string
The new device name.
-
Returns Promise<void>
A Promise that resolves when the name is set.
-- name: string
unsubscribe
Unsubscribes from the notify characteristic.
-Returns Promise<void>
A Promise that resolves when the unsubscription is complete.
-
Staticparse
- parseServiceData(
serviceData: Buffer,
manufacturerData: Buffer,
emitLog: (level: string, message: string) => void,
reverse?: boolean,
): Promise<null | curtainServiceData | curtain3ServiceData>Parses the service data for WoCurtain.
-Parameters
- serviceData: Buffer
The service data buffer.
- - manufacturerData: Buffer
The manufacturer data buffer.
- - emitLog: (level: string, message: string) => void
The function to emit log messages.
- Optionalreverse: boolean = falseWhether to reverse the position.
-
Returns Promise<null | curtainServiceData | curtain3ServiceData>
-
-
- Parsed service data or null if invalid. -
- serviceData: Buffer
Constructors
constructor
- new WoCurtain(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoCurtainParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoCurtain
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
close
Close curtain (position 100%)
+Parameters
- speed: number = 255
Returns Promise<boolean>
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get extended device information (Curtain 3) +Returns device chain information and grouped curtain status
+Returns Promise<CurtainExtendedInfo>
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Returns Promise<CurtainStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
open
Open curtain (position 0%)
+Parameters
- speed: number = 255
Returns Promise<boolean>
pause
Pause curtain movement
+Returns Promise<boolean>
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3 complex operations
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for Curtain 3 fallback operations
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
Set curtain position (0-100%)
+Parameters
- position: number
- speed: number = 255
Returns Promise<boolean>
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Class WoFloorLamp
Floor Lamp Device +Uses same logic as Color Bulb
+Hierarchy (View Summary)
- WoBulb
- WoFloorLamp
Index
Constructors
Properties
Accessors
Methods
Constructors
constructor
- new WoFloorLamp(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoFloorLampParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoFloorLamp
Properties
StaticEFFECTS
Preset effect name to effect ID mapping
+Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get device status (BLE-first/API-fallback, centralized)
+Returns Promise<BulbStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Strip Light 3 and complex light patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex light patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Set brightness (0-100)
+Parameters
- brightness: number
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Set RGB color
+Parameters
- red: number
- green: number
- blue: number
Returns Promise<boolean>
set
Set color temperature with min/max bounds +For advanced bulbs that support color temperature range control
+Parameters
- minTemp: number
- maxTemp: number
- temp: number
Returns Promise<boolean>
set
Set color temperature (2700-6500K)
+Parameters
- temperature: number
Returns Promise<boolean>
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Set preset light effect
+Parameters
- effectName: string
- speed: number = 100
Returns Promise<boolean>
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
turn
Turn off
+Returns Promise<boolean>
turn
Turn on
+Returns Promise<boolean>
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
verify
Verifies the BLE encryption key by attempting a status read with encryption. +Throws an error if the key is invalid or the device rejects the command.
+Returns Promise<boolean>
Class WoGarageDoorOpener
Garage Door Opener Device (uses relay switch control) +Extends Relay Switch 1 for simple open/close control
+Hierarchy (View Summary)
- WoRelaySwitch1
- WoGarageDoorOpener
Index
Constructors
Accessors
Methods
Constructors
constructor
- new WoGarageDoorOpener(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoGarageDoorOpenerParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoGarageDoorOpener
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get device status (BLE-first, API-fallback)
+Returns Promise<RelaySwitchStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
toggle
Toggle power
+Returns Promise<boolean>
turn
Turn off
+Returns Promise<boolean>
turn
Turn on
+Returns Promise<boolean>
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Refresh status for this device. Called automatically after sequence changes.
+Returns Promise<DeviceStatus>
update
Update device information and react to sequence number changes.
+Parameters
- newInfo: Partial<DeviceInfo>
Returns void
verify
Verifies the BLE encryption key by attempting a status read with encryption. +Throws an error if the key is invalid or the device rejects the command.
+Returns Promise<boolean>
Class WoHand
Class representing a WoHand device.
-Hierarchy (View Summary)
- SwitchbotDevice
- WoHand
Index
Constructors
Accessors
Class WoHand
Bot (WoHand) Device - Press or switch button device +Supports optional BLE password protection
+Hierarchy (View Summary)
Implements
Index
Constructors
Accessors
Methods
Methods
Constructors
constructor
Parameters
- peripheral: Peripheral
- noble: Noble
Returns WoHand
Accessors
address
- get address(): string
Returns string
connection
- get connectionState(): string
Returns string
friendly
Returns SwitchBotBLEModelFriendlyName
id
- get id(): string
Returns string
model
Returns SwitchBotBLEModel
model
Returns SwitchBotBLEModelName
on
- get onConnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onConnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
on
- get onDisconnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onDisconnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
Methods
command
Sends a command to the device and awaits a response.
-Parameters
- reqBuf: Buffer
The command buffer.
-
Returns Promise<Buffer<ArrayBufferLike>>
A Promise that resolves with the response buffer.
-- reqBuf: Buffer
connect
Connects to the device.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
disconnect
Disconnects from the device.
-Returns Promise<void>
A Promise that resolves when the disconnection is complete.
-
discover
Discovers the device services.
-Returns Promise<Service[]>
A Promise that resolves with the list of services.
-
down
Moves the bot down.
-Returns Promise<void>
get
Retrieves the device characteristics.
-Returns Promise<Chars>
A Promise that resolves with the device characteristics.
-
get
Retrieves the device name.
-Returns Promise<string>
A Promise that resolves with the device name.
-
internal
Internal method to handle the connection process.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
log
Logs a message with the specified log level.
-Parameters
- level: string
The severity level of the log (e.g., 'info', 'warn', 'error').
- - message: string
The log message to be emitted.
-
Returns Promise<void>
- level: string
press
Presses the bot.
-Returns Promise<void>
set
Sets the device name.
-Parameters
- name: string
The new device name.
-
Returns Promise<void>
A Promise that resolves when the name is set.
-- name: string
turn
Turns off the bot.
-Returns Promise<void>
turn
Turns on the bot.
-Returns Promise<void>
unsubscribe
Unsubscribes from the notify characteristic.
-Returns Promise<void>
A Promise that resolves when the unsubscription is complete.
-
up
Moves the bot up.
-Returns Promise<void>
Staticparse
- parseServiceData(
serviceData: Buffer,
emitLog: (level: string, message: string) => void,
): Promise<null | botServiceData>Parses the service data for WoHand.
-Parameters
- serviceData: Buffer
The service data buffer.
- - emitLog: (level: string, message: string) => void
The function to emit log messages.
-
Returns Promise<null | botServiceData>
-
-
- Parsed service data or null if invalid. -
- serviceData: Buffer
Constructors
constructor
- new WoHand(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
password?: string;
preferredConnection?: "ble" | "api";
},
): WoHandParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
password?: string;
preferredConnection?: "ble" | "api";
} = {}
Returns WoHand
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
clear
Clear Bot password
+Returns void
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get device status (BLE-first, API-fallback)
+Returns Promise<BotStatus>
hand
Lower Bot arm
+Returns Promise<boolean>
hand
Raise Bot arm
+Returns Promise<boolean>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
has
Check if password is configured
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
press
Press (press mode)
+Returns Promise<boolean>
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Set Bot long-press duration (1-255 deciseconds)
+Parameters
- duration: number
Returns Promise<boolean>
set
set
Set or update Bot password
+Parameters
- password: string
4-character alphanumeric password (case-sensitive)
+
Returns void
- password: string
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
turn
Turn off (switch mode)
+Returns Promise<boolean>
turn
Turn on (switch mode)
+Returns Promise<boolean>
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Class WoHub2
Class representing a WoHub2 device.
-Hierarchy (View Summary)
- SwitchbotDevice
- WoHub2
Index
Constructors
Accessors
Class WoHub2
Hub 2 Device (Hub Mini/Hub Plus also use this)
+Hierarchy (View Summary)
Index
Constructors
Accessors
Methods
Constructors
constructor
Parameters
- peripheral: Peripheral
- noble: Noble
Returns WoHub2
Accessors
address
- get address(): string
Returns string
connection
- get connectionState(): string
Returns string
friendly
Returns SwitchBotBLEModelFriendlyName
id
- get id(): string
Returns string
model
Returns SwitchBotBLEModel
model
Returns SwitchBotBLEModelName
on
- get onConnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onConnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
on
- get onDisconnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onDisconnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
Methods
command
Sends a command to the device and awaits a response.
-Parameters
- reqBuf: Buffer
The command buffer.
-
Returns Promise<Buffer<ArrayBufferLike>>
A Promise that resolves with the response buffer.
-- reqBuf: Buffer
connect
Connects to the device.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
disconnect
Disconnects from the device.
-Returns Promise<void>
A Promise that resolves when the disconnection is complete.
-
discover
Discovers the device services.
-Returns Promise<Service[]>
A Promise that resolves with the list of services.
-
get
Retrieves the device characteristics.
-Returns Promise<Chars>
A Promise that resolves with the device characteristics.
-
get
Retrieves the device name.
-Returns Promise<string>
A Promise that resolves with the device name.
-
internal
Internal method to handle the connection process.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
log
Logs a message with the specified log level.
-Parameters
- level: string
The severity level of the log (e.g., 'info', 'warn', 'error').
- - message: string
The log message to be emitted.
-
Returns Promise<void>
- level: string
set
Sets the device name.
-Parameters
- name: string
The new device name.
-
Returns Promise<void>
A Promise that resolves when the name is set.
-- name: string
unsubscribe
Unsubscribes from the notify characteristic.
-Returns Promise<void>
A Promise that resolves when the unsubscription is complete.
-
Staticparse
- parseServiceData(
manufacturerData: Buffer,
emitLog: (level: string, message: string) => void,
): Promise<null | hub2ServiceData>Parses the service data for WoHub2.
-Parameters
- manufacturerData: Buffer
The manufacturer data buffer.
- - emitLog: (level: string, message: string) => void
The function to emit log messages.
-
Returns Promise<null | hub2ServiceData>
-
-
- Parsed service data or null if invalid. -
- manufacturerData: Buffer
Methods
Constructors
constructor
- new WoHub2(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoHub2Parameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoHub2
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get device status (BLE-first, API-fallback)
+Returns Promise<HubStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Class WoHub3
Class representing a WoHub3 device.
-Hierarchy (View Summary)
- SwitchbotDevice
- WoHub3
Index
Constructors
Accessors
Class WoHub3
Hub 3 Device +Uses same logic as Hub 2
+Hierarchy (View Summary)
- WoHub2
- WoHub3
Index
Constructors
Accessors
Methods
Constructors
constructor
Parameters
- peripheral: Peripheral
- noble: Noble
Returns WoHub3
Accessors
address
- get address(): string
Returns string
connection
- get connectionState(): string
Returns string
friendly
Returns SwitchBotBLEModelFriendlyName
id
- get id(): string
Returns string
model
Returns SwitchBotBLEModel
model
Returns SwitchBotBLEModelName
on
- get onConnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onConnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
on
- get onDisconnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onDisconnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
Methods
command
Sends a command to the device and awaits a response.
-Parameters
- reqBuf: Buffer
The command buffer.
-
Returns Promise<Buffer<ArrayBufferLike>>
A Promise that resolves with the response buffer.
-- reqBuf: Buffer
connect
Connects to the device.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
disconnect
Disconnects from the device.
-Returns Promise<void>
A Promise that resolves when the disconnection is complete.
-
discover
Discovers the device services.
-Returns Promise<Service[]>
A Promise that resolves with the list of services.
-
get
Retrieves the device characteristics.
-Returns Promise<Chars>
A Promise that resolves with the device characteristics.
-
get
Retrieves the device name.
-Returns Promise<string>
A Promise that resolves with the device name.
-
internal
Internal method to handle the connection process.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
log
Logs a message with the specified log level.
-Parameters
- level: string
The severity level of the log (e.g., 'info', 'warn', 'error').
- - message: string
The log message to be emitted.
-
Returns Promise<void>
- level: string
set
Sets the device name.
-Parameters
- name: string
The new device name.
-
Returns Promise<void>
A Promise that resolves when the name is set.
-- name: string
unsubscribe
Unsubscribes from the notify characteristic.
-Returns Promise<void>
A Promise that resolves when the unsubscription is complete.
-
Staticparse
- parseServiceData(
manufacturerData: Buffer,
emitLog: (level: string, message: string) => void,
): Promise<null | hub3ServiceData>Parses the service data for WoHub3.
-Parameters
- manufacturerData: Buffer
The manufacturer data buffer.
- - emitLog: (level: string, message: string) => void
The function to emit log messages.
-
Returns Promise<null | hub3ServiceData>
-
-
- Parsed service data or null if invalid. -
- manufacturerData: Buffer
Methods
Constructors
constructor
- new WoHub3(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoHub3Parameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoHub3
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get device status (BLE-first, API-fallback)
+Returns Promise<HubStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Class WoHubMiniMatter
HubMini Matter Device +Uses same hub logic as Hub 2
+Hierarchy (View Summary)
- WoHub2
- WoHubMiniMatter
Index
Constructors
Accessors
Methods
Constructors
constructor
- new WoHubMiniMatter(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoHubMiniMatterParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoHubMiniMatter
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get device status (BLE-first, API-fallback)
+Returns Promise<HubStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Class WoHumi
Class representing a WoHumi device.
-Hierarchy (View Summary)
- SwitchbotDevice
- WoHumi
Index
Constructors
Accessors
Class WoHumi
Humidifier Device
+Hierarchy (View Summary)
- SwitchBotDevice
- WoHumi
Implements
Index
Constructors
Accessors
Methods
Methods
Constructors
constructor
Parameters
- peripheral: Peripheral
- noble: Noble
Returns WoHumi
Accessors
address
- get address(): string
Returns string
connection
- get connectionState(): string
Returns string
friendly
Returns SwitchBotBLEModelFriendlyName
id
- get id(): string
Returns string
model
Returns SwitchBotBLEModel
model
Returns SwitchBotBLEModelName
on
- get onConnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onConnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
on
- get onDisconnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onDisconnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
Methods
command
Sends a command to the device and awaits a response.
-Parameters
- reqBuf: Buffer
The command buffer.
-
Returns Promise<Buffer<ArrayBufferLike>>
A Promise that resolves with the response buffer.
-- reqBuf: Buffer
connect
Connects to the device.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
decrease
Decreases the humidifier setting.
-Returns Promise<void>
disconnect
Disconnects from the device.
-Returns Promise<void>
A Promise that resolves when the disconnection is complete.
-
discover
Discovers the device services.
-Returns Promise<Service[]>
A Promise that resolves with the list of services.
-
get
Retrieves the device characteristics.
-Returns Promise<Chars>
A Promise that resolves with the device characteristics.
-
get
Retrieves the device name.
-Returns Promise<string>
A Promise that resolves with the device name.
-
increase
Increases the humidifier setting.
-Returns Promise<void>
internal
Internal method to handle the connection process.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
log
Logs a message with the specified log level.
-Parameters
- level: string
The severity level of the log (e.g., 'info', 'warn', 'error').
- - message: string
The log message to be emitted.
-
Returns Promise<void>
- level: string
percentage
Sets the humidifier level.
-Parameters
- level: number
The level to set (0-100).
-
Returns Promise<void>
- level: number
set
Sets the humidifier to auto mode.
-Returns Promise<void>
set
Sets the device name.
-Parameters
- name: string
The new device name.
-
Returns Promise<void>
A Promise that resolves when the name is set.
-- name: string
set
Sets the humidifier to manual mode.
-Returns Promise<void>
turn
Turns off the humidifier.
-Returns Promise<void>
turn
Turns on the humidifier.
-Returns Promise<void>
unsubscribe
Unsubscribes from the notify characteristic.
-Returns Promise<void>
A Promise that resolves when the unsubscription is complete.
-
Staticparse
- parseServiceData(
serviceData: Buffer,
emitLog: (level: string, message: string) => void,
): Promise<null | humidifierServiceData>Parses the service data for WoHumi.
-Parameters
- serviceData: Buffer
The service data buffer.
- - emitLog: (level: string, message: string) => void
The function to emit log messages.
-
Returns Promise<null | humidifierServiceData>
-
-
- Parsed service data or null if invalid. -
- serviceData: Buffer
Constructors
constructor
- new WoHumi(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoHumiParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoHumi
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get device status (BLE-first/API-fallback, centralized)
+Returns Promise<HumidifierStatus>
get
Get target humidity level (if available)
+Returns Promise<number | undefined>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Set auto mode
+Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Set nebulization efficiency (0-100)
+Parameters
- level: number
Returns Promise<boolean>
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Set target humidity level (1-100)
+Parameters
- level: number
Returns Promise<boolean>
set
Set manual mode
+Returns Promise<boolean>
set
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
turn
Turn off
+Returns Promise<boolean>
turn
Turn on
+Returns Promise<boolean>
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Class WoHumi2
Class representing a WoHumi device.
-Hierarchy (View Summary)
- SwitchbotDevice
- WoHumi2
Index
Constructors
Accessors
Class WoHumi2
Humidifier 2 Device +Uses same logic as Humidifier
+Hierarchy (View Summary)
- WoHumi
- WoHumi2
Index
Constructors
Accessors
Methods
Constructors
constructor
Parameters
- peripheral: Peripheral
- noble: Noble
Returns WoHumi2
Accessors
address
- get address(): string
Returns string
connection
- get connectionState(): string
Returns string
friendly
Returns SwitchBotBLEModelFriendlyName
id
- get id(): string
Returns string
model
Returns SwitchBotBLEModel
model
Returns SwitchBotBLEModelName
on
- get onConnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onConnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
on
- get onDisconnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onDisconnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
Methods
command
Sends a command to the device and awaits a response.
-Parameters
- reqBuf: Buffer
The command buffer.
-
Returns Promise<Buffer<ArrayBufferLike>>
A Promise that resolves with the response buffer.
-- reqBuf: Buffer
connect
Connects to the device.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
decrease
Decreases the humidifier setting.
-Returns Promise<void>
disconnect
Disconnects from the device.
-Returns Promise<void>
A Promise that resolves when the disconnection is complete.
-
discover
Discovers the device services.
-Returns Promise<Service[]>
A Promise that resolves with the list of services.
-
get
Retrieves the device characteristics.
-Returns Promise<Chars>
A Promise that resolves with the device characteristics.
-
get
Retrieves the device name.
-Returns Promise<string>
A Promise that resolves with the device name.
-
increase
Increases the humidifier setting.
-Returns Promise<void>
internal
Internal method to handle the connection process.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
log
Logs a message with the specified log level.
-Parameters
- level: string
The severity level of the log (e.g., 'info', 'warn', 'error').
- - message: string
The log message to be emitted.
-
Returns Promise<void>
- level: string
percentage
Sets the humidifier level.
-Parameters
- level: number
The level to set (0-100).
-
Returns Promise<void>
- level: number
set
Sets the humidifier to auto mode.
-Returns Promise<void>
set
Sets the device name.
-Parameters
- name: string
The new device name.
-
Returns Promise<void>
A Promise that resolves when the name is set.
-- name: string
set
Sets the humidifier to manual mode.
-Returns Promise<void>
turn
Turns off the humidifier.
-Returns Promise<void>
turn
Turns on the humidifier.
-Returns Promise<void>
unsubscribe
Unsubscribes from the notify characteristic.
-Returns Promise<void>
A Promise that resolves when the unsubscription is complete.
-
Staticparse
- parseServiceData(
serviceData: Buffer,
emitLog: (level: string, message: string) => void,
): Promise<null | humidifier2ServiceData>Parses the service data for WoHumi.
-Parameters
- serviceData: Buffer
The service data buffer.
- - emitLog: (level: string, message: string) => void
The function to emit log messages.
-
Returns Promise<null | humidifier2ServiceData>
-
-
- Parsed service data or null if invalid. -
- serviceData: Buffer
Methods
Constructors
constructor
- new WoHumi2(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoHumi2Parameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoHumi2
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get device status (BLE-first/API-fallback, centralized)
+Returns Promise<HumidifierStatus>
get
Get target humidity level (if available)
+Returns Promise<number | undefined>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Set auto mode
+Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Set nebulization efficiency (0-100)
+Parameters
- level: number
Returns Promise<boolean>
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Set target humidity level (1-100)
+Parameters
- level: number
Returns Promise<boolean>
set
Set manual mode
+Returns Promise<boolean>
set
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
turn
Turn off
+Returns Promise<boolean>
turn
Turn on
+Returns Promise<boolean>
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Class WoIOSensorTH
Class representing a WoIOSensorTH device.
-Hierarchy (View Summary)
- SwitchbotDevice
- WoIOSensorTH
Index
Constructors
Accessors
Class WoIOSensorTH
Outdoor Meter (Temperature/Humidity Sensor for outdoor use) +Uses same logic as standard Meter
+Hierarchy (View Summary)
- WoSensorTH
- WoIOSensorTH
Index
Constructors
Accessors
Methods
Constructors
constructor
Parameters
- peripheral: Peripheral
- noble: Noble
Returns WoIOSensorTH
Accessors
address
- get address(): string
Returns string
connection
- get connectionState(): string
Returns string
friendly
Returns SwitchBotBLEModelFriendlyName
id
- get id(): string
Returns string
model
Returns SwitchBotBLEModel
model
Returns SwitchBotBLEModelName
on
- get onConnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onConnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
on
- get onDisconnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onDisconnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
Methods
command
Sends a command to the device and awaits a response.
-Parameters
- reqBuf: Buffer
The command buffer.
-
Returns Promise<Buffer<ArrayBufferLike>>
A Promise that resolves with the response buffer.
-- reqBuf: Buffer
connect
Connects to the device.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
disconnect
Disconnects from the device.
-Returns Promise<void>
A Promise that resolves when the disconnection is complete.
-
discover
Discovers the device services.
-Returns Promise<Service[]>
A Promise that resolves with the list of services.
-
get
Retrieves the device characteristics.
-Returns Promise<Chars>
A Promise that resolves with the device characteristics.
-
get
Retrieves the device name.
-Returns Promise<string>
A Promise that resolves with the device name.
-
internal
Internal method to handle the connection process.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
log
Logs a message with the specified log level.
-Parameters
- level: string
The severity level of the log (e.g., 'info', 'warn', 'error').
- - message: string
The log message to be emitted.
-
Returns Promise<void>
- level: string
set
Sets the device name.
-Parameters
- name: string
The new device name.
-
Returns Promise<void>
A Promise that resolves when the name is set.
-- name: string
unsubscribe
Unsubscribes from the notify characteristic.
-Returns Promise<void>
A Promise that resolves when the unsubscription is complete.
-
Staticparse
- parseServiceData(
serviceData: Buffer,
manufacturerData: Buffer,
emitLog: (level: string, message: string) => void,
): Promise<null | outdoorMeterServiceData>Parses the service data for WoIOSensorTH.
-Parameters
- serviceData: Buffer
The service data buffer.
- - manufacturerData: Buffer
The manufacturer data buffer.
- - emitLog: (level: string, message: string) => void
The function to emit log messages.
-
Returns Promise<null | outdoorMeterServiceData>
-
-
- Parsed service data or null if invalid. -
- serviceData: Buffer
Methods
Constructors
constructor
- new WoIOSensorTH(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoIOSensorTHParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoIOSensorTH
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get device status (BLE-first, API-fallback)
+Returns Promise<MeterStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Class WoKeypad
Class representing a WoKeypad device.
-Hierarchy (View Summary)
- SwitchbotDevice
- WoKeypad
Index
Constructors
Accessors
Class WoKeypad
Keypad Device (Touch/Physical) +Note: Keypad is primarily for lock control, read-only for status
+Hierarchy (View Summary)
Index
Constructors
Accessors
Methods
Constructors
constructor
Parameters
- peripheral: Peripheral
- noble: Noble
Returns WoKeypad
Accessors
address
- get address(): string
Returns string
connection
- get connectionState(): string
Returns string
friendly
Returns SwitchBotBLEModelFriendlyName
id
- get id(): string
Returns string
model
Returns SwitchBotBLEModel
model
Returns SwitchBotBLEModelName
on
- get onConnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onConnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
on
- get onDisconnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onDisconnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
Methods
command
Sends a command to the device and awaits a response.
-Parameters
- reqBuf: Buffer
The command buffer.
-
Returns Promise<Buffer<ArrayBufferLike>>
A Promise that resolves with the response buffer.
-- reqBuf: Buffer
connect
Connects to the device.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
disconnect
Disconnects from the device.
-Returns Promise<void>
A Promise that resolves when the disconnection is complete.
-
discover
Discovers the device services.
-Returns Promise<Service[]>
A Promise that resolves with the list of services.
-
get
Retrieves the device characteristics.
-Returns Promise<Chars>
A Promise that resolves with the device characteristics.
-
get
Retrieves the device name.
-Returns Promise<string>
A Promise that resolves with the device name.
-
internal
Internal method to handle the connection process.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
log
Logs a message with the specified log level.
-Parameters
- level: string
The severity level of the log (e.g., 'info', 'warn', 'error').
- - message: string
The log message to be emitted.
-
Returns Promise<void>
- level: string
set
Sets the device name.
-Parameters
- name: string
The new device name.
-
Returns Promise<void>
A Promise that resolves when the name is set.
-- name: string
unsubscribe
Unsubscribes from the notify characteristic.
-Returns Promise<void>
A Promise that resolves when the unsubscription is complete.
-
Staticparse
- parseServiceData(
serviceData: Buffer,
manufacturerData: Buffer,
emitLog: (level: string, message: string) => void,
): Promise<null | keypadDetectorServiceData>Parses the service data for WoKeypad.
-Parameters
- serviceData: Buffer
The service data buffer.
- - manufacturerData: Buffer
The manufacturer data buffer.
- - emitLog: (level: string, message: string) => void
The function to emit log messages.
-
Returns Promise<null | keypadDetectorServiceData>
-
-
- Parsed service data or null if invalid. -
- serviceData: Buffer
Methods
Constructors
constructor
- new WoKeypad(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoKeypadParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoKeypad
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get device status (BLE-first, API-fallback)
+Returns Promise<KeypadStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Class WoKeypadVision
Keypad Vision Device +Uses same logic as Keypad for lock control
+Hierarchy (View Summary)
- WoKeypad
- WoKeypadVision
Index
Constructors
Accessors
Methods
Constructors
constructor
- new WoKeypadVision(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoKeypadVisionParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoKeypadVision
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get device status (BLE-first, API-fallback)
+Returns Promise<KeypadStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Class WoKeypadVisionPro
SwitchBot Keypad Vision Pro device
+Hierarchy (View Summary)
- WoKeypad
- WoKeypadVisionPro
Index
Constructors
Accessors
Methods
Constructors
constructor
- new WoKeypadVisionPro(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoKeypadVisionProParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoKeypadVisionPro
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get keypad status (inherited from WoKeypad)
+Returns Promise<KeypadStatus>
Promise resolving to KeypadStatus
+
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Class WoLeak
Class representing a WoLeak device.
-Hierarchy (View Summary)
- SwitchbotDevice
- WoLeak
Index
Constructors
Accessors
Class WoLeak
Water Leak Detector Device
+Hierarchy (View Summary)
- SwitchBotDevice
- WoLeak
Index
Constructors
Accessors
Methods
Constructors
constructor
Parameters
- peripheral: Peripheral
- noble: Noble
Returns WoLeak
Accessors
address
- get address(): string
Returns string
connection
- get connectionState(): string
Returns string
friendly
Returns SwitchBotBLEModelFriendlyName
id
- get id(): string
Returns string
model
Returns SwitchBotBLEModel
model
Returns SwitchBotBLEModelName
on
- get onConnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onConnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
on
- get onDisconnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onDisconnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
Methods
command
Sends a command to the device and awaits a response.
-Parameters
- reqBuf: Buffer
The command buffer.
-
Returns Promise<Buffer<ArrayBufferLike>>
A Promise that resolves with the response buffer.
-- reqBuf: Buffer
connect
Connects to the device.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
disconnect
Disconnects from the device.
-Returns Promise<void>
A Promise that resolves when the disconnection is complete.
-
discover
Discovers the device services.
-Returns Promise<Service[]>
A Promise that resolves with the list of services.
-
get
Retrieves the device characteristics.
-Returns Promise<Chars>
A Promise that resolves with the device characteristics.
-
get
Retrieves the device name.
-Returns Promise<string>
A Promise that resolves with the device name.
-
internal
Internal method to handle the connection process.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
log
Logs a message with the specified log level.
-Parameters
- level: string
The severity level of the log (e.g., 'info', 'warn', 'error').
- - message: string
The log message to be emitted.
-
Returns Promise<void>
- level: string
set
Sets the device name.
-Parameters
- name: string
The new device name.
-
Returns Promise<void>
A Promise that resolves when the name is set.
-- name: string
unsubscribe
Unsubscribes from the notify characteristic.
-Returns Promise<void>
A Promise that resolves when the unsubscription is complete.
-
Staticparse
- parseServiceData(
serviceData: Buffer,
manufacturerData: Buffer,
emitLog: (level: string, message: string) => void,
): Promise<null | waterLeakDetectorServiceData>Parses the service data for WoLeak.
-Parameters
- serviceData: Buffer
The service data buffer.
- - manufacturerData: Buffer
The manufacturer data buffer.
- - emitLog: (level: string, message: string) => void
The function to emit log messages.
-
Returns Promise<null | waterLeakDetectorServiceData>
-
-
- Parsed service data or null if invalid. -
- serviceData: Buffer
Methods
Constructors
constructor
- new WoLeak(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoLeakParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoLeak
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get device status (BLE-first, API-fallback)
+Returns Promise<LeakStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Class WoPanTiltCamPlus3K
Base class for all SwitchBot devices
+BLE-first, API-fallback Logic
+This class provides a centralized, robust hybrid connection strategy for all SwitchBot devices:
+-
+
- BLE-first, API-fallback: By default, status and command methods attempt BLE first (if available), then fall back to OpenAPI if BLE fails or is unavailable. This is controlled by
preferredConnectionandenableFallback.
+ - Centralized Fallback: The
getStatusWithFallback()andsendCommand()methods implement this logic. Device subclasses should call these methods and provide normalization/mapping as needed.
+ - Connection Intelligence: Tracks connection health and performance, automatically preferring the most reliable connection if enabled. +
- Circuit Breaker & Retry: Both BLE and API commands are protected by circuit breaker and retry logic to handle transient failures gracefully. +
Usage in Subclasses
+-
+
- For status: Call
await this.getStatusWithFallback(normalizeBLE, normalizeAPI)in yourgetStatus()implementation.
+ - For commands: Use
await this.sendCommand(bleCommand, apiCommand, apiParameter)to automatically select the best connection and handle fallback.
+ - For custom logic: You may override or extend these methods, but should preserve the fallback and error-handling patterns for consistency. +
Example (in a device subclass)
+async getStatus(): Promise<DeviceStatus> {
return this.getStatusWithFallback(
bleData => ({ ... }), // normalize BLE data
apiData => ({ ... }), // normalize API data
)
}
async turnOn(): Promise<boolean> {
const result = await this.sendCommand([0x57, 0x01, 0x01], 'turnOn')
return result.success
}
+Configuration
+-
+
preferredConnection: 'ble' | 'api' (default: 'ble')
+enableFallback: boolean (default: true)
+enableConnectionIntelligence: boolean (default: true)
+enableCircuitBreaker: boolean (default: true)
+enableRetry: boolean (default: true)
+
See Also
+-
+
getStatusWithFallback()
+sendCommand()
+hasBLE(),hasAPI()
+setPreferredConnection(),setFallbackEnabled()
+
This pattern ensures all device classes benefit from robust, testable, and consistent connection logic.
+Hierarchy (View Summary)
- SwitchBotDevice
- WoPanTiltCamPlus3K
Index
Constructors
Accessors
Methods
Constructors
constructor
- new WoPanTiltCamPlus3K(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoPanTiltCamPlus3KParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoPanTiltCamPlus3K
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get device status (BLE-first, API-fallback, centralized)
+Returns Promise<DeviceStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
pan
Pan the camera (degrees: -180 to 180)
+Parameters
- degrees: number
Returns Promise<boolean>
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
reset
Reset the camera position
+Returns Promise<boolean>
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
tilt
Tilt the camera (degrees: -90 to 90)
+Parameters
- degrees: number
Returns Promise<boolean>
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Class WoPlugMiniJP
Class representing a WoPlugMini device.
-Hierarchy (View Summary)
- SwitchbotDevice
- WoPlugMiniJP
Index
Constructors
Accessors
Class WoPlugMiniJP
Plug Mini (JP) Device +Uses same logic as US version
+Hierarchy (View Summary)
- WoPlugMiniUS
- WoPlugMiniJP
Index
Constructors
Accessors
Methods
Constructors
constructor
Parameters
- peripheral: Peripheral
- noble: Noble
Returns WoPlugMiniJP
Accessors
address
- get address(): string
Returns string
connection
- get connectionState(): string
Returns string
friendly
Returns SwitchBotBLEModelFriendlyName
id
- get id(): string
Returns string
model
Returns SwitchBotBLEModel
model
Returns SwitchBotBLEModelName
on
- get onConnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onConnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
on
- get onDisconnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onDisconnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
Methods
command
Sends a command to the device and awaits a response.
-Parameters
- reqBuf: Buffer
The command buffer.
-
Returns Promise<Buffer<ArrayBufferLike>>
A Promise that resolves with the response buffer.
-- reqBuf: Buffer
connect
Connects to the device.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
disconnect
Disconnects from the device.
-Returns Promise<void>
A Promise that resolves when the disconnection is complete.
-
discover
Discovers the device services.
-Returns Promise<Service[]>
A Promise that resolves with the list of services.
-
get
Retrieves the device characteristics.
-Returns Promise<Chars>
A Promise that resolves with the device characteristics.
-
get
Retrieves the device name.
-Returns Promise<string>
A Promise that resolves with the device name.
-
internal
Internal method to handle the connection process.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
log
Logs a message with the specified log level.
-Parameters
- level: string
The severity level of the log (e.g., 'info', 'warn', 'error').
- - message: string
The log message to be emitted.
-
Returns Promise<void>
- level: string
operate
Operates the plug with the given bytes.
-Parameters
- bytes: number[]
The byte array to send to the plug.
-
Returns Promise<boolean>
-
-
- Resolves with a boolean that tells whether the plug is ON (true) or OFF (false). -
- bytes: number[]
read
Reads the state of the plug.
-Returns Promise<boolean>
-
-
- Resolves with a boolean that tells whether the plug is ON (true) or OFF (false). -
set
Sets the device name.
-Parameters
- name: string
The new device name.
-
Returns Promise<void>
A Promise that resolves when the name is set.
-- name: string
toggle
Toggles the state of the plug.
-Returns Promise<boolean>
-
-
- Resolves with a boolean that tells whether the plug is ON (true) or OFF (false). -
turn
Turns off the plug.
-Returns Promise<boolean>
-
-
- Resolves with a boolean that tells whether the plug is ON (true) or OFF (false). -
turn
Turns on the plug.
-Returns Promise<boolean>
-
-
- Resolves with a boolean that tells whether the plug is ON (true) or OFF (false). -
unsubscribe
Unsubscribes from the notify characteristic.
-Returns Promise<void>
A Promise that resolves when the unsubscription is complete.
-
Staticparse
- parseServiceData(
manufacturerData: Buffer,
emitLog: (level: string, message: string) => void,
): Promise<null | plugMiniJPServiceData>Parses the service data for WoPlugMini JP.
-Parameters
- manufacturerData: Buffer
The manufacturer data buffer.
- - emitLog: (level: string, message: string) => void
The function to emit log messages.
-
Returns Promise<null | plugMiniJPServiceData>
-
-
- Parsed service data or null if invalid. -
- manufacturerData: Buffer
Methods
Constructors
constructor
- new WoPlugMiniJP(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoPlugMiniJPParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoPlugMiniJP
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get device status (BLE-first, API-fallback, centralized)
+Returns Promise<PlugStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
toggle
Toggle power
+Returns Promise<boolean>
turn
Turn off
+Returns Promise<boolean>
turn
Turn on
+Returns Promise<boolean>
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Class WoPlugMiniUS
Class representing a WoPlugMini device.
-Hierarchy (View Summary)
- SwitchbotDevice
- WoPlugMiniUS
Index
Constructors
Accessors
Class WoPlugMiniUS
Plug Mini (US) Device
+Hierarchy (View Summary)
- DeviceOverrideStateDuringConnection
- WoPlugMiniUS
Implements
Index
Constructors
Accessors
Methods
Methods
Constructors
constructor
Parameters
- peripheral: Peripheral
- noble: Noble
Returns WoPlugMiniUS
Accessors
address
- get address(): string
Returns string
connection
- get connectionState(): string
Returns string
friendly
Returns SwitchBotBLEModelFriendlyName
id
- get id(): string
Returns string
model
Returns SwitchBotBLEModel
model
Returns SwitchBotBLEModelName
on
- get onConnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onConnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
on
- get onDisconnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onDisconnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
Methods
command
Sends a command to the device and awaits a response.
-Parameters
- reqBuf: Buffer
The command buffer.
-
Returns Promise<Buffer<ArrayBufferLike>>
A Promise that resolves with the response buffer.
-- reqBuf: Buffer
connect
Connects to the device.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
disconnect
Disconnects from the device.
-Returns Promise<void>
A Promise that resolves when the disconnection is complete.
-
discover
Discovers the device services.
-Returns Promise<Service[]>
A Promise that resolves with the list of services.
-
get
Retrieves the device characteristics.
-Returns Promise<Chars>
A Promise that resolves with the device characteristics.
-
get
Retrieves the device name.
-Returns Promise<string>
A Promise that resolves with the device name.
-
internal
Internal method to handle the connection process.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
log
Logs a message with the specified log level.
-Parameters
- level: string
The severity level of the log (e.g., 'info', 'warn', 'error').
- - message: string
The log message to be emitted.
-
Returns Promise<void>
- level: string
operate
Operates the plug with the given bytes.
-Parameters
- bytes: number[]
The byte array to send to the plug.
-
Returns Promise<boolean>
-
-
- Resolves with a boolean that tells whether the plug is ON (true) or OFF (false). -
- bytes: number[]
read
Reads the state of the plug.
-Returns Promise<boolean>
-
-
- Resolves with a boolean that tells whether the plug is ON (true) or OFF (false). -
set
Sets the device name.
-Parameters
- name: string
The new device name.
-
Returns Promise<void>
A Promise that resolves when the name is set.
-- name: string
toggle
Toggles the state of the plug.
-Returns Promise<boolean>
-
-
- Resolves with a boolean that tells whether the plug is ON (true) or OFF (false). -
turn
Turns off the plug.
-Returns Promise<boolean>
-
-
- Resolves with a boolean that tells whether the plug is ON (true) or OFF (false). -
turn
Turns on the plug.
-Returns Promise<boolean>
-
-
- Resolves with a boolean that tells whether the plug is ON (true) or OFF (false). -
unsubscribe
Unsubscribes from the notify characteristic.
-Returns Promise<void>
A Promise that resolves when the unsubscription is complete.
-
Staticparse
- parseServiceData(
manufacturerData: Buffer,
emitLog: (level: string, message: string) => void,
): Promise<null | plugMiniUSServiceData>Parses the service data for WoPlugMini US.
-Parameters
- manufacturerData: Buffer
The manufacturer data buffer.
- - emitLog: (level: string, message: string) => void
The function to emit log messages.
-
Returns Promise<null | plugMiniUSServiceData>
-
-
- Parsed service data or null if invalid. -
- manufacturerData: Buffer
Constructors
constructor
- new WoPlugMiniUS(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoPlugMiniUSParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoPlugMiniUS
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get device status (BLE-first, API-fallback, centralized)
+Returns Promise<PlugStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
toggle
Toggle power
+Returns Promise<boolean>
turn
Turn off
+Returns Promise<boolean>
turn
Turn on
+Returns Promise<boolean>
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Class WoPresence
Class representing a WoPresence device.
-Hierarchy (View Summary)
- SwitchbotDevice
- WoPresence
Index
Constructors
Accessors
Class WoPresence
Motion/Presence Sensor
+Hierarchy (View Summary)
- SwitchBotDevice
- WoPresence
Index
Constructors
Accessors
Methods
Constructors
constructor
Parameters
- peripheral: Peripheral
- noble: Noble
Returns WoPresence
Accessors
address
- get address(): string
Returns string
connection
- get connectionState(): string
Returns string
friendly
Returns SwitchBotBLEModelFriendlyName
id
- get id(): string
Returns string
model
Returns SwitchBotBLEModel
model
Returns SwitchBotBLEModelName
on
- get onConnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onConnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
on
- get onDisconnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onDisconnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
Methods
command
Sends a command to the device and awaits a response.
-Parameters
- reqBuf: Buffer
The command buffer.
-
Returns Promise<Buffer<ArrayBufferLike>>
A Promise that resolves with the response buffer.
-- reqBuf: Buffer
connect
Connects to the device.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
disconnect
Disconnects from the device.
-Returns Promise<void>
A Promise that resolves when the disconnection is complete.
-
discover
Discovers the device services.
-Returns Promise<Service[]>
A Promise that resolves with the list of services.
-
get
Retrieves the device characteristics.
-Returns Promise<Chars>
A Promise that resolves with the device characteristics.
-
get
Retrieves the device name.
-Returns Promise<string>
A Promise that resolves with the device name.
-
internal
Internal method to handle the connection process.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
log
Logs a message with the specified log level.
-Parameters
- level: string
The severity level of the log (e.g., 'info', 'warn', 'error').
- - message: string
The log message to be emitted.
-
Returns Promise<void>
- level: string
set
Sets the device name.
-Parameters
- name: string
The new device name.
-
Returns Promise<void>
A Promise that resolves when the name is set.
-- name: string
unsubscribe
Unsubscribes from the notify characteristic.
-Returns Promise<void>
A Promise that resolves when the unsubscription is complete.
-
Staticparse
- parsePresenceSensorServiceData(
serviceData: null | Buffer<ArrayBufferLike>,
manufacturerData: Buffer,
emitLog: (level: string, message: string) => void,
): Promise<null | presenceSensorServiceData>Parses the manufacturer data for presence sensors.
-Parameters
- serviceData: null | Buffer<ArrayBufferLike>
The optional service data buffer.
- - manufacturerData: Buffer
The manufacturer data buffer.
- - emitLog: (level: string, message: string) => void
The function to emit log messages.
-
Returns Promise<null | presenceSensorServiceData>
-
-
- Parsed service data or null if invalid. -
- serviceData: null | Buffer<ArrayBufferLike>
Staticparse
- parseServiceData(
serviceData: Buffer,
emitLog: (level: string, message: string) => void,
): Promise<null | motionSensorServiceData>Parses the service data for WoPresence.
-Parameters
- serviceData: Buffer
The service data buffer.
- - emitLog: (level: string, message: string) => void
The function to emit log messages.
-
Returns Promise<null | motionSensorServiceData>
-
-
- Parsed service data or null if invalid. -
- serviceData: Buffer
Methods
Constructors
constructor
- new WoPresence(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoPresenceParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoPresence
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get device status (BLE-first, API-fallback)
+Returns Promise<MotionStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Class WoRGBICBulb
RGBIC Bulb Device with segmented/multi-zone color control +Supports individual LED segment control for addressable RGB+IC strips
+Hierarchy (View Summary)
- WoBulb
- WoRGBICBulb
Implements
- RGBICBulbCommands
Index
Constructors
Properties
Accessors
Methods
Constructors
constructor
- new WoRGBICBulb(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoRGBICBulbParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoRGBICBulb
Properties
StaticEFFECTS
Preset effect name to effect ID mapping
+Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get device status (inherited from WoBulb, centralized fallback)
+Returns Promise<RGBICBulbStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Strip Light 3 and complex light patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex light patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Set brightness (0-100)
+Parameters
- brightness: number
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Set RGB color
+Parameters
- red: number
- green: number
- blue: number
Returns Promise<boolean>
set
Set color temperature with min/max bounds +For advanced bulbs that support color temperature range control
+Parameters
- minTemp: number
- maxTemp: number
- temp: number
Returns Promise<boolean>
set
Set color temperature (2700-6500K)
+Parameters
- temperature: number
Returns Promise<boolean>
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Set preset light effect
+Parameters
- effectName: string
- speed: number = 100
Returns Promise<boolean>
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
set
Set color for individual LED segment
+Parameters
- segmentId: number
Segment identifier (0-based index)
+ - red: number
Red value (0-255)
+ - green: number
Green value (0-255)
+ - blue: number
Blue value (0-255)
+
Returns Promise<boolean>
- segmentId: number
set
Set effect for individual LED segment
+Parameters
- segmentId: number
Segment identifier (0-based index)
+ - effectName: string
Effect name from RGBIC_EFFECTS
+ - speed: number = 50
Effect speed (1-100, default: 50)
+
Returns Promise<boolean>
- segmentId: number
turn
Turn off
+Returns Promise<boolean>
turn
Turn on
+Returns Promise<boolean>
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
verify
Verifies the BLE encryption key by attempting a status read with encryption. +Throws an error if the key is invalid or the device rejects the command.
+Returns Promise<boolean>
Class WoRGBICNeonWireRopeLight
Base class for all SwitchBot devices
+BLE-first, API-fallback Logic
+This class provides a centralized, robust hybrid connection strategy for all SwitchBot devices:
+-
+
- BLE-first, API-fallback: By default, status and command methods attempt BLE first (if available), then fall back to OpenAPI if BLE fails or is unavailable. This is controlled by
preferredConnectionandenableFallback.
+ - Centralized Fallback: The
getStatusWithFallback()andsendCommand()methods implement this logic. Device subclasses should call these methods and provide normalization/mapping as needed.
+ - Connection Intelligence: Tracks connection health and performance, automatically preferring the most reliable connection if enabled. +
- Circuit Breaker & Retry: Both BLE and API commands are protected by circuit breaker and retry logic to handle transient failures gracefully. +
Usage in Subclasses
+-
+
- For status: Call
await this.getStatusWithFallback(normalizeBLE, normalizeAPI)in yourgetStatus()implementation.
+ - For commands: Use
await this.sendCommand(bleCommand, apiCommand, apiParameter)to automatically select the best connection and handle fallback.
+ - For custom logic: You may override or extend these methods, but should preserve the fallback and error-handling patterns for consistency. +
Example (in a device subclass)
+async getStatus(): Promise<DeviceStatus> {
return this.getStatusWithFallback(
bleData => ({ ... }), // normalize BLE data
apiData => ({ ... }), // normalize API data
)
}
async turnOn(): Promise<boolean> {
const result = await this.sendCommand([0x57, 0x01, 0x01], 'turnOn')
return result.success
}
+Configuration
+-
+
preferredConnection: 'ble' | 'api' (default: 'ble')
+enableFallback: boolean (default: true)
+enableConnectionIntelligence: boolean (default: true)
+enableCircuitBreaker: boolean (default: true)
+enableRetry: boolean (default: true)
+
See Also
+-
+
getStatusWithFallback()
+sendCommand()
+hasBLE(),hasAPI()
+setPreferredConnection(),setFallbackEnabled()
+
This pattern ensures all device classes benefit from robust, testable, and consistent connection logic.
+Hierarchy (View Summary)
- SwitchBotDevice
- WoRGBICNeonWireRopeLight
Index
Constructors
Accessors
Methods
Constructors
constructor
- new WoRGBICNeonWireRopeLight(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoRGBICNeonWireRopeLightParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoRGBICNeonWireRopeLight
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get device status (BLE-first/API-fallback, centralized)
+Returns Promise<RGBICBulbStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Set brightness (1-100)
+Parameters
- level: number
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Set color (RGB)
+Parameters
- red: number
- green: number
- blue: number
Returns Promise<boolean>
set
Set color temperature (Kelvin)
+Parameters
- temperature: number
Returns Promise<boolean>
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
turn
Turn off the neon wire rope light
+Returns Promise<boolean>
turn
Turn on the neon wire rope light
+Returns Promise<boolean>
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Class WoRGBICWWFloorLamp
RGBICWW Floor Lamp Device +Uses same logic as RGBIC Bulb with segmented control
+Hierarchy (View Summary)
- WoRGBICBulb
- WoRGBICWWFloorLamp
Index
Constructors
Properties
Accessors
Methods
Constructors
constructor
- new WoRGBICWWFloorLamp(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoRGBICWWFloorLampParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoRGBICWWFloorLamp
Properties
StaticEFFECTS
Preset effect name to effect ID mapping
+Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get device status (inherited from WoBulb, centralized fallback)
+Returns Promise<RGBICBulbStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Strip Light 3 and complex light patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex light patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Set brightness (0-100)
+Parameters
- brightness: number
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Set RGB color
+Parameters
- red: number
- green: number
- blue: number
Returns Promise<boolean>
set
Set color temperature with min/max bounds +For advanced bulbs that support color temperature range control
+Parameters
- minTemp: number
- maxTemp: number
- temp: number
Returns Promise<boolean>
set
Set color temperature (2700-6500K)
+Parameters
- temperature: number
Returns Promise<boolean>
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Set preset light effect
+Parameters
- effectName: string
- speed: number = 100
Returns Promise<boolean>
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
set
Set color for individual LED segment
+Parameters
- segmentId: number
Segment identifier (0-based index)
+ - red: number
Red value (0-255)
+ - green: number
Green value (0-255)
+ - blue: number
Blue value (0-255)
+
Returns Promise<boolean>
- segmentId: number
set
Set effect for individual LED segment
+Parameters
- segmentId: number
Segment identifier (0-based index)
+ - effectName: string
Effect name from RGBIC_EFFECTS
+ - speed: number = 50
Effect speed (1-100, default: 50)
+
Returns Promise<boolean>
- segmentId: number
turn
Turn off
+Returns Promise<boolean>
turn
Turn on
+Returns Promise<boolean>
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
verify
Verifies the BLE encryption key by attempting a status read with encryption. +Throws an error if the key is invalid or the device rejects the command.
+Returns Promise<boolean>
Class WoRGBICWWStripLight
RGBICWW Strip Light Device +Uses same logic as RGBIC Bulb with segmented control
+Hierarchy (View Summary)
- WoRGBICBulb
- WoRGBICWWStripLight
Index
Constructors
Properties
Accessors
Methods
Constructors
constructor
- new WoRGBICWWStripLight(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoRGBICWWStripLightParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoRGBICWWStripLight
Properties
StaticEFFECTS
Preset effect name to effect ID mapping
+Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get device status (inherited from WoBulb, centralized fallback)
+Returns Promise<RGBICBulbStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Strip Light 3 and complex light patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex light patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Set brightness (0-100)
+Parameters
- brightness: number
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Set RGB color
+Parameters
- red: number
- green: number
- blue: number
Returns Promise<boolean>
set
Set color temperature with min/max bounds +For advanced bulbs that support color temperature range control
+Parameters
- minTemp: number
- maxTemp: number
- temp: number
Returns Promise<boolean>
set
Set color temperature (2700-6500K)
+Parameters
- temperature: number
Returns Promise<boolean>
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Set preset light effect
+Parameters
- effectName: string
- speed: number = 100
Returns Promise<boolean>
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
set
Set color for individual LED segment
+Parameters
- segmentId: number
Segment identifier (0-based index)
+ - red: number
Red value (0-255)
+ - green: number
Green value (0-255)
+ - blue: number
Blue value (0-255)
+
Returns Promise<boolean>
- segmentId: number
set
Set effect for individual LED segment
+Parameters
- segmentId: number
Segment identifier (0-based index)
+ - effectName: string
Effect name from RGBIC_EFFECTS
+ - speed: number = 50
Effect speed (1-100, default: 50)
+
Returns Promise<boolean>
- segmentId: number
turn
Turn off
+Returns Promise<boolean>
turn
Turn on
+Returns Promise<boolean>
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
verify
Verifies the BLE encryption key by attempting a status read with encryption. +Throws an error if the key is invalid or the device rejects the command.
+Returns Promise<boolean>
Class WoRelaySwitch1
Class representing a WoRelaySwitch1 device.
-Hierarchy (View Summary)
- SwitchbotDevice
- WoRelaySwitch1
Index
Constructors
Accessors
Class WoRelaySwitch1
Relay Switch 1 Device (1-channel)
+Hierarchy (View Summary)
Implements
Index
Constructors
Accessors
Methods
Methods
Constructors
constructor
Parameters
- peripheral: Peripheral
- noble: Noble
Returns WoRelaySwitch1
Accessors
address
- get address(): string
Returns string
connection
- get connectionState(): string
Returns string
friendly
Returns SwitchBotBLEModelFriendlyName
id
- get id(): string
Returns string
model
Returns SwitchBotBLEModel
model
Returns SwitchBotBLEModelName
on
- get onConnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onConnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
on
- get onDisconnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onDisconnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
Methods
command
Sends a command to the device and awaits a response.
-Parameters
- reqBuf: Buffer
The command buffer.
-
Returns Promise<Buffer<ArrayBufferLike>>
A Promise that resolves with the response buffer.
-- reqBuf: Buffer
connect
Connects to the device.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
disconnect
Disconnects from the device.
-Returns Promise<void>
A Promise that resolves when the disconnection is complete.
-
discover
Discovers the device services.
-Returns Promise<Service[]>
A Promise that resolves with the list of services.
-
get
Retrieves the device characteristics.
-Returns Promise<Chars>
A Promise that resolves with the device characteristics.
-
get
Retrieves the device name.
-Returns Promise<string>
A Promise that resolves with the device name.
-
internal
Internal method to handle the connection process.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
log
Logs a message with the specified log level.
-Parameters
- level: string
The severity level of the log (e.g., 'info', 'warn', 'error').
- - message: string
The log message to be emitted.
-
Returns Promise<void>
- level: string
set
Sets the device name.
-Parameters
- name: string
The new device name.
-
Returns Promise<void>
A Promise that resolves when the name is set.
-- name: string
turn
Turns off the bot.
-Returns Promise<void>
turn
Turns on the bot.
-Returns Promise<void>
unsubscribe
Unsubscribes from the notify characteristic.
-Returns Promise<void>
A Promise that resolves when the unsubscription is complete.
-
Staticparse
- parseServiceData(
serviceData: Buffer,
manufacturerData: Buffer,
emitLog: (level: string, message: string) => void,
): Promise<null | relaySwitch1ServiceData>Parses the service data for WoRelaySwitch1.
-Parameters
- serviceData: Buffer
The service data buffer.
- - manufacturerData: Buffer
The manufacturer data buffer.
- - emitLog: (level: string, message: string) => void
The function to emit log messages.
-
Returns Promise<null | relaySwitch1ServiceData>
-
-
- Parsed service data or null if invalid. -
- serviceData: Buffer
Constructors
constructor
- new WoRelaySwitch1(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoRelaySwitch1Parameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoRelaySwitch1
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get device status (BLE-first, API-fallback)
+Returns Promise<RelaySwitchStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
toggle
Toggle power
+Returns Promise<boolean>
turn
Turn off
+Returns Promise<boolean>
turn
Turn on
+Returns Promise<boolean>
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Refresh status for this device. Called automatically after sequence changes.
+Returns Promise<DeviceStatus>
update
Update device information and react to sequence number changes.
+Parameters
- newInfo: Partial<DeviceInfo>
Returns void
verify
Verifies the BLE encryption key by attempting a status read with encryption. +Throws an error if the key is invalid or the device rejects the command.
+Returns Promise<boolean>
Class WoRelaySwitch1PM
Class representing a WoRelaySwitch1PM device.
-Hierarchy (View Summary)
- SwitchbotDevice
- WoRelaySwitch1PM
Index
Constructors
Accessors
Class WoRelaySwitch1PM
Relay Switch 1PM Device (1-channel with power monitoring) +Uses same logic as Relay Switch 1
+Hierarchy (View Summary)
- WoRelaySwitch1
- WoRelaySwitch1PM
Index
Constructors
Accessors
Methods
Constructors
constructor
Parameters
- peripheral: Peripheral
- noble: Noble
Returns WoRelaySwitch1PM
Accessors
address
- get address(): string
Returns string
connection
- get connectionState(): string
Returns string
friendly
Returns SwitchBotBLEModelFriendlyName
id
- get id(): string
Returns string
model
Returns SwitchBotBLEModel
model
Returns SwitchBotBLEModelName
on
- get onConnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onConnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
on
- get onDisconnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onDisconnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
Methods
command
Sends a command to the device and awaits a response.
-Parameters
- reqBuf: Buffer
The command buffer.
-
Returns Promise<Buffer<ArrayBufferLike>>
A Promise that resolves with the response buffer.
-- reqBuf: Buffer
connect
Connects to the device.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
disconnect
Disconnects from the device.
-Returns Promise<void>
A Promise that resolves when the disconnection is complete.
-
discover
Discovers the device services.
-Returns Promise<Service[]>
A Promise that resolves with the list of services.
-
get
Retrieves the device characteristics.
-Returns Promise<Chars>
A Promise that resolves with the device characteristics.
-
get
Retrieves the device name.
-Returns Promise<string>
A Promise that resolves with the device name.
-
internal
Internal method to handle the connection process.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
log
Logs a message with the specified log level.
-Parameters
- level: string
The severity level of the log (e.g., 'info', 'warn', 'error').
- - message: string
The log message to be emitted.
-
Returns Promise<void>
- level: string
set
Sets the device name.
-Parameters
- name: string
The new device name.
-
Returns Promise<void>
A Promise that resolves when the name is set.
-- name: string
turn
Turns off the bot.
-Returns Promise<void>
turn
Turns on the bot.
-Returns Promise<void>
unsubscribe
Unsubscribes from the notify characteristic.
-Returns Promise<void>
A Promise that resolves when the unsubscription is complete.
-
Staticparse
- parseServiceData(
serviceData: Buffer,
manufacturerData: Buffer,
emitLog: (level: string, message: string) => void,
): Promise<null | relaySwitch1PMServiceData>Parses the service data for WoRelaySwitch1PM.
-Parameters
- serviceData: Buffer
The service data buffer.
- - manufacturerData: Buffer
The manufacturer data buffer.
- - emitLog: (level: string, message: string) => void
The function to emit log messages.
-
Returns Promise<null | relaySwitch1PMServiceData>
-
-
- Parsed service data or null if invalid. -
- serviceData: Buffer
Methods
Constructors
constructor
- new WoRelaySwitch1PM(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoRelaySwitch1PMParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoRelaySwitch1PM
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get device status (BLE-first, API-fallback)
+Returns Promise<RelaySwitchStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
toggle
Toggle power
+Returns Promise<boolean>
turn
Turn off
+Returns Promise<boolean>
turn
Turn on
+Returns Promise<boolean>
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Refresh status for this device. Called automatically after sequence changes.
+Returns Promise<DeviceStatus>
update
Update device information and react to sequence number changes.
+Parameters
- newInfo: Partial<DeviceInfo>
Returns void
verify
Verifies the BLE encryption key by attempting a status read with encryption. +Throws an error if the key is invalid or the device rejects the command.
+Returns Promise<boolean>
Class WoRelaySwitch2PM
Relay Switch 2PM Device (2-channel with power monitoring) +Extends Relay Switch 1 with channel-specific control
+Hierarchy (View Summary)
- WoRelaySwitch1
- WoRelaySwitch2PM
Implements
- RelaySwitchChannelCommands
Index
Constructors
Accessors
Methods
Constructors
constructor
- new WoRelaySwitch2PM(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoRelaySwitch2PMParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoRelaySwitch2PM
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get device status (inherited, same as 1PM)
+Returns Promise<RelaySwitchStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Set channel 1 state
+Parameters
- state: boolean
Returns Promise<boolean>
set
Set channel 2 state
+Parameters
- state: boolean
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
toggle
Toggle power
+Returns Promise<boolean>
turn
Turn off
+Returns Promise<boolean>
turn
Turn on
+Returns Promise<boolean>
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Refresh status for this device. Called automatically after sequence changes.
+Returns Promise<DeviceStatus>
update
Update device information and react to sequence number changes.
+Parameters
- newInfo: Partial<DeviceInfo>
Returns void
verify
Verifies the BLE encryption key by attempting a status read with encryption. +Throws an error if the key is invalid or the device rejects the command.
+Returns Promise<boolean>
Class WoRemote
Class representing a WoRemote device.
-Hierarchy (View Summary)
- SwitchbotDevice
- WoRemote
Index
Constructors
Accessors
Class WoRemote
Remote Device (IR remote control) +Note: Remote is read-only for battery status
+Hierarchy (View Summary)
- SwitchBotDevice
- WoRemote
Index
Constructors
Accessors
Methods
Constructors
constructor
Parameters
- peripheral: Peripheral
- noble: Noble
Returns WoRemote
Accessors
address
- get address(): string
Returns string
connection
- get connectionState(): string
Returns string
friendly
Returns SwitchBotBLEModelFriendlyName
id
- get id(): string
Returns string
model
Returns SwitchBotBLEModel
model
Returns SwitchBotBLEModelName
on
- get onConnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onConnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
on
- get onDisconnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onDisconnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
Methods
command
Sends a command to the device and awaits a response.
-Parameters
- reqBuf: Buffer
The command buffer.
-
Returns Promise<Buffer<ArrayBufferLike>>
A Promise that resolves with the response buffer.
-- reqBuf: Buffer
connect
Connects to the device.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
disconnect
Disconnects from the device.
-Returns Promise<void>
A Promise that resolves when the disconnection is complete.
-
discover
Discovers the device services.
-Returns Promise<Service[]>
A Promise that resolves with the list of services.
-
get
Retrieves the device characteristics.
-Returns Promise<Chars>
A Promise that resolves with the device characteristics.
-
get
Retrieves the device name.
-Returns Promise<string>
A Promise that resolves with the device name.
-
internal
Internal method to handle the connection process.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
log
Logs a message with the specified log level.
-Parameters
- level: string
The severity level of the log (e.g., 'info', 'warn', 'error').
- - message: string
The log message to be emitted.
-
Returns Promise<void>
- level: string
set
Sets the device name.
-Parameters
- name: string
The new device name.
-
Returns Promise<void>
A Promise that resolves when the name is set.
-- name: string
unsubscribe
Unsubscribes from the notify characteristic.
-Returns Promise<void>
A Promise that resolves when the unsubscription is complete.
-
Staticparse
- parseServiceData(
serviceData: Buffer,
emitLog: (level: string, message: string) => void,
): Promise<null | remoteServiceData>Parses the service data for WoRemote.
-Parameters
- serviceData: Buffer
The service data buffer.
- - emitLog: (level: string, message: string) => void
The function to emit log messages.
-
Returns Promise<null | remoteServiceData>
-
-
- Parsed service data or null if invalid. -
- serviceData: Buffer
Methods
Constructors
constructor
- new WoRemote(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoRemoteParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoRemote
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get device status (BLE-first, API-fallback)
+Returns Promise<RemoteStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Class WoRemoteWithScreen
Base class for all SwitchBot devices
+BLE-first, API-fallback Logic
+This class provides a centralized, robust hybrid connection strategy for all SwitchBot devices:
+-
+
- BLE-first, API-fallback: By default, status and command methods attempt BLE first (if available), then fall back to OpenAPI if BLE fails or is unavailable. This is controlled by
preferredConnectionandenableFallback.
+ - Centralized Fallback: The
getStatusWithFallback()andsendCommand()methods implement this logic. Device subclasses should call these methods and provide normalization/mapping as needed.
+ - Connection Intelligence: Tracks connection health and performance, automatically preferring the most reliable connection if enabled. +
- Circuit Breaker & Retry: Both BLE and API commands are protected by circuit breaker and retry logic to handle transient failures gracefully. +
Usage in Subclasses
+-
+
- For status: Call
await this.getStatusWithFallback(normalizeBLE, normalizeAPI)in yourgetStatus()implementation.
+ - For commands: Use
await this.sendCommand(bleCommand, apiCommand, apiParameter)to automatically select the best connection and handle fallback.
+ - For custom logic: You may override or extend these methods, but should preserve the fallback and error-handling patterns for consistency. +
Example (in a device subclass)
+async getStatus(): Promise<DeviceStatus> {
return this.getStatusWithFallback(
bleData => ({ ... }), // normalize BLE data
apiData => ({ ... }), // normalize API data
)
}
async turnOn(): Promise<boolean> {
const result = await this.sendCommand([0x57, 0x01, 0x01], 'turnOn')
return result.success
}
+Configuration
+-
+
preferredConnection: 'ble' | 'api' (default: 'ble')
+enableFallback: boolean (default: true)
+enableConnectionIntelligence: boolean (default: true)
+enableCircuitBreaker: boolean (default: true)
+enableRetry: boolean (default: true)
+
See Also
+-
+
getStatusWithFallback()
+sendCommand()
+hasBLE(),hasAPI()
+setPreferredConnection(),setFallbackEnabled()
+
This pattern ensures all device classes benefit from robust, testable, and consistent connection logic.
+Hierarchy (View Summary)
- SwitchBotDevice
- WoRemoteWithScreen
Index
Constructors
Accessors
Methods
Constructors
constructor
- new WoRemoteWithScreen(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoRemoteWithScreenParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoRemoteWithScreen
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get device status (BLE-first, API-fallback)
+Returns Promise<DeviceStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Class WoRollerShade
Roller Shade Device +Uses same logic as Curtain (motorized window covering)
+Hierarchy (View Summary)
- WoCurtain
- WoRollerShade
Index
Constructors
Properties
Accessors
Methods
Constructors
constructor
- new WoRollerShade(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoRollerShadeParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoRollerShade
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
close
Close curtain (position 100%)
+Parameters
- speed: number = 255
Returns Promise<boolean>
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get extended device information (Curtain 3) +Returns device chain information and grouped curtain status
+Returns Promise<CurtainExtendedInfo>
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Returns Promise<CurtainStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
open
Open curtain (position 0%)
+Parameters
- speed: number = 255
Returns Promise<boolean>
pause
Pause curtain movement
+Returns Promise<boolean>
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3 complex operations
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for Curtain 3 fallback operations
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
Set curtain position (0-100%)
+Parameters
- position: number
- speed: number = 255
Returns Promise<boolean>
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Class WoSensorTH
Class representing a WoSensorTH device.
-Hierarchy (View Summary)
- SwitchbotDevice
- WoSensorTH
Index
Constructors
Accessors
Class WoSensorTH
Meter (Temperature/Humidity Sensor)
+Hierarchy (View Summary)
Index
Constructors
Accessors
Methods
Constructors
constructor
Parameters
- peripheral: Peripheral
- noble: Noble
Returns WoSensorTH
Accessors
address
- get address(): string
Returns string
connection
- get connectionState(): string
Returns string
friendly
Returns SwitchBotBLEModelFriendlyName
id
- get id(): string
Returns string
model
Returns SwitchBotBLEModel
model
Returns SwitchBotBLEModelName
on
- get onConnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onConnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
on
- get onDisconnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onDisconnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
Methods
command
Sends a command to the device and awaits a response.
-Parameters
- reqBuf: Buffer
The command buffer.
-
Returns Promise<Buffer<ArrayBufferLike>>
A Promise that resolves with the response buffer.
-- reqBuf: Buffer
connect
Connects to the device.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
disconnect
Disconnects from the device.
-Returns Promise<void>
A Promise that resolves when the disconnection is complete.
-
discover
Discovers the device services.
-Returns Promise<Service[]>
A Promise that resolves with the list of services.
-
get
Retrieves the device characteristics.
-Returns Promise<Chars>
A Promise that resolves with the device characteristics.
-
get
Retrieves the device name.
-Returns Promise<string>
A Promise that resolves with the device name.
-
internal
Internal method to handle the connection process.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
log
Logs a message with the specified log level.
-Parameters
- level: string
The severity level of the log (e.g., 'info', 'warn', 'error').
- - message: string
The log message to be emitted.
-
Returns Promise<void>
- level: string
set
Sets the device name.
-Parameters
- name: string
The new device name.
-
Returns Promise<void>
A Promise that resolves when the name is set.
-- name: string
unsubscribe
Unsubscribes from the notify characteristic.
-Returns Promise<void>
A Promise that resolves when the unsubscription is complete.
-
Staticparse
- parseServiceData(
serviceData: Buffer,
emitLog: (level: string, message: string) => void,
): Promise<null | meterServiceData>Parameters
- serviceData: Buffer
- emitLog: (level: string, message: string) => void
Returns Promise<null | meterServiceData>
Methods
Constructors
constructor
- new WoSensorTH(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoSensorTHParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoSensorTH
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get device status (BLE-first, API-fallback)
+Returns Promise<MeterStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Class WoSensorTHPlus
Class representing a WoSensorTH device.
-Hierarchy (View Summary)
- SwitchbotDevice
- WoSensorTHPlus
Index
Constructors
Accessors
Class WoSensorTHPlus
Meter Plus (Temperature/Humidity Sensor with screen) +Uses same logic as standard Meter
+Hierarchy (View Summary)
- WoSensorTH
- WoSensorTHPlus
Index
Constructors
Accessors
Methods
Constructors
constructor
Parameters
- peripheral: Peripheral
- noble: Noble
Returns WoSensorTHPlus
Accessors
address
- get address(): string
Returns string
connection
- get connectionState(): string
Returns string
friendly
Returns SwitchBotBLEModelFriendlyName
id
- get id(): string
Returns string
model
Returns SwitchBotBLEModel
model
Returns SwitchBotBLEModelName
on
- get onConnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onConnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
on
- get onDisconnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onDisconnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
Methods
command
Sends a command to the device and awaits a response.
-Parameters
- reqBuf: Buffer
The command buffer.
-
Returns Promise<Buffer<ArrayBufferLike>>
A Promise that resolves with the response buffer.
-- reqBuf: Buffer
connect
Connects to the device.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
disconnect
Disconnects from the device.
-Returns Promise<void>
A Promise that resolves when the disconnection is complete.
-
discover
Discovers the device services.
-Returns Promise<Service[]>
A Promise that resolves with the list of services.
-
get
Retrieves the device characteristics.
-Returns Promise<Chars>
A Promise that resolves with the device characteristics.
-
get
Retrieves the device name.
-Returns Promise<string>
A Promise that resolves with the device name.
-
internal
Internal method to handle the connection process.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
log
Logs a message with the specified log level.
-Parameters
- level: string
The severity level of the log (e.g., 'info', 'warn', 'error').
- - message: string
The log message to be emitted.
-
Returns Promise<void>
- level: string
set
Sets the device name.
-Parameters
- name: string
The new device name.
-
Returns Promise<void>
A Promise that resolves when the name is set.
-- name: string
unsubscribe
Unsubscribes from the notify characteristic.
-Returns Promise<void>
A Promise that resolves when the unsubscription is complete.
-
Staticparse
- parseServiceData(
serviceData: Buffer,
emitLog: (level: string, message: string) => void,
): Promise<null | meterPlusServiceData>Parameters
- serviceData: Buffer
- emitLog: (level: string, message: string) => void
Returns Promise<null | meterPlusServiceData>
Methods
Constructors
constructor
- new WoSensorTHPlus(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoSensorTHPlusParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoSensorTHPlus
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get device status (BLE-first, API-fallback)
+Returns Promise<MeterStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Class WoSensorTHPro
Class representing a WoSensorTH device.
-Hierarchy (View Summary)
- SwitchbotDevice
- WoSensorTHPro
Index
Constructors
Accessors
Class WoSensorTHPro
Meter Pro (Advanced Temperature/Humidity Sensor) +Uses same logic as standard Meter
+Hierarchy (View Summary)
- WoSensorTH
- WoSensorTHPro
Index
Constructors
Accessors
Methods
Constructors
constructor
Parameters
- peripheral: Peripheral
- noble: Noble
Returns WoSensorTHPro
Accessors
address
- get address(): string
Returns string
connection
- get connectionState(): string
Returns string
friendly
Returns SwitchBotBLEModelFriendlyName
id
- get id(): string
Returns string
model
Returns SwitchBotBLEModel
model
Returns SwitchBotBLEModelName
on
- get onConnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onConnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
on
- get onDisconnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onDisconnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
Methods
command
Sends a command to the device and awaits a response.
-Parameters
- reqBuf: Buffer
The command buffer.
-
Returns Promise<Buffer<ArrayBufferLike>>
A Promise that resolves with the response buffer.
-- reqBuf: Buffer
connect
Connects to the device.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
disconnect
Disconnects from the device.
-Returns Promise<void>
A Promise that resolves when the disconnection is complete.
-
discover
Discovers the device services.
-Returns Promise<Service[]>
A Promise that resolves with the list of services.
-
get
Retrieves the device characteristics.
-Returns Promise<Chars>
A Promise that resolves with the device characteristics.
-
get
Retrieves the device name.
-Returns Promise<string>
A Promise that resolves with the device name.
-
internal
Internal method to handle the connection process.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
log
Logs a message with the specified log level.
-Parameters
- level: string
The severity level of the log (e.g., 'info', 'warn', 'error').
- - message: string
The log message to be emitted.
-
Returns Promise<void>
- level: string
set
Sets the device name.
-Parameters
- name: string
The new device name.
-
Returns Promise<void>
A Promise that resolves when the name is set.
-- name: string
unsubscribe
Unsubscribes from the notify characteristic.
-Returns Promise<void>
A Promise that resolves when the unsubscription is complete.
-
Staticparse
- parseServiceData(
serviceData: Buffer,
emitLog: (level: string, message: string) => void,
): Promise<null | meterProServiceData>Parameters
- serviceData: Buffer
- emitLog: (level: string, message: string) => void
Returns Promise<null | meterProServiceData>
Methods
Constructors
constructor
- new WoSensorTHPro(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoSensorTHProParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoSensorTHPro
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get device status (BLE-first, API-fallback)
+Returns Promise<MeterStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Class WoSensorTHProCO2
Class representing a WoSensorTH device.
-Hierarchy (View Summary)
- SwitchbotDevice
- WoSensorTHProCO2
Index
Constructors
Accessors
Class WoSensorTHProCO2
Meter Pro CO2 (Temperature/Humidity/CO2 Sensor) +Use same logic as standard Meter (CO2 data available in extended status)
+Hierarchy (View Summary)
- WoSensorTH
- WoSensorTHProCO2
Index
Constructors
Accessors
Methods
Constructors
constructor
Parameters
- peripheral: Peripheral
- noble: Noble
Returns WoSensorTHProCO2
Accessors
address
- get address(): string
Returns string
connection
- get connectionState(): string
Returns string
friendly
Returns SwitchBotBLEModelFriendlyName
id
- get id(): string
Returns string
model
Returns SwitchBotBLEModel
model
Returns SwitchBotBLEModelName
on
- get onConnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onConnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
on
- get onDisconnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onDisconnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
Methods
command
Sends a command to the device and awaits a response.
-Parameters
- reqBuf: Buffer
The command buffer.
-
Returns Promise<Buffer<ArrayBufferLike>>
A Promise that resolves with the response buffer.
-- reqBuf: Buffer
connect
Connects to the device.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
disconnect
Disconnects from the device.
-Returns Promise<void>
A Promise that resolves when the disconnection is complete.
-
discover
Discovers the device services.
-Returns Promise<Service[]>
A Promise that resolves with the list of services.
-
get
Retrieves the device characteristics.
-Returns Promise<Chars>
A Promise that resolves with the device characteristics.
-
get
Retrieves the device name.
-Returns Promise<string>
A Promise that resolves with the device name.
-
internal
Internal method to handle the connection process.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
log
Logs a message with the specified log level.
-Parameters
- level: string
The severity level of the log (e.g., 'info', 'warn', 'error').
- - message: string
The log message to be emitted.
-
Returns Promise<void>
- level: string
set
Sets the device name.
-Parameters
- name: string
The new device name.
-
Returns Promise<void>
A Promise that resolves when the name is set.
-- name: string
unsubscribe
Unsubscribes from the notify characteristic.
-Returns Promise<void>
A Promise that resolves when the unsubscription is complete.
-
Staticparse
- parseServiceData(
serviceData: Buffer,
manufacturerData: Buffer,
emitLog: (level: string, message: string) => void,
): Promise<null | meterProCO2ServiceData>Parameters
- serviceData: Buffer
- manufacturerData: Buffer
- emitLog: (level: string, message: string) => void
Returns Promise<null | meterProCO2ServiceData>
Methods
Constructors
constructor
- new WoSensorTHProCO2(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoSensorTHProCO2Parameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoSensorTHProCO2
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get device status (BLE-first, API-fallback)
+Returns Promise<MeterStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Class WoSmartLock
Class representing a WoSmartLock device.
-Hierarchy (View Summary)
- SwitchbotDevice
- WoSmartLock
Index
Constructors
Properties
Accessors
Class WoSmartLock
Smart Lock Device
+Hierarchy (View Summary)
Implements
Index
Constructors
Accessors
Methods
Methods
Constructors
constructor
Parameters
- peripheral: Peripheral
- noble: Noble
Returns WoSmartLock
Properties
encryption_
iv
key_
StaticResult
Accessors
address
- get address(): string
Returns string
connection
- get connectionState(): string
Returns string
friendly
Returns SwitchBotBLEModelFriendlyName
id
- get id(): string
Returns string
model
Returns SwitchBotBLEModel
model
Returns SwitchBotBLEModelName
on
- get onConnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onConnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
on
- get onDisconnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onDisconnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
Methods
command
Sends a command to the device and awaits a response.
-Parameters
- reqBuf: Buffer
The command buffer.
-
Returns Promise<Buffer<ArrayBufferLike>>
A Promise that resolves with the response buffer.
-- reqBuf: Buffer
connect
Connects to the device.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
decrypt
Decrypts a buffer using AES-128-CTR.
-Parameters
- data: Buffer
The data to decrypt.
-
Returns Promise<Buffer<ArrayBufferLike>>
-
-
- The decrypted data. -
- data: Buffer
disconnect
Disconnects from the device.
-Returns Promise<void>
A Promise that resolves when the disconnection is complete.
-
discover
Discovers the device services.
-Returns Promise<Service[]>
A Promise that resolves with the list of services.
-
encrypt
Encrypts a string using AES-128-CTR.
-Parameters
- str: string
The string to encrypt.
-
Returns Promise<string>
-
-
- The encrypted string in hex format. -
- str: string
encrypted
Sends an encrypted command to the device.
-Parameters
- key: string
The command key.
-
Returns Promise<Buffer<ArrayBufferLike>>
-
-
- The response buffer. -
- key: string
get
Retrieves the device characteristics.
-Returns Promise<Chars>
A Promise that resolves with the device characteristics.
-
get
Retrieves the device name.
-Returns Promise<string>
A Promise that resolves with the device name.
-
get
Retrieves the IV from the device.
-Returns Promise<Buffer<ArrayBufferLike>>
-
-
- The IV buffer. -
info
Gets general state info from the Smart Lock.
-Returns Promise<null | object>
-
-
- The state object or null if an error occurred. -
internal
Internal method to handle the connection process.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
lock
Locks the Smart Lock.
-Returns Promise<number>
-
-
- The result of the lock operation. -
log
Logs a message with the specified log level.
-Parameters
- level: string
The severity level of the log (e.g., 'info', 'warn', 'error').
- - message: string
The log message to be emitted.
-
Returns Promise<void>
- level: string
operate
Operates the lock with the given command.
-Parameters
- key: string
The command key.
- Optionalencrypt: boolean = trueWhether to encrypt the command.
-
Returns Promise<Buffer<ArrayBufferLike>>
-
-
- The response buffer. -
- key: string
set
Sets the device name.
-Parameters
- name: string
The new device name.
-
Returns Promise<void>
A Promise that resolves when the name is set.
-- name: string
set
Initializes the encryption key info for valid lock communication.
-Parameters
- keyId: string
The key ID.
- - encryptionKey: string
The encryption key.
-
Returns Promise<void>
- keyId: string
unlock
Unlocks the Smart Lock.
-Returns Promise<number>
-
-
- The result of the unlock operation. -
unlock
Unlocks the Smart Lock without unlatching the door.
-Returns Promise<number>
-
-
- The result of the unlock operation. -
unsubscribe
Unsubscribes from the notify characteristic.
-Returns Promise<void>
A Promise that resolves when the unsubscription is complete.
-
Staticget
Parameters
- code: number
Returns string
Staticparse
- parseServiceData(
serviceData: Buffer,
manufacturerData: Buffer,
emitLog: (level: string, message: string) => void,
): Promise<null | lockServiceData>Parses the service data from the SwitchBot Strip Light.
-Parameters
- serviceData: Buffer
The service data buffer.
- - manufacturerData: Buffer
The manufacturer data buffer.
- - emitLog: (level: string, message: string) => void
The function to emit log messages.
-
Returns Promise<null | lockServiceData>
-
-
- Parsed service data or null if invalid. -
- serviceData: Buffer
Staticvalidate
Parameters
- res: Buffer
Returns Promise<number>
Constructors
constructor
- new WoSmartLock(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoSmartLockParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoSmartLock
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Returns Promise<Record<string, unknown>>
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get device status (BLE-first, API-fallback)
+Returns Promise<LockStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
lock
Lock the lock
+Returns Promise<boolean>
off
Parameters
- handler: (payload: Buffer) => void
Returns void
on
Parameters
- handler: (payload: Buffer) => void
Returns Promise<void>
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
unlock
Unlock the lock
+Returns Promise<boolean>
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Refresh status for this device. Called automatically after sequence changes.
+Returns Promise<DeviceStatus>
update
Update device information and react to sequence number changes.
+Parameters
- newInfo: Partial<DeviceInfo>
Returns void
Class WoSmartLockLite
Smart Lock Lite Device
+Hierarchy (View Summary)
- WoSmartLock
- WoSmartLockLite
Index
Constructors
Accessors
Methods
Constructors
constructor
- new WoSmartLockLite(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoSmartLockLiteParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoSmartLockLite
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Returns Promise<Record<string, unknown>>
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get device status (BLE-first, API-fallback)
+Returns Promise<LockStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
lock
Lock the lock
+Returns Promise<boolean>
off
Parameters
- handler: (payload: Buffer) => void
Returns void
on
Parameters
- handler: (payload: Buffer) => void
Returns Promise<void>
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
unlock
Unlock the lock
+Returns Promise<boolean>
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Refresh status for this device. Called automatically after sequence changes.
+Returns Promise<DeviceStatus>
update
Update device information and react to sequence number changes.
+Parameters
- newInfo: Partial<DeviceInfo>
Returns void
Class WoSmartLockPro
Class representing a WoSmartLockPro device.
-Hierarchy (View Summary)
- SwitchbotDevice
- WoSmartLockPro
Index
Constructors
Properties
Accessors
Class WoSmartLockPro
Smart Lock Pro Device (with unlatch support)
+Hierarchy (View Summary)
- SequenceDevice
- WoSmartLockPro
Implements
Index
Constructors
Accessors
Methods
Methods
Constructors
constructor
Parameters
- peripheral: Peripheral
- noble: Noble
Returns WoSmartLockPro
Properties
encryption_
iv
key_
StaticResult
Accessors
address
- get address(): string
Returns string
connection
- get connectionState(): string
Returns string
friendly
Returns SwitchBotBLEModelFriendlyName
id
- get id(): string
Returns string
model
Returns SwitchBotBLEModel
model
Returns SwitchBotBLEModelName
on
- get onConnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onConnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
on
- get onDisconnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onDisconnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
Methods
command
Sends a command to the device and awaits a response.
-Parameters
- reqBuf: Buffer
The command buffer.
-
Returns Promise<Buffer<ArrayBufferLike>>
A Promise that resolves with the response buffer.
-- reqBuf: Buffer
connect
Connects to the device.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
decrypt
Decrypts a buffer using AES-128-CTR.
-Parameters
- data: Buffer
The data to decrypt.
-
Returns Promise<Buffer<ArrayBufferLike>>
-
-
- The decrypted data. -
- data: Buffer
disconnect
Disconnects from the device.
-Returns Promise<void>
A Promise that resolves when the disconnection is complete.
-
discover
Discovers the device services.
-Returns Promise<Service[]>
A Promise that resolves with the list of services.
-
encrypt
Encrypts a string using AES-128-CTR.
-Parameters
- str: string
The string to encrypt.
-
Returns Promise<string>
-
-
- The encrypted string in hex format. -
- str: string
encrypted
Sends an encrypted command to the device.
-Parameters
- key: string
The command key.
-
Returns Promise<Buffer<ArrayBufferLike>>
-
-
- The response buffer. -
- key: string
get
Retrieves the device characteristics.
-Returns Promise<Chars>
A Promise that resolves with the device characteristics.
-
get
Retrieves the device name.
-Returns Promise<string>
A Promise that resolves with the device name.
-
get
Retrieves the IV from the device.
-Returns Promise<Buffer<ArrayBufferLike>>
-
-
- The IV buffer. -
info
Gets general state info from the Smart Lock.
-Returns Promise<null | object>
-
-
- The state object or null if an error occurred. -
internal
Internal method to handle the connection process.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
lock
Locks the Smart Lock.
-Returns Promise<number>
-
-
- The result of the lock operation. -
log
Logs a message with the specified log level.
-Parameters
- level: string
The severity level of the log (e.g., 'info', 'warn', 'error').
- - message: string
The log message to be emitted.
-
Returns Promise<void>
- level: string
operate
Operates the lock with the given command.
-Parameters
- key: string
The command key.
- Optionalencrypt: boolean = trueWhether to encrypt the command.
-
Returns Promise<Buffer<ArrayBufferLike>>
-
-
- The response buffer. -
- key: string
set
Sets the device name.
-Parameters
- name: string
The new device name.
-
Returns Promise<void>
A Promise that resolves when the name is set.
-- name: string
set
Initializes the encryption key info for valid lock communication.
-Parameters
- keyId: string
The key ID.
- - encryptionKey: string
The encryption key.
-
Returns Promise<void>
- keyId: string
unlock
Unlocks the Smart Lock.
-Returns Promise<number>
-
-
- The result of the unlock operation. -
unlock
Unlocks the Smart Lock without unlatching the door.
-Returns Promise<number>
-
-
- The result of the unlock operation. -
unsubscribe
Unsubscribes from the notify characteristic.
-Returns Promise<void>
A Promise that resolves when the unsubscription is complete.
-
Staticget
Parameters
- code: number
Returns string
Staticparse
- parseServiceData(
serviceData: Buffer,
manufacturerData: Buffer,
emitLog: (level: string, message: string) => void,
): Promise<null | lockProServiceData>Parses the service data from the SwitchBot Strip Light.
-Parameters
- serviceData: Buffer
The service data buffer.
- - manufacturerData: Buffer
The manufacturer data buffer.
- - emitLog: (level: string, message: string) => void
The function to emit log messages.
-
Returns Promise<null | lockProServiceData>
-
-
- Parsed service data or null if invalid. -
- serviceData: Buffer
Staticvalidate
Parameters
- res: Buffer
Returns Promise<number>
Constructors
constructor
- new WoSmartLockPro(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoSmartLockProParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoSmartLockPro
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Returns Promise<Record<string, unknown>>
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get device status (BLE-first, API-fallback)
+Returns Promise<LockStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
lock
Lock the lock
+Returns Promise<boolean>
off
Parameters
- handler: (payload: Buffer) => void
Returns void
on
Parameters
- handler: (payload: Buffer) => void
Returns Promise<void>
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
unlatch
Unlatch the lock (Lock Pro only)
+Returns Promise<boolean>
unlock
Unlock the lock
+Returns Promise<boolean>
unlock
Unlock without unlatching the door
+Returns Promise<boolean>
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Refresh status for this device. Called automatically after sequence changes.
+Returns Promise<DeviceStatus>
update
Update device information and react to sequence number changes.
+Parameters
- newInfo: Partial<DeviceInfo>
Returns void
Class WoSmartLockProWiFi
Smart Lock Pro WiFi Device (with WiFi connectivity and unlatch support)
+Hierarchy (View Summary)
- WoSmartLockPro
- WoSmartLockProWiFi
Index
Constructors
Accessors
Methods
Constructors
constructor
- new WoSmartLockProWiFi(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoSmartLockProWiFiParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoSmartLockProWiFi
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Returns Promise<Record<string, unknown>>
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get device status (BLE-first, API-fallback)
+Returns Promise<LockStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
lock
Lock the lock
+Returns Promise<boolean>
off
Parameters
- handler: (payload: Buffer) => void
Returns void
on
Parameters
- handler: (payload: Buffer) => void
Returns Promise<void>
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
unlatch
Unlatch the lock (Lock Pro only)
+Returns Promise<boolean>
unlock
Unlock the lock
+Returns Promise<boolean>
unlock
Unlock without unlatching the door
+Returns Promise<boolean>
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Refresh status for this device. Called automatically after sequence changes.
+Returns Promise<DeviceStatus>
update
Update device information and react to sequence number changes.
+Parameters
- newInfo: Partial<DeviceInfo>
Returns void
Class WoSmartLockVision
Smart Lock Vision Device (with camera)
+Hierarchy (View Summary)
- WoSmartLock
- WoSmartLockVision
Index
Constructors
Accessors
Methods
Constructors
constructor
- new WoSmartLockVision(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoSmartLockVisionParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoSmartLockVision
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Returns Promise<Record<string, unknown>>
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get device status (BLE-first, API-fallback)
+Returns Promise<LockStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
lock
Lock the lock
+Returns Promise<boolean>
off
Parameters
- handler: (payload: Buffer) => void
Returns void
on
Parameters
- handler: (payload: Buffer) => void
Returns Promise<void>
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
unlock
Unlock the lock
+Returns Promise<boolean>
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Refresh status for this device. Called automatically after sequence changes.
+Returns Promise<DeviceStatus>
update
Update device information and react to sequence number changes.
+Parameters
- newInfo: Partial<DeviceInfo>
Returns void
Class WoSmartLockVisionPro
Smart Lock Vision Pro Device (with camera and unlatch support)
+Hierarchy (View Summary)
- WoSmartLockPro
- WoSmartLockVisionPro
Index
Constructors
Accessors
Methods
Constructors
constructor
- new WoSmartLockVisionPro(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoSmartLockVisionProParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoSmartLockVisionPro
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Returns Promise<Record<string, unknown>>
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get device status (BLE-first, API-fallback)
+Returns Promise<LockStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
lock
Lock the lock
+Returns Promise<boolean>
off
Parameters
- handler: (payload: Buffer) => void
Returns void
on
Parameters
- handler: (payload: Buffer) => void
Returns Promise<void>
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
unlatch
Unlatch the lock (Lock Pro only)
+Returns Promise<boolean>
unlock
Unlock the lock
+Returns Promise<boolean>
unlock
Unlock without unlatching the door
+Returns Promise<boolean>
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Refresh status for this device. Called automatically after sequence changes.
+Returns Promise<DeviceStatus>
update
Update device information and react to sequence number changes.
+Parameters
- newInfo: Partial<DeviceInfo>
Returns void
Class WoSmartThermostatRadiator
Smart Thermostat Radiator Device +Reuses climate control behavior for power, mode, and speed-level style control.
+Hierarchy (View Summary)
- WoAirPurifier
- WoSmartThermostatRadiator
Index
Constructors
Accessors
Methods
Constructors
constructor
- new WoSmartThermostatRadiator(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoSmartThermostatRadiatorParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoSmartThermostatRadiator
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get device status (BLE-first, API-fallback)
+Returns Promise<AirPurifierStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Set fan speed (1-4)
+Parameters
- speed: number
Returns Promise<boolean>
set
set
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
turn
Turn off
+Returns Promise<boolean>
turn
Turn on
+Returns Promise<boolean>
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Refresh status for this device. Called automatically after sequence changes.
+Returns Promise<DeviceStatus>
update
Update device information and react to sequence number changes.
+Parameters
- newInfo: Partial<DeviceInfo>
Returns void
verify
Verifies the BLE encryption key by attempting a status read with encryption. +Throws an error if the key is invalid or the device rejects the command.
+Returns Promise<boolean>
Class WoStrip
Class representing a WoStrip device.
-Hierarchy (View Summary)
- SwitchbotDevice
- WoStrip
Index
Constructors
Accessors
Class WoStrip
Strip Light Device +Uses same logic as Color Bulb
+Hierarchy (View Summary)
- WoBulb
- WoStrip
Index
Constructors
constructor
Parameters
- peripheral: Peripheral
- noble: Noble
Returns WoStrip
Accessors
address
- get address(): string
Returns string
connection
- get connectionState(): string
Returns string
friendly
Returns SwitchBotBLEModelFriendlyName
id
- get id(): string
Returns string
model
Returns SwitchBotBLEModel
model
Returns SwitchBotBLEModelName
on
- get onConnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onConnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
on
- get onDisconnectHandler(): () => Promise<void>
Returns () => Promise<void>
- set onDisconnectHandler(func: () => Promise<void>): void
Parameters
- func: () => Promise<void>
Returns void
Methods
command
Sends a command to the device and awaits a response.
-Parameters
- reqBuf: Buffer
The command buffer.
-
Returns Promise<Buffer<ArrayBufferLike>>
A Promise that resolves with the response buffer.
-- reqBuf: Buffer
connect
Connects to the device.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
disconnect
Disconnects from the device.
-Returns Promise<void>
A Promise that resolves when the disconnection is complete.
-
discover
Discovers the device services.
-Returns Promise<Service[]>
A Promise that resolves with the list of services.
-
get
Retrieves the device characteristics.
-Returns Promise<Chars>
A Promise that resolves with the device characteristics.
-
get
Retrieves the device name.
-Returns Promise<string>
A Promise that resolves with the device name.
-
internal
Internal method to handle the connection process.
-Returns Promise<void>
A Promise that resolves when the connection is complete.
-
log
Logs a message with the specified log level.
-Parameters
- level: string
The severity level of the log (e.g., 'info', 'warn', 'error').
- - message: string
The log message to be emitted.
-
Returns Promise<void>
- level: string
operate
Operates the strip light with the given byte array.
-Parameters
- bytes: number[]
The byte array to send.
-
Returns Promise<boolean>
-
-
- Resolves with true if the operation was successful. -
- bytes: number[]
read
Reads the state of the strip light.
-Returns Promise<boolean>
-
-
- Resolves with true if the strip light is ON, false otherwise. -
set
Sets the brightness of the strip light.
-Parameters
- brightness: number
The brightness percentage (0-100).
-
Returns Promise<boolean>
-
-
- Resolves with true if the operation was successful. -
- brightness: number
set
Sets the device name.
-Parameters
- name: string
The new device name.
-
Returns Promise<void>
A Promise that resolves when the name is set.
-- name: string
set
Sets the RGB values of the strip light.
-Parameters
- brightness: number
The brightness percentage (0-100).
- - red: number
The red value (0-255).
- - green: number
The green value (0-255).
- - blue: number
The blue value (0-255).
-
Returns Promise<boolean>
-
-
- Resolves with true if the operation was successful. -
- brightness: number
set
Sets the state of the strip light.
-Parameters
- reqByteArray: number[]
The request byte array.
-
Returns Promise<boolean>
-
-
- Resolves with true if the operation was successful. -
- reqByteArray: number[]
turn
Turns the strip light off.
-Returns Promise<boolean>
-
-
- Resolves with true if the strip light is OFF. -
turn
Turns the strip light on.
-Returns Promise<boolean>
-
-
- Resolves with true if the strip light is ON. -
unsubscribe
Unsubscribes from the notify characteristic.
-Returns Promise<void>
A Promise that resolves when the unsubscription is complete.
-
Staticparse
- parseServiceData(
serviceData: Buffer,
emitLog: (level: string, message: string) => void,
): Promise<null | stripLightServiceData>Parses the service data from the SwitchBot Strip Light.
-Parameters
- serviceData: Buffer
The service data buffer.
- - emitLog: (level: string, message: string) => void
The function to emit log messages.
-
Returns Promise<null | stripLightServiceData>
-
-
- Parsed service data or null if invalid. -
- serviceData: Buffer
Methods
Constructors
constructor
- new WoStrip(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoStripParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoStrip
Properties
StaticEFFECTS
Preset effect name to effect ID mapping
+Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get device status (BLE-first/API-fallback, centralized)
+Returns Promise<BulbStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Strip Light 3 and complex light patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex light patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Set brightness (0-100)
+Parameters
- brightness: number
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Set RGB color
+Parameters
- red: number
- green: number
- blue: number
Returns Promise<boolean>
set
Set color temperature with min/max bounds +For advanced bulbs that support color temperature range control
+Parameters
- minTemp: number
- maxTemp: number
- temp: number
Returns Promise<boolean>
set
Set color temperature (2700-6500K)
+Parameters
- temperature: number
Returns Promise<boolean>
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Set preset light effect
+Parameters
- effectName: string
- speed: number = 100
Returns Promise<boolean>
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
turn
Turn off
+Returns Promise<boolean>
turn
Turn on
+Returns Promise<boolean>
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
verify
Verifies the BLE encryption key by attempting a status read with encryption. +Throws an error if the key is invalid or the device rejects the command.
+Returns Promise<boolean>
Class WoStripLight3
Strip Light 3 Device +Uses same logic as Color Bulb
+Hierarchy (View Summary)
- WoBulb
- WoStripLight3
Index
Constructors
Properties
Accessors
Methods
Constructors
constructor
- new WoStripLight3(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoStripLight3Parameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoStripLight3
Properties
StaticEFFECTS
Preset effect name to effect ID mapping
+Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get device status (BLE-first/API-fallback, centralized)
+Returns Promise<BulbStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Strip Light 3 and complex light patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex light patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Set brightness (0-100)
+Parameters
- brightness: number
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Set RGB color
+Parameters
- red: number
- green: number
- blue: number
Returns Promise<boolean>
set
Set color temperature with min/max bounds +For advanced bulbs that support color temperature range control
+Parameters
- minTemp: number
- maxTemp: number
- temp: number
Returns Promise<boolean>
set
Set color temperature (2700-6500K)
+Parameters
- temperature: number
Returns Promise<boolean>
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Set preset light effect
+Parameters
- effectName: string
- speed: number = 100
Returns Promise<boolean>
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
turn
Turn off
+Returns Promise<boolean>
turn
Turn on
+Returns Promise<boolean>
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
verify
Verifies the BLE encryption key by attempting a status read with encryption. +Throws an error if the key is invalid or the device rejects the command.
+Returns Promise<boolean>
Class WoVacuum
Vacuum Device
+Hierarchy (View Summary)
Implements
Index
Constructors
Accessors
Methods
Constructors
constructor
- new WoVacuum(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoVacuumParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoVacuum
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
clean
Start cleaning (BLE-first, API-fallback)
+Parameters
- protocolVersion: number
Returns Promise<boolean>
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Return advertised battery value
+Returns number | undefined
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Return advertised dustbin bound state
+Returns boolean | undefined
get
Return advertised dustbin connected state
+Returns boolean | undefined
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Return advertised network connected state
+Returns boolean | undefined
get
Get device status (BLE-first/API-fallback, centralized)
+Returns Promise<VacuumStatus>
get
Return advertised work status value
+Returns number | undefined
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
return
Return to dock (BLE-first, API-fallback)
+Parameters
- protocolVersion: number
Returns Promise<boolean>
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Refresh status for this device. Called automatically after sequence changes.
+Returns Promise<DeviceStatus>
update
Update device information and react to sequence number changes.
+Parameters
- newInfo: Partial<DeviceInfo>
Returns void
Class WoVacuumK10Plus
Robot Vacuum Cleaner K10+
+Hierarchy (View Summary)
- WoVacuum
- WoVacuumK10Plus
Index
Constructors
Accessors
Methods
Constructors
constructor
- new WoVacuumK10Plus(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoVacuumK10PlusParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoVacuumK10Plus
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
clean
Start cleaning (BLE-first, API-fallback)
+Parameters
- protocolVersion: number
Returns Promise<boolean>
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Return advertised battery value
+Returns number | undefined
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Return advertised dustbin bound state
+Returns boolean | undefined
get
Return advertised dustbin connected state
+Returns boolean | undefined
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Return advertised network connected state
+Returns boolean | undefined
get
Get device status (BLE-first/API-fallback, centralized)
+Returns Promise<VacuumStatus>
get
Return advertised work status value
+Returns number | undefined
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
return
Return to dock (BLE-first, API-fallback)
+Parameters
- protocolVersion: number
Returns Promise<boolean>
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Refresh status for this device. Called automatically after sequence changes.
+Returns Promise<DeviceStatus>
update
Update device information and react to sequence number changes.
+Parameters
- newInfo: Partial<DeviceInfo>
Returns void
Class WoVacuumK10Pro
Robot Vacuum Cleaner K10+ Pro
+Hierarchy (View Summary)
- WoVacuum
- WoVacuumK10Pro
Index
Constructors
Accessors
Methods
Constructors
constructor
- new WoVacuumK10Pro(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoVacuumK10ProParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoVacuumK10Pro
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
clean
Start cleaning (BLE-first, API-fallback)
+Parameters
- protocolVersion: number
Returns Promise<boolean>
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Return advertised battery value
+Returns number | undefined
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Return advertised dustbin bound state
+Returns boolean | undefined
get
Return advertised dustbin connected state
+Returns boolean | undefined
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Return advertised network connected state
+Returns boolean | undefined
get
Get device status (BLE-first/API-fallback, centralized)
+Returns Promise<VacuumStatus>
get
Return advertised work status value
+Returns number | undefined
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
return
Return to dock (BLE-first, API-fallback)
+Parameters
- protocolVersion: number
Returns Promise<boolean>
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Refresh status for this device. Called automatically after sequence changes.
+Returns Promise<DeviceStatus>
update
Update device information and react to sequence number changes.
+Parameters
- newInfo: Partial<DeviceInfo>
Returns void
Class WoVacuumK10ProCombo
Robot Vacuum Cleaner K10+ Pro Combo
+Hierarchy (View Summary)
- WoVacuum
- WoVacuumK10ProCombo
Index
Constructors
Accessors
Methods
Constructors
constructor
- new WoVacuumK10ProCombo(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoVacuumK10ProComboParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoVacuumK10ProCombo
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
clean
Start cleaning (BLE-first, API-fallback)
+Parameters
- protocolVersion: number
Returns Promise<boolean>
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Return advertised battery value
+Returns number | undefined
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Return advertised dustbin bound state
+Returns boolean | undefined
get
Return advertised dustbin connected state
+Returns boolean | undefined
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Return advertised network connected state
+Returns boolean | undefined
get
Get device status (BLE-first/API-fallback, centralized)
+Returns Promise<VacuumStatus>
get
Return advertised work status value
+Returns number | undefined
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
return
Return to dock (BLE-first, API-fallback)
+Parameters
- protocolVersion: number
Returns Promise<boolean>
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Refresh status for this device. Called automatically after sequence changes.
+Returns Promise<DeviceStatus>
update
Update device information and react to sequence number changes.
+Parameters
- newInfo: Partial<DeviceInfo>
Returns void
Class WoVacuumK11Plus
Robot Vacuum Cleaner K11+
+Hierarchy (View Summary)
- WoVacuum
- WoVacuumK11Plus
Index
Constructors
Accessors
Methods
Constructors
constructor
- new WoVacuumK11Plus(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoVacuumK11PlusParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoVacuumK11Plus
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
clean
Start cleaning (BLE-first, API-fallback)
+Parameters
- protocolVersion: number
Returns Promise<boolean>
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Return advertised battery value
+Returns number | undefined
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Return advertised dustbin bound state
+Returns boolean | undefined
get
Return advertised dustbin connected state
+Returns boolean | undefined
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Return advertised network connected state
+Returns boolean | undefined
get
Get device status (BLE-first/API-fallback, centralized)
+Returns Promise<VacuumStatus>
get
Return advertised work status value
+Returns number | undefined
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
return
Return to dock (BLE-first, API-fallback)
+Parameters
- protocolVersion: number
Returns Promise<boolean>
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Refresh status for this device. Called automatically after sequence changes.
+Returns Promise<DeviceStatus>
update
Update device information and react to sequence number changes.
+Parameters
- newInfo: Partial<DeviceInfo>
Returns void
Class WoVacuumK20
Robot Vacuum Cleaner K20
+Hierarchy (View Summary)
- WoVacuum
- WoVacuumK20
Index
Constructors
Accessors
Methods
Constructors
constructor
- new WoVacuumK20(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoVacuumK20Parameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoVacuumK20
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
clean
Start cleaning (BLE-first, API-fallback)
+Parameters
- protocolVersion: number
Returns Promise<boolean>
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Return advertised battery value
+Returns number | undefined
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Return advertised dustbin bound state
+Returns boolean | undefined
get
Return advertised dustbin connected state
+Returns boolean | undefined
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Return advertised network connected state
+Returns boolean | undefined
get
Get device status (BLE-first/API-fallback, centralized)
+Returns Promise<VacuumStatus>
get
Return advertised work status value
+Returns number | undefined
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
return
Return to dock (BLE-first, API-fallback)
+Parameters
- protocolVersion: number
Returns Promise<boolean>
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Refresh status for this device. Called automatically after sequence changes.
+Returns Promise<DeviceStatus>
update
Update device information and react to sequence number changes.
+Parameters
- newInfo: Partial<DeviceInfo>
Returns void
Class WoVacuumS10
Robot Vacuum Cleaner S10
+Hierarchy (View Summary)
- WoVacuum
- WoVacuumS10
Index
Constructors
Accessors
Methods
Constructors
constructor
- new WoVacuumS10(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoVacuumS10Parameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoVacuumS10
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
clean
Start cleaning (BLE-first, API-fallback)
+Parameters
- protocolVersion: number
Returns Promise<boolean>
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Return advertised battery value
+Returns number | undefined
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Return advertised dustbin bound state
+Returns boolean | undefined
get
Return advertised dustbin connected state
+Returns boolean | undefined
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Return advertised network connected state
+Returns boolean | undefined
get
Get device status (BLE-first/API-fallback, centralized)
+Returns Promise<VacuumStatus>
get
Return advertised work status value
+Returns number | undefined
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
return
Return to dock (BLE-first, API-fallback)
+Parameters
- protocolVersion: number
Returns Promise<boolean>
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Refresh status for this device. Called automatically after sequence changes.
+Returns Promise<DeviceStatus>
update
Update device information and react to sequence number changes.
+Parameters
- newInfo: Partial<DeviceInfo>
Returns void
Class WoVacuumS20
Robot Vacuum Cleaner S20
+Hierarchy (View Summary)
- WoVacuum
- WoVacuumS20
Index
Constructors
Accessors
Methods
Constructors
constructor
- new WoVacuumS20(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoVacuumS20Parameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoVacuumS20
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
clean
Start cleaning (BLE-first, API-fallback)
+Parameters
- protocolVersion: number
Returns Promise<boolean>
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Return advertised battery value
+Returns number | undefined
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Return advertised dustbin bound state
+Returns boolean | undefined
get
Return advertised dustbin connected state
+Returns boolean | undefined
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Return advertised network connected state
+Returns boolean | undefined
get
Get device status (BLE-first/API-fallback, centralized)
+Returns Promise<VacuumStatus>
get
Return advertised work status value
+Returns number | undefined
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
return
Return to dock (BLE-first, API-fallback)
+Parameters
- protocolVersion: number
Returns Promise<boolean>
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Refresh status for this device. Called automatically after sequence changes.
+Returns Promise<DeviceStatus>
update
Update device information and react to sequence number changes.
+Parameters
- newInfo: Partial<DeviceInfo>
Returns void
Class WoWaterDetector
Base class for all SwitchBot devices
+BLE-first, API-fallback Logic
+This class provides a centralized, robust hybrid connection strategy for all SwitchBot devices:
+-
+
- BLE-first, API-fallback: By default, status and command methods attempt BLE first (if available), then fall back to OpenAPI if BLE fails or is unavailable. This is controlled by
preferredConnectionandenableFallback.
+ - Centralized Fallback: The
getStatusWithFallback()andsendCommand()methods implement this logic. Device subclasses should call these methods and provide normalization/mapping as needed.
+ - Connection Intelligence: Tracks connection health and performance, automatically preferring the most reliable connection if enabled. +
- Circuit Breaker & Retry: Both BLE and API commands are protected by circuit breaker and retry logic to handle transient failures gracefully. +
Usage in Subclasses
+-
+
- For status: Call
await this.getStatusWithFallback(normalizeBLE, normalizeAPI)in yourgetStatus()implementation.
+ - For commands: Use
await this.sendCommand(bleCommand, apiCommand, apiParameter)to automatically select the best connection and handle fallback.
+ - For custom logic: You may override or extend these methods, but should preserve the fallback and error-handling patterns for consistency. +
Example (in a device subclass)
+async getStatus(): Promise<DeviceStatus> {
return this.getStatusWithFallback(
bleData => ({ ... }), // normalize BLE data
apiData => ({ ... }), // normalize API data
)
}
async turnOn(): Promise<boolean> {
const result = await this.sendCommand([0x57, 0x01, 0x01], 'turnOn')
return result.success
}
+Configuration
+-
+
preferredConnection: 'ble' | 'api' (default: 'ble')
+enableFallback: boolean (default: true)
+enableConnectionIntelligence: boolean (default: true)
+enableCircuitBreaker: boolean (default: true)
+enableRetry: boolean (default: true)
+
See Also
+-
+
getStatusWithFallback()
+sendCommand()
+hasBLE(),hasAPI()
+setPreferredConnection(),setFallbackEnabled()
+
This pattern ensures all device classes benefit from robust, testable, and consistent connection logic.
+Hierarchy (View Summary)
- SwitchBotDevice
- WoWaterDetector
Index
Constructors
Accessors
Methods
Constructors
constructor
- new WoWaterDetector(
info: DeviceInfo,
options?: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
},
): WoWaterDetectorParameters
- info: DeviceInfo
- options: {
apiClient?: OpenAPIClient;
bleConnection?: BLEConnection;
circuitBreakerConfig?: CircuitBreakerConfig;
enableCircuitBreaker?: boolean;
enableConnectionIntelligence?: boolean;
enableFallback?: boolean;
enableRetry?: boolean;
logLevel?: number;
preferredConnection?: ConnectionType;
retryConfig?: RetryConfig;
} = {}
Returns WoWaterDetector
Accessors
active
Get active connection type (property accessor for convenience)
+Returns ConnectionType | undefined
device
- get deviceType(): string
Get device type (property accessor for convenience)
+Returns string
id
- get id(): string | undefined
Get device ID (property accessor for convenience)
+Returns string | undefined
mac
- get mac(): string | undefined
Get MAC address (property accessor for convenience)
+Returns string | undefined
name
- get name(): string
Get device name (property accessor for convenience)
+Returns string
Methods
get
Get active connection type
+Returns ConnectionType | undefined
get
Get basic device info (universal settings retrieval) +Returns: battery, firmware, device-specific settings, etc. +Command: 0x57 0x02 (BLE), 'getBasicInfo' (API)
+Example usage: +const info = await device.getBasicInfo(); +console.log(info);
+Returns a CommandResult object with device info fields.
+Returns Promise<CommandResult>
get
Get circuit breaker for API
+Returns CircuitBreaker
get
Get circuit breaker for BLE
+Returns CircuitBreaker
get
Get connection tracker for this device
+Returns ConnectionTracker
get
Get device type
+Returns string
get
Get fallback handler manager
+Returns FallbackHandlerManager
get
Get device ID
+Returns string
get
Get device information
+Returns DeviceInfo
get
Get MAC address (if available)
+Returns string | undefined
get
Get device name
+Returns string
get
Get device status (BLE-first, API-fallback)
+Returns Promise<LeakStatus>
has
Check if API is available for this device
+Returns boolean
has
Check if BLE is available for this device
+Returns boolean
poll
Poll device status if needed (passive polling)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns Promise<DeviceStatus | undefined>
poll
Returns true if device should be polled (passive polling interval elapsed)
+Parameters
- interval: number = PASSIVE_POLL_INTERVAL
Returns boolean
register
Register a custom fallback handler
+Parameters
- handler: FallbackHandler
Optionaloptions: FallbackHandlerOptions
Returns string
send
Send multiple commands in sequence (all must succeed) +Used for Curtain 3, bulbs, strips, and other multi-step devices
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
send
Send multiple commands (returns true if any succeed) +Used for fallback operations with complex patterns
+Parameters
- commands: (() => Promise<boolean>)[]
Returns Promise<boolean>
set
Enable or disable circuit breaker
+Parameters
- enabled: boolean
Returns void
set
Enable or disable connection intelligence
+Parameters
- enabled: boolean
Returns void
set
Enable or disable fallback
+Parameters
- enabled: boolean
Returns void
set
Universal mode setting command +BLE: 0x57 0x03 [modeByte] +API: 'setMode' (if available)
+Parameters
- mode: string | number
Mode value (number or string, per-device enum recommended)
+Example usage: +await device.setMode('auto') +await device.setMode(1)
+Returns a CommandResult object indicating success and mode info.
+
Returns Promise<CommandResult>
- mode: string | number
set
set
Enable or disable retry logic
+Parameters
- enabled: boolean
Returns void
unregister
Unregister a fallback handler
+Parameters
- id: string
Returns boolean
update
Enumeration LogLevel
Enum for log levels.
-Index
Enumeration Members
Enumeration LogLevel
Log levels for debugging and diagnostics
+Enumeration SwitchBotBLEModel
Index
Enumeration Members
Enumeration SwitchBotBLEModel
SwitchBot BLE Model identifiers
+Index
Enumeration Members
Enumeration Members
Air
Air
Blind
Bot
Ceiling
Ceiling
Color
Contact
Curtain
Curtain3
Hub2
Hub3
Humidifier
Humidifier2
Keypad
Leak
Lock
Lock
Meter
Meter
Meter
Meter
Motion
Outdoor
Plug
Plug
Presence
Relay
Relay
Remote
Strip
Unknown
Enumeration Members
Air
Air
Battery
Blind
Bot
Ceiling
Ceiling
Color
Contact
Curtain
Curtain3
Hub2
Hub3
Humidifier
Humidifier2
K10
Keypad
Keypad
Lock
Lock
Meter
Meter
Meter
Meter
Motion
Outdoor
Plug
Plug
Plug
Presence
Relay
Relay
Remote
Robot
Robot
Robot
Strip
Water
Enumeration SwitchBotBLEModelFriendlyName
Index
Enumeration Members
Enumeration Members
Air
Air
Air
Air
Air
Air
Battery
Blind
Bot
Ceiling
Ceiling
Circulator
Color
Contact
Curtain
Curtain3
Hub2
Hub3
Humidifier
Humidifier2
Keypad
Leak
Lock
Lock
Meter
Meter
Meter
Meter
Motion
Outdoor
Plug
Presence
Relay
Relay
Remote
Strip
Unknown
Enumeration SwitchBotBLEModelName
Index
Enumeration Members
Enumeration SwitchBotBLEModelName
SwitchBot BLE Model Names
+Index
Enumeration Members
Enumeration Members
Air
Air
Blind
Bot
Ceiling
Ceiling
Color
Contact
Curtain
Curtain3
Hub2
Hub3
Humidifier
Humidifier2
Keypad
Leak
Lock
Lock
Meter
Meter
Meter
Meter
Motion
Outdoor
Plug
Presence
Relay
Relay
Remote
Strip
Unknown
Enumeration Members
Air
Air
Battery
Blind
Bot
Ceiling
Ceiling
Color
Contact
Curtain
Curtain3
Hub2
Hub3
Humidifier
Humidifier2
K10
Keypad
Keypad
Lock
Lock
Meter
Meter
Meter
Meter
Motion
Outdoor
Plug
Plug
Plug
Presence
Relay
Relay
Remote
Robot
Robot
Robot
Strip
Water
Enumeration SwitchBotModel
Index
Enumeration Members
Enumeration Members
Air
Air
Battery
Blind
Bot
Ceiling
Ceiling
Circulator
Color
Contact
Curtain
Curtain3
Hub2
Hub3
Hub
Hub
Humidifier
Humidifier2
Indoor
K10
K10
Keypad
Keypad
Lock
Lock
Meter
Meter
Meter
Meter
Meter
Motion
Outdoor
Pan
Pan
Plug
Plug
Plug
Presence
Relay
Relay
Remote
Robot
Robot
Robot
Strip
Universal
Unknown
Water
Wo
Wo
node-switchbot
Hierarchy Summary
- BLEServiceData
- SwitchBotDevice
node-switchbot
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:
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
-
+
+
Quick Start (v4.0.0)
+v4.0.0 introduces a unified hybrid approach that automatically uses BLE when available with seamless API fallback.
+Basic Usage
+import { SwitchBot } from 'node-switchbot'
const switchbot = new SwitchBot({
token: 'YOUR_TOKEN', // OpenAPI token (optional for BLE-only)
secret: 'YOUR_SECRET', // OpenAPI secret (optional for BLE-only)
enableBLE: true, // Enable BLE discovery (Linux/macOS)
enableFallback: true, // Auto-fallback between BLE/API
})
// Discover all devices (BLE + API)
const devices = await switchbot.discover()
// Control devices
const bot = switchbot.devices.get('YOUR_DEVICE_ID')
await bot.press()
// Get status
const status = await bot.getStatus()
console.log(status)
// Cleanup
await switchbot.cleanup()
+Device Control Examples
+// Bot - Press/Switch control
await bot.turnOn()
await bot.turnOff()
await bot.press()
// Bot with Password Protection (BLE only)
const protectedBot = new WoHand({ id: 'YOUR_BOT_ID', password: 'A1b2' })
await protectedBot.setPassword('A1b2') // Set 4-char alphanumeric password
await protectedBot.press() // Commands are automatically encrypted
await protectedBot.clearPassword() // Remove password protection
// Curtain - Position control
await curtain.open()
await curtain.close()
await curtain.setPosition(50) // 50% open
// Lock - Lock/Unlock
await lock.lock()
await lock.unlock()
// Bulb - Color and brightness
await bulb.turnOn()
await bulb.setBrightness(80)
await bulb.setColor(255, 0, 0) // Red
// Meter - Read sensors
const meterStatus = await meter.getStatus()
console.log(meterStatus.temperature, meterStatus.humidity)
+See the examples directory for more usage patterns.
++
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.
++
Migration from v3.x
+Breaking Changes in v4.0.0:
+-
+
- ✨ Unified API: Single
SwitchBotclass replaces separateSwitchBotBLEandSwitchBotOpenAPIclasses
+ - 🔄 Automatic Discovery: Combined BLE + OpenAPI discovery in one call +
- 🛡️ Automatic Fallback: BLE commands automatically fall back to API on failure +
- 📦 Device Manager: Access devices via
switchbot.devices.get(id)instead of direct discovery results
+ - 🏷️ TypeScript: Full TypeScript rewrite with comprehensive type definitions +
- ⚠️ No Backward Compatibility: v3.x APIs are not supported - migration required +
Migration Example:
+// v3.x (old)
import { SwitchBotBLE, SwitchBotOpenAPI } from 'node-switchbot'
const ble = new SwitchBotBLE()
const api = new SwitchBotOpenAPI(token, secret)
// v4.0.0 (new)
import { SwitchBot } from 'node-switchbot'
const switchbot = new SwitchBot({ token, secret, enableBLE: true })
++
Error thrown when API request fails
+