Matterbridge SwitchBot Plugin

A Matterbridge plugin that integrates SwitchBot devices with the Matter protocol, allowing you to control your SwitchBot devices through Matter-compatible smart home platforms like Apple HomeKit, Google Home, Amazon Alexa, and others.

Features

- Full SwitchBot API v1.1+ Support: Uses the latest SwitchBot API with enhanced security
- Wide Device Support: Supports physical devices (Bot, Plug, Lights, Curtains) and infrared remote devices
- Matter Protocol Integration: Exposes SwitchBot devices as Matter-compatible devices
- Real-time Status Updates: Polls device status and updates Matter attributes accordingly
- Secure Authentication: Implements SwitchBot's HMAC-SHA256 signature authentication
- UI Configuration: Configure through Matterbridge's web interface
- TypeScript: Fully typed for better development experience

Supported Devices

$3

- SwitchBot Bot: Exposed as an on/off switch
- SwitchBot Plug (Mini US/JP, Standard): Exposed as outlets
- SwitchBot Lights (Color Bulb, Strip Light, Ceiling Light): Exposed as dimmable/color lights
- SwitchBot Curtain/Roller Shade: Exposed as on/off switches (open/close)

$3

- Air Conditioner: Exposed as on/off switch
- TV: Exposed as on/off switch
- Light: Exposed as on/off switch
- Fan: Exposed as on/off switch

Prerequisites

1. Matterbridge: Version 3.0.7 or higher
2. SwitchBot Account: With API access enabled
3. SwitchBot Token and Secret: Obtained from the SwitchBot app

Installation

$3

1. Install the plugin:
``bash npm install -g matterbridge-switchbot`

2. Add the plugin to Matterbridge: - Open the Matterbridge web interface - Go to Plugins → Add Plugin - Search for "matterbridge-switchbot" or add it manually - Click Install

`$3`

1. Clone this repository:`bash git clone https://github.com/derbirch/matterbridge-switchbot.git cd matterbridge-switchbot`

2. Install dependencies:`bash npm install`

3. Build the plugin:`bash npx tsc`

4. Link the plugin to your Matterbridge installation:`bash npm link`

5. Add the plugin to Matterbridge:`bash matterbridge -add /path/to/your/matterbridge-switchbot`

`Configuration`

`$3`

1. Open the SwitchBot app on your mobile device 2. Go to Profile → Preferences 3. Tap App Version 10 times to enable developer options 4. Go back and tap Developer Options 5. Generate your Token and Secret

`$3`

#### Via Matterbridge Web Interface (Recommended)

1. Open the Matterbridge web interface 2. Go to Plugins → matterbridge-switchbot 3. Click Settings or Configure 4. Fill in the configuration form: - SwitchBot API Token: Your SwitchBot API token - SwitchBot API Secret: Your SwitchBot API secret - Polling Interval: How often to check device status (default: 30 seconds) - SwitchBot API Base URL: API endpoint (default: https://api.switch-bot.com) 5. Click Save

#### Via Configuration File (Alternative)

Add the following configuration to your Matterbridge config file:

`json { "name": "SwitchBot", "type": "DynamicPlatform", "token": "your-switchbot-token", "secret": "your-switchbot-secret", "baseUrl": "https://api.switch-bot.com", "pollInterval": 30 }`

#### Configuration Options

| Option | Type | Required | Default | Description | |--------|------|----------|---------|-------------| |token| string | Yes | - | Your SwitchBot API token | |secret| string | Yes | - | Your SwitchBot API secret | |baseUrl | string | No | https://api.switch-bot.com| SwitchBot API base URL | |pollInterval | number | No | 30 | Status polling interval in seconds (minimum: 5) |

`Usage`

1. Start Matterbridge: The plugin will automatically discover your SwitchBot devices 2. Device Registration: Devices will be registered with Matter and appear in your smart home app 3. Control Devices: Use your Matter-compatible smart home platform to control devices 4. Status Updates: Device status is automatically synchronized based on the polling interval

`Device Mapping`

`$3`


- Bot → Matter On/Off Switch
- Plug → Matter Outlet
- Color Bulb → Matter Color Temperature Light (with brightness and color temperature control)
- Strip Light → Matter Color Temperature Light (with brightness control)
- Ceiling Light → Matter Color Temperature Light (with brightness and color temperature control)
- Curtain/Roller Shade → Matter On/Off Switch (open = on, close = off)
$3

- All IR Devices → Matter On/Off Switch (power on/off commands)
API Reference
$3
The plugin uses SwitchBot API v1.1 with the following endpoints:

- GET /v1.1/devices- Discover devices -GET /v1.1/devices/{deviceId}/status- Get device status -POST /v1.1/devices/{deviceId}/commands - Send device commands

`$3`

The plugin implements SwitchBot's secure authentication using: - HMAC-SHA256 signature generation - Timestamp-based nonce - Token and secret key validation

`Development`

`$3`

`bash

`Clone the repository`


git clone https://github.com/derbirch/matterbridge-switchbot.git
cd matterbridge-switchbot
Install dependencies

npm install
Build the project

npx tsc
Run tests (if available)

npm test

$3

`src/ ├── index.ts # Main plugin module (formerly module.ts) ├── switchbot-api.ts # SwitchBot API client └── device-manager.ts # Device discovery and management

matterbridge-switchbot.schema.json # UI configuration schema dist/ # Compiled JavaScript output`

`$3`

The plugin includes comprehensive unit tests:

`bash npm test # Run all tests npm run test:coverage # Run tests with coverage npm run test:watch # Run tests in watch mode`

`Troubleshooting`

`$3`

1. "SwitchBot API not initialized" - Verify your token and secret are correct - Check that both token and secret are provided in configuration - Ensure you've enabled developer options in the SwitchBot app

2. "Failed to get devices" - Ensure your SwitchBot account has API access enabled - Verify your token hasn't expired - Check network connectivity - Verify the API base URL is correct

3. Devices not appearing in Matter app - Restart Matterbridge after configuration changes - Check Matterbridge logs for device registration errors - Ensure devices are online in the SwitchBot app - Verify the plugin is properly installed and configured

4. Commands not working - Verify device is online and responsive in SwitchBot app - Check if device type is supported - Review plugin logs for command errors - Ensure polling interval is not too aggressive

5. Plugin not showing in Matterbridge UI - Ensure the plugin is properly installed (npm install -g matterbridge-switchbot) - Check that the schema file is included in the package - Restart Matterbridge after installation - Verify Matterbridge version compatibility (>= 3.0.7)

`$3`

Enable debug logging in your Matterbridge configuration:

`json { "name": "SwitchBot", "type": "DynamicPlatform", "debug": true, ... }`

`$3`

Check Matterbridge logs for detailed information: - Plugin initialization messages - Device discovery results - API communication status - Error messages and stack traces

`Contributing`

1. Fork the repository 2. Create a feature branch:git checkout -b feature-name3. Make your changes and add tests 4. Run tests:npm test5. Submit a pull request

`License`

This project is licensed under the Apache-2.0 License - see the LICENSE file for details.

`Support`

- Issues: Report bugs and feature requests on GitHub Issues - Documentation: Check the Matterbridge documentation for general setup - SwitchBot API: Refer to the official SwitchBot API documentation

`Changelog`

`$3`


- Renamed

module.ts to index.ts and updated package.json` to reflect this change, which might help with Matterbridge UI discovery.
- Added UI configuration schema for Matterbridge web interface
- Fixed TypeScript compilation issues
- Updated repository URLs and package metadata
- Improved error handling and logging

$3

- Fixed plugin loading mechanism
- Updated dependencies and peer dependencies
- Improved installation instructions

$3

- Fixed plugin loading mechanism
- Updated dependencies and peer dependencies
- Improved installation instructions

$3

- Initial release
- Support for SwitchBot API v1.1
- Physical device support (Bot, Plug, Lights, Curtains)
- Infrared device support (AC, TV, Light, Fan)
- Matter protocol integration
- Real-time status polling
- Comprehensive test suite

Acknowledgments

- Matterbridge - The bridge platform this plugin is built for
- SwitchBot - For providing the API and devices
- Matter - The smart home standard

Matterbridge SwitchBot Plugin

Features

Supported Devices

$3

- Air Conditioner: Exposed as on/off switch
- TV: Exposed as on/off switch
- Light: Exposed as on/off switch
- Fan: Exposed as on/off switch

Prerequisites

1. Matterbridge: Version 3.0.7 or higher
2. SwitchBot Account: With API access enabled
3. SwitchBot Token and Secret: Obtained from the SwitchBot app

Installation

$3

1. Install the plugin:
``bash npm install -g matterbridge-switchbot`

2. Add the plugin to Matterbridge: - Open the Matterbridge web interface - Go to Plugins → Add Plugin - Search for "matterbridge-switchbot" or add it manually - Click Install

`$3`

1. Clone this repository:`bash git clone https://github.com/derbirch/matterbridge-switchbot.git cd matterbridge-switchbot`

2. Install dependencies:`bash npm install`

3. Build the plugin:`bash npx tsc`

4. Link the plugin to your Matterbridge installation:`bash npm link`

5. Add the plugin to Matterbridge:`bash matterbridge -add /path/to/your/matterbridge-switchbot`

`Configuration`

`$3`

#### Via Matterbridge Web Interface (Recommended)

#### Via Configuration File (Alternative)

Add the following configuration to your Matterbridge config file:

`json { "name": "SwitchBot", "type": "DynamicPlatform", "token": "your-switchbot-token", "secret": "your-switchbot-secret", "baseUrl": "https://api.switch-bot.com", "pollInterval": 30 }`

#### Configuration Options

`Usage`

`Device Mapping`

`$3`


- Bot → Matter On/Off Switch
- Plug → Matter Outlet
- Color Bulb → Matter Color Temperature Light (with brightness and color temperature control)
- Strip Light → Matter Color Temperature Light (with brightness control)
- Ceiling Light → Matter Color Temperature Light (with brightness and color temperature control)
- Curtain/Roller Shade → Matter On/Off Switch (open = on, close = off)
$3

- All IR Devices → Matter On/Off Switch (power on/off commands)
API Reference
$3
The plugin uses SwitchBot API v1.1 with the following endpoints:

- GET /v1.1/devices- Discover devices -GET /v1.1/devices/{deviceId}/status- Get device status -POST /v1.1/devices/{deviceId}/commands - Send device commands

`$3`

The plugin implements SwitchBot's secure authentication using: - HMAC-SHA256 signature generation - Timestamp-based nonce - Token and secret key validation

`Development`

`$3`

`bash

`Clone the repository`


git clone https://github.com/derbirch/matterbridge-switchbot.git
cd matterbridge-switchbot
Install dependencies

npm install
Build the project

npx tsc
Run tests (if available)

npm test

$3

`src/ ├── index.ts # Main plugin module (formerly module.ts) ├── switchbot-api.ts # SwitchBot API client └── device-manager.ts # Device discovery and management

matterbridge-switchbot.schema.json # UI configuration schema dist/ # Compiled JavaScript output`

`$3`

The plugin includes comprehensive unit tests:

`bash npm test # Run all tests npm run test:coverage # Run tests with coverage npm run test:watch # Run tests in watch mode`

`Troubleshooting`

`$3`

2. "Failed to get devices" - Ensure your SwitchBot account has API access enabled - Verify your token hasn't expired - Check network connectivity - Verify the API base URL is correct

`$3`

Enable debug logging in your Matterbridge configuration:

`json { "name": "SwitchBot", "type": "DynamicPlatform", "debug": true, ... }`

`$3`

Check Matterbridge logs for detailed information: - Plugin initialization messages - Device discovery results - API communication status - Error messages and stack traces

`Contributing`

1. Fork the repository 2. Create a feature branch:git checkout -b feature-name3. Make your changes and add tests 4. Run tests:npm test5. Submit a pull request

`License`

This project is licensed under the Apache-2.0 License - see the LICENSE file for details.

`Support`

`Changelog`

`$3`


- Renamed

$3

- Fixed plugin loading mechanism
- Updated dependencies and peer dependencies
- Improved installation instructions

$3

- Fixed plugin loading mechanism
- Updated dependencies and peer dependencies
- Improved installation instructions

$3

Acknowledgments

- Matterbridge - The bridge platform this plugin is built for
- SwitchBot - For providing the API and devices
- Matter - The smart home standard