From fd516a6784f8856ab4165937c0be2b46118ffbae Mon Sep 17 00:00:00 2001 From: Paulus Schoutsen Date: Sun, 21 Dec 2014 20:16:45 -0800 Subject: [PATCH] Updated content --- source/api/index.markdown | 100 +++++++++++++++++++------- source/architecture/index.markdown | 10 ++- source/demo/states.json | 6 +- source/developers/index.markdown | 52 ++++++++------ source/getting-started/index.markdown | 6 +- 5 files changed, 120 insertions(+), 54 deletions(-) diff --git a/source/api/index.markdown b/source/api/index.markdown index 56a512711ed..6c27f9bc2ce 100644 --- a/source/api/index.markdown +++ b/source/api/index.markdown @@ -30,7 +30,7 @@ Successful calls will return status code 200 or 201. Other status codes that can The api supports the following actions: -**/api - GET**
+#### GET /api Returns message if API is up and running. ```json @@ -39,7 +39,7 @@ Returns message if API is up and running. } ``` -**/api/events - GET**
+#### GET /api/events Returns an array of event objects. Each event object contain event name and listener count. ```json @@ -55,7 +55,7 @@ Returns an array of event objects. Each event object contain event name and list ] ``` -**/api/services - GET**
+#### GET /api/services Returns an array of service objects. Each object contains the domain and which services it contains. ```json @@ -76,7 +76,7 @@ Returns an array of service objects. Each object contains the domain and which s ] ``` -**/api/states - GET**
+#### GET /api/states Returns an array of state objects. Each state has the following attributes: entity_id, state, last_changed and attributes. ```json @@ -99,7 +99,7 @@ Returns an array of state objects. Each state has the following attributes: enti ] ``` -**/api/states/<entity_id>** - GET
+#### GET /api/states/<entity_id> Returns a state object for specified entity_id. Returns 404 if not found. ```json @@ -114,13 +114,20 @@ Returns a state object for specified entity_id. Returns 404 if not found. } ``` -**/api/states/<entity_id>** - POST
+#### POST /api/states/<entity_id> Updates or creates the current state of an entity. -Return code is 200 if the entity existed, 201 if the state of a new entity was set. A location header will be returned with the url of the new resource. The response body will contain a JSON encoded State object.
-
-parameter: state - string
-optional parameter: attributes - JSON object +Expects a JSON object that has atleast a state attribute: + +```json +{ + "state": "below_horizon", + "next_rising": "07:04:15 29-10-2013", + "next_setting": "18:00:31 29-10-2013" +} +``` + +Return code is 200 if the entity existed, 201 if the state of a new entity was set. A location header will be returned with the url of the new resource. The response body will contain a JSON encoded State object. ```json { @@ -134,9 +141,18 @@ optional parameter: attributes - JSON object } ``` -**/api/events/<event_type>** - POST
-Fires an event with event_type
-optional body: JSON encoded object that represents event_data +#### POST /api/events/<event_type> +Fires an event with event_type + +You can pass an optional JSON object to be used as `event_data`. + +```json +{ + "next_rising": "18:00:31 29-10-2013" +} +``` + +Returns a message if successful. ```json { @@ -144,11 +160,18 @@ optional body: JSON encoded object that represents event_data } ``` -**/api/services/<domain>/<service>** - POST
-Calls a service within a specific domain. Will return when the service has been executed or 10 seconds has past, whichever comes first.
-optional body: JSON encoded object that represents service_data +#### POST /api/services/<domain>/<service> +Calls a service within a specific domain. Will return when the service has been executed or 10 seconds has past, whichever comes first. -Returns a list of states that have changed since the start of this service call. +You can pass an optional JSON object to be used as `service_data`. + +```json +{ + "entity_id": "light.Ceiling" +} +``` + +Returns a list of states that have changed while the service was being executed. ```json [ @@ -170,11 +193,24 @@ Returns a list of states that have changed since the start of this service call. ] ``` -**/api/event_forwarding** - POST
-Setup event forwarding to another Home Assistant instance.
-parameter: host - string
-parameter: api_password - string
-optional parameter: port - int
+

Note

+The result will include any changed states that changed while the service was being executed, even if their change was the result of something else happening in the system. +

+ +#### POST /api/event_forwarding +Setup event forwarding to another Home Assistant instance. + +Requires a JSON object that represents the API to forward to. + +```json +{ + "host": "machine", + "api_password": "my_super_secret_password", + "port": 8880 // optional +} +``` + +It will return a message if event forwarding was setup successful. ```json { @@ -182,15 +218,27 @@ optional parameter: port - int
} ``` -**/api/event_forwarding** - DELETE
+#### DELETE /api/event_forwarding Cancel event forwarding to another Home Assistant instance.
-parameter: host - string
-optional parameter: port - int
-If your client does not support DELETE HTTP requests you can add an optional attribute _METHOD and set its value to DELETE. +Requires a JSON object that represents the API to cancel forwarding to. + +```json +{ + "host": "machine", + "api_password": "my_super_secret_password", + "port": 8880 // optional +} +``` + +It will return a message if event forwarding was cancelled successful. ```json { "message": "Event forwarding cancelled." } ``` + +

Note

+If your client does not support DELETE HTTP requests you can add an optional attribute _METHOD and set its value to DELETE. +

diff --git a/source/architecture/index.markdown b/source/architecture/index.markdown index 674898fb4ad..cf70fd82918 100644 --- a/source/architecture/index.markdown +++ b/source/architecture/index.markdown @@ -30,10 +30,14 @@ This setup allows us to create simple yet powerful logic for controlling your ho If the sun has set and the lights are not on: Turn on the lights + + In the event that the combined state of all tracked devices changes to 'Not Home': If the lights are on: Turn off the lights + + In the event of the sun setting: If the lights are off and the combined state of all tracked device equals 'Home': Turn on the lights @@ -44,8 +48,6 @@ By using the Bus as a central communication hub between components it is easy to Home Assistant supports running multiple synchronzied instances using a master-slave model. Slaves forward all local events fired and states set to the master instance which will then replicate it to each slave. -Because each slave maintains its own ServiceRegistry it is possible to have multiple slaves respond to one service call. - @@ -65,3 +67,7 @@ http.setup(hass, "my_local_api_password") hass.start() hass.block_till_stopped() ``` + +

Note

+Because each slave maintains its own ServiceRegistry it is possible to have multiple slaves respond to one service call. +

\ No newline at end of file diff --git a/source/demo/states.json b/source/demo/states.json index c5fa7447da8..cff185cc590 100644 --- a/source/demo/states.json +++ b/source/demo/states.json @@ -90,7 +90,7 @@ }, { "attributes": { - "entity_picture": "http://graph.facebook.com/KillBillMovie/picture", + "entity_picture": "//graph.facebook.com/KillBillMovie/picture", "friendly_name": "Living Room" }, "entity_id": "chromecast.Living_Rm", @@ -117,7 +117,7 @@ }, { "attributes": { - "entity_picture": "http://graph.facebook.com/schoutsen/picture" + "entity_picture": "//graph.facebook.com/schoutsen/picture" }, "entity_id": "device_tracker.Paulus", "last_changed": "14:55:25 21-12-2014", @@ -157,7 +157,7 @@ }, { "attributes": { - "entity_picture": "http://graph.facebook.com/anne.t.frederiksen/picture" + "entity_picture": "//graph.facebook.com/anne.t.frederiksen/picture" }, "entity_id": "device_tracker.Anne_Therese", "last_changed": "14:55:25 21-12-2014", diff --git a/source/developers/index.markdown b/source/developers/index.markdown index 36a995b1c38..0840ac9f1c2 100644 --- a/source/developers/index.markdown +++ b/source/developers/index.markdown @@ -8,52 +8,64 @@ sharing: true footer: true --- -Home Assistant can be extended by components. Components can listen for- or trigger events and offer services. Components are written in Python and can do all the goodness that Python has to offer. +Home Assistant can be extended by components. Each component is responsible for a specific domain within Home Assistant. An example is the switch component, which is responsible for interaction with different types of switches. Components can listen for- or trigger events, offer services and maintain states. Components are written in Python and can do all the goodness that Python has to offer. Home Assistant offers [built-in components]({{site_root}}/components/) but it is easy to built your own. An example component can be found in [`/config/custom_components/example.py`](https://github.com/balloob/home-assistant/blob/master/config/custom_components/example.py). +## Component structure + +Components that interact with devices are structured in core- and platform logic. This allows the same logic to be used for different platforms. Components that add automation usually consist of, but are not limited to, one file. + +For example, the built-in switch component consists of the following files in [`homeassistant/components/switch/`](https://github.com/balloob/home-assistant/tree/master/homeassistant/components/switch): + +| File | Description | +| ---- | ----------- | +| \_\_init\_\_.py | Contains the Switch core logic.| +| wemo.py | WeMo platform logic. Included if in config `platform=wemo`. | +| tellstick.py | Tellstick platform logic. Included if in config `platform=tellstick`. | + +## Deciding what to built + +If you are planning to add support for a new type of device to an existing component, you can get away with only writing a platform. Have a look at how the component works with other platforms and create a similar file for the platform that you would like to add. +

Note

-Home Assistant will use the directory that contains your config file as the directory that holds your customizations. By default this is the config folder in your current work directory. You can use a different folder by running Home Assistant with the --config argument python3 homeassistant --config /YOUR/CONFIG/PATH/. +Platform logic should not interface directly with the devices but use a third-party Python 3 library that speaks the actual API.

+## Loading components + A component will be loaded on start if a section (ie. `[light]`) for it exists in the config file. A component can also be loaded if another component is loaded that depends on it. When loading a component Home Assistant will check the following paths: * <config directory>/custom_components/<component name> * homeassistant/components/<component name> (built-in components) -Once loaded, a component will only be setup if all dependencies can be loaded and are able to setup. Keep an eye on the logs to see if loading and setup of your component went well. +Once loaded, a component will only be setup if all dependencies can be loaded and are able to setup. Keep an eye on the logs to see if your component could be loaded and initialized.

Warning

-*Warning:* You can override a built-in component by offering a component with the same name in your custom_components folder. This is not recommended and may lead to unexpected behavior! +You can override a built-in component by having a component with the same name in your config/custom_components folder. This is not recommended and will probably break things!

-Each component is responsible for a specific domain within Home Assistant. An example is the switch component, which is responsible for interaction with different types of switches. The switch component consists of the following files in `homeassistant/components/switch/`: +

Note

+Home Assistant will use the directory that contains your config file as the directory that holds your customizations. By default this is the config folder in your current work directory. You can use a different folder by running Home Assistant with the --config argument: python3 homeassistant --config /YOUR/CONFIG/PATH/. +

-| File | Description | -| ---- | ----------- | -| \_\_init\_\_.py | Contains the Switch component code.| -| wemo.py | WeMo platform support. Included if in config `platform=wemo`. | -| tellstick.py | Tellstick platform support. Included if in config `platform=tellstick`. | +## Initializing components -If a component exists, your job is easy. Have a look at how the component works with other platforms and create a similar file for the platform that you would like to add. If you cannot find a suitable component, you'll have to add it yourself. When writing a component try to structure it after the Switch component to maximize reusability. - -Communication between Home Assistant and devices should happen via third-party libraries that implement the device API. This will make sure the platform support code stays as small as possible. - -After a component is loaded the bootstrapper will call its setup method `setup(hass, config)`: +After loading, the bootstrapper will call `setup(hass, config)` method on the component to initialize it. The following parameters are passed in: | Parameter | Description | | --------- | ----------- | -| hass | The Home Assistant object. Call its methods to track time, register services or listen for events: [Overview of available methods.](https://github.com/balloob/home-assistant/blob/master/homeassistant/__init__.py#L38) | -| config | A dict containing the configuration. The keys of the config-dict are component names and the value is another dict with configuration attributes. | +| hass | The Home Assistant object. Call its methods to track time, register services, listen for events or track states: [Overview of available methods.](https://github.com/balloob/home-assistant/blob/master/homeassistant/__init__.py#L38) | +| config | A dict containing the configuration. The keys of the config-dict are component names and the value is another dict with the component configuration. | ### Guidance on using the Home Assistant object The Home Assistant object contains three objects to help you interact with the system. | Object | Description | | ------ | ----------- | -| hass.states | This is the StateMachine. The StateMachine allows you to see which states are available and set/test states for specified entities. [See available methods](https://github.com/balloob/home-assistant/blob/master/homeassistant/__init__.py#L473). | -| hass.events | This is the EventBus. The EventBus allows you to listen and trigger events. [See available methods](https://github.com/balloob/home-assistant/blob/master/homeassistant/__init__.py#L308). | -| hass.services | This is the ServiceRegistry. The ServiceRegistry allows you to register services. [See available methods](https://github.com/balloob/home-assistant/blob/master/homeassistant/__init__.py#L589). | +| hass.states | This is the StateMachine. It allows you to set states and trach when they are changed. [See available methods](https://github.com/balloob/home-assistant/blob/master/homeassistant/__init__.py#L473). | +| hass.events | This is the EventBus. It allows you to trigger and listen for events.
[See available methods](https://github.com/balloob/home-assistant/blob/master/homeassistant/__init__.py#L308). | +| hass.services | This is the ServiceRegistry. It allows you to register services.
[See available methods](https://github.com/balloob/home-assistant/blob/master/homeassistant/__init__.py#L589). | ### Example on using the configuration parameter If your configuration file containes the following lines: diff --git a/source/getting-started/index.markdown b/source/getting-started/index.markdown index c6e59535c0c..3bbc9596181 100644 --- a/source/getting-started/index.markdown +++ b/source/getting-started/index.markdown @@ -18,7 +18,7 @@ pip3 install -r requirements.txt python3 -m homeassistant ``` -This will start the Home Assistant server and create an initial configuration file in `config/home-assistant.conf` that is setup for demo mode. It will launch its web interface on [http://127.0.0.1:8123](http://127.0.0.1:8123). The default password is 'password'. +This will start the Home Assistant server and create an initial configuration file `config/home-assistant.conf` that is setup for demo mode. It will launch its web interface on [http://127.0.0.1:8123](http://127.0.0.1:8123). The default password is 'password'. If you're using Docker, you can use @@ -26,7 +26,7 @@ If you're using Docker, you can use docker run -d --name="home-assistant" -v /path/to/homeassistant/config:/config -v /etc/localtime:/etc/localtime:ro -p 8123:8123 balloob/home-assistant ``` -After you got the demo mode running it is time to enable some [components]({{site_root}}/components/) and get started. An example configuration file has been provided in [`/config/home-assistant.conf.example`](https://github.com/balloob/home-assistant/blob/master/config/home-assistant.conf.example). +After you got the demo mode running it is time to customize your configuration and enable some [built-in components]({{site_root}}/components/). See [`/config/home-assistant.conf.example`](https://github.com/balloob/home-assistant/blob/master/config/home-assistant.conf.example) for an example configuration.

Note

You can append ?api_password=YOUR_PASSWORD to any url to log in automatically. @@ -69,7 +69,7 @@ Tomato requires an extra config variable called `http_id`. The value can be obta

Note on Luci

-Before the Luci scanner can be used you have to install the luci RPC package on OpenWRT: `opkg install luci-mod-rpc`. +Before the Luci scanner can be used you have to install the luci RPC package on OpenWRT: opkg install luci-mod-rpc.

Once tracking, the `device_tracker` component will maintain a file in your config dir called `known_devices.csv`. Edit this file to adjust which devices have to be tracked. Here you can also setup a url for each device to be used as the entity picture.