SwitchBot Smart Plug Control

A Python utility for controlling SwitchBot Smart Plugs using the SwitchBot API.

Overview

This project provides a set of Python scripts to interact with SwitchBot Smart Plugs. It allows users to:

• List all SwitchBot devices associated with your account
• Control smart plugs (turn on/off)
• Check the current status of smart plugs

Prerequisites

• Python 3.12 or higher
• SwitchBot account with API access
• SwitchBot Smart Plug device(s)
• SwitchBot API token and secret

Installation

1. Clone this repository:

   git clone https://github.com/yourusername/switchbot_smartplug_control.git
   cd switchbot_smartplug_control
   

2. Install dependencies using pipenv:

   pipenv install
   

3. Activate the virtual environment:

   pipenv shell
   

Configuration

1. Copy the example environment file:

   cp .env.example .env
   

2. Edit the .env file and update it with your own SwitchBot API credentials:

   TOKEN=your_switchbot_token_here
   SECRET=your_switchbot_secret_here
   DEVICE_ID=your_device_id_here
   

Note: If you don't know your device ID, you can run the get_device_id.py script to list all your devices.

Usage

List All Devices

To list all available SwitchBot devices and their IDs:

python get_device_id.py

Control a Smart Plug

To control a smart plug, use the plug_control.py script:

# Get current status
python plug_control.py status

# Turn on the plug
python plug_control.py on

# Turn off the plug
python plug_control.py off

Check Device Details

To view detailed information about your SwitchBot device:

python check_device.py

Project Structure

• get_device_id.py - Script to list all your SwitchBot devices and their IDs
• plug_control.py - Main script for controlling the smart plug
• check_device.py - Utility script to check device details and available methods
• Pipfile & Pipfile.lock - Dependency management with pipenv
• .env - Environment variables file (contains your API credentials)
• .env.example - Example environment variables file
• .gitignore - Git ignore file to prevent committing sensitive files

API Documentation

This project uses the python-switchbot library. For more details on the SwitchBot API, refer to:

• SwitchBot API Documentation
• python-switchbot Documentation

Security Note

This project now uses environment variables to store sensitive API credentials:

• Your actual credentials are stored in the .env file
• The .env file is included in .gitignore to prevent accidental commits
• Use the .env.example file as a template for setting up your credentials
• Never commit your actual API tokens to version control

License

This project is available under the MIT License.

Last Updated

June 13, 2025