This repository has been archived on 2023-11-18. You can view files and clone it, but cannot push or open issues or pull requests.
ha-client-website/docs.md

83 lines
4.6 KiB
Markdown
Raw Normal View History

2019-02-08 17:00:02 +02:00
# Documentation
## Table of content
2019-02-08 16:08:59 +02:00
- [Requirements](#requirements)
2019-02-08 16:18:13 +02:00
- [Home Assistant general](#home-assistant-general)
2019-02-08 17:00:02 +02:00
- [Port](#port)
- [HTTP or HTTPS](#http-or-https)
2019-02-08 20:14:24 +02:00
- [SSL Certificates](#ssl-certificates)
- [Android](#android)
2019-02-08 20:18:32 +02:00
- [Authentication](#authentication)
2019-02-08 20:27:30 +02:00
- [UI configuration](#ui-configuration)
2019-02-08 20:18:32 +02:00
- [Log Viewer](#log-viewer)
2019-02-08 16:08:59 +02:00
2019-02-08 17:00:02 +02:00
## Requirements
### Home Assistant general
2019-02-08 16:08:59 +02:00
To check if you are using right configuration for app, try to access your Home Assistant web interface with the same protocol (http:// or https://), the same domain or IP and port. If it is not loading the app will not work as well.
2019-02-08 16:18:13 +02:00
To connect to your Home Assistant instance with HA Client you need `http` and `websocket_api` components to be enabled as well as [remote access](https://www.home-assistant.io/docs/configuration/remote/) configured. If you are using `frontend` component (Home Assistant web interface actually) `websocket_api` is enabled by default and `http` component is already configured on your server, but still you need to double check.
In other cases changes should be made to you `configuration.yaml`:
```yaml
http:
api_password: #some password here
base_url: #your domain for Home Assistant instance
ssl_certificate: /ssl/fullchain.pem #ssl configuration to access your HA by https
ssl_key: /ssl/privkey.pem
websocket_api:
```
2019-02-08 20:18:32 +02:00
2019-02-08 20:14:24 +02:00
[Back to top](#documentation)
2019-02-08 19:54:12 +02:00
### Port
2019-02-08 17:00:02 +02:00
By default your Home Assistant is using port number `8123`. But to access your instance from outside of your home network, probably you configured some port forwarding rules on you router. If you forward some other port from outside to `8123` port on Home Assistant IP, you need to use that port instead.
If you are accessing your web interface without port, then you need to try port `80` or `443` in app.
2019-02-08 20:18:32 +02:00
2019-02-08 20:14:24 +02:00
[Back to top](#documentation)
2019-02-08 19:54:12 +02:00
### HTTP or HTTPS
2019-02-08 17:00:02 +02:00
It is not required to use secure connection. Just remember: if you are accessing your web interface with http, you need to switch “Use ssl” off in app settings as well.
But if you are using ssl (accessing web interface with https://) your certificate should be valid (not self-signed).
2019-02-08 20:18:32 +02:00
2019-02-08 20:14:24 +02:00
[Back to top](#documentation)
2019-02-08 19:54:12 +02:00
### SSL Certificates
The main requirement is that your SSL Certificate should not be self-signed. Most certificates from providers like Lets Encrypt will work. There is [known issue](https://github.com/estevez-dev/ha_client_pub/issues/24) with RapidSSL certificate, but this problem is common not only for HA Client.
Using of self-signed certificate is not possible for now and this is a restriction of Flutters WebSocket implementation. To stay up to date with this issue solving or possible workarounds please [follow this issue in GitHub](https://github.com/estevez-dev/ha_client_pub/issues/3).
2019-02-08 20:18:32 +02:00
2019-02-08 20:14:24 +02:00
[Back to top](#documentation)
2019-02-08 19:54:12 +02:00
### Android
Minimum supported Android API level is 21. Thats Android 5.0 and higher.
2019-02-08 20:18:32 +02:00
2019-02-08 20:14:24 +02:00
[Back to top](#documentation)
2019-02-08 19:54:12 +02:00
## Authentication
Starting from Home Assistant 0.78.0 `api_password` is a deprecated way to authenticate third party apps and services. You should use long-lived access tokens instead. To make HA Client use access token to authenticate you need:
1. Go to your Home Assistant web interface and open your profile settings (just click on your user picture in the top part of left menu)
2019-02-08 20:00:42 +02:00
2019-02-08 19:54:12 +02:00
![image](/assets/images/ha_profile.png)
2019-02-08 20:02:15 +02:00
2019-02-08 19:54:12 +02:00
2. Scroll down to *Long-lived access tokens* section and click *Create token*
2019-02-08 20:00:42 +02:00
2019-02-08 19:54:12 +02:00
![image](/assets/images/ha_access_tokens.png)
2019-02-08 20:02:15 +02:00
2019-02-08 19:54:12 +02:00
3. Give it a name `HA Client` as it will be used only for HA Client app (it is recommended to use different access tokens for different apps and services)
4. Click *Ok* and copy newly generated access token somewhere in a safe place or directly to Connection settings of HA Client
2019-02-08 20:00:42 +02:00
2019-02-08 19:57:20 +02:00
![image](/assets/images/setting_access_token.png)
2019-02-08 20:14:24 +02:00
2019-02-08 20:18:32 +02:00
[Back to top](#documentation)
2019-02-08 20:14:24 +02:00
## UI Configuration
By default HA Client UI is based on your Lovelace UI config, so it should display the same views as your Home Assistant web UI. It is still possible to switch off Lovelace UI in app settings. In this canse app UI will be based on groups configuration, the same as old Home Assistant UI.
![image](/assets/images/setting_ui.png)
2019-02-08 20:18:32 +02:00
[Back to top](#documentation)
2019-02-08 20:14:24 +02:00
## Log Viewer
There is a built in debug messages viewer in the app. You can access it by *Log* item in main menu. It will be very helpful if you will attach a copy of this log to your issue report. It is easy to do with button in header (![image](/assets/images/log_copy_btn.png)) that will copy all log entries to clipboard.
![image](/assets/images/log_viewer.png)
Please note that oldest entries goes first, so to see latest messages you need to scroll this view down.
2019-02-08 20:27:30 +02:00
[Back to top](#documentation)