Riptide Cloud API

Installing

riptide-cloud is available using pip.

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:

{
  "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

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.

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

The following are some of the examples.

/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

---

/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

---

/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.

{'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.

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.

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.

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.

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