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+
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!
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
importhomescript# Initialize with hostname, port and auth code. Debug and sys.argv are optionalhs=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 itemshs.setStates(1)
hs.setValues('Brightness',250)
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
请发表评论