1 files changed, 52 insertions(+), 24 deletions(-)

M README.md

@@ 26,28 26,56 @@ New features:
 * Binding now understands which protocols must be paired and will indicate this during thing configuration.
 * Binding has very primitive support for using HomePods and AppleTV devices as audio sinks. This is preliminary and has a number of restrictions
 
-Installing:
-
-Because things are currently under heavy development, this binding will need to be built from source. 
-
-1. You'll need git, jdk, maven and python 3.8/3.9 installed before beginning. 
-2. If you happen to have pyatv installed already, you should uninstall it. This binding uses an enhanced (but hopefully backward-compatible) version.
-3. Install the customized version of PyATV:
-   a. git clone https://git.sr.ht/~hww3/pyatv
-   b. cd pyatv
-   c. sudo pip3 install . <-- note the "." is part of the command line.
-4. Make sure pyatv is installed:
-   a. atvremote scan <-- should find your ATV device.
-5. Prepare the appletv binding:
-   a. git clone https://git.sr.ht/~hww3/org.openhab.binding.appletv
-   b. cd org.openhab.binding.appletv
-   c. mvn clean package
-   d. If all goes well, copy the org.openhab.binding.appletv jar file to your openhab addons directory.
-   e. Profit (hopefully)!
-6. Standard binding troubleshooting applies here: 
-      delete your old AppleTV things, check the log files for errors and bundle:status in the openhab cli client. Restarting openhab might be helpful.
-7. The binding should auto-discover your devices. You'll need to generate pairing credentials and put them in your thing configuration.
-8. When you have added a new AppleTV thing and configured it properly with pairing information, it will be listed as "Online". 
+##Installing:
+
+_Install pyatv_
+
+The AppleTV binding uses pyatv to communicate with the various Apple devices it supports. I’ve made some enhancements to pyatv in order to support more features than currently exists in the main pyatv project. So, for now, the easiest thing we can do to prevent conflicts if you might already have pyatv installed is to use python’s “virtual environments” feature. This allows you to have multiple independent copies of python modules installed so that they don’t need to be installed in python’s main system location. 
+
+First, make sure you’ve got python 3 installed (I’m using python 3.8). Also, make sure you have git and gcc and friends, required to install pytv’s dependencies. There’s usually a build-essentials package that will install all of this for you.
+
+Now, run:
+
+# my copy of openhab is installed in /opt/openhab3; you’ll want to set this to 
+# whatever folder contains your user data director.
+
+OH_HOME=/opt/openhab3
+python3.8 -m venv $OH_HOME/userdata/tmp/appletv-binding
+source $OH_HOME/userdata/tmp/appletv-binding/bin/activate
+pip3.8 install git+https://git.sr.ht/~hww3/pyatv
+
+At this point, you’ve got a private installation of my customized pyatv located in the openhab temp directory. If you clear this out, you’ll need to reinstall pyatv. 
+
+Eventually, I’m going to attempt to automate this process so it won’t need to be done manually in the future.
+
+If you want to try out the pyatv installation, enable the python virtual environment you created by running:
+
+source $OH_HOME/userdata/tmp/appletv-binding/bin/activate
+
+And the command prompt should change to reflect this. Now you can run something like:
+
+atvremote scan
+
+And you should see output that shows your AppleTV and HomePod devices.
+
+Now, you’ll need to make sure that openhab can find this, and the easiest way to do that is to add that “activate” line above to your openhab startup script. For me, that’s in the $OH_HOME/start.sh script.
+
+If the binding can’t find the atvscript command (in particular), things won’t work and you’ll see failures in the log when the binding tries to do discovery and such.
+
+_Install the binding_
+
+Download the binding jar and place it in your OpenHAB addons/ directory. It should be detected automatically and be loaded. 
+
+Standard binding troubleshooting applies here: 
+
+      - delete your old AppleTV things.
+      - check the log files for errors.
+      - bundle:status in the openhab cli client.
+      - Restarting openhab might be helpful.
+
+The binding should auto-discover your devices. You'll need to generate pairing credentials and put them in your thing configuration. If you don't see your devices in the inbox after a few minutes, you should check the log files to see if there are errors related to running the pyatv tools (atvscript scan, etc). This is usually an indication that the pyatv tools aren't in the PATH that OpenHAB is looking in.
+
+When you have added a new AppleTV thing and configured it properly with pairing information, it will be listed as "Online". 
 
 Note: Each AppleTV thing should cause 2 copies of atvscript to run on your openhab host: atvscript push_updates and atvscript command_loop. The binding uses these to communicate with your AppleTV to receive status updates and send commands, respectively. If you see more than one of each running for each AppleTV thing (and especially if you see many more), please report it as a bug! 
 


@@ 90,13 118,13 @@ atvremote pair -i C869CD8002EA --protocol companion
 
 Once you've paired and entered the authentication strings into your thing configuration, the binding should connect and start receiving updates automatically. The binding currently outputs a good deal of information about the process, so if things don't seem to be working, you should check your openhab log file. 
 
-UPDATES:
+##UPDATES:
 
 * Added a number of new remote keys, such as Home, Home Hold and Skip Forward/Backward
 * Shuffle mode, Repeat mode and Position are wired up for setting
 * App Name and App ID channels are now updated properly
 
-TODO:
+##TODO:
 
 * Better error handling when pyATV has a problem
 * Need to control restarting of pyATV tools so that if the tool fails to start repeatedly, we back off. (in progress)