Skip to content

Commit

Permalink
docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@Apollon77
Apollon77 committed Jul 5, 2024
1 parent c7281db commit 251b30f
Showing 1 changed file with 39 additions and 14 deletions.
53 changes: 39 additions & 14 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
[![Downloads](https://img.shields.io/npm/dm/daikin-controller-cloud.svg)](https://www.npmjs.com/package/daikin-controller-cloud)
![Test and Release](https://github.com/Apollon77/daikin-controller-cloud/workflows/Test%20and%20Release/badge.svg)

Library to generate/retrieve tokens to communicate with the Daikin cloud and to control Daikin devices via the cloud adapters like (BRP069C4x).
Library to generate/retrieve tokens to communicate with the Daikin cloud and to control Daikin devices via the cloud adapters like (BRP069C4x). The Library uses the new Daikin Europe Developer cloud API since v2.0.0.

## Disclaimer
**All product and company names or logos are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them or any associated subsidiaries! This personal project is maintained in spare time and has no business goal.**
Expand All @@ -24,9 +24,16 @@ Note: For devices with older WLAN-Adapters like **BRP069A4x** which can only be
used by the Daikin Controller App please use the
[Daikin-Controller](https://github.com/Apollon77/daikin-controller) lib instead.

## IMPORTANT
## IMPORTANT information and best practices

The Onecta API limits each client application to 200 requests per day.
The Onecta API limits each client application to 200 requests per day. Please make sure to not exceed this limit, as the API will block further requests for the day.

Because of this we propose the following usage limits to be implemented by the applications using this library:
* Better always read the full device details rather than single devices to make best use of the rate limit
* A default polling interval of 15 minutes should be sufficient for most use cases while leaving some space for controlling the devices too.
* Consider using a (longer) slow polling interval for timeframes where updated data are not that important - with this the normal polling interval could be faster.
* After you have "set" a value, wait at least 1-2 minutes before you read the updated values again because executing commands and updating the cloud data can take some time
* Ideally have at least 10 minutes time between switching the device power status because else thats bad for the moving parts of the devices

## Pre-requisites

Expand All @@ -40,38 +47,56 @@ you'll have to provide the following:
2. The ability for the process that uses this library to listen on a local TCP
port (configurable) in order to start an HTTP server that your browser will
be redirected to at the end of the `Authorization` grant flow
3. A domain name that resolves to the machine that hosts the process using this
library (if running locally you will not be able to use `localhost` as it is
rejected by the Onecta API)
3. A domain name or an IP that resolves to the machine that hosts the process using this
library (if running locally you will not be able to use `localhost` or `127.0.0.1`
as it is rejected by the Onecta API)

You will have to combine the port (point 2.) and domain name (point 3.) to
create the URL to be set as the application's `Redirect URI` in the
[Daikin Developer portal][p1]. Note that the same URL **must** also be passed
as a configuration parameter of the `DaikinCloudController` class. Also note
that the `Redirect URI` must use the secure `https:` protocol and that this
library ships with its own self-signed SSL/TLS certificate, which will cause
your browser to present you with a security warning.
as a configuration parameter of the `DaikinCloudController` class or is build
automatically from the provided values. Also note that the `Redirect URI` must
use the secure `https:` protocol and that this library ships with its own self-signed
SSL/TLS certificate, which will cause your browser to present you with a security warning.

[p1]: https://developer.cloud.daikineurope.com

## Install
For now while being in basic development install from Github:

`npm i Apollon77/daikin-controller-cloud`
`npm i daikin-controller-cloud`

## Code-Usage example
See [`src/example.ts`](./src/example.ts).

## DaikinControllerCloud options overview

| Option | Required? | Description | Default |
|-------------------------------------|-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------|
| `oidcClientId` | Yes | The client ID of the registered Daikin Developer Account application | |
| `oidcClientSecret` | Yes | The client secret of the registered Daikin Developer Account application | |
| `oidcCallbackServerExternalAddress` | Maybe, see desc | The external address (domainname/IP) of the machine running the library, ot external Docker IP or such when using docker. Mandatory if `oidcCallbackServerBaseUrl` or `customOidcCodeReceiver` is not provided. | |
| `oidcCallbackServerBaseUrl` | Maybe, see desc | The full externally reachable callback URl including protocol, domain/ip/basepath. If not provided will be build internally using `oidcCallbackServerExternalAddress`or `oidcCallbackServerBindAddr` and `oidcCallbackServerPort` | |
| `oidcCallbackServerPort` | Maybe, see desc | The port the callback server listens on, required when `customOidcCodeReceiver` is not used. | |
| `oidcCallbackServerBindAddr` | No | The address the callback server listens on, required when `customOidcCodeReceiver` is not used. | ` |
| `oidcAuthorizationTimeoutS` | Yes | The timeout in seconds for the OIDC authorization flow | |
| `oidcTokenSetFilePath` | No | The path to a file where the token set is stored. When not set the tokens are _not_ persisted and application need to listen to "token_updated" event and store and restore itself! | |
| `certificatePathCert` | No | The path to the SSL certificate | `./cert/cert.key` in library root |
| `certificatePathKey` | No | The path to the SSL key | `./cert/cert.pem` in library root |
| `onectaOidcAuthThankYouHtml` | No | The HTML content to be displayed after successful OIDC authorization, requiored when `customOidcCodeReceiver` is not used | |
| `customOidcCodeReceiver` | No | A custom function to receive the OIDC code. WHen this is used the library donot start any Webservcer and application needs to handle this. | |
| `tokenSet` | No | A token set to be used initially when no token file is stored | |

## Issue reporting and enhancements
* Create Issues here in Github
* Provide PRs for actual changes and enhancements to code or documentation!

## Todos
* Generate SSL Certs automatically
* Mooooaaar documentation
* Add Tests
*

## Changelog:
### 2.0.0-alpha.9 (2024-07-04)
### __WORK IN PROGRESS__
* BREAKING: Username/Passwort and Proxy Authentications are removed and replaced by the new Daikin Portal Authentication! You need to re-authenticate!
* BREAKING: DaikinCloudController class constructor changed and has new options structure!
* Minimum Node.js version is 18.2
Expand Down

0 comments on commit 251b30f

Please sign in to comment.