jeans/home-assistant.io
jeans/home-assistant.io
1
0
Fork 0
mirror of https://github.com/home-assistant/home-assistant.io.git synced 2025-07-19 07:17:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

Make titles linkable

Browse Source
This commit is contained in:
Fabian Affolter 2017-02-02 12:05:43 +01:00
parent 53c3ff3fdc
commit ebecd9fce6
No known key found for this signature in database
GPG Key ID: E23CD2DD36A4397F
1 changed files with 39 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

78
source/developers/websocket_api.markdown
View File

@ -13,7 +13,7 @@ Home Assistant contains a websocket API. This API can be used to stream informat
- [JavaScript](https://github.com/home-assistant/home-assistant-js-websocket) - powers the frontend - [JavaScript](https://github.com/home-assistant/home-assistant-js-websocket) - powers the frontend
# Server states # {% linkable_title Server states %}
1. Client connects 1. Client connects
2. Authentication phase starts 2. Authentication phase starts
@ -31,20 +31,20 @@ Home Assistant contains a websocket API. This API can be used to stream informat
During the command phase, the client attaches a unique identifier to each message. The server will add this identifier to each message so that the client can link each message to it's origin. During the command phase, the client attaches a unique identifier to each message. The server will add this identifier to each message so that the client can link each message to it's origin.
# Message format # {% linkable_title Message format %}
Each API message is a JSON serialized object containing a `type` key. After the authentication phase messages also must contain an `id`, an integer that contains the number of interactions. Each API message is a JSON serialized object containing a `type` key. After the authentication phase messages also must contain an `id`, an integer that contains the number of interactions.
Example of an auth message: Example of an auth message:
```json5 ```json
{ {
"type": "auth", "type": "auth",
"api_password": "supersecret" "api_password": "supersecret"
} }
``` ```
```json5 ```json
{ {
"id" 5, "id" 5,
"type":"event", "type":"event",
@ -57,13 +57,13 @@ Example of an auth message:
} }
``` ```
# Authentication phase # {% linkable_title Authentication phase %}
When a client connects to the server, the server will test if the client is authenticated. Authentication will not be necessary if no api_password is set or if the user fulfills one of the other criteria for authentication (trusted network, password in url/header). When a client connects to the server, the server will test if the client is authenticated. Authentication will not be necessary if no api_password is set or if the user fulfills one of the other criteria for authentication (trusted network, password in url/header).
If no authentication is needed, the authentication phase will complete and the server will send an `auth_ok` message. If no authentication is needed, the authentication phase will complete and the server will send an `auth_ok` message.
```json5 ```json
{ {
"type": "auth_ok" "type": "auth_ok"
} }
@ -71,7 +71,7 @@ If no authentication is needed, the authentication phase will complete and the s
If authentication is necessary, the server sends out `auth_required`. If authentication is necessary, the server sends out `auth_required`.
```json5 ```json
{ {
"type": "auth_required" "type": "auth_required"
} }
@ -79,7 +79,7 @@ If authentication is necessary, the server sends out `auth_required`.
This means that the next message from the client should be an auth message: This means that the next message from the client should be an auth message:
```json5 ```json
{ {
"type": "auth", "type": "auth",
"api_password": "supersecret" "api_password": "supersecret"
@ -88,7 +88,7 @@ This means that the next message from the client should be an auth message:
If the client supplies valid authentication, the authentication phase will complete by the server sending the `auth_ok` message: If the client supplies valid authentication, the authentication phase will complete by the server sending the `auth_ok` message:
```json5 ```json
{ {
"type": "auth_ok" "type": "auth_ok"
} }
@ -96,18 +96,18 @@ If the client supplies valid authentication, the authentication phase will compl
If the data is incorrect, the server will reply with `auth_invalid` message and disconnect the session. If the data is incorrect, the server will reply with `auth_invalid` message and disconnect the session.
```json5 ```json
{ {
"type": "auth_invalid", "type": "auth_invalid",
"message": "Invalid password" "message": "Invalid password"
} }
``` ```
# Command phase # {% linkable_title Command phase %}
During this phase the client can give commands to the server. The server will respond to each command with a `result` message indicating when the command is done and if it was successful. During this phase the client can give commands to the server. The server will respond to each command with a `result` message indicating when the command is done and if it was successful.
```json5 ```json
{ {
"id": 6. "id": 6.
"type": "result", "type": "result",
@ -117,11 +117,11 @@ During this phase the client can give commands to the server. The server will re
} }
``` ```
## Subscribe to events ## {% linkable_title Subscribe to events %}
The command `subscribe_events` will subscribe your client to the event bus. You can either listen to all events or to a specific event type. If you want to listen to multiple event types, you will have to send multiple `subscribe_events` commands. The command `subscribe_events` will subscribe your client to the event bus. You can either listen to all events or to a specific event type. If you want to listen to multiple event types, you will have to send multiple `subscribe_events` commands.
```json5 ```json
{ {
"id": 18, "id": 18,
"type": "subscribe_events", "type": "subscribe_events",
@ -132,7 +132,7 @@ The command `subscribe_events` will subscribe your client to the event bus. You
The server will respond with a result message to indicate that the subscription is active. The server will respond with a result message to indicate that the subscription is active.
```json5 ```json
{ {
"id": 18, "id": 18,
"type": "result", "type": "result",
@ -143,7 +143,7 @@ The server will respond with a result message to indicate that the subscription
For each event that matches, the server will send a message of type `event`. The `id` in the message will point at the original `id` of the `listen_event` command. For each event that matches, the server will send a message of type `event`. The `id` in the message will point at the original `id` of the `listen_event` command.
```json5 ```json
{ {
"id": 18, "id": 18,
"type":"event", "type":"event",
@ -190,11 +190,11 @@ For each event that matches, the server will send a message of type `event`. The
} }
``` ```
## Unsubscribing from events ## {% linkable_title Unsubscribing from events %}
You can unsubscribe from previously created subscription events. Pass the id of the original subscription command as value to the subscription field. You can unsubscribe from previously created subscription events. Pass the id of the original subscription command as value to the subscription field.
```json5 ```json
{ {
"id": 19, "id": 19,
"type": "unsubscribe_events", "type": "unsubscribe_events",
@ -204,7 +204,7 @@ You can unsubscribe from previously created subscription events. Pass the id of
The server will respond with a result message to indicate that unsubscribing was successful. The server will respond with a result message to indicate that unsubscribing was successful.
```json5 ```json
{ {
"id": 19, "id": 19,
"type": "result", "type": "result",
@ -214,7 +214,7 @@ The server will respond with a result message to indicate that unsubscribing was
``` ```
## Calling a service ## {% linkable_title Calling a service %}
This will call a service in Home Assistant. Right now there is no return value. The client can listen to `state_changed` events if it is interested in changed entities as a result of a service call. This will call a service in Home Assistant. Right now there is no return value. The client can listen to `state_changed` events if it is interested in changed entities as a result of a service call.
@ -233,7 +233,7 @@ This will call a service in Home Assistant. Right now there is no return value.
The server will indicate with a message indicating that the service is done executing. The server will indicate with a message indicating that the service is done executing.
```json5 ```json
{ {
"id": 24, "id": 24,
"type": "result", "type": "result",
@ -242,11 +242,11 @@ The server will indicate with a message indicating that the service is done exec
} }
``` ```
## Fetching states ## {% linkable_title Fetching states %}
This will get a dump of all the current states in Home Assistant. This will get a dump of all the current states in Home Assistant.
```json5 ```json
{ {
"id": 19, "id": 19,
"type": "get_states" "type": "get_states"
@ -255,20 +255,20 @@ This will get a dump of all the current states in Home Assistant.
The server will respond with a result message containing the states. The server will respond with a result message containing the states.
```json5 ```json
{ {
"id": 19, "id": 19,
"type": "result", "type": "result",
"success": true, "success": true,
"result": [ … ] "result": [ ... ]
} }
``` ```
## Fetching config ## {% linkable_title Fetching config %}
This will get a dump of the current config in Home Assistant. This will get a dump of the current config in Home Assistant.
```json5 ```json
{ {
"id": 19, "id": 19,
"type": "get_config" "type": "get_config"
@ -277,20 +277,20 @@ This will get a dump of the current config in Home Assistant.
The server will respond with a result message containing the config. The server will respond with a result message containing the config.
```json5 ```json
{ {
"id": 19, "id": 19,
"type": "result", "type": "result",
"success": true, "success": true,
"result": { … } "result": { ... }
} }
``` ```
## Fetching services ## {% linkable_title Fetching services %}
This will get a dump of the current services in Home Assistant. This will get a dump of the current services in Home Assistant.
```json5 ```json
{ {
"id": 19, "id": 19,
"type": "get_config" "type": "get_config"
@ -299,20 +299,20 @@ This will get a dump of the current services in Home Assistant.
The server will respond with a result message containing the services. The server will respond with a result message containing the services.
```json5 ```json
{ {
"id": 19, "id": 19,
"type": "result", "type": "result",
"success": true, "success": true,
"result": { … } "result": { ... }
} }
``` ```
## Fetching panels ## {% linkable_title Fetching panels %}
This will get a dump of the current registered panels in Home Assistant. This will get a dump of the current registered panels in Home Assistant.
```json5 ```json
{ {
"id": 19, "id": 19,
"type": "get_panels" "type": "get_panels"
@ -321,16 +321,16 @@ This will get a dump of the current registered panels in Home Assistant.
The server will respond with a result message containing the current registered panels. The server will respond with a result message containing the current registered panels.
```json5 ```json
{ {
"id": 19, "id": 19,
"type": "result", "type": "result",
"success": true, "success": true,
"result": [ … ] "result": [ ... ]
} }
``` ```
# Error handling # {% linkable_title Error handling %}
If an error occurs, the `success` key in the `result` message will be set to `false`. It will contain an `error` key containing an object with two keys: `code` and `message`. If an error occurs, the `success` key in the `result` message will be set to `false`. It will contain an `error` key containing an object with two keys: `code` and `message`.
@ -340,7 +340,7 @@ If an error occurs, the `success` key in the `result` message will be set to `fa
| 2 | Received message is not in expected format (voluptuous validation error). | 2 | Received message is not in expected format (voluptuous validation error).
| 3 | Requested item cannot be found | 3 | Requested item cannot be found
```json5 ```json
{ {
"id": 12, "id": 12,
"type":"result", "type":"result",