Merge pull request #21 from maddox/2.0

2.0

README.md

@@ -1,18 +1,19 @@
 # Harmony API!!
 
-Harmony API is a simple server allowing you to query/control a local [Harmony
-Home Hub](http://myharmony.com/products/detail/home-hub/) over HTTP or MQTT.
+Harmony API is a simple server allowing you to query/control multiple local [Harmony
+Home Hubs](http://myharmony.com/products/detail/home-hub/) over HTTP or MQTT.
 
 With HTTP, you can simply turn your devices on and off and check their status
 with simple HTTP requests from almost any other project.
 
-With MQTT, you can easily monitor the state of your devices as well as switch
-the current activity of your whole hub. This makes it super easy to integrate
+With MQTT, you can easily monitor the state of your devices as well as set
+the current activity of your hub. This makes it super easy to integrate
 into your existing home automation setup.
 
 
 ## Features
 
+* Control multiple Harmony hubs.
 * List activities.
 * Get current status, including if everything is off, or what the current activity is.
 * Turn everything off.
@@ -24,12 +25,12 @@ into your existing home automation setup.
 
 ## Settings
 
-Harmony API discovers your hub automatically. You can optionally add your MQTT
+Harmony API discovers your hubs automatically. You can optionally add your MQTT
 broker's host to connect to it.
 
 ```json
 {
-  "mqtt_host": "192.168.1.106",
+  "mqtt_host": "mqtt://192.168.1.106",
   "mqtt_options": {
       "port": 1883,
       "username": "someuser",
@@ -52,7 +53,16 @@ variable to use your own port.
 ### Forever
 harmony-api has support for [Forever](https://github.com/foreverjs/forever). It uses
 `launchd` on OS X to kick it off so that it starts on boot. There is no `init.d`
-other Linux support of this type. Pull requests would be welcome for this though.
+or other Linux support of this type. Pull requests would be welcome for this though.
+
+## How to Upgrade to 2.0
+
+Simply run `script/upgrade` from the root of the project and Harmony API will
+upgrade to the newest version.
+
+You are then going to have to change anything you integrate with Harmony API to
+reflect the change in HTTP endpoints and MQTT topics. Read the docs in this
+README to see how they have changed.
 
 ### Development
 You can simply run it by calling `script/server`. This will run it in development
@@ -85,7 +95,7 @@ Launch the app via `script/server` to run it in the development environment.
 ## MQTT Docs
 
 harmony-api can report its state changes to your MQTT broker. Just edit your
-config file in `config/config.json` to add your MQTT host.
+config file in `config/config.json` to add your MQTT host and options.
 
 By default harmony-api publishes topics with the namespace of: `harmony-api`. This can be overriden
 by setting `topic_namespace` in your config file.
@@ -95,29 +105,32 @@ by setting `topic_namespace` in your config file.
 When the state changes on your harmony hub, state topics will be immediately
 broadcasted over your broker. There's quite a few topics that are broadcasted.
 
+State topics are namespaced by your Harmony hub's name, as a slug. You can rename your hub
+in the Harmony app.
+
 Here's a list:
 
 #### Current State
 
 This topic describes the current power state. Message is `on` or `off`.
 
-`harmony-api/state` `on`
+`harmony-api/hubs/family-room/state` `on`
 
 #### Current Activity
 
 This topic describes what the current activity of the hub is. The message is
 the slug of an activity name.
 
-`harmony-api/current_activity` `watch-tv`
+`harmony-api/hubs/family-room/current_activity` `watch-tv`
 
 #### Activity States
 
 These topics describe the state of each activity that the hub has. The message
 is `on` or `off`. There will a topic for every activity on your hub.
 
-`harmony-api/activities/watch-tv/state` `off`  
-`harmony-api/activities/watch-apple-tv/state` `on`  
-`harmony-api/activities/play-xbox-one/state` `off`  
+`harmony-api/hubs/family-room/activities/watch-tv/state` `off`  
+`harmony-api/hubs/family-room/activities/watch-apple-tv/state` `on`  
+`harmony-api/hubs/family-room/activities/play-xbox-one/state` `off`  
 
 
 ### Command Topics
@@ -126,20 +139,18 @@ You can also command harmony-api to change activities by publishing topics.
 harmony-api listens to this topic and will change to the activity when it sees
 it.
 
-Just provide the slug of the activity you want to switch to and `on` as the
-message. Any use of this topic with the message `off` will turn everything off.
+Just provide the slug of the hub and activity you want to switch to and `on` as
+the message. Any use of this topic with the message `off` will turn everything
+off.
 
 `harmony-api/activities/watch-tv/command` `on`  
 
 
 ## HTTP API Docs
 
-This is a quick overview of the service. Read [app.js](app.js) if you need more
+This is a quick overview of the HTTP service. Read [app.js](app.js) if you need more
 info.
 
-:warning: These endpoints may not be stable as this project moves fast towards
-`1.0.0`.
-
 ### Resources
 
 Here's a list of resources that may be returned in a response.
@@ -181,20 +192,15 @@ These are the endpoints you can hit to do things.
 #### Info
   Use these endpoints to query the current state of your Harmony Hub.
 
-    GET /status => StatusResource
-    GET /activities => {:activities => [ActivityResource, ActivityResource, ...]}
+    GET /hubs => {"hubs": ["family-room", "bedroom"] }
+    GET /hubs/:hub_slug/status => StatusResource
+    GET /hubs/:hub_slug/activities => {"activities": [ActivityResource, ActivityResource, ...]}
 
 #### Control
   Use these endpoints to control your devices through your Harmony Hub.
 
-    PUT /off => NowPlayingResource => {message: "ok"}
-    POST /start_activity?activity=watch-tv => {message: "ok"}
-
-## To Do
-
-- [ ] Support multiple Harmony Hubs
-- [ ] Support raw commands to control individual devices
-
+    PUT /hubs/:hub_slug/off => {message: "ok"}
+    POST /hubs/:hub_slug/start_activity?activity=watch-tv => {message: "ok"}
 
 ## Contributions