Metadata-Version: 2.4
Name: thingsboard-monitor
Version: 2.0.0
Summary: ThingsBoard monitor package
Home-page: https://gitlab.com/things-board
Author: HES-SO Valais, School of Engineering, Sion
Author-email: thomas.sterren@hes-so.ch
License-Expression: MIT
Project-URL: Bug Tracker, https://gitlab.com/things-board/thingsboard-monitor/-/issues
Project-URL: Source Code, https://gitlab.com/things-board/thingsboard-monitor
Project-URL: Documentation, https://gitlab.com/things-board/thingsboard-monitor#thingsboard-monitor
Keywords: ThingsBoard monitor library
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Information Technology
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Operating System :: OS Independent
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: configobj~=5.0.9
Requires-Dist: thingsboard-common~=0.2.0
Requires-Dist: tb-rest-client<5,>=4.4
Requires-Dist: websockets~=17.0.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: home-page
Dynamic: keywords
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-dist
Dynamic: summary

# ThingsBoard Monitor

> Note:
>
> This is not an official project of the [
> ThingsBoard](https://thingsboard.io/) authors! Please refer to [ThingsBoard - Open-source IoT Platform](https://github.com/thingsboard) for official ThingsBoard projects!

The _ThingsBoard Monitor_ package provides some classes to create an application monitoring and controlling
one or more ThingsBoard endpoints (devices).

## Requirements

- Python 3.13 or newer.
- [`tb-rest-client`](https://pypi.org/project/tb-rest-client/) 4.4 or newer (below 5). Version 4.3 and older are not
  supported: they have a different module layout (`tb_rest_client.rest_client_ce`).

## Application API

`ThingsboardMonitorApp` is the way for an application to get and set data of ThingsBoard devices, without dealing with
REST, WebSocket, tokens or network problems. It owns the REST client, the thread that keeps its token fresh and one
WebSocket, and hides them. The application declares its endpoints (devices) and nodes (groups of parameters inside a
device) in code, then reads, writes and subscribes through them. Only `ThingsboardError`s come out of it.

```python
from thingsboard.monitor.app import ThingsboardMonitorApp

app = ThingsboardMonitorApp.connect('thingsboard-monitor.config', timeout=30)   # constructs, starts, waits
app.set_app_name('ems')

boiler = app.add_endpoint('boiler', device_id)
heating = boiler.add_node('heating')
heating.declare('temperature', float)

heating.set_parameter('setpoint', 21.5)                  # writes the shared attribute set/heating/parameter/setpoint
heating.get_parameter('setpoint')                        # 21.5: what this app last wrote
heating.latest('temperature')                            # HistoryPoint(ts=..., value=20.3): what the device reports
heating.history('temperature', start_ms, end_ms).points  # [HistoryPoint, ...]
heating.subscribe_latest(lambda update: print(update.parameter, update.value))

app.stop()
```

The config file is the one of the [REST client](#rest-client); its `thingsboard` group is required. The WebSocket is that
of the `websocket` group if there is one (see [Keepalive and timing settings](#keepalive-and-timing-settings)); without
one it is derived from the `thingsboard` group: the same host and port, with `ws` for `http` and `wss` for `https`, and
the path `/api/ws`.

### Endpoints and nodes

Endpoints and nodes share the reads and the subscriptions below (`ThingsboardMonitorEntity`), and `app`, `device_id`,
`name` and `declare()`.

```python
endpoint = app.add_endpoint('boiler', device_id)   # ValueError if the name is in use
node = endpoint.add_node('heating')
app.endpoint('boiler')                             # KeyError if unknown
endpoint.node('heating')                           # KeyError if unknown
app.endpoints, endpoint.nodes                      # read-only mappings by name
node.endpoint                                      # the endpoint of a node
```

An endpoint belongs to its app: several apps can live in one process.

On ThingsBoard the keys have a fixed shape. A property (what the device reports) is `property/<name>` for an endpoint and
`<node>/property/<name>` for a node. A parameter (what the app asks of the device) is the shared attribute
`set/parameter/<name>` for an endpoint and `set/<node>/parameter/<name>` for a node. The `parameter` and `property`
prefixes are configurable on the endpoint (`endpoint.set_config_parameters(PARAMETER_PREFIX_KEY_NAME='cmd',
PROPERTY_PREFIX_KEY_NAME='')`; an empty prefix leaves it out, with its slash).

### Writes

```python
endpoint.set_endpoint_parameter('mode', 'auto')                      # shared attribute set/parameter/mode
endpoint.set_endpoint_parameter('setpoint', 21.5, node_name='heating')   # set/heating/parameter/setpoint
node.set_parameter('setpoint', 21.5)                                 # the same
endpoint.set_server_parameter('state', 'running')                    # server attribute <app name>/state
```

A parameter change is also logged as telemetry, `<key>/from/<app name>`, to be able to backtrace it
(`backtrace=False` of `set_endpoint_parameter()` leaves it out). A server attribute can be seen by the server, not by the
device. An unknown `node_name` raises `KeyError` and sends nothing.

### Reads

```python
node.latest('temperature')                    # HistoryPoint(ts, value, warning), None if the key has no data
node.latest_points(['temperature', 'humidity'])   # {name: HistoryPoint or None}, one request
node.history('temperature', start_ms, end_ms)     # HistoryResult(points, complete, cause, pages)
node.history('temperature', start_ms, end_ms, agg='AVG', interval_ms=60_000)
endpoint.latest_raw('some/raw/key')           # a key of ThingsBoard as it is

endpoint.attributes('shared')                 # {key: value}, the scope is required: 'shared', 'server' or 'client'
endpoint.attributes('client', ['firmware'])
node.attributes('shared')                     # only the keys <node>/property/...

node.get_parameter('setpoint', default=None)                  # the last value this app wrote
endpoint.get_endpoint_parameter('setpoint', node_name='heating')
endpoint.get_server_parameter('state')
node.get_parameter_reading('setpoint')        # HistoryPoint(ts of the write, value, warning), None if none
endpoint.get_endpoint_parameter_reading('mode')
endpoint.get_server_parameter_reading('state')
```

`latest()`, `latest_points()` and `history()` of an endpoint read the key `property/<name>`, those of a node
`<node>/property/<name>`, and `latest_raw(key)` any key. The results are `HistoryPoint`, `HistoryPage` and `HistoryResult`
of `thingsboard.monitor.history` (see [Telemetry history](#telemetry-history-and-the-latest-point) for the options and
the way a long window is read: `page_size`, `max_pages`, `deadline_s`, `page_retries`).

The getters read back what this app wrote; what the device reports is `latest()`. They return `default` where the app
wrote nothing. `attributes()` takes the keys of ThingsBoard (a string of comma separated keys, or an iterable; all of
them by default) and returns the ones that exist; without `keys` a node returns only those that start with
`<node>/property/`.

`history()` ends incomplete instead of raising when a page keeps failing (see `HistoryResult.cause`); a bad argument
raises `ValueError` and sends nothing.

### Values

ThingsBoard sends values as text. Every read and every subscription takes `coerce=True` by default and converts the value
of a name this way:

1. `coerce=False` turns every conversion off, the declared types included: the value is what ThingsBoard sent.
2. The type declared for the name applies. `endpoint.declare(name, type)` and `node.declare(name, type)` take `bool`,
   `int`, `float` or `str`. `str` is never converted. `float` accepts integer text, `int` only integer text, `bool` the
   words `true` and `false` in any case. A node and its endpoint declare their names apart.
3. Otherwise the text is guessed with `coerce_value()` (`'true'` is `True`, `'42'` is `42`, `'21.5'` is `21.5`, a leading
   zero, a sign, spaces, `NaN` and the rest stay text).

A value that does not fit its declared type is kept as it was received, and a warning is logged once for its key; it does
not raise. `HistoryPoint.warning` and `SubscriptionUpdate.warning` carry a `ValueWarning` (`key`, `expected_type`,
`raw_value`, `reason`) then, and are `None` otherwise. A declared type applies to the values of a name wherever they are
read: the property, the parameter that has this name, and the keys of an attribute or subscription that stand for it.

```python
from thingsboard.monitor.values import coerce_value
```

### Subscriptions

```python
def on_update(update):
    print(update.endpoint.name, update.node, update.parameter, update.key, update.value, update.ts, update.warning)

subscription = node.subscribe_latest(on_update)                     # the properties of the node
endpoint.subscribe_latest(on_update, keys=['property/level'])       # given keys of ThingsBoard
node.subscribe_attributes('shared', on_update)                      # 'shared', 'server' or 'client'
endpoint.subscribe_attributes('client', on_update, on_error=lambda error: ...)
subscription.cancel()
```

The callback gets one `SubscriptionUpdate` per key and message: `endpoint`, `node` (`None` for the endpoint itself),
`parameter` (the name that a property or parameter key stands for, else the key), `key`, `value` (converted as above, the
newest point of the message), `ts` (milliseconds UTC) and `warning`.

- Callbacks run in the thread of the WebSocket. Keep them short. An exception in one is logged and swallowed.
- A subscription can be declared before `app.start()`. It is sent when the WebSocket is authenticated, and again after
  every reconnection, until it is cancelled.
- `keys` are the keys of ThingsBoard. Without them an endpoint follows all keys of the device. A node follows only the keys
  that start with `<node>/property/`: the filter is applied on the client side.
- `on_error` is called with the `ThingsboardRequestError` of a subscription that ThingsBoard refuses for good. The
  subscription then ends (`subscription.active` is `False`). Without `on_error` the refusal is logged.
- `subscription.cancel()` tells ThingsBoard to stop; calling it again does nothing.
- Subscribing on an app without a config file, or after `app.stop()`, raises `ThingsboardConnectionError`; a scope other
  than `shared`, `server` and `client` raises `ValueError`.

### Lifecycle and state

```python
app = ThingsboardMonitorApp('thingsboard-monitor.config')     # contacts nothing
# ... add endpoints, nodes and subscriptions
app.start()                                                    # does not block
app.wait_until_ready(timeout=30)                               # ThingsboardLoginError or ThingsboardTimeoutError
app.stop()

with ThingsboardMonitorApp('thingsboard-monitor.config') as app:   # starts and waits on entry, stops on exit
    ...

app = ThingsboardMonitorApp.connect('thingsboard-monitor.config', timeout=30)   # construct, start, wait
```

`start()` returns at once. A thread logs in: a server that is down is retried with a growing pause (`initial_backoff` 2 s up
to `max_backoff` 60 s, constructor arguments); credentials that ThingsBoard refuses (HTTP 401 or 403) are not retried, as
that could lock the account, and the state becomes `REFUSED`. Once logged in the thread starts the token refresher and the
WebSocket, which sends the subscriptions. `start()` after `REFUSED` tries again; after `stop()` it raises `ThingsboardConnectionError`,
and so does a start without a config file.

`wait_until_ready(timeout=None)` returns when the login is done, the token thread runs and the WebSocket is
authenticated. It raises `ThingsboardLoginError` if the credentials are refused, `ThingsboardTimeoutError` when the
timeout is over, and `ThingsboardConnectionError` if the app is not started or is stopped meanwhile.

`app.state` is an `AppState` (a `StrEnum`) and `app.subscribe_state_changes(callback)` calls `callback(state)` on each
change and returns a `Subscription`:

| State        | Meaning                                                                                       |
|--------------|-----------------------------------------------------------------------------------------------|
| `STOPPED`    | not started, or stopped                                                                       |
| `STARTING`   | logging in                                                                                    |
| `CONNECTING` | logged in, the WebSocket is not authenticated (also after it was lost, until it is again)      |
| `READY`      | logged in, the token thread runs, the WebSocket is authenticated                              |
| `REFUSED`    | ThingsBoard refused the credentials                                                           |

Reads and writes need the login, not the WebSocket: before it, after a failed first login or after `stop()`, they raise
`ThingsboardConnectionError` and send nothing. `app.login()` logs in in the foreground (`ThingsboardLoginError` if it
fails), after which reads and writes work without `start()`. `lazy_login=False` logs in in the constructor.

`app.client` is the only way to the `ThingsboardRestClient`, for what the application API does not cover. It has the
token refresh, the retry on an expired token and the timeouts of the app (see [REST client](#rest-client)), but its
calls raise `ApiException` and not `ThingsboardError`s. `app.client.require_connection()` raises
`ThingsboardConnectionError` if the client is not logged in or was closed (`app.stop()` closes it), which is the check
the endpoints and nodes make before they read or write. `app.client` is `None` for an app without a config file.

### Errors

Everything the library raises on purpose derives from `ThingsboardError` (`thingsboard.monitor.errors`):

| Exception                     | When                                                                                       |
|-------------------------------|--------------------------------------------------------------------------------------------|
| `ThingsboardConnectionError`  | ThingsBoard cannot be reached, the connection was lost, or the app is not connected        |
| `ThingsboardTimeoutError`     | no answer in time                                                                          |
| `ThingsboardRequestError`     | ThingsBoard answered with an error: `error_code` is the HTTP status (or the `errorCode` of a WebSocket answer), `error_msg` |
| `ThingsboardResponseError`    | the answer is not what ThingsBoard sends (the page of a proxy, another JSON)               |
| `ThingsboardAuthError`        | a request for a token failed, `status` is the HTTP status (`None`: the server was not reached) |
| `ThingsboardLoginError`       | the login failed (an `AuthError`); `credentials_refused` is `True` for HTTP 401 and 403      |
| `ThingsboardTokenRefreshError`| the token could not be refreshed (an `AuthError`)                                          |

`ThingsboardConnectionError` and `ThingsboardTimeoutError` are also a `ConnectionError` and a `TimeoutError`.

## REST client

`ThingsboardMonitorApp` logs in with a `ThingsboardRestClient` (a `tb_rest_client.rest_client.RestClient`). It is
available as `app.client`, for what the application API does not cover, and it is the client the observers can read the
telemetry history with (see [Telemetry history](#telemetry-history-and-the-latest-point)):

```python
from thingsboard.monitor.app import ThingsboardMonitorApp

app = ThingsboardMonitorApp.connect('thingsboard-monitor.config')
app.client.save_entity_telemetry(entity_id=EntityId(device_id, 'DEVICE'), scope='ANY', body={'key': 1})
```

`RestClient` is imported from `tb_rest_client.rest_client`, and `EntityId`, `DeviceId` and the other models from
`tb_rest_client.models`.

### Key filters of the read calls

ThingsBoard answers HTTP 200 and no data to a `keys` filter it does not understand. `tb-rest-client` sends a list given
as `keys` as the text `"['active']"`, which names no key, so `keys=['active']` returned `[]` without any error.
`get_attributes_by_scope()`, `get_latest_timeseries()` and `get_timeseries()` of `ThingsboardRestClient` take `keys` as
`None` (all keys), a string of comma separated names, or an iterable of strings. The names are joined with commas, or
sent as repeated `key` parameters if one of them holds a comma. Any other type (a number, bytes, a dict, an iterable
holding something else than non-empty strings, an empty one) raises `ValueError` and sends nothing:

```python
from tb_rest_client.models import DeviceId

device = DeviceId(device_id, 'DEVICE')
app.client.get_latest_timeseries(device, keys=['temperature', 'humidity'])
app.client.get_attributes_by_scope(device, 'SERVER_SCOPE', keys='active,mode')
app.client.get_timeseries(device, start_ms, end_ms, keys=['temperature'], limit=100)
```

The three calls also take `read_timeout=` (seconds, `None` for no limit) in place of the timeout of the client.

### JSON writes: `text/plain` or `application/json`

The write calls of `tb-rest-client` 4.4 send their JSON as `text/plain`. ThingsBoard's current server code reads these
bodies as a plain string, so it accepts any content type. An older ThingsBoard may parse them as typed JSON and answer
HTTP 415. `ThingsboardRestClient` handles both: if a write is answered with 415 it is sent again as `application/json`,
and when that is accepted, all further JSON text writes of the same client object use `application/json` directly
(`app.client.json_content_type_required` tells which case applies). Other errors are not retried.

### Token lifecycle, timeouts and reconnecting the client

The access token of the REST client is kept valid without any help of the caller:

- `app.start()` (or `auto_start=True`) starts, once the login is done, a thread that refreshes the token when 20 % of its lifetime is left. The
  lifetime is the one the token states about itself (`exp` - `iat`), counted from the moment the token was received, so
  a clock that is off on the ThingsBoard side or on the local side does not matter. The thread never gives up: it
  retries with a growing pause (5 s, 10 s, ... up to 60 s) until the refresh succeeds. If ThingsBoard refuses the
  refresh token, or the login gave none, the client logs in again with the credentials of the config file. A client that
  was logged in with `token_login()` only has neither: it cannot renew its token, `refresh()` raises
  `ThingsboardTokenRefreshError` and a refused request raises its original `ApiException`.
- A call (also `app.client.<call>`) that ThingsBoard refuses with `401`, because the token expired or is not accepted
  any more for another reason, refreshes the token (or logs in again) and is sent once more. If that fails, or the
  request is refused again with the new token, the original `ApiException` is raised and no renewal is tried for 30 s
  (`RENEWAL_COOLDOWN`), so that credentials that no longer work are not tried on every call.
- The refresh replaces the token as a whole, so concurrent calls use the old token or the new one.
- `app.client.last_refresh_at` and `app.client.token_expires_at` (seconds since the epoch, local clock) and
  `app.client.refresher_alive` tell the state of the token and of the thread.
- `app.stop()` ends the thread, so the process can exit.

A failed login raises `ThingsboardLoginError` (`from thingsboard.monitor.errors import ThingsboardLoginError`).
`app.is_logged_in` tells whether the app has a token. The constructor does not log in unless `lazy_login=False`;
`app.start()` does, in a thread (see [Lifecycle and state](#lifecycle-and-state)).

`app.reconnect_client()` logs the client in again and gives it a new transport (`app.client.reconnect()`): a new token and
new connections, on the same object. Whoever holds `app.client` (the observers, threads of your own) keeps a client that is
current, nothing has to be handed over, and the refresher thread keeps running if it was. A request in flight is not cut:
it ends on the old connections, which are closed afterwards. If the login fails, `ThingsboardLoginError` is raised and the
client is left as it was. Lost and stuck connections need none of it: a failed connection is dropped and the next call
opens a new one. Use it to start over with a fresh session and fresh connections, for example after changing
`app.client.configuration` (timeouts, TLS), which a transport reads once, when it is built. It logs in with the credentials
of the first login, so it does not pick up new ones.

Connect and read timeouts apply to the login, the refresh and every request, and the transport does not repeat failed
requests by itself. They are set in the `thingsboard` group of the config file or in the constructor (the constructor
wins); `0` disables a timeout:

```ini
[thingsboard]
connect-timeout = 10    # seconds, default 10
read-timeout = 60       # seconds, default 60
```

```python
app = ThingsboardMonitorApp(config_file='thingsboard-monitor.config', connect_timeout=5, read_timeout=30)
```

## WebSocket observer and supervisors

`ThingsboardMonitorApp` has one observer inside. `ThingsboardMonitorEndpointObserver` and the
`ThingsboardMonitorEndpointSupervisor` and `ThingsboardMonitorMultiEndpointSupervisor` derived from it are the low-level
API, for an application that wants to manage the connection itself. They receive telemetry and attribute updates over a WebSocket.
The WebSocket is for subscriptions only; the history and the latest point of a key are read over REST. The observers
need no supervision by the caller:

- **The thread never dies.** Its loop survives any `Exception`: it logs, waits (backoff from `initial_backoff` growing
  to `max_backoff`) and connects again. This includes the first connection: the constructor does not connect, the
  thread does when it is started, and retries until it succeeds. A server that is down, a login that fails for
  another reason than the credentials, a refused handshake, a connection closed during authentication or mid-stream
  are all retried the same way, so the observer connects once the server is back. A connection that stays open for
  10 s resets the backoff.
- **Wrong credentials are not retried.** If ThingsBoard answers the login with HTTP 401 or 403, retrying would not help
  and could lock the account. The thread logs an error and stops, the state becomes `ConnectionState.REFUSED`
  (`'refused'` for the state callbacks), `fatal_error` holds the `ThingsboardLoginError` and `wait_until_ready()`
  raises it. For the supervisors that means `start()`, and with `autostart=True` the constructor, raises it. After
  fixing the credentials, `restart()` tries again.
- **Subscriptions are replayed.** Every subscription (latest telemetry, attributes) is kept by the observer and sent
  again after each re-authentication. A subscription made while the connection is down is sent once it is up. A
  subscription ThingsBoard refuses with an internal error (`errorCode` 1) is sent again up to 5 times, after 2 s,
  4 s, ... (`initial_backoff` doubling up to `max_backoff`), and the callback registered for it stays in place, so a
  transient error of the server does not lose it. A bad request (2) or missing authorization (3), or an internal error
  that does not pass, is given up: the subscription is dropped, not replayed, and the caller is told by the callback set
  with `set_on_request_error_callback()` (see below), not by an exception, because the answer comes long after
  `subscribe_*` returned.
- **Subscriptions can be cancelled.** `unsubscribe_command(command_id)` removes a subscription from the registry and
  tells ThingsBoard to stop sending its updates (the command is sent again with `unsubscribe` set). The supervisors do
  this in `unregister_callback_method()` and `unregister_all_callback_methods()`.
- **Command ids are checked.** An explicit `command_id` that is used by a subscription raises `ValueError` and sends
  nothing. Ids allocated by the library skip the ones in use.
- **Connection state is observable.** `state` (a `ConnectionState`), `is_connected`, `last_connect_at`,
  `last_disconnect_at` and `last_message_at` (seconds since the epoch, local clock, `None` if it never happened),
  `is_ready` (authenticated at least once) and `thread_alive`.
  `subscribe_connection_state_changes(callback)` calls `callback(state)` with `'connected'`, then
  `'authenticated'` when a connection is established, `'disconnected'` when an open connection is lost and `'refused'`
  when ThingsBoard refused the credentials. A failed
  attempt to connect does not notify. `ConnectionState` is a `StrEnum`, so the callbacks may compare with strings.
  ThingsBoard sends no answer to a valid authentication: `'authenticated'` means the token was sent.
  One that is refused makes ThingsBoard close the connection, which is reported as `'disconnected'`.
- `wait_until_ready(timeout=None)` returns when the session is authenticated for the first time and raises
  `ThingsboardTimeoutError` when the timeout is over. `start(wait_until_ready=True, ...)` of the supervisors waits
  without limit; call `start(wait_until_ready=False)` and `wait_until_ready(timeout=...)` to bound it.
- `restart()` closes the connection and builds it again at once, without backoff, and replays the subscriptions. It
  returns without waiting. It starts the thread if it is not running.

### Errors of the observers

The observers raise the errors of [Errors](#errors) above: `ThingsboardRequestError` (`error_code` is the `errorCode` of the
WebSocket answer, or the HTTP status of a REST read), `ThingsboardConnectionError` (no authenticated connection to send
on, or it was lost; or ThingsBoard cannot be reached by a REST read), `ThingsboardTimeoutError` (no answer in time, or
`wait_until_ready` ran out of time), `ThingsboardResponseError` and `ThingsboardLoginError`.

A subscription ThingsBoard refuses for good fails long after `subscribe_*` returned, so it is not an exception: the
callback set with `set_on_request_error_callback(lambda command_id, error: ...)` is told with the `command_id` and the
`ThingsboardRequestError`. The callback set with `set_on_telemetry_update_callback()` of the observer receives
every message, error answers included.

`get_jwt_session_token()` returns the token and raises `ThingsboardLoginError` when the login fails. It uses the `connect-timeout` and `read-timeout` of the `thingsboard` group. Tokens are never
logged.

### Telemetry history and the latest point

History is read over REST only: the WebSocket is for subscriptions, and there is no callback API for history. The calls
below return the points.

The reads go through a `ThingsboardRestClient` (`get_timeseries()` with `startTs`, `endTs`, `limit`, `agg`, `interval`
and `orderBy`, and `get_latest_timeseries()`) and need no WebSocket: an observer that was never started can read.
The client has the token lifecycle of the REST client above: proactive refresh when its thread runs, a new token and a
second try when a request is refused for an expired token, a new login when the refresh token is refused, and its
timeouts: the read timeout of the client applies unless `timeout=` is passed to the call, or `request_timeout` was set on
the observer (constructor argument or `request-timeout` of the `websocket` group).

Pass the client of the app, so that the observer shares its token and its refresh. The app keeps that client for good,
also when it reconnects it, so the observer needs nothing else:

```python
app = ThingsboardMonitorApp.connect('thingsboard-monitor.config')
observer = ThingsboardMonitorEndpointObserver(config_file='thingsboard-monitor.config', rest_client=app.client)
```

The supervisors take `rest_client=` too and pass it on. A client that is not logged in is logged in with the
credentials of the config file. Without a client the observer builds its own from the config file when it first reads
and closes it in `stop()`; the observer never closes a client it was given. The client it builds gets the same refresher
thread as the one of the app (a daemon thread, so it never keeps the process alive), so its token is refreshed ahead of
its expiry as well.

```python
# One page: at most `limit` points, newest kept, in chronological order
page = observer.get_device_telemetry_history(device_id, 'temperature', start_ms, end_ms, limit=500, timeout=10)
page.points         # [HistoryPoint(ts, value), ...]
page.truncated      # the window holds more points than were returned (exactly `limit` points is not truncated)
page.oldest_ts      # the oldest timestamp returned, None if there is none

# A window of any size, read page after page
result = observer.read_history(device_id, 'temperature', start_ms, end_ms, page_size=1000, max_pages=100,
                               deadline_s=300, page_retries=2)
result.points       # chronological, one per timestamp
result.complete     # False if the read ended early: result.cause says why, result.points holds what was obtained
result.pages

# Averaged: pages are windows of whole buckets, so no bucket is split
observer.read_history(device_id, 'temperature', start_ms, end_ms, agg='AVG', interval_ms=60_000)

# The newest point of a key, whatever its age, None if it has no data. It comes from the latest values of ThingsBoard
point = observer.get_device_latest_point(device_id, 'temperature')

# The newest point of several keys in one request: {key: point}, None for a key without data
points = observer.get_device_latest_points(device_id, ['temperature', 'humidity'])   # or 'temperature,humidity'
```

`get_device_telemetry_history()`, `get_device_latest_point()` and `get_device_latest_points()` raise `ThingsboardRequestError` (`error_code` is the HTTP
status), `ThingsboardTimeoutError` or `ThingsboardConnectionError`, `ThingsboardLoginError` when a login fails, and
`ValueError` for an invalid argument (nothing is sent). They can be called from any thread, also from a callback of the
observer.

`read_history()` raises only `ValueError`: a page that keeps failing, the page bound (`max_pages`) and the deadline
(`deadline_s`) end the read with `complete=False` and the points obtained so far. A failed page is asked again
`page_retries` times with a growing pause (0.5 s, 1 s, ...), unless ThingsBoard refused the request for good: a bad
request or missing authorization (HTTP 4xx other than 408 and 429), or credentials it refused. A server error (5xx), a
timeout and a lost connection are asked again. `None` for `max_pages` or `deadline_s` removes the bound. A raw read
follows a full page with another request, so a window that is an exact multiple of `page_size` costs one extra, empty
page. An averaged read costs one request per window of `page_size` buckets, data or not, so `max_pages` may end a read of
a long window incomplete. It assumes that the end of a window is included: the next page ends 1 ms before the oldest
point obtained.

### Values and coercion

ThingsBoard sends every value of a WebSocket push as a string, and the REST reads return strings as well. The observers
guess nothing by default: a string attribute `"true"` stays a string. Their reads take `coerce=True` to turn the values
into `bool`, `int` or `float` where the text is unambiguous, and `coerce_value()` does the same for one value (the
application API of the app converts by default, with declared types: see [Values](#values)):

```python
from thingsboard.monitor.values import coerce_value

coerce_value('true')      # True (also 'True', 'FALSE')
coerce_value('42')        # 42
coerce_value('21.5')      # 21.5
coerce_value('1.0E10')    # 1e10
coerce_value('007')       # '007': a leading zero, a sign, spaces, 'NaN', 'Infinity' and anything else stay strings

observer.get_device_latest_point(device_id, 'temperature', coerce=True)
observer.get_device_latest_points(device_id, 'temperature,humidity', coerce=True)
observer.read_history(device_id, 'temperature', start_ms, end_ms, coerce=True)
```

The values that the subscription callbacks of an observer get are the raw ones: coerce them yourself where you need to.

### Keepalive and timing settings

In the `websocket` group of the config file, or as constructor arguments (the constructor wins); `0` disables:

```ini
[websocket]
ping-interval = 20      # seconds between keepalive pings, default 20
ping-timeout = 20       # seconds to wait for the pong before the connection is rebuilt, default 20
request-timeout = 60    # seconds to wait for the answer of a REST read (history, latest point), default: the read
                        # timeout of the REST client
```

The connection is opened with the `connect-timeout` of the `thingsboard` group.

### Logging

The library logs state changes and the first failure of an outage at `WARNING` (no traceback), each further attempt
at `DEBUG`, and `Connection established again` at `INFO`. A traceback is only logged for a failure nobody expects.

## Tests

The default test suite needs no network and no ThingsBoard server. It uses fake servers running in the test process:

```bash
python -m unittest discover -s tests/offline -t .
```

The tests in `tests/thingsboard` need a real ThingsBoard endpoint and are run by hand.
