HomeScript

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

---