homescript 5.2

HomeScript CLI: Command Line Control of HomeBridge

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

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

---