/HomeScript

Python script for command line control of HomeBridge (HomeKit)

Primary LanguagePythonGNU General Public License v3.0GPL-3.0

HomeScript

Donate

Python script for command line control of HomeBridge (HomeKit)

Used to toggle Homebridge accessories On or Off via python script, no Home app required. You can set up a cronjob to enable automation, scripting and mimic other HomeKit functionalities

Note: as of HomeScript 4.1 the minimum requirement is Python3+ and HomeBridge 1.x.x+

Examples

hs.py -s MainLight 0 | Switch off
hs.py -s MainLight 1 | Switch on
hs.py -s MainLight | Toggle
hs.py -s lifx -hue 140 | RGB Lights Support (brightness, hue, saturation, temperature)
hs.py -s desk -b +10 | Increment/Decrement values

Easy Match

The script doesn't require full names of the accessories.

For example, if your light is called "MainLight", you can run:
hs.py -s MainLight 0 or
hs.py -s main 0
The script will automatically search for matching substrings and set the accessory value

Group Actions

You can set multiple accessories (of the same type) in a single command:
hs.py -s all lights 1
hs.py -s all switches 0

Looking for maintainers: If you are interested in maintaining this project, feel free to reach out.

Setup

Important: HomeBridge must be run in insecure mode for this script to work!

Running HomeBridge in Insecure Mode

  • via Command Line
homebridge -I
  • via Systemd
HOMEBRIDGE_OPTS=-U /var/lib/homebridge -I
  • via pm2
pm2 stop homebridge; pm2 delete homebridge; pm2 start homebridge -- -I

Installation

  • Install the HomeScript API pip install homescript or pip3 install homescript
  • On your client computer: Download hs.py and move it to a convenient location
    • Edit the script to include your homebridge URL, port and authorization key
    • Change permissions chmod +x /path/to/hs.py (on linux)

Usage

Usage: hs.py [option] [value]

Options:

  • -l, --list : Lists all available HomeKit accessories
  • Usage: hs.py -l [argument]
  • Arguments:
    • <none> : lists accessory names
    • aid : lists accessory names with AID value
    • iid : lists accessory names with IID value
    • id : lists accessory names with AID and IID
    • type : lists accessory names with type
    • value : lists accessory names current state
  • -g, --get : [EasyMatch] gets current value of accessory
    • Usage: hs.py -g <accessory-name>
  • -s, --set : [EasyMatch] toggles the accessory On or Off, or sets to the specified value
    • Usage: hs.py -s <accessory-name> [value]
    • Arguments:
      • <accessory-name> : accessory that you want to change
      • -b : adjusts accessory brightness
      • -hue : adjusts accessory hue
      • -sat : adjusts accessory saturation
      • -t : adjusts accessory color temperature
      • [value] : value that you want to set it to. Prefix +/- to inc/dec
  • all : Gets or sets value of multiple HomeKit accessories
    • Usage: hs.py -g all <accessory-type> hs.py -s all <accessory-type> value
  • -d, --debug : generates debug log file.
    • Usage: hs.py -d <command>
    • Eg: hs.py -d -s all lights 0
  • -h, --help : prints usage info
  • -v, --version : prints HomeScript version

API

As of v5.1+ HomeScript is now a fully importable API

import homescript

# Initialize with hostname, port and auth code. Debug and sys.argv are optional
hs = homescript.HomeScript(hostname, port, auth, [debug], [sys.argv])

# Select an accessory or group of accessories. Any get/set/print operation requires accessories to be selected first.
hs.selectAccessory('mainlight')
hs.selectGroup('lights')

hs.printSelectedItems()

# Operates on all selected items
hs.setStates(1)
hs.setValues('Brightness',250)
Function Description
HomeScript( hostname: str, port: str, auth: str, debug: Boolean, argv: list ) Constructor to initialize HomeBridge Connection. Debug: Set to True if you want to create debug and exception logfile. Default: None. argv: Only required if debug is True
getAccessories() Returns raw list of all available accessories on the Bridge
selectAccessories( searchString: str ) Saves matching accessory into selectedAccessories and returns them
selectGroup( searchString: str ) Saves all matching accessories into selectedAccessories and returns them
printAccessories() Prints all available accessories on the Bridge
printSelectedItems() Prints selectedAccessories
getSelectedItems() Returns selectedAccessories
setStates(state: Boolean) Sets state as the on/off value of all item(s) in selectedAccessories. If no argument is specified it toggles the state of all selectedAccessories
setValues(attribute: str, value: int) Sets numeric value to attribute of the item(s) in selectedAccessories. Attrubute: Brightness/Hue/Saturation/Color Temperature
getVersion() Does what it says on the can...

Troubleshooting/Error Reporting/Contributing

The debug option helps generate a logfile for troubleshooting and error detection.

  • If you face an error, open a new issue on this repo prefixed by [Error] describing the error and attach your both your debug log and your exception log, along with any other outputs you receive.
  • If you would like to help improve the tool or request features, open an issue prefixed by [Feature Request] describing the functionality.
  • You must attach your debug log or else your issue will be closed. A simple debug log can be obtained from hs.py -d -l

PRs and Commit Template

PRs and commits that you make to this repo must include the following:

  • Type: bug-fix or enhancement
  • Description: Brief description about what the commit achieves
  • Notes: (heads ups/pointers to other developers if necessary)

To Do

☑️ Color control for RGB and Hue Lights
⬜️ Control for PositionOpeners, GarageDoorOpener, LockMechanism
⬜️ WebColors
☑️ Increment/Decrement values
☑️ Querying API interface to return status of devices to stdout
☑️ Automation creation, viewing and monitoring without Home Hub

Changelog

v5.2

  • Added support for Increment/Decrement values
  • HS Automations and HS Apps are now deprecated

v5.1.1

  • Fixed import bug

v5.1

  • Rewritten from the ground up to be object oriented
  • Now features an importable API

v5.0

  • Support for RGB lights! Now lets you control brightness, hue, saturation and color temperature of your lights!
  • Added additional value format recognition
  • Device type detection
  • Updated accessory structure
  • Added smart toggle support for integer values
  • Added validity checks for integer values
  • Ignore bridge in accessory list
  • Updated listing format
  • Finer control over listing parameters for devices with multiple interfaces
  • Updated exclusive value-only listing for easier interfacing in programs
  • Cleaned up accessory name recognition
  • Backward compatibility with v4.x syntax for all devices

v4.1

  • Update to python 3
  • Update to support HomeBridge v1.0+

v4.0

  • Syntax update to be POSIX compliant
  • Get option to return item status
  • Introducing Automation and scripting support
  • Modularity and Third-party HomeScript Apps
  • Version logging
  • Improved Debugging Note: Some parts of release withheld until the next minor release

v3.0.2

  • Bug fix: HomeBridge was displayed as "0"

v3.0.1

  • Added debug support

v3.0

  • Added group actions. You can now set values for all matching accessory types

v2.2

  • Added json listing support

v2.1

  • Added type support to identify accessory type
  • Updated help doc

v2.0

  • List of accessories are now automatically fetched from the homebridge, instead of having to manually set them up in the script

v1.3

  • Added easy name matching

v1.2

  • Added help doc
  • Added listing

v1.1

  • Added toggling

v1.0

  • Initial release