diff --git a/en/_posts/2015-08-10-how-to-get-data-from-runabove-iot.markdown b/en/_posts/2015-08-10-how-to-get-data-from-runabove-iot.markdown deleted file mode 100644 index 1fd75f6..0000000 --- a/en/_posts/2015-08-10-how-to-get-data-from-runabove-iot.markdown +++ /dev/null @@ -1,85 +0,0 @@ ---- -layout: post -title: "How to get data from the RunAbove IoT metrics storage" -categories: iot -lang: en -author: babelouest ---- - -[IoT Labs][6] is an Internet of Things Platform designed to store and retrieve metric data, and automatically compute and process that data. - -This documentation is about how to get data from the RunAbove IoT metrics storage. It explains how to transfer your data from the service via an https REST API. - -We assume you have a valid READ token from the application you're working with. Applications and token management is explained in the [How to push data to the RunAbove IoT metrics storage][1] - -# Get IoT Metrics Data - -## Query data from OpenTSDB HTTPS REST API - -The Runabove Metrics Storage system can be queried using a subset of the OpenTSDB REST API. [OpenTSDB](http://opentsdb.net) is a popular open source time series database which is integrated in many third-party tools such as [collectd](https://collectd.org/wiki/index.php/Plugin:OpenTSDB) or [Grafana](http://grafana.org/) - -The endpoint to query data via the webservice is at `https://opentsdb.iot.runabove.io/api/query` - -This endpoint uses the POST method, expecting data in the request body in JSON format. The complete documentation for OpenTSDB queries is available in the official [OpenTSDB Documentation][3] - -A valid example body has the following form: - -```json -{ - "start":1438956901, - "queries":[{ - "metric":"my.metric", - "aggregator":"sum", - "tags":{ - "boxid": "1F43" - } - }] -} -``` - -Please note that RunAbove IoT Metrics Storage does not implement TSUIDs, so a query filter using TSUID will be ignored. - -The other most common parameters are the following: - -- start: numeric, start date in Unix Epoch format in seconds (required) -- end: numeric, end date in Unix Epoch format in seconds (optional) -- queries: Array, a list of subqueries to filter data (required) - -A subquery accepts (but not only) the following parameters: - -- metric: string, the name of the metric stored (required) -- aggregator: string, the name of the [aggregator function][5] to use (required) - -The authentication method is a HTTP Basic Auth using a read token: use the token id as the username, and the token key as the password. - -On success, the body response has the following format: - -```json -[{ - "metric":"my.metric", - "tags":{ - "boxid":"1F43" - }, - "aggregateTags":[], - "dps":{ - "1438956980":1, - "1438957000":4, - "1438957110":3, - "1438957280":1 - } -}] -``` - -In this exemple, the main parameters are the following: - -- metrics: string, the metric name -- tags: object, the common tags for the data, -- dps: object, the data points with the timestamp as key and the numeric value as value. - -For a complete description, the query parameters are fully described in the official [OpenTSDB documentation][4]. - - [1]: /kb/en/iot/how-to-push-data-to-runabove-iot.html - [3]: http://opentsdb.net/docs/build/html/api_http/index.html - [4]: http://opentsdb.net/docs/build/html/api_http/query/index.html - [5]: http://opentsdb.net/docs/build/html/api_http/aggregators.html - [6]: https://runabove.com/iot/ diff --git a/en/_posts/2015-08-10-how-to-manage-iot-applications-using-runabove-api.markdown b/en/_posts/2015-08-10-how-to-manage-iot-applications-using-runabove-api.markdown deleted file mode 100644 index 1a6ca8a..0000000 --- a/en/_posts/2015-08-10-how-to-manage-iot-applications-using-runabove-api.markdown +++ /dev/null @@ -1,130 +0,0 @@ ---- -layout: post -title: "How to manage applications using the RunAbove API" -categories: iot -author: DavidTONeill -lang: en ---- - -# Introduction - -In this tutorial we assume you already have a RunAbove Account and have subscribed to the IoT lab. -We also assume that you have read the first documentation [How to manage applications using the manager][1]. -We use the curl command to illustrate examples. - -To use the RunAbove API, your application must be authenticated with it. To do so you can read the - [How to use RunAbove API?](https://community.runabove.com/kb/en/instances/how-to-use-runabove-api.html) tutorial. - -# How to create a new application - -```bash -$ curl -X POST - -H 'X-Ra-Application:your_application_key' \ - -H 'X-Ra-Timestamp:current_timestamp' \ - -H 'X-Ra-Signature:generated_signature' \ - -H 'X-Ra-Consumer:the_consumer_key' \ - -H 'Content-Type: application/json' \ - -d '{"cluster":"the cluster name", - "description":"application_description", - "name":"application_name"}' \ - https://api.runabove.com/1.0/iot/app -``` - -* cluster: The cluster is the location where your data is stored, please note that you cannot change the cluster after creation. -* description: the description you want to assign to your application. -* name: the name you want to assign to your new application. It can contain letters, numbers and dash '-' characters only. - -# How to modify an application - -```bash -$ curl -X PUT - -H 'X-Ra-Application:your_application_key' \ - -H 'X-Ra-Timestamp:current_timestamp' \ - -H 'X-Ra-Signature:generated_signature' \ - -H 'X-Ra-Consumer:the_consumer_key' \ - -H 'Content-Type: application/json' \ - -d '{"description":"the application description"}' \ - https://api.runabove.com/1.0/iot/app/application_name -``` - -* description: the description you want to assign to your application. -* application_name: the name you want to assign to your new application. It can contain letters, numbers and dash '-' characters only. - -# How to delete an application - -```bash -$ curl -X DELETE - -H 'X-Ra-Application:your_application_key' \ - -H 'X-Ra-Timestamp:current_timestamp' \ - -H 'X-Ra-Signature:generated_signature' \ - -H 'X-Ra-Consumer:the_consumer_key' \ - https://api.runabove.com/1.0/iot/app/application_name -``` - -* application_name: the name of the application you want to delete. - - -# How to create a new Token - -```bash -$ curl -X POST - -H 'X-Ra-Application:your_application_key' \ - -H 'X-Ra-Timestamp:current_timestamp' \ - -H 'X-Ra-Signature:generated_signature' \ - -H 'X-Ra-Consumer:the_consumer_key' \ - -d '{"description":"a description"}' \ - https://api.runabove.com/1.0/iot/app/your_application_name/token -``` - -* your_application_name: application_name in which will reside the token. -* description: the description of the token. -* endDate: endDate format is a unix timestamp based on seconds since standard epoch of 01/01/1970. -* tagList: the tags of your token. - -# How to modify a token - -```bash -$ curl -X PUT - -H 'X-Ra-Application:your_application_key' \ - -H 'X-Ra-Timestamp:current_timestamp' \ - -H 'X-Ra-Signature:generated_signature' \ - -H 'X-Ra-Consumer:the_consumer_key' \ - -H 'Content-Type: application/json' \ - -d '{"description":"the application description", - "tagList":[{"name":"a tag key","value":"a tag value"},{"name":"another tag key","value":"another tag value"}]}' \ - https://api.runabove.com/1.0/iot/app/application_name/token/token_name -``` - -* application_name: the name of the application hosting the token. This value cannot be changed -* token_name: the name of the token you want to modify. -* description: the description of the token. -* tagList: the tags of your token, that will replace the existing tags. This is an array of name/value pairs. - -# How to delete a token - -```bash -$ curl -X DELETE - -H 'X-Ra-Application:your_application_key' \ - -H 'X-Ra-Timestamp:current_timestamp' \ - -H 'X-Ra-Signature:generated_signature' \ - -H 'X-Ra-Consumer:the_consumer_key' \ - https://api.runabove.com/1.0/iot/app/your_application_name/token/your_token_name -``` - -* your_application_name: the name of the application you want to delete. -* your_token_name: the name of the token you want to modify. - -# How to retrieve my tokens - -```bash -$ curl -X GET - -H 'X-Ra-Application:your_application_key' \ - -H 'X-Ra-Timestamp:current_timestamp' \ - -H 'X-Ra-Signature:generated_signature' \ - -H 'X-Ra-Consumer:the_consumer_key' \ - https://api.runabove.com/1.0/iot/app/your_application_name/token -``` - -* your_application_name: application_name in which resides the tokens you want to retrieve. - -[1]: how-to-manage-iot-applications-using-runabove-manager.html diff --git a/en/_posts/2015-08-10-how-to-manage-iot-applications-using-runabove-manager.markdown b/en/_posts/2015-08-10-how-to-manage-iot-applications-using-runabove-manager.markdown deleted file mode 100644 index 5ef718f..0000000 --- a/en/_posts/2015-08-10-how-to-manage-iot-applications-using-runabove-manager.markdown +++ /dev/null @@ -1,95 +0,0 @@ ---- -layout: post -title: "Managing IoT applications with the Runabove Manager" -categories: iot -author: DavidTONeill -lang: en ---- - -This tutorial assumes you already have a RunAbove account and have subscribed to the [IoT lab](https://www.runabove.com/iot/). - -# Concepts - -## IoT applications - -An application is an isolated container for your metrics data. You can define separate applications for projects that have no relation, e.g. one for greenhouse monitoring in a farm, and another one for all the sensors in a building. Access to the data is defined per application. - -If a project or product has multiple tenants that should see only a subset of the data, use a single applications and create separate tokens (see below) for each tenant. - -## Access tokens - -Tokens are used for authentication and authorization. They have a unique identifier, and contain : - -* a name -* a key, used to authenticate the token, -* permissions (read or write), -* tags (key/value pairs) that define the subset in the application's data that can be accessed with the token. - -The tags attached to a write token are automatically added to any value written using this token, and the tags attached to a read token are automatically added as filters to any query made with this token. This allows tags to effectively restrict the scope of the token to a subset of the application's data. - -Typical use cases for tags: - -* with write token tags, enforce a device identifier (or data source), making sure a device cannot write data on behalf of others. It also limits potential data corruption if a device's token is compromised. -* with read tokens tags, restrict visibility of a given user to the devices owned by that user. - -# How to create a new application - -Go to the [RunAbove Manager](https://cloud.runabove.com) and choose "[Internet of Things](https://cloud.runabove.com/#/iot)" in the left menu. - -![main-page][2] - -To create your first application, click on the "New application" button in the upper-right corner. - -Enter the name, description and cluster of your new application : - -* The name can contain only alphanumeric characters and dash and are case sensitive. -* The cluster is the location where your data are stored. - -![application-creation-page][3] - -Once you click "Ok", the application is shown in the list and is ready for further actions. - -![application-creation-page][4] - -Use the left column action icons to: - -* go to the token list for this application. -* edit the application. Only the name and description can be changed, not the storage location. -* delete the application. - -# How to create a new token - -From the application list, either select the application name or the key icon. This will show the token management screen. - -![token-page][7] - -Select the "New token" top right button. In the example below, we create a specific token for the greenhouse's ceiling sensor gateway. The token has a "location" tags that will automatically tag metrics with their origin. - -Having a separate token for the ceiling sensors also strengthens the system's security. If that device and its token are compromised, the impact is limited since the token can only write to a narrow subset of the application's full data set. - -![token-creation-page][8] - -Once you have defined the token's parameters, it is displayed in the application's token list. That list also contain the token's read and write identifier and keys. - -![token-list][9] - -You can then copy/paste these identifiers and keys to [send data][10] to the metric storage or [query that storage][11]. - -Use the left column action icons to: - -* edit the token's name and tags, -* download a JSON representation the token, -* delete the token. - - -[1]: /kb/images/2015-08-10-how-to-manage-iot-applications-using-runabove-manager/main-page.png -[2]: /kb/images/2015-08-10-how-to-manage-iot-applications-using-runabove-manager/empty-application-page.png -[3]: /kb/images/2015-08-10-how-to-manage-iot-applications-using-runabove-manager/application-creation-page.png -[4]: /kb/images/2015-08-10-how-to-manage-iot-applications-using-runabove-manager/application-page.png -[5]: /kb/images/2015-08-10-how-to-manage-iot-applications-using-runabove-manager/application-row.png -[6]: /kb/images/2015-08-10-how-to-manage-iot-applications-using-runabove-manager/application-modification-page.png -[7]: /kb/images/2015-08-10-how-to-manage-iot-applications-using-runabove-manager/token-page.png -[8]: /kb/images/2015-08-10-how-to-manage-iot-applications-using-runabove-manager/token-creation-page.png -[9]: /kb/images/2015-08-10-how-to-manage-iot-applications-using-runabove-manager/token-list.png -[10]: how-to-push-data-to-runabove-iot.html -[11]: how-to-get-data-from-runabove-iot.html diff --git a/en/_posts/2015-08-10-how-to-push-data-to-runabove-iot.markdown b/en/_posts/2015-08-10-how-to-push-data-to-runabove-iot.markdown deleted file mode 100644 index 1310071..0000000 --- a/en/_posts/2015-08-10-how-to-push-data-to-runabove-iot.markdown +++ /dev/null @@ -1,109 +0,0 @@ ---- -layout: post -title: "How to push data to RunAbove IoT Lab" -categories: iot -tags: iot opentsdb -lang: en -author: babelouest ---- - -The [Runabove IoT Lab][1] is an Internet of Things Platform designed to store and retrieve numeric data, and automatically compute and process the data. - -This tutorial explains how to push data into the IoT metrics storage. It assumes you have a valid RunAbove account and have subscribed to the IoT Lab. - -In order to push and get data from IoT Lab, you first have to create an application and a token. See the [application and token management tutorial][7] for this. You will need a WRITE token's identifier and key. - -All connections to the IoT Lab metrics storages are encrypted using TLS and authenticated with your tokens. - -# Pushing IoT metrics - -## Metric name, value and tags - -Every time series in the IoT Lab metric storage is identified by: - -- the metric name, representing what is measured, e.g. `temperature`, `speed`, `humidity` -- metric tags, that identify the source of the metric, e.g. `room=cellar` for temperature or humidity, `car=5BBM99` for speed. - -The combination of metric name and tags and their value uniquely identify a time series. - -Separating metric name and tag values allow to easily select entire collections of time series to perform calculations and aggregations. So you have to "design" your metric names and tags according to how you plan to filter and aggregate metrics afterwards. - -Allowed characters for metric names, tag names and tag values are letters, numbers, dash and points ([a-zA-Z0-9-.]). Timestamps are in Unix Epoch format, either in seconds or milliseconds. - -In IoT Lab, each data must be provided with a metric and a timestamp value. You can also improve the metadata with an additional set of tags. Each tag is a pair of key and value. - -When you push data in IoT Lab, you have to use a valid WRITE Token provided by the token management. The data will be authenticated with the token provided, as metadata, you will also have its application and the token tags. You can also provide additional tags for any purpose (identification, grouping, filter, geolocalisation, etc.). - -The metric metadata will represent the type of data you send such as `"cpu.temp"` or `"network.packets.in"`. Characters allowed are letters, numbers, dash and points ([a-zA-Z0-9-.]). The timestamp is in Epoch Unix format -- both seconds and milliseconds are accepted. - -## Sample programs - -Sample programs are available for different languages (C, Java, Python, Go) as examples to help you write your own programs to push data. The source code of the samples is [available here][5]. - -## Pushing data via a HTTPS - -The IoT Lab metric storage uses the [OpenTSDB](http://opentsdb.net/) API to push data. Authentication is handled using HTTP Basic authentication, using the WRITE token id as user name, and the token key as password. - -The endpoint to push data via the webservice is `https://opentsdb.iot.runabove.io/api/put`. It uses the POST method with metric values in a JSON request body. - -A valid request body has the following form: - -```json -[{ - "metric":"app.test", - "timestamp":1437591536, - "value":1, - "tags":{ - "key1":"value1", - "key2":"value0", - } -},{ - "metric":"app.test", - "timestamp":1437591539, - "value":2, - "tags":{ - "key1":"value1", - "key2":"value2", - } -}] -``` - -The parameters are as follows: - -- metric: string, the metric used to name the data type (required) -- timestamp: numeric, the timestamp associated with the value in Unix Epoch format in seconds or milliseconds (required) -- value: numeric, the valu itself (required) -- tags: object, a set of additional tags for the data - -The parameters are fully described in the [OpenTSDB documentation][2]. - -On success, the response is a 2xx HTTP Response code. On error, the response code and the response body will explain the issue. - -## Pushing data via the Telnet Protocol - -OpenTSDB offers also a telnet protocol (text over TCP/IP) to push data. To use it, you must connect to `opentsdb.iot.runabove.io:4243` with a TLS connection. - -When you are connected, you can ask for the complete command list by typing `help` and quit by typing `exit`. - -To push data in telnet mode, you must use a command `put` for each data. The format of `put` is: - -`put ` - -As in the https endpoint, you must provide a valid WRITE token. The OpenTSDB telnet has no native support for authentication, so the IoT Lab added ways to pass the token. Two methods are available, depending on what your environment allows: - -- send the token in a special tag: `ovh.auth=:` (token id and key separated with a colon). This tag only serves for authentication purposes and is not stored in the metrics storage. -- use the special `auth` command before sending metrics. The format for this command is `auth :` (token id and key separated with a colon). - -Using the `auth` command is recommended to save bandwidth and CPU cycles, but you may not be able to send it when using existing tools. The `ovh.auth` tag is there for these situations. - -If the data is properly stored, no answer will be sent from the server. If an error occurs, the server will send back an error message explaining the issue, and close the connection. - -# Using your data - -When your data is properly sent into the RunAbove IoT Lab platform, you can start managing the data for your needs. This is explained in the tutorial [How to get data from the RunAbove IoT metrics storage][3] - - [1]: https://runabove.com/iot/ - [2]: http://opentsdb.net/docs/build/html/api_http/put.html - [3]: how-to-get-data-from-runabove-iot.html - [5]: https://github.com/runabove/iot-push-examples - [7]: how-to-manage-iot-applications-using-runabove-manager.html