Homebridge SwitchBot Pusher

A Homebridge plugin for controlling SwitchBot Pusher (Bot) devices via the SwitchBot Cloud API.

Features

• Momentary Push Action: Appears as a switch in HomeKit that automatically turns off after pushing
• Configurable Push Duration: Set how long the bot holds the push (0.5-10 seconds)
• Status Verification: Checks device status after push to ensure completion
• No Continuous Polling: Only checks status after push actions to preserve battery life

Installation

1. Install the plugin via Homebridge UI or npm:

   npm install -g homebridge-switchbot-pusher

2. Add the platform to your Homebridge configuration

Configuration

Required Settings

• API Token: Get from SwitchBot app → Profile → Preferences → App Version (tap 10 times) → Developer Options
• API Secret: From the same Developer Options menu
• Device ID: The device ID of your SwitchBot Bot/Pusher

Optional Settings

• Accessory Name: Name displayed in HomeKit (default: "Pusher")
• Push Duration: How long to hold the push in seconds (default: 1, range: 0.5-10)
• Status Check Delay: How long to wait before verifying push completed (default: 2, range: 1-30)

Example Configuration

{
    "platform": "SwitchBotPusher",
    "name": "SwitchBot Pusher",
    "accessoryName": "Coffee Machine",
    "token": "your-switchbot-token",
    "secret": "your-switchbot-secret", 
    "deviceId": "your-device-id",
    "pushDuration": 1.5,
    "statusCheckDelay": 3
}

How It Works

1. Activation: When you turn the switch "on" in HomeKit, the plugin sends a "press" command to your SwitchBot Bot
2. Push Duration: The switch stays "on" for the configured duration while the bot physically pushes
3. Status Check: After the push duration + status check delay, the plugin verifies the push completed
4. Auto-Off: The switch automatically turns back "off" to indicate the push sequence is complete

Use Cases

Perfect for:

• Coffee machines with physical buttons
• Light switches that need to be pressed
• Appliances with momentary buttons
• Any device that requires a physical button press

API Requirements

• SwitchBot app account
• SwitchBot Bot device added to your account
• Developer API access enabled in the SwitchBot app

Troubleshooting

Common Issues

1. "Missing required configuration": Ensure token, secret, and deviceId are all provided
2. API errors: Verify your token and secret are correct and device ID matches your bot
3. Push not working: Check that your bot is online and properly positioned on the button
4. Switch doesn't turn off: Check logs for API errors during status verification

Debug Mode

Enable debug logging in Homebridge to see detailed API communication and timing information.

Support

For issues and feature requests, please visit the GitHub repository.

License

MIT License - see LICENSE file for details.