mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-07-19 07:17:14 +00:00
Make titles linkable
This commit is contained in:
Fabian Affolter
parent
53c3ff3fdc
commit
ebecd9fce6
@ -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
|
||||
|
||||
# Server states
|
||||
# {% linkable_title Server states %}
|
||||
|
||||
1. Client connects
|
||||
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.
|
||||
|
||||
# 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.
|
||||
|
||||
Example of an auth message:
|
||||
|
||||
```json5
|
||||
```json
|
||||
{
|
||||
"type": "auth",
|
||||
"api_password": "supersecret"
|
||||
}
|
||||
```
|
||||
|
||||
```json5
|
||||
```json
|
||||
{
|
||||
"id" 5,
|
||||
"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).
|
||||
|
||||
If no authentication is needed, the authentication phase will complete and the server will send an `auth_ok` message.
|
||||
|
||||
```json5
|
||||
```json
|
||||
{
|
||||
"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`.
|
||||
|
||||
```json5
|
||||
```json
|
||||
{
|
||||
"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:
|
||||
|
||||
```json5
|
||||
```json
|
||||
{
|
||||
"type": "auth",
|
||||
"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:
|
||||
|
||||
```json5
|
||||
```json
|
||||
{
|
||||
"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.
|
||||
|
||||
```json5
|
||||
```json
|
||||
{
|
||||
"type": "auth_invalid",
|
||||
"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.
|
||||
|
||||
```json5
|
||||
```json
|
||||
{
|
||||
"id": 6.
|
||||
"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.
|
||||
|
||||
```json5
|
||||
```json
|
||||
{
|
||||
"id": 18,
|
||||
"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.
|
||||
|
||||
```json5
|
||||
```json
|
||||
{
|
||||
"id": 18,
|
||||
"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.
|
||||
|
||||
```json5
|
||||
```json
|
||||
{
|
||||
"id": 18,
|
||||
"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.
|
||||
|
||||
```json5
|
||||
```json
|
||||
{
|
||||
"id": 19,
|
||||
"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.
|
||||
|
||||
```json5
|
||||
```json
|
||||
{
|
||||
"id": 19,
|
||||
"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.
|
||||
|
||||
@ -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.
|
||||
|
||||
```json5
|
||||
```json
|
||||
{
|
||||
"id": 24,
|
||||
"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.
|
||||
|
||||
```json5
|
||||
```json
|
||||
{
|
||||
"id": 19,
|
||||
"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.
|
||||
|
||||
```json5
|
||||
```json
|
||||
{
|
||||
"id": 19,
|
||||
"type": "result",
|
||||
"success": true,
|
||||
"result": [ … ]
|
||||
"result": [ ... ]
|
||||
}
|
||||
```
|
||||
|
||||
## Fetching config
|
||||
## {% linkable_title Fetching config %}
|
||||
|
||||
This will get a dump of the current config in Home Assistant.
|
||||
|
||||
```json5
|
||||
```json
|
||||
{
|
||||
"id": 19,
|
||||
"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.
|
||||
|
||||
```json5
|
||||
```json
|
||||
{
|
||||
"id": 19,
|
||||
"type": "result",
|
||||
"success": true,
|
||||
"result": { … }
|
||||
"result": { ... }
|
||||
}
|
||||
```
|
||||
|
||||
## Fetching services
|
||||
## {% linkable_title Fetching services %}
|
||||
|
||||
This will get a dump of the current services in Home Assistant.
|
||||
|
||||
```json5
|
||||
```json
|
||||
{
|
||||
"id": 19,
|
||||
"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.
|
||||
|
||||
```json5
|
||||
```json
|
||||
{
|
||||
"id": 19,
|
||||
"type": "result",
|
||||
"success": true,
|
||||
"result": { … }
|
||||
"result": { ... }
|
||||
}
|
||||
```
|
||||
|
||||
## Fetching panels
|
||||
## {% linkable_title Fetching panels %}
|
||||
|
||||
This will get a dump of the current registered panels in Home Assistant.
|
||||
|
||||
```json5
|
||||
```json
|
||||
{
|
||||
"id": 19,
|
||||
"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.
|
||||
|
||||
```json5
|
||||
```json
|
||||
{
|
||||
"id": 19,
|
||||
"type": "result",
|
||||
"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`.
|
||||
|
||||
@ -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).
|
||||
| 3 | Requested item cannot be found
|
||||
|
||||
```json5
|
||||
```json
|
||||
{
|
||||
"id": 12,
|
||||
"type":"result",
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user