Metadata-Version: 2.1
Name: homescript
Version: 5.2
Summary: HomeScript CLI: Command Line Control of HomeBridge
Home-page: https://github.com/menahishayan/HomeScript
Author: Menahi Shayan
Author-email: menahi.shayan@gmail.com
License: UNKNOWN
Description: # 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+
        
        ## 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
        ```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)
        
        <hr/>
        
        ## 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  
        
        <hr/>
        
        ## 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
        
        <hr/>
        
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
