Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/menahishayan/HomeScript

Python script for command line control of HomeBridge (HomeKit)
https://github.com/menahishayan/HomeScript

cli command-line home-automation homebridge homebridge-interface homebridge-plugin homekit ios lights linux modularity python python-script

Last synced: about 2 months ago
JSON representation

Python script for command line control of HomeBridge (HomeKit)

Host: GitHub
URL: https://github.com/menahishayan/HomeScript
Owner: menahishayan
License: gpl-3.0
Created: 2019-07-20T16:39:16.000Z (about 5 years ago)
Default Branch: master
Last Pushed: 2023-12-23T20:56:55.000Z (9 months ago)
Last Synced: 2024-05-04T01:02:11.178Z (5 months ago)
Topics: cli, command-line, home-automation, homebridge, homebridge-interface, homebridge-plugin, homekit, ios, lights, linux, modularity, python, python-script
Language: Python
Homepage:
Size: 105 KB
Stars: 93
Watchers: 6
Forks: 17
Open Issues: 10
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

# HomeScript
[![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg)](https://www.paypal.me/menahishayan)

Python script for command line control of [HomeBridge](https://github.com/nfarina/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+

## 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:
- \ : 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 `
- -s, --set : [EasyMatch] toggles the accessory On or Off, or sets to the specified value
- Usage: `hs.py -s [value]`
- Arguments:
- \ : 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 `
hs.py -s all \ value
- -d, --debug : generates debug log file.
- Usage: `hs.py -d `
- 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
```python
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