riptide-cloud 0.0.2
Riptide Cloud API.
License: MIT
Requires Python: >=3.6
Keywords: riptide alarm entity watch history IoT cloud

# Riptide Cloud API

## Installing

`riptide-cloud` is available using pip.

```.env
pip install riptide-cloud
```

## Introduction

The APIs provided as part of the `riptide-cloud` package can be used to read
the following information.

 - `entity` (like `site`, `equipments`, `points`, etc),
 - `alarms` (a.k.a. `alerts`),
 - `history` (past data about any entity),
 - `watch` (list of entities that you are interested in watching), etc.

Please note that the APIs can only be used to `read` information from the
Riptide cloud. No `write`/`create` is allowed (except `watch` where you are
allowed to `create` one-or-more watches to monitor points at the real-time).

The request and response payload are in `JSON` format. So the `content-type`
in the header would be `application/json`.

## RiptideCloudApp

Create a `JSON` file with the following contents:

```json
{
  "auth": "Basic",
  "username": "<username>",
  "password": "<password>"
}
```

`username` and `password` should be a valid username and password provided
to you for accessing Riptide cloud.

Say you save this file as `riptide.json` and the full path to this file is
`/tmp/riptide.json`.

Create an instance of `RiptideCloudApp` with `config_file=/tmp/riptide.json`

```python
from riptide.cloud.app import RiptideCloudApp

rca = RiptideCloudApp(config_file="/tmp/riptide.json")
```

NOTE: For all interactions with riptide cloud, you will use the
`RiptideCloudApp` instance `rca`.


## Entity

Entity APIs can be invoked as follows:

- `rca.entity.get_entity(uri=<uri>)`
- `rca.entity.get_entity_tag(uri=<uri>, name=<tag-name>)`
- `rca.entity.get_entity_tags(uri=<uri>)`
- `rca.entity.entity_read_override(uri=<uri>)`
- `rca.entity.entity_read_override_at(uri=<uri>, level=<priority-level>)`

`<uri>` in the above API calls are called as `Riptide Entity URI`. Riptide
uses `uri` (Uniform Resource Identifier) to represent `site`, `equipments`
and `points` in the following way.

```.env
/<customer-name>/<site-name>[/<path-to-equipment>]/<equipment-name>/properties/<property-type>/<property-name>[/presentValue | priorityArray[/<priorityLevel>]]
```

The following are some of the examples.

```.env
/McDonalds/San Bernardino/Weather/properties/AI/Temperature
```

- `customer-name` is `McDonalds`
- `site-name` is `San Bernardino`
- `equipment-name` is `Weather`
- `property-type` is `AI`
- `property-name` is `Temperature`

---

```.env
/McDonalds/San Bernardino/HVAC/Outdoor Unit - 05/properties/AI/Target Condensing Temperature
```

- `customer-name` is `McDonalds`
- `site-name` is `San Bernardino`
- `path-to-equipment` is `HVAC`
- `equipment-name` is `Outdoor Unit - 05`
- `property-type` is `AI`
- `property-name` is `Target Condensing Temperature`

---

```.env
/McDonalds/San Bernardino/HVAC/Indoor Unit - 11/properties/AO/Set Temperature/priorityArray/10
```

- `customer-name` is `McDonalds`
- `site-name` is `San Bernardino`
- `path-to-equipment` is `HVAC`
- `equipment-name` is `Indoor Unit - 11`
- `property-type` is `AO`
- `property-name` is `Set Temperature`
- `priority-level` is `10`

The following are syntactically valid examples.

- `/McDonalds/San Bernardino/HVAC/Indoor Unit - 11/properties/AO/Set Temperature/priorityArray/10`
- `/McDonalds/San Bernardino/HVAC/Indoor Unit - 11/properties/AO/Set Temperature/priorityArray`
- `/McDonalds/San Bernardino/HVAC/Indoor Unit - 11/properties/AO/Set Temperature/presentValue`
- `/McDonalds/San Bernardino/HVAC/Indoor Unit - 11/properties/AO/Set Temperature`
- `/McDonalds/San Bernardino/HVAC/Indoor Unit - 11`
- `/McDonalds/San Bernardino/HVAC`
- `/McDonalds/San Bernardino` *
- `/McDonalds` *

`* -> NOT RECOMMENDED`

Most of the `entity` APIs takes the entity url as input. The output of these
 APIs varies based on the entity `url`.

For example:

 - `/priorityArray` would give the following output.

```json
{'1': None,
 '10': None,
 '11': None,
 '12': None,
 '13': None,
 '14': 73,
 '15': None,
 '16': None,
 '2': None,
 '3': None,
 '4': None,
 '5': None,
 '6': 73.5,
 '7': None,
 '8': None,
 '9': 75,
 'relinquish': None}
```

 - `/presentValue` would give the following output.

```json
21.3
```


## Alarm

Alarm APIs can be invoked as follows:

- `rca.alarms.get_alarm(uuids, context)`
- `rca.alarms.get_alarm_history(uuids, context, start, end)`

To get more help on these APIs, you could type the following in your Python
terminal.

```python
help(rca.alarms.get_alarm)
help(rca.alarms.get_alarm_history)
```

## History

Riptide cloud offers the following flavors of historic data.

- `Raw Historic Data` : The value of a point as recorded at the site at
various instances of time.

- `Interpolated Historic Data` : The value of a point as recorded at the site
at various instances of time and also the estimated or interpolated values
of the point for the missing periods by using re-sampling technique.

- `Rolled-up Historic Data` : The value of point condensed for a time period
(e.g. 1 day, 10 days, 1 week and so on).

- `Digested Historic Data` : The value of a point summarized over a period of
period of time (e.g. mean, sum, median and so on). This also allows user
to apply a function on every value of a point like say add, subtract etc.

History APIs can be invoked as follows:

- `rca.history.get_history(identifiers=[uri1, uri2 ... ], start=<datetime>,
stop=<datetime>)`

Few important points to NOTE:
- `identifiers` are entity property uri's. It must not be site or equipment
uri's but only point uri's.
- Maximum number of `identifiers` that are allowed per API call is 50.
- `start` and `end` accepts only `datetime` objects; `start` should be
lesser-than-or-equal-to `end` but must not exceed 31 days.

To get more help on the above API, you could type the following in your
Python terminal.

```python
help(rca.history.get_history)
```

## Watch

You can create a watch and then interacts with that watch to obtain the
latest readings associated with a group of entity properties.

Watch APIs can be invoked as follows:

- `rca.watch.create_watch(identifiers=[uri1, uri2 ... ])`
- `rca.watch.get_watches()`
- `rca.watch.poll_watch(watch_id=<watch-id>)`
- `rca.watch.poll_watch_changed(watch_id=<watch-id>)`
- `rca.watch.delete_watch(watch_id=<watch-id>)`
- `rca.watch.read_present_value(identifier=<entity-property-uri>)`

To get more help on the above API, you could type the following in your
Python terminal.

```python
help(rca.watch.create_watch)
help(rca.watch.get_watches)
help(rca.watch.poll_watch)
help(rca.watch.poll_watch_changed)
help(rca.watch.delete_watch)
help(rca.watch.read_present_value)
```

## Support

For any support, please reach out to `support@riptideio.com`


# __END__