Resources

Renesas IoT Sandbox Documentation

Renesas IoT Sandbox API


API Keys

API Keys are keys associated with your account to be able to access the API.These can be viewed on the Manage API Keys page. Here, you can create, edit, and delete keys.

To create an API Key, click on the “Add New API Key” button. A description is required to save the API Key. This description is for your own use and does not affect the functionality of the API Key. Click “save” once done and the API Key should be automatically generated and set to enabled by default. These API Keys are important for any API access to Renesas IoT Sandbox.

Note: If an API Key is disabled, it can no longer access the API unless it is enabled again.



REST API

The REST API is designed for developers using the Renesas IoT Sandbox service. In order to use the REST API, the developer must be registered with Renesas IoT Sandbox.

The following API endpoints are appended to the base URL.

  • /v2/login - Endpoint to login
  • /v2/users - Endpoint to create/retrieve/update/delete Basic Users (see roles)
  • /v2/events/stream_name - Collection of endpoints to access event data, for example:
    • /v2/events/raw - Raw event data
    • /v2/events/processed - Processed event data
  • /v2/store - Endpoint to access Store data


/v2/login

POST
Role permissions

This operation is permitted for all user roles.

Headers
Content-Type: application/json
Accept: application/json
Body
  • For Login / Password authentication, the following keys are required:

    • login_id: Email address associated with user
    • password: User’s password
    • api_key: API key (Setup / Manage API Keys web page)
  • Optional keys:
    • no_cookies: Value not used. Session cookie header will not be returned; instead a token will be returned in the response body.

Calling /v2/login with a POST will log in and produce login cookies to identify the user's logged-in state. The cookies must be passed in with subsequent requests to the other API endpoints. Cookie sessions last for 24 hours. If no_cookies is specified, the returned token must be saved and from then on, token=<<RETURNED TOKEN>> is added to the URL parameters for each following request.

HTTP Response

200 OK

  • The user is successfully logged in. The response body will contain: true. However if no_cookies is specified, the return value will be the token.

400 BAD REQUEST

  • The request was missing login_id/password/key parameters.

400 UNAUTHORIZED

  • The parameters contained invalid data, or the password didn’t match

403 FORBIDDEN

  • No user matching login_id can be found or insufficient permissions to login.

500 SERVER ERROR

  • Could not complete the request due to an internal server error.

503 SERVICE UNAVAILABLE

  • Temporarily unable to complete the login request. Please try again.
Examples:

Curl

#!/bin/sh
curl -c cookie_user.txt -i -X POST -d '{"login_id":"john.doe@renesas.com","password":"12345","api_key":"ABCDEFGHIJKLmnopabcdefghijklmnop1234567890"}' https://api-renesas-na-sandbox.mediumone.com/v2/login/ --header "Content-Type: application/json"

Python

import requests
import json

headers ={'Content-Type': 'application/json', 'Accept': 'application/json'}
data = {'login_id': 'john.doe@renesas.com', 'password': '12345', 'api_key': 'ABCDEFGHIJKLmnopabcdefghijklmnop1234567890'}

session = requests.session()
response = session.post('https://api-renesas-na-sandbox.mediumone.com/v2/login', data=json.dumps(data), headers=headers)

Curl

#!/bin/sh
curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' 'https://api-renesas-na-sandbox.mediumone.com/v2/login?no_cookies' -d '{"login_id": "john.doe@renesas.com", "password": "12345", "api_key": "ABCDEFGHIJKLmnopabcdefghijklmnop1234567890"}'

Python

import requests
import json

headers ={'Content-Type': 'application/json', 'Accept': 'application/json'}
data = {'login_id': 'john.doe@renesas.com', 'password': '12345', 'api_key': 'ABCDEFGHIJKLmnopabcdefghijklmnop1234567890'}

session = requests.session()
response = session.post('https://api-renesas-na-sandbox.mediumone.com/v2/login?no_cookies', data=json.dumps(data), headers=headers)



/v2/users/login_id

The /v2/users/login_id endpoint can be used for CRUD manipulations on new and existing users, depending on the role of the user used for the log in step.

GET

Fetch the user data for login_id.

Role permissions:

This operation is permitted for Basic User and Business User roles.

Headers
Accept: application/json
Cookies: < login cookies >
HTTP Response

200 OK

  • The user information is successfully retrieved. The response body should contain a JSON structure with the user’s email address Eg: {"login_id": "johndoe@renesas.com"}

403 FORBIDDEN

  • No user matching login_id can be found or insufficient permissions to view that user’s data.

404 NOT FOUND

  • No user matching login_id can be found.

500 SERVER ERROR

  • Could not complete the request due to an internal server error.

503 SERVICE UNAVAILABLE

  • Temporarily unable to complete the login request. Please try again.
Example

Curl

#!/bin/sh
curl -b cookie_user.txt -i -X GET https://api-renesas-na-sandbox.mediumone.com/v2/users/john.doe@renesas.com --header "Content-Type: application/json"

Python

import requests
import json

headers ={'Content-Type': 'application/json', 'Accept': 'application/json'}
data = {'login_id': 'john.doe@renesas.com', 'password': '12345', 'api_key': 'ABCDEFGHIJKLmnopabcdefghijklmnop1234567890'}

session = requests.session()
response = session.post('https://api-renesas-na-sandbox.mediumone.com/v2/login', data=json.dumps(data), headers=headers)

headers = {'Accept': 'application/json'}

response = session.get('https://api-renesas-na-sandbox.mediumone.com/v2/users/john.doe@renesas.com', headers=headers)
PATCH

Calling /v2/users/login_id with a PATCH will update the data for the user. Only updating the password or disabling/enabling a basic user is supported at this time. Password updating is not supported for Facebook and Google Plus token-authenticated users.

Role permissions
  • This operation is permitted for Basic User and Business User roles.
Headers
Content-Type: application/json
Accept: application/json
Cookies: < login cookies >
Body

password: password disabled: boolean

HTTP Response

200 OK

  • The user information is successfully updated. The response body contains a JSON document with a list of the fields that were updated Eg: "password"

400 BAD REQUEST

  • The request was missing parameters or the password did not meet minimum complexity requirements

401 UNAUTHORIZED

  • There is no logged in user or the logged in user is not permitted to access the requested user.

404 NOT FOUND

  • The requested user could not be found.

500 SERVER ERROR

  • Could not complete the request due to an internal server error.

503 SERVICE UNAVAILABLE

  • Temporarily unable to complete the login request. Please try again.
Examples

Curl

#!/bin/sh
curl -b cookie_user.txt -i -X PATCH -d '{"password":"12345"}' https://api-renesas-na-sandbox.mediumone.com/v2/users/john.doe@renesas.com --header "Content-Type: application/json"
curl -b cookie_user.txt -i -X PATCH -d '{"disabled":true}' https://api-renesas-na-sandbox.mediumone.com/v2/users/john.doe@renesas.com --header "Content-Type: application/json"

Python

import requests
import json

headers = {'Content-Type': 'application/json', 'Accept': 'application/json'}
data = {'login_id': 'john.doe@renesas.com', 'password': '12345', 'api_key': 'ABCDEFGHIJKLmnopabcdefghijklmnop1234567890'}

session = requests.session()
response = session.post('https://api-renesas-na-sandbox.mediumone.com/v2/login', data=json.dumps(data), headers=headers)

headers = {'Accept': 'application/json'}

data = { 'password': '123456', 'disabled': True}         

response = session.patch('https://api-renesas-na-sandbox.mediumone.com/v2/users/john.doe@renesas.com', data=json.dumps(data), headers=headers)
POST

Calling /v2/users with a POST will create a new user. Only one user can have a particular email address. This operation is not supported for Facebook and Google Plus token-authenticated users.

Role permissions

Only users with the role of Business User and Registration User are permitted for this operation.

Headers
Content-Type: application/json
Accept: application/json
Cookies: < login cookies >
Body
  • login_id: user’s login_id
  • password: password
HTTP Response

200 OK

  • The user is successfully created. The response body contains a JSON document with the created user’s email address. Eg: {"login_id": "johndoe@aol.com"}

400 BAD REQUEST

  • The request was missing parameters or the user already exists or the password did not meet minimum complexity requirements.

401 UNAUTHORIZED

  • The HTTP basic auth is invalid, or there is no logged in user or the logged in user is not permitted to access the requested user. 403 FORBIDDEN
  • The user could not be created (eg. the user already exists).

429 TOO MANY REQUESTS

  • The user has sent too many requests in a given amount of time.

500 SERVER ERROR

  • Could not complete the request due to an internal server error.

503 SERVICE UNAVAILABLE

  • Temporarily unable to complete the login request. Please try again.
Examples

Curl

#!/bin/sh
curl -b cookie_user.txt -i -X POST -d '{"login_id":"joe.doe@renesas.com","password":"123456"}' https://api-renesas-na-sandbox.mediumone.com/v2/users/ --header "Content-Type: application/json"

Python

import requests
import json

headers ={'Content-Type': 'application/json', 'Accept': 'application/json'}
data = {'login_id': 'apibusinessuser@renesas.com', 'password': '12345', 'api_key': 'ABCDEFGHIJKLmnopabcdefghijklmnop1234567890'}

session = requests.session()
response = session.post('https://api-renesas-na-sandbox.mediumone.com/v2/login', data=json.dumps(data), headers=headers)

headers = {'Content-Type': 'application/json', 'Accept': 'application/json'}

data = { 'login_id': 'john.doe@renesas.com',
         'password': '123456'}

response = session.post('https://api-renesas-na-sandbox.mediumone.com/v2/users/', data=json.dumps(data), headers=headers)
DELETE

Calling /v2/user/login_id with a DELETE will delete the user identified by login_id. As every event belongs to a user, once a user is deleted, all associated event data will also be deleted.

Role permissions

Only users with the role of Business User are permitted to do this operation.

Headers
Accept: application/json
Cookies: < login cookies >
HTTP Response

204 OK

  • The user is successfully deleted.

403 UNAUTHORIZED

  • There is no logged in user or the logged in user is not permitted to access the requested user.

404 NOT FOUND

  • The user for login_id does not exist.

500 SERVER ERROR

  • Could not complete the request due to an internal server error.

503 SERVICE UNAVAILABLE

  • Temporarily unable to complete the login request. Please try again.
Examples

Curl

#!/bin/sh
curl -b cookie_user.txt -i -X DELETE https://api-renesas-na-sandbox.mediumone.com/v2/users/john.doe@renesas.com --header "Content-Type: application/json"

Python

import requests
import json

headers ={'Content-Type': 'application/json', 'Accept': 'application/json'}
data = {'login_id': 'apibusinessuser@renesas.com', 'password': '12345', 'api_key': 'ABCDEFGHIJKLmnopabcdefghijklmnop1234567890'}

session = requests.session()
response = session.post('https://api-renesas-na-sandbox.mediumone.com/v2/login', data=json.dumps(data), headers=headers)

headers = {'Accept': 'application/json'}

response = session.delete('https://api-renesas-na-sandbox.mediumone.com/v2/users/john.doe@renesas.com', headers=headers)



/v2/events/stream_name

The /v2/events/stream_name is a collection of endpoints that map to specific streams, as defined in the Renesas IoT Sandbox business configuration (Config → Data Streams page).

/v2/events/stream_name/login_id

The /v2/events/stream_name endpoint is used for creation and retrieval of event data.

login_id is optional if an API Basic User is logged in, as that user can only post data on his own behalf. It is required if an API Business User is logged in and transferring event data on behalf of the API Basic User. Each posted event belongs to the API Basic User specified or logged in.

Role permissions

Users with the roles of Business User or Basic User are permitted for the below operations.

A user with the Basic User role can only see his/her own data. login_id is optional when Basic User role, and, if unspecified, defaults to all events the current session user is allowed to see.

GET
Headers
Accept: application/json
Cookies: < login cookies >
Path

URL-encoded parameters, all optional:

  • since: ISO8601 format timestamp, including timezone, fetches all data after specified time
  • until: ISO8601 format timestamp, including timezone, fetches all data before specified time
  • limit: limits the number of results, must be a whole number up to a maximum of 10,000 (default). For retrieving more than this number of data events, since and until parameters can be used to select a specific time span
  • sort_by: Valid values for "sort_by" are "observed_at", "received_at" and "internal". "internal" is roughly equivalent to "received_at" but sorts by event_ids, so events received at the same millisecond may not sort in the same order as "received_at". The advantage of the internal sort order is that the queries are faster, especially when a user isn't specified.
  • sort_direction: Valid values for "sort_direction" are "asc" and "desc" for ascending and descending. If not specified "sort_direction" is considered to be "asc". Specifying "sort_direction" without "sort_by" is an error.
  • include: Fetches data of the specified tag
  • exclude: Fetches all data, omitting the specified tag
HTTP RESPONSE

200 OK

  • events successfully read. The response body should contain one JSON document per line, with no specific ordering:
    {"observed_at": "< ISO_observed_at >", "event_data": {event_data}, "stream":"raw", "login_id": "< some_id >"}
    {"observed_at": < ISO_observed_at >, "event_data": {event_data}, "stream":"raw", "login_id": "< some_id >"}

400 BAD REQUEST

  • The request was missing parameters.

401 UNAUTHORIZED

  • No authorized user is currently logged in.

403 FORBIDDEN

  • No user matching login_id can be found or insufficient permissions to view that user’s data.

404 NOT FOUND

  • No user matching login_id can be found.

500 SERVER ERROR

  • Could not complete the request due to an internal server error.

503 SERVICE UNAVAILABLE

  • Temporarily unable to complete the request. Please try again.
Examples

Curl

# login as API Basic User and save session cookies
curl -c cookies.txt -X POST -k -H 'Content-Type: application/json' -H 'Accept: application/json' -i 'https://api-renesas-na-sandbox.mediumone.com/v2/login' -d '{"login_id": "john.doe@renesas.com", "password": "123456", "api_key": "Abcdefghijklmnopqrstuvwxyz0123456789"}'

# get data
curl -b cookies.txt -X GET -k -H 'Accept: application/json' 'https://api-renesas-na-sandbox.mediumone.com/v2/events/raw/john.doe@renesas.com?since=2015-01-10T00%3A00%3A00.000-0800&limit=100&include=$.event_data.tagname'

Python

import requests
import json

headers = {'Content-Type': 'application/json', 'Accept': 'application/json'}
data = {'login_id': 'john.doe@renesas.com', 'password': '12345', 'api_key': 'ABCDEFGHIJKLmnopabcdefghijklmnop1234567890'}

# Login
session = requests.session()
response = session.post('https://api-renesas-na-sandbox.mediumone.com/v2/login', data=json.dumps(data), headers=headers)

url = 'https://api-renesas-na-sandbox.mediumone.com/v2/events/raw/john.doe@renesas.com'
headers = {'Accept': 'application/json'}
params = {"since":"2015-01-10T00:00:00.000-0800", "until":"2015-01-17T00:00:00.000-0800", "limit":100, "include":"$.event_data.tagname"}

# GET
response = session.get(url=url, params=params, headers=headers)
POST

login_id must be specified, events posted will be associated with the specified user.

Headers
Content-Type: application/json
Accept: application/json
Cookies: < login cookies >
Body

A json object of the data to be written (event_data is a required field). If observed_at is missing, the received_at time will be used. Can be multiple items, one JSON document per line (with newline character between each JSON document). The POST body has a maximum limit of 10MB.

  • Example of single data event

    {"observed_at": "2014-06-11T02:11:25.076001", "event_data": {"sensor1": 37.3, "sensor2": 183}}
  • Example of multiple data events:

    CORRECT

    {'observed_at': '2014-06-11T02:11:26.157759', 'event_data': {'sensor1': 38.6}}
    {'observed_at': '2014-06-11T02:12:27.458693', 'event_data': {'sensor1': 39.4}}

    INCORRECT

    {'observed_at': '2014-06-11T02:11:26.157759', 'event_data': {'sensor1': 38.6}}{'observed_at': '2014-06-11T02:12:27.458693', 'event_data': {'sensor1': 39.4}}

Notes on specific key/value fields:

  • observed_at must be an ISO8601-formatted text string, for example "2014-07-25T12:12:56.2345-08:00"

  • If observed_at is missing, the received_at time will be used.

  • add_client_ip can be added and will put the client IP address into the pushed event's event_data as the tag ip_address. It is a boolean placed at the same level as the "event_data" dictionary. (ex: "add_client_ip": true)

  • Timezone offset must be specified to avoid ambiguity.

  • event_data can be a multi-level json document for the purposes of storage and retrieval.

Values can contain the following JSON data types: text (string) numbers without decimal point (interpreted as integer values) numbers with decimal point (interpreted as floating point values) dates (ISO8601 string format) Note: Other data types are not supported at this time

HTTP Response

200 OK

  • eventlog is successfully created. Returns number of events created.

400 BAD REQUEST

  • The request was missing parameters.

401 UNAUTHORIZED

  • No authorized user is currently logged in.

403 FORBIDDEN

  • No user matching login_id can be found or not authorized to post data for the given user.

404 NOT FOUND

  • No user matching login_id can be found.

500 SERVER ERROR

  • Could not complete the request due to an internal server error.

503 SERVICE UNAVAILABLE

  • Temporarily unable to complete the request. Please try again.
Examples

Curl

# login as API Basic User and save session cookies
curl -c cookies.txt -i -X POST -d '{"login_id":"john.doe@renesas.com","password":"12345","api_key":"ABCDEFGHIJKLMNOPabcdefghijklmnop1234567890"}' https://api-renesas-na-sandbox.mediumone.com/v2/login/ --header "Content-Type: application/json"

# send data
curl -b cookies.txt -X POST -k -H 'Content-Type: application/json' -i https://api-renesas-na-sandbox.mediumone.com/v2/events/raw/john.doe@renesas.com -d '{"observed_at": "2015-01-10T00:00:00.000-0800", "event_data": {"sensor1" : 38.6}}'

Python

import requests
import json

headers = {'Content-Type': 'application/json', 'Accept': 'application/json'}
data = {'login_id': 'john.doe@renesas.com', 'password': '12345', 'api_key': 'ABCDEFGHIJKLmnopabcdefghijklmnop1234567890'}

session = requests.session()
response = session.post('https://api-renesas-na-sandbox.mediumone.comv2/login', data=json.dumps(data), headers=headers)

url = 'https://api-renesas-na-sandbox.mediumone.com/v2/events/raw/john.doe@renesas.com'
data = {'observed_at': '2015-01-10T00:00:00.000-0800', 'event_data': {'sensor1' : 38.6}}

response = session.post(url=url, data=json.dumps(data), headers=headers)



/v2/store/login_id

The /v2/store/login_id endpoint is used for creation, retrieval, and update of Store data.

login_id is optional. If not specified, the API commands operate on the global Store data. If specified, the API commands operate on the Store data for the specified user.

Role permissions

Users with the roles of Business User or Basic User are permitted for the below operations.

GET
Headers
Accept: application/json
Cookies: < login cookies >
Path

URL-encoded parameters, all optional:

  • key: Store key to retrieve
HTTP RESPONSE

200 OK

  • if key was not specified, a JSON list of the existing Store keys is returned
  • if key was specified, a JSON object with fields "key" and "value" will be returned with associated values of key and the data associated with the Store key, respectively.
    ["foo", "bar"]
    {"key": "foo", "value": "123"}

400 BAD REQUEST

  • The request was missing parameters.

401 UNAUTHORIZED

  • No authorized user is currently logged in.

403 FORBIDDEN

  • No user matching login_id can be found or insufficient permissions to view that user’s data.

404 NOT FOUND

  • No user matching login_id can be found.

500 SERVER ERROR

  • Could not complete the request due to an internal server error.

503 SERVICE UNAVAILABLE

  • Temporarily unable to complete the request. Please try again.
Examples

Curl

# login as API Basic User and save session cookies
curl -c cookies.txt -i -X POST -d '{"login_id":"john.doe@renesas.com","password":"12345","api_key":"ABCDEFGHIJKLMNOPabcdefghijklmnop1234567890"}' https://api-renesas-na-sandbox.mediumone.com/v2/login/ --header "Content-Type: application/json"

# get data
curl -b cookies.txt -X GET -k -H 'Accept: application/json' 'https://api-renesas-na-sandbox.mediumone.com/v2/store?key=foo'

Python

import requests
import json

headers = {'Content-Type': 'application/json', 'Accept': 'application/json'}
data = {'login_id': 'john.doe@renesas.com', 'password': '12345', 'api_key': 'ABCDEFGHIJKLmnopabcdefghijklmnop1234567890'}

# Login
session = requests.session()
response = session.post('https://api-renesas-na-sandbox.mediumone.com/v2/login', data=json.dumps(data), headers=headers)

url = 'https://api-renesas-na-sandbox.mediumone.com/v2/store'
headers = {'Accept': 'application/json'}
params = {"key":"foo"}

# GET
response = session.get(url=url, params=params, headers=headers)
POST
Headers
Content-Type: application/json
Accept: application/json
Cookies: < login cookies >
Body

A json object containing fields "key", "value", and "operation", set to the Store key to update/create, the "value" to associate, and the "operation" to use when associating. "operation" must be one of "set" or "incr", where "set" associates the value specified by "value" with the key and "incr" increments the existing value (0 if it doesn't exist) by the value specified by "value". Can be multiple items, one JSON document per line (with newline character between each JSON document). The POST body has a maximum limit of 10MB.

  • Example of single item

    {"key": "foo", "value": "123", "operation": "set"}
  • Example of multiple data events:

    CORRECT

    {"key": "foo", "value": "123", "operation": "set"}
    {"key": "bar", "value": 5, "operation": "incr"}

    INCORRECT

    {"key": "foo", "value": "123", "operation": "set"}{"key": "bar", "value": 5, "operation": "incr"}

Notes on specific key/value fields:

  • key must be a string meeting Store requirements

  • value must be a value meeting Store requirements, or a number if operation is set to "incr"
HTTP Response

200 OK

  • Store entry successfully created/updated

400 BAD REQUEST

  • The request was missing parameters.

401 UNAUTHORIZED

  • No authorized user is currently logged in.

403 FORBIDDEN

  • No user matching login_id can be found or not authorized to post data for the given user.

404 NOT FOUND

  • No user matching login_id can be found.

500 SERVER ERROR

  • Could not complete the request due to an internal server error.

503 SERVICE UNAVAILABLE

  • Temporarily unable to complete the request. Please try again.
Examples

Curl

# login as API Basic User and save session cookies
curl -c cookies.txt -i -X POST -d '{"login_id":"john.doe@renesas.com","password":"12345","api_key":"ABCDEFGHIJKLMNOPabcdefghijklmnop1234567890"}' https://api-renesas-na-sandbox.mediumone.com/v2/login/ --header "Content-Type: application/json"

# send data
curl -b cookies.txt -X POST -k -H 'Content-Type: application/json' -i https://api-renesas-na-sandbox.mediumone.com/v2/store/john.doe@renesas.com -d '{"key": "foo", "value": "123", "operation": "set"}'

Python

import requests
import json

headers = {'Content-Type': 'application/json', 'Accept': 'application/json'}
data = {'login_id': 'john.doe@renesas.com', 'password': '12345', 'api_key': 'ABCDEFGHIJKLmnopabcdefghijklmnop1234567890'}

session = requests.session()
response = session.post('https://api-renesas-na-sandbox.mediumone.comv2/login', data=json.dumps(data), headers=headers)

url = 'https://api-renesas-na-sandbox.mediumone.com/v2/store/john.doe@renesas.com'
data = {"key": "foo", "value": "123", "operation": "set"}

response = session.post(url=url, data=json.dumps(data), headers=headers)
DELETE
Headers
Content-Type: application/json
Accept: application/json
Cookies: < login cookies >
Body

A JSON object containing field "key" set to the Store key to delete. Can be multiple items, one JSON document per line (with newline character between each JSON document). The POST body has a maximum limit of 10MB.

  • Example of single item

    {"key": "foo"}
  • Example of multiple items:

    CORRECT

    {"key": "foo"}
    {"key": "bar"}

    INCORRECT

    {"key": "foo"}{"key": "bar"}

Notes on specific key/value fields:

  • key must be a string meeting Store requirements
HTTP Response

200 OK

  • Store entry successfully deleted

400 BAD REQUEST

  • The request was missing parameters.

401 UNAUTHORIZED

  • No authorized user is currently logged in.

403 FORBIDDEN

  • No user matching login_id can be found or not authorized to post data for the given user.

404 NOT FOUND

  • No user matching login_id can be found.

500 SERVER ERROR

  • Could not complete the request due to an internal server error.

503 SERVICE UNAVAILABLE

  • Temporarily unable to complete the request. Please try again.
Examples

Curl

# login as API Basic User and save session cookies
curl -c cookies.txt -i -X POST -d '{"login_id":"john.doe@renesas.com","password":"12345","api_key":"ABCDEFGHIJKLMNOPabcdefghijklmnop1234567890"}' https://api-renesas-na-sandbox.mediumone.com/v2/login/ --header "Content-Type: application/json"

# send data
curl -b cookies.txt -X DELETE -k -H 'Content-Type: application/json' -i https://api-renesas-na-sandbox.mediumone.com/v2/store/john.doe@renesas.com -d '{"key": "foo"}'

Python

import requests
import json

headers = {'Content-Type': 'application/json', 'Accept': 'application/json'}
data = {'login_id': 'john.doe@renesas.com', 'password': '12345', 'api_key': 'ABCDEFGHIJKLmnopabcdefghijklmnop1234567890'}

session = requests.session()
response = session.post('https://api-renesas-na-sandbox.mediumone.com/v2/login', data=json.dumps(data), headers=headers)

url = 'https://api-renesas-na-sandbox.mediumone.com/v2/store/john.doe@renesas.com'
data = {"key": "foo"}

response = session.delete(url=url, data=json.dumps(data), headers=headers)



Analytics

All of the analytics endpoints are GET functions and return data.

/v2/analytics/last_n_values/“login_id”

This endpoint returns a dictionary containing the most recent n values of the specified tag for the specified user. Note: If you do not specifiy the user, it will redirect you to the "last_value" endpoint listed below.

Role permissions

This operation is permitted for business users or the user with the given login id.

GET
Headers
Content-Type: application/json


URL Encoded Parameters
  • The following keys are required:
    • field : The clean name of the tag you want the data for. It must have the stream name before the tag, for example: raw.tag
  • The following keys are optional:
    • limit : limit of how many fields returned, default to 1
    • since : ISO8601 format with tzoffset
    • until : ISO8601 format with tzoffset
  • Returns a list of dictionaries, one dictionary for each of the last N values, with N as the limit field.


HTTP Response

200 OK

  • Successfully received data

400 BAD REQUEST

  • The request had a syntax or type error cause before sending it to the server

401 UNAUTHORIZED

  • No authorized user is currently logged in.

403 FORBIDDEN

  • Not authorized to post data for the given user.

415 NOT FOUND

  • Unsupported Media Type; likely missing the header

404 NOT FOUND

  • No user matching login_id can be found.

500 SERVER ERROR

  • Could not complete the request due to an internal server error.

503 SERVICE UNAVAILABLE

  • Temporarily unable to complete the request. Please try again.



Examples

Curl

#Login as a business user
curl -c cookies.txt -X POST -k -H 'Content-Type:application/json' -H 'Accept: application/json' -i 'https://api-renesas-na-sandbox.mediumone.com/v2/login' -d '{"login_id":"john_doe_business", "password":"12345", "api_key":"ABCDEFGHIJKLMNOPabcdefghijklmnop1234567890"}'

#Request up to 10 recent values of the tag test in stream raw, for user john_doe
curl -b cookies.txt -X GET -k -H 'Content-Type: application/json' -i 'https://api-renesas-na-sandbox.mediumone.com/v2/analytics/last_n_values/john_doe?field=raw.test&limit=10'

Python

import certifi
import requests
import json
import urllib

login_headers = {'Content-Type': 'application/json', 'Accept': 'application/json'}
analytics_headers = {'Content-Type': 'application/json'}
data = {'login_id': 'john.doe@mediumone.com', 'password': '12345', 'api_key': 'ABCDEFGHIJKLmnopabcdefghijklmnop1234567890'}

session = requests.session()
response = session.post('https://api-renesas-na-sandbox.mediumone.com/v2/login', data=json.dumps(data), headers=headers, verify=certifi.where())

data = {"field":"raw.test", "limit": "10"}

url = 'https://api-renesas-na-sandbox.mediumone.com/v2/analytics/last_n_values?' + urllib.urlencode(data)

response = session.get(url=url, headers=analytics_headers, verify=certifi.where())


/v2/analytics/last_value/“login_id”

This endpoint returns the last value of one or more tags for the specified user.

Role permissions

This operation is permitted for both business users and regular users, but a regular user can only access its own data.


GET
Headers
Content-Type: application/json


Body
  • Required URL Encoded parameters:
    • field : The clean tag names for each field you want the data for. They must have the stream name before the tag, for example: raw.tag or processed.tag. This parameter can repeat multiple times in the url, once for each field you want.
  • Returns: a dictionary with each field and its respective most recent value.


HTTP Response

200 OK

  • Successfully received data

400 BAD REQUEST

  • The request had a syntax or type error cause before sending it to the server

401 UNAUTHORIZED

  • No authorized user is currently logged in

403 FORBIDDEN

  • Not authorized to post data for the given user

415 NOT FOUND

  • Unsupported Media Type; likely missing the header

500 SERVER ERROR

  • Could not complete the request due to an internal server error

503 SERVICE UNAVAILABLE

  • Temporarily unable to complete the request. Please try again


Examples

Curl

#Login as correct user
curl -c cookies.txt -X POST -k -H 'Content-Type:application/json' -H 'Accept: application/json' -i 'https://api-renesas-na-sandbox.mediumone.com/v2/login' -d '{"login_id":"john_doe", "password":"abcde", "api_key":"ABCDEFGHIJKLMNOPabcdefghijklmnop1234567890"}'

curl -b cookies.txt -X GET -k -H 'Content-Type: application/json' -i 'https://api-renesas-na-sandbox.mediumone.com/v2/analytics/last_value/john_doe?field=raw.test&field=processed.test2'

Python

import certifi
import requests
import json

login_headers = {'Content-Type': 'application/json', 'Accept': 'application/json'}
analytics_headers = {'Content-Type': 'application/json'}
data = {'login_id': 'john.doe@mediumone.com', 'password': '12345', 'api_key': 'ABCDEFGHIJKLmnopabcdefghijklmnop1234567890'}

session = requests.session()
response = session.post('https://api-renesas-na-sandbox.mediumone.com/v2/login', data=json.dumps(data), headers=headers, verify=certifi.where())

url = 'https://api-renesas-na-sandbox.mediumone.com/v2/analytics/last_value/john_doe?field=raw.test'

response = session.get(url=url, headers=analytics_headers, verify=certifi.where())


/v2/analytics/last_value/

This endpoint returns the last value of each tag for all users.


Role permissions

This operation is permitted only by business users.


GET
Headers
Content-Type: application/json


Body
  • Optional URL Encoded parameters:
    • order : The optional field for the tags to be sorted by, default is event timestamp (optional)
    • direction : the direction to be sorted, ASC or DESC, default is DESC (optional)
    • limit : the number of returned records, default to 1000
  • Returns: a list of lists where the first element of the list is the userID, second is a dictionary containing all the last values. For example, [["user", {last_values}]]


HTTP Response

200 OK

  • Successfully received data

400 BAD REQUEST

  • The request had a syntax or type error cause before sending it to the server

401 UNAUTHORIZED

  • No authorized user is currently logged in

403 FORBIDDEN

  • Not authorized to post data for the given user

415 NOT FOUND

  • Unsupported Media Type; likely missing the header

500 SERVER ERROR

  • Could not complete the request due to an internal server error

503 SERVICE UNAVAILABLE

  • Temporarily unable to complete the request. Please try again


Examples

Curl

#Login as business user
curl -c cookies.txt -X POST -k -H 'Content-Type:application/json' -H 'Accept: application/json' -i 'https://api-renesas-na-sandbox.mediumone.com/v2/login' -d '{"login_id":"john_doe", "password":"abcde", "api_key":"ABCDEFGHIJKLMNOPabcdefghijklmnop1234567890"}'

curl -b cookies.txt -X GET -k -H 'Content-Type: application/json' -i 'https://api-renesas-na-sandbox.mediumone.com/v2/analytics/last_value?limit=4'

Python

import certifi
import requests
import json

login_headers = {'Content-Type': 'application/json', 'Accept': 'application/json'}
analytics_headers = {'Content-Type': 'application/json'}
data = {'login_id': 'john.doe@mediumone.com', 'password': '12345', 'api_key': 'ABCDEFGHIJKLmnopabcdefghijklmnop1234567890'}

session = requests.session()
response = session.post('https://api-renesas-na-sandbox.mediumone.comv2/login', data=json.dumps(data), headers=headers, verify=certifi.where())

url = 'https://api-renesas-na-sandbox.mediumone.com/v2/analytics/last_value/?limit=4'

response = session.get(url=url, headers=analytics_headers, verify=certifi.where())



MQTT

  • To access in Workflows: [MQTT Workflow Library](?libraries/mqtt)


Definitions

Project hash and user hash are unique ASCII string identifiers for projects and users respectively that are legal MQTT topic levels (no control characters, or '#', '+' or '/' characters). Note that as they are used in MQTT topic levels, these are case sensitive.

Important Note: client_id is part the MQTT protocol. It’s required to be a unique string (up 32 characters). Most MQTT clients generate a unique ID. If your MQTT client does not generate a unique MQTT ID (ie. using Arduino, we’ll need to supply a unique client_id). We recommend using your username: /

Device IDs are identifiers assigned by you for individual devices (or possibly applications on a device). Device IDs must be valid MQTT topic levels (valid UTF-8 strings without the characters '+', '/' or '#" or any control characters). It's highly recommended that device IDs be restricted to ASCII alphanumeric characters and the characters '-' and '_'. Failing that, standard ASCII (again excluding control characters, '+', '/' or '#") , or finally normalized unicode strings.

Groups IDs are identifiers assigned by you that may cut across multiple users. Group IDs should follow the same rule as Device IDs. For instance there may be a "microwaves" group, a "2014-microwaves" group and a "MT-2014A" group for a specific model number. A MT-2014A microwave might listen to messages sent to all three groups.

Note: There are no formal controls for groups or device IDs, which groups a device should listen to are up to you. Nothing prevents a dishwasher from listening to the microwave group, and nothing prevents device A from sending messages as device B or listening to messages for device B.



Getting hash information

project_hash can be found at the Project MQTT ID page

user_hash can be found by grabbing user info from the REST API. It will return user_hash in the user info.



MQTT authentication

Device users authenticate with a username of the form "<project_hash>/<user_hash>" with a password of the form "<api_key>/<user_password>". Device users can send events associated with their user hash, receive messages associated with their user hash, and receive group messages associated with their project hash.



MQTT Servers

The server for MQTT is mqtt2.mediumone.com. For each environment there are four port numbers: one for standard non-encrypted MQTT, one for encrypted MQTT, one for unencrypted MQTT over websockets and one for encrypted MQTT over websockets.

Port number  
Unencrypted MQTT 61619
MQTT Over SSL 61620
Unencrypted websockets 80
Websockets over SSL 443


It is recommended that if at all possible, that the encrypted ports be used. Otherwise user information like passwords can be seen in the clear text.



MQTT topics

Basic topic formatting: first level is a message delivery classification. 0 indicates a message from device to the cloud. 1 indicates a message from the cloud to a specific device. 2 indicates a message from the cloud to a group of devices.

Messages from device:

  • Event data. Ex: temperature, light level
    • 0/<project_mqtt_id>/<user_mqtt_id>/<device_id>/
    • Here <device_id> may be a zero length string.
    • The message payload will be interpreted as a JSON dictionary that will be sent as the event. If <device_id> is not a zero length string, then "device": <device_id> will be added to the event_data dictionary. If "observed_at" is not part of the dictionary, server time will be added as the "observed_at" time.

Message to device:

  • Processed events from workflows. E.g.: signal to turn on light
    • 1/<project_mqtt_id>/<user_mqtt_id>/<device_id>/event
    • No constraints are made regarding the contents of the message sent to the device other than the payload constraints of MQTT.
  • Logic, data updates. These would likely be sent as retained messages so that a device would be able to receive messages sent when not connected. Ex: new filters, ML models
    • Could be user/device specific: such as ML model
      • 1/<project_mqtt_id>/<user_mqtt_id>/<device_id>/update/<update_type>
    • For updates for all devices for a user _all can be used as a device ID.
      • 1/<project_mqtt_id>/<user_mqtt_id>/_all/update/<update_type>
    • Could be general for all users for a project or a subset of the users (all users that share a device type, device model, firmware version, etc.)
      • 2/<project_mqtt_id>/_all/<update_type>
      • 2/<project_mqtt_id>/<group_id>/<update_type>

Device should subscribe to:

  • If the project uses device IDs:
    • 1/<project_mqtt_id>/<user_mqtt_id>/<device_id>/#
    • 1/<project_mqtt_id>/<user_mqtt_id>/_all/#
  • Otherwise:
    • 1/<project_mqtt_id>/<user_mqtt_id>/#
  • 2/<project_mqtt_id>/_all/#
  • For every relevant group:
    • 2/<project_mqtt_id>/<group_id>/#

Device registration:

  • Must be connected as an API Registration User
  • Subscribe to topic:
    • 5/<project_mqtt_id>/<desired_login_id>
  • Publish
    • 4/<project_mqtt_id>/<desired_login_id>
    • Message should be an empty JSON object {}
  • 'desired_login_id' is the username of the device you want to register
  • Once the user is created, you will receive a message to your subscription of the format:
    • { "mqtt_id" : "..." , "password" : "..." }

Getting Started
User Roles & Permissions
Streams, Tags, & Data Types
Dashboard Widgets
API
Workflow Studio
Workflow Libraries
Metering
Special Characters
Third Party Integration
Mobile
API Explorer

Renesas IoT Sandbox API


API Keys

API Keys are keys associated with your account to be able to access the API.These can be viewed on the Manage API Keys page. Here, you can create, edit, and delete keys.

To create an API Key, click on the “Add New API Key” button. A description is required to save the API Key. This description is for your own use and does not affect the functionality of the API Key. Click “save” once done and the API Key should be automatically generated and set to enabled by default. These API Keys are important for any API access to Renesas IoT Sandbox.

Note: If an API Key is disabled, it can no longer access the API unless it is enabled again.



REST API

The REST API is designed for developers using the Renesas IoT Sandbox service. In order to use the REST API, the developer must be registered with Renesas IoT Sandbox.

The following API endpoints are appended to the base URL.

  • /v2/login - Endpoint to login
  • /v2/users - Endpoint to create/retrieve/update/delete Basic Users (see roles)
  • /v2/events/stream_name - Collection of endpoints to access event data, for example:
    • /v2/events/raw - Raw event data
    • /v2/events/processed - Processed event data
  • /v2/store - Endpoint to access Store data


/v2/login

POST
Role permissions

This operation is permitted for all user roles.

Headers
Content-Type: application/json
Accept: application/json
Body
  • For Login / Password authentication, the following keys are required:

    • login_id: Email address associated with user
    • password: User’s password
    • api_key: API key (Setup / Manage API Keys web page)
  • Optional keys:
    • no_cookies: Value not used. Session cookie header will not be returned; instead a token will be returned in the response body.

Calling /v2/login with a POST will log in and produce login cookies to identify the user's logged-in state. The cookies must be passed in with subsequent requests to the other API endpoints. Cookie sessions last for 24 hours. If no_cookies is specified, the returned token must be saved and from then on, token=<<RETURNED TOKEN>> is added to the URL parameters for each following request.

HTTP Response

200 OK

  • The user is successfully logged in. The response body will contain: true. However if no_cookies is specified, the return value will be the token.

400 BAD REQUEST

  • The request was missing login_id/password/key parameters.

400 UNAUTHORIZED

  • The parameters contained invalid data, or the password didn’t match

403 FORBIDDEN

  • No user matching login_id can be found or insufficient permissions to login.

500 SERVER ERROR

  • Could not complete the request due to an internal server error.

503 SERVICE UNAVAILABLE

  • Temporarily unable to complete the login request. Please try again.
Examples:

Curl

#!/bin/sh
curl -c cookie_user.txt -i -X POST -d '{"login_id":"john.doe@renesas.com","password":"12345","api_key":"ABCDEFGHIJKLmnopabcdefghijklmnop1234567890"}' https://api-renesas-na-sandbox.mediumone.com/v2/login/ --header "Content-Type: application/json"

Python

import requests
import json

headers ={'Content-Type': 'application/json', 'Accept': 'application/json'}
data = {'login_id': 'john.doe@renesas.com', 'password': '12345', 'api_key': 'ABCDEFGHIJKLmnopabcdefghijklmnop1234567890'}

session = requests.session()
response = session.post('https://api-renesas-na-sandbox.mediumone.com/v2/login', data=json.dumps(data), headers=headers)

Curl

#!/bin/sh
curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' 'https://api-renesas-na-sandbox.mediumone.com/v2/login?no_cookies' -d '{"login_id": "john.doe@renesas.com", "password": "12345", "api_key": "ABCDEFGHIJKLmnopabcdefghijklmnop1234567890"}'

Python

import requests
import json

headers ={'Content-Type': 'application/json', 'Accept': 'application/json'}
data = {'login_id': 'john.doe@renesas.com', 'password': '12345', 'api_key': 'ABCDEFGHIJKLmnopabcdefghijklmnop1234567890'}

session = requests.session()
response = session.post('https://api-renesas-na-sandbox.mediumone.com/v2/login?no_cookies', data=json.dumps(data), headers=headers)



/v2/users/login_id

The /v2/users/login_id endpoint can be used for CRUD manipulations on new and existing users, depending on the role of the user used for the log in step.

GET

Fetch the user data for login_id.

Role permissions:

This operation is permitted for Basic User and Business User roles.

Headers
Accept: application/json
Cookies: < login cookies >
HTTP Response

200 OK

  • The user information is successfully retrieved. The response body should contain a JSON structure with the user’s email address Eg: {"login_id": "johndoe@renesas.com"}

403 FORBIDDEN

  • No user matching login_id can be found or insufficient permissions to view that user’s data.

404 NOT FOUND

  • No user matching login_id can be found.

500 SERVER ERROR

  • Could not complete the request due to an internal server error.

503 SERVICE UNAVAILABLE

  • Temporarily unable to complete the login request. Please try again.
Example

Curl

#!/bin/sh
curl -b cookie_user.txt -i -X GET https://api-renesas-na-sandbox.mediumone.com/v2/users/john.doe@renesas.com --header "Content-Type: application/json"

Python

import requests
import json

headers ={'Content-Type': 'application/json', 'Accept': 'application/json'}
data = {'login_id': 'john.doe@renesas.com', 'password': '12345', 'api_key': 'ABCDEFGHIJKLmnopabcdefghijklmnop1234567890'}

session = requests.session()
response = session.post('https://api-renesas-na-sandbox.mediumone.com/v2/login', data=json.dumps(data), headers=headers)

headers = {'Accept': 'application/json'}

response = session.get('https://api-renesas-na-sandbox.mediumone.com/v2/users/john.doe@renesas.com', headers=headers)
PATCH

Calling /v2/users/login_id with a PATCH will update the data for the user. Only updating the password or disabling/enabling a basic user is supported at this time. Password updating is not supported for Facebook and Google Plus token-authenticated users.

Role permissions
  • This operation is permitted for Basic User and Business User roles.
Headers
Content-Type: application/json
Accept: application/json
Cookies: < login cookies >
Body

password: password disabled: boolean

HTTP Response

200 OK

  • The user information is successfully updated. The response body contains a JSON document with a list of the fields that were updated Eg: "password"

400 BAD REQUEST

  • The request was missing parameters or the password did not meet minimum complexity requirements

401 UNAUTHORIZED

  • There is no logged in user or the logged in user is not permitted to access the requested user.

404 NOT FOUND

  • The requested user could not be found.

500 SERVER ERROR

  • Could not complete the request due to an internal server error.

503 SERVICE UNAVAILABLE

  • Temporarily unable to complete the login request. Please try again.
Examples

Curl

#!/bin/sh
curl -b cookie_user.txt -i -X PATCH -d '{"password":"12345"}' https://api-renesas-na-sandbox.mediumone.com/v2/users/john.doe@renesas.com --header "Content-Type: application/json"
curl -b cookie_user.txt -i -X PATCH -d '{"disabled":true}' https://api-renesas-na-sandbox.mediumone.com/v2/users/john.doe@renesas.com --header "Content-Type: application/json"

Python

import requests
import json

headers = {'Content-Type': 'application/json', 'Accept': 'application/json'}
data = {'login_id': 'john.doe@renesas.com', 'password': '12345', 'api_key': 'ABCDEFGHIJKLmnopabcdefghijklmnop1234567890'}

session = requests.session()
response = session.post('https://api-renesas-na-sandbox.mediumone.com/v2/login', data=json.dumps(data), headers=headers)

headers = {'Accept': 'application/json'}

data = { 'password': '123456', 'disabled': True}         

response = session.patch('https://api-renesas-na-sandbox.mediumone.com/v2/users/john.doe@renesas.com', data=json.dumps(data), headers=headers)
POST

Calling /v2/users with a POST will create a new user. Only one user can have a particular email address. This operation is not supported for Facebook and Google Plus token-authenticated users.

Role permissions

Only users with the role of Business User and Registration User are permitted for this operation.

Headers
Content-Type: application/json
Accept: application/json
Cookies: < login cookies >
Body
  • login_id: user’s login_id
  • password: password
HTTP Response

200 OK

  • The user is successfully created. The response body contains a JSON document with the created user’s email address. Eg: {"login_id": "johndoe@aol.com"}

400 BAD REQUEST

  • The request was missing parameters or the user already exists or the password did not meet minimum complexity requirements.

401 UNAUTHORIZED

  • The HTTP basic auth is invalid, or there is no logged in user or the logged in user is not permitted to access the requested user. 403 FORBIDDEN
  • The user could not be created (eg. the user already exists).

429 TOO MANY REQUESTS

  • The user has sent too many requests in a given amount of time.

500 SERVER ERROR

  • Could not complete the request due to an internal server error.

503 SERVICE UNAVAILABLE

  • Temporarily unable to complete the login request. Please try again.
Examples

Curl

#!/bin/sh
curl -b cookie_user.txt -i -X POST -d '{"login_id":"joe.doe@renesas.com","password":"123456"}' https://api-renesas-na-sandbox.mediumone.com/v2/users/ --header "Content-Type: application/json"

Python

import requests
import json

headers ={'Content-Type': 'application/json', 'Accept': 'application/json'}
data = {'login_id': 'apibusinessuser@renesas.com', 'password': '12345', 'api_key': 'ABCDEFGHIJKLmnopabcdefghijklmnop1234567890'}

session = requests.session()
response = session.post('https://api-renesas-na-sandbox.mediumone.com/v2/login', data=json.dumps(data), headers=headers)

headers = {'Content-Type': 'application/json', 'Accept': 'application/json'}

data = { 'login_id': 'john.doe@renesas.com',
         'password': '123456'}

response = session.post('https://api-renesas-na-sandbox.mediumone.com/v2/users/', data=json.dumps(data), headers=headers)
DELETE

Calling /v2/user/login_id with a DELETE will delete the user identified by login_id. As every event belongs to a user, once a user is deleted, all associated event data will also be deleted.

Role permissions

Only users with the role of Business User are permitted to do this operation.

Headers
Accept: application/json
Cookies: < login cookies >
HTTP Response

204 OK

  • The user is successfully deleted.

403 UNAUTHORIZED

  • There is no logged in user or the logged in user is not permitted to access the requested user.

404 NOT FOUND

  • The user for login_id does not exist.

500 SERVER ERROR

  • Could not complete the request due to an internal server error.

503 SERVICE UNAVAILABLE

  • Temporarily unable to complete the login request. Please try again.
Examples

Curl

#!/bin/sh
curl -b cookie_user.txt -i -X DELETE https://api-renesas-na-sandbox.mediumone.com/v2/users/john.doe@renesas.com --header "Content-Type: application/json"

Python

import requests
import json

headers ={'Content-Type': 'application/json', 'Accept': 'application/json'}
data = {'login_id': 'apibusinessuser@renesas.com', 'password': '12345', 'api_key': 'ABCDEFGHIJKLmnopabcdefghijklmnop1234567890'}

session = requests.session()
response = session.post('https://api-renesas-na-sandbox.mediumone.com/v2/login', data=json.dumps(data), headers=headers)

headers = {'Accept': 'application/json'}

response = session.delete('https://api-renesas-na-sandbox.mediumone.com/v2/users/john.doe@renesas.com', headers=headers)



/v2/events/stream_name

The /v2/events/stream_name is a collection of endpoints that map to specific streams, as defined in the Renesas IoT Sandbox business configuration (Config → Data Streams page).

/v2/events/stream_name/login_id

The /v2/events/stream_name endpoint is used for creation and retrieval of event data.

login_id is optional if an API Basic User is logged in, as that user can only post data on his own behalf. It is required if an API Business User is logged in and transferring event data on behalf of the API Basic User. Each posted event belongs to the API Basic User specified or logged in.

Role permissions

Users with the roles of Business User or Basic User are permitted for the below operations.

A user with the Basic User role can only see his/her own data. login_id is optional when Basic User role, and, if unspecified, defaults to all events the current session user is allowed to see.

GET
Headers
Accept: application/json
Cookies: < login cookies >
Path

URL-encoded parameters, all optional:

  • since: ISO8601 format timestamp, including timezone, fetches all data after specified time
  • until: ISO8601 format timestamp, including timezone, fetches all data before specified time
  • limit: limits the number of results, must be a whole number up to a maximum of 10,000 (default). For retrieving more than this number of data events, since and until parameters can be used to select a specific time span
  • sort_by: Valid values for "sort_by" are "observed_at", "received_at" and "internal". "internal" is roughly equivalent to "received_at" but sorts by event_ids, so events received at the same millisecond may not sort in the same order as "received_at". The advantage of the internal sort order is that the queries are faster, especially when a user isn't specified.
  • sort_direction: Valid values for "sort_direction" are "asc" and "desc" for ascending and descending. If not specified "sort_direction" is considered to be "asc". Specifying "sort_direction" without "sort_by" is an error.
  • include: Fetches data of the specified tag
  • exclude: Fetches all data, omitting the specified tag
HTTP RESPONSE

200 OK

  • events successfully read. The response body should contain one JSON document per line, with no specific ordering:
    {"observed_at": "< ISO_observed_at >", "event_data": {event_data}, "stream":"raw", "login_id": "< some_id >"}
    {"observed_at": < ISO_observed_at >, "event_data": {event_data}, "stream":"raw", "login_id": "< some_id >"}

400 BAD REQUEST

  • The request was missing parameters.

401 UNAUTHORIZED

  • No authorized user is currently logged in.

403 FORBIDDEN

  • No user matching login_id can be found or insufficient permissions to view that user’s data.

404 NOT FOUND

  • No user matching login_id can be found.

500 SERVER ERROR

  • Could not complete the request due to an internal server error.

503 SERVICE UNAVAILABLE

  • Temporarily unable to complete the request. Please try again.
Examples

Curl

# login as API Basic User and save session cookies
curl -c cookies.txt -X POST -k -H 'Content-Type: application/json' -H 'Accept: application/json' -i 'https://api-renesas-na-sandbox.mediumone.com/v2/login' -d '{"login_id": "john.doe@renesas.com", "password": "123456", "api_key": "Abcdefghijklmnopqrstuvwxyz0123456789"}'

# get data
curl -b cookies.txt -X GET -k -H 'Accept: application/json' 'https://api-renesas-na-sandbox.mediumone.com/v2/events/raw/john.doe@renesas.com?since=2015-01-10T00%3A00%3A00.000-0800&limit=100&include=$.event_data.tagname'

Python

import requests
import json

headers = {'Content-Type': 'application/json', 'Accept': 'application/json'}
data = {'login_id': 'john.doe@renesas.com', 'password': '12345', 'api_key': 'ABCDEFGHIJKLmnopabcdefghijklmnop1234567890'}

# Login
session = requests.session()
response = session.post('https://api-renesas-na-sandbox.mediumone.com/v2/login', data=json.dumps(data), headers=headers)

url = 'https://api-renesas-na-sandbox.mediumone.com/v2/events/raw/john.doe@renesas.com'
headers = {'Accept': 'application/json'}
params = {"since":"2015-01-10T00:00:00.000-0800", "until":"2015-01-17T00:00:00.000-0800", "limit":100, "include":"$.event_data.tagname"}

# GET
response = session.get(url=url, params=params, headers=headers)
POST

login_id must be specified, events posted will be associated with the specified user.

Headers
Content-Type: application/json
Accept: application/json
Cookies: < login cookies >
Body

A json object of the data to be written (event_data is a required field). If observed_at is missing, the received_at time will be used. Can be multiple items, one JSON document per line (with newline character between each JSON document). The POST body has a maximum limit of 10MB.

  • Example of single data event

    {"observed_at": "2014-06-11T02:11:25.076001", "event_data": {"sensor1": 37.3, "sensor2": 183}}
  • Example of multiple data events:

    CORRECT

    {'observed_at': '2014-06-11T02:11:26.157759', 'event_data': {'sensor1': 38.6}}
    {'observed_at': '2014-06-11T02:12:27.458693', 'event_data': {'sensor1': 39.4}}

    INCORRECT

    {'observed_at': '2014-06-11T02:11:26.157759', 'event_data': {'sensor1': 38.6}}{'observed_at': '2014-06-11T02:12:27.458693', 'event_data': {'sensor1': 39.4}}

Notes on specific key/value fields:

  • observed_at must be an ISO8601-formatted text string, for example "2014-07-25T12:12:56.2345-08:00"

  • If observed_at is missing, the received_at time will be used.

  • add_client_ip can be added and will put the client IP address into the pushed event's event_data as the tag ip_address. It is a boolean placed at the same level as the "event_data" dictionary. (ex: "add_client_ip": true)

  • Timezone offset must be specified to avoid ambiguity.

  • event_data can be a multi-level json document for the purposes of storage and retrieval.

Values can contain the following JSON data types: text (string) numbers without decimal point (interpreted as integer values) numbers with decimal point (interpreted as floating point values) dates (ISO8601 string format) Note: Other data types are not supported at this time

HTTP Response

200 OK

  • eventlog is successfully created. Returns number of events created.

400 BAD REQUEST

  • The request was missing parameters.

401 UNAUTHORIZED

  • No authorized user is currently logged in.

403 FORBIDDEN

  • No user matching login_id can be found or not authorized to post data for the given user.

404 NOT FOUND

  • No user matching login_id can be found.

500 SERVER ERROR

  • Could not complete the request due to an internal server error.

503 SERVICE UNAVAILABLE

  • Temporarily unable to complete the request. Please try again.
Examples

Curl

# login as API Basic User and save session cookies
curl -c cookies.txt -i -X POST -d '{"login_id":"john.doe@renesas.com","password":"12345","api_key":"ABCDEFGHIJKLMNOPabcdefghijklmnop1234567890"}' https://api-renesas-na-sandbox.mediumone.com/v2/login/ --header "Content-Type: application/json"

# send data
curl -b cookies.txt -X POST -k -H 'Content-Type: application/json' -i https://api-renesas-na-sandbox.mediumone.com/v2/events/raw/john.doe@renesas.com -d '{"observed_at": "2015-01-10T00:00:00.000-0800", "event_data": {"sensor1" : 38.6}}'

Python

import requests
import json

headers = {'Content-Type': 'application/json', 'Accept': 'application/json'}
data = {'login_id': 'john.doe@renesas.com', 'password': '12345', 'api_key': 'ABCDEFGHIJKLmnopabcdefghijklmnop1234567890'}

session = requests.session()
response = session.post('https://api-renesas-na-sandbox.mediumone.comv2/login', data=json.dumps(data), headers=headers)

url = 'https://api-renesas-na-sandbox.mediumone.com/v2/events/raw/john.doe@renesas.com'
data = {'observed_at': '2015-01-10T00:00:00.000-0800', 'event_data': {'sensor1' : 38.6}}

response = session.post(url=url, data=json.dumps(data), headers=headers)



/v2/store/login_id

The /v2/store/login_id endpoint is used for creation, retrieval, and update of Store data.

login_id is optional. If not specified, the API commands operate on the global Store data. If specified, the API commands operate on the Store data for the specified user.

Role permissions

Users with the roles of Business User or Basic User are permitted for the below operations.

GET
Headers
Accept: application/json
Cookies: < login cookies >
Path

URL-encoded parameters, all optional:

  • key: Store key to retrieve
HTTP RESPONSE

200 OK

  • if key was not specified, a JSON list of the existing Store keys is returned
  • if key was specified, a JSON object with fields "key" and "value" will be returned with associated values of key and the data associated with the Store key, respectively.
    ["foo", "bar"]
    {"key": "foo", "value": "123"}

400 BAD REQUEST

  • The request was missing parameters.

401 UNAUTHORIZED

  • No authorized user is currently logged in.

403 FORBIDDEN

  • No user matching login_id can be found or insufficient permissions to view that user’s data.

404 NOT FOUND

  • No user matching login_id can be found.

500 SERVER ERROR

  • Could not complete the request due to an internal server error.

503 SERVICE UNAVAILABLE

  • Temporarily unable to complete the request. Please try again.
Examples

Curl

# login as API Basic User and save session cookies
curl -c cookies.txt -i -X POST -d '{"login_id":"john.doe@renesas.com","password":"12345","api_key":"ABCDEFGHIJKLMNOPabcdefghijklmnop1234567890"}' https://api-renesas-na-sandbox.mediumone.com/v2/login/ --header "Content-Type: application/json"

# get data
curl -b cookies.txt -X GET -k -H 'Accept: application/json' 'https://api-renesas-na-sandbox.mediumone.com/v2/store?key=foo'

Python

import requests
import json

headers = {'Content-Type': 'application/json', 'Accept': 'application/json'}
data = {'login_id': 'john.doe@renesas.com', 'password': '12345', 'api_key': 'ABCDEFGHIJKLmnopabcdefghijklmnop1234567890'}

# Login
session = requests.session()
response = session.post('https://api-renesas-na-sandbox.mediumone.com/v2/login', data=json.dumps(data), headers=headers)

url = 'https://api-renesas-na-sandbox.mediumone.com/v2/store'
headers = {'Accept': 'application/json'}
params = {"key":"foo"}

# GET
response = session.get(url=url, params=params, headers=headers)
POST
Headers
Content-Type: application/json
Accept: application/json
Cookies: < login cookies >
Body

A json object containing fields "key", "value", and "operation", set to the Store key to update/create, the "value" to associate, and the "operation" to use when associating. "operation" must be one of "set" or "incr", where "set" associates the value specified by "value" with the key and "incr" increments the existing value (0 if it doesn't exist) by the value specified by "value". Can be multiple items, one JSON document per line (with newline character between each JSON document). The POST body has a maximum limit of 10MB.

  • Example of single item

    {"key": "foo", "value": "123", "operation": "set"}
  • Example of multiple data events:

    CORRECT

    {"key": "foo", "value": "123", "operation": "set"}
    {"key": "bar", "value": 5, "operation": "incr"}

    INCORRECT

    {"key": "foo", "value": "123", "operation": "set"}{"key": "bar", "value": 5, "operation": "incr"}

Notes on specific key/value fields:

  • key must be a string meeting Store requirements

  • value must be a value meeting Store requirements, or a number if operation is set to "incr"
HTTP Response

200 OK

  • Store entry successfully created/updated

400 BAD REQUEST

  • The request was missing parameters.

401 UNAUTHORIZED

  • No authorized user is currently logged in.

403 FORBIDDEN

  • No user matching login_id can be found or not authorized to post data for the given user.

404 NOT FOUND

  • No user matching login_id can be found.

500 SERVER ERROR

  • Could not complete the request due to an internal server error.

503 SERVICE UNAVAILABLE

  • Temporarily unable to complete the request. Please try again.
Examples

Curl

# login as API Basic User and save session cookies
curl -c cookies.txt -i -X POST -d '{"login_id":"john.doe@renesas.com","password":"12345","api_key":"ABCDEFGHIJKLMNOPabcdefghijklmnop1234567890"}' https://api-renesas-na-sandbox.mediumone.com/v2/login/ --header "Content-Type: application/json"

# send data
curl -b cookies.txt -X POST -k -H 'Content-Type: application/json' -i https://api-renesas-na-sandbox.mediumone.com/v2/store/john.doe@renesas.com -d '{"key": "foo", "value": "123", "operation": "set"}'

Python

import requests
import json

headers = {'Content-Type': 'application/json', 'Accept': 'application/json'}
data = {'login_id': 'john.doe@renesas.com', 'password': '12345', 'api_key': 'ABCDEFGHIJKLmnopabcdefghijklmnop1234567890'}

session = requests.session()
response = session.post('https://api-renesas-na-sandbox.mediumone.comv2/login', data=json.dumps(data), headers=headers)

url = 'https://api-renesas-na-sandbox.mediumone.com/v2/store/john.doe@renesas.com'
data = {"key": "foo", "value": "123", "operation": "set"}

response = session.post(url=url, data=json.dumps(data), headers=headers)
DELETE
Headers
Content-Type: application/json
Accept: application/json
Cookies: < login cookies >
Body

A JSON object containing field "key" set to the Store key to delete. Can be multiple items, one JSON document per line (with newline character between each JSON document). The POST body has a maximum limit of 10MB.

  • Example of single item

    {"key": "foo"}
  • Example of multiple items:

    CORRECT

    {"key": "foo"}
    {"key": "bar"}

    INCORRECT

    {"key": "foo"}{"key": "bar"}

Notes on specific key/value fields:

  • key must be a string meeting Store requirements
HTTP Response

200 OK

  • Store entry successfully deleted

400 BAD REQUEST

  • The request was missing parameters.

401 UNAUTHORIZED

  • No authorized user is currently logged in.

403 FORBIDDEN

  • No user matching login_id can be found or not authorized to post data for the given user.

404 NOT FOUND

  • No user matching login_id can be found.

500 SERVER ERROR

  • Could not complete the request due to an internal server error.

503 SERVICE UNAVAILABLE

  • Temporarily unable to complete the request. Please try again.
Examples

Curl

# login as API Basic User and save session cookies
curl -c cookies.txt -i -X POST -d '{"login_id":"john.doe@renesas.com","password":"12345","api_key":"ABCDEFGHIJKLMNOPabcdefghijklmnop1234567890"}' https://api-renesas-na-sandbox.mediumone.com/v2/login/ --header "Content-Type: application/json"

# send data
curl -b cookies.txt -X DELETE -k -H 'Content-Type: application/json' -i https://api-renesas-na-sandbox.mediumone.com/v2/store/john.doe@renesas.com -d '{"key": "foo"}'

Python

import requests
import json

headers = {'Content-Type': 'application/json', 'Accept': 'application/json'}
data = {'login_id': 'john.doe@renesas.com', 'password': '12345', 'api_key': 'ABCDEFGHIJKLmnopabcdefghijklmnop1234567890'}

session = requests.session()
response = session.post('https://api-renesas-na-sandbox.mediumone.com/v2/login', data=json.dumps(data), headers=headers)

url = 'https://api-renesas-na-sandbox.mediumone.com/v2/store/john.doe@renesas.com'
data = {"key": "foo"}

response = session.delete(url=url, data=json.dumps(data), headers=headers)



Analytics

All of the analytics endpoints are GET functions and return data.

/v2/analytics/last_n_values/“login_id”

This endpoint returns a dictionary containing the most recent n values of the specified tag for the specified user. Note: If you do not specifiy the user, it will redirect you to the "last_value" endpoint listed below.

Role permissions

This operation is permitted for business users or the user with the given login id.

GET
Headers
Content-Type: application/json


URL Encoded Parameters
  • The following keys are required:
    • field : The clean name of the tag you want the data for. It must have the stream name before the tag, for example: raw.tag
  • The following keys are optional:
    • limit : limit of how many fields returned, default to 1
    • since : ISO8601 format with tzoffset
    • until : ISO8601 format with tzoffset
  • Returns a list of dictionaries, one dictionary for each of the last N values, with N as the limit field.


HTTP Response

200 OK

  • Successfully received data

400 BAD REQUEST

  • The request had a syntax or type error cause before sending it to the server

401 UNAUTHORIZED

  • No authorized user is currently logged in.

403 FORBIDDEN

  • Not authorized to post data for the given user.

415 NOT FOUND

  • Unsupported Media Type; likely missing the header

404 NOT FOUND

  • No user matching login_id can be found.

500 SERVER ERROR

  • Could not complete the request due to an internal server error.

503 SERVICE UNAVAILABLE

  • Temporarily unable to complete the request. Please try again.



Examples

Curl

#Login as a business user
curl -c cookies.txt -X POST -k -H 'Content-Type:application/json' -H 'Accept: application/json' -i 'https://api-renesas-na-sandbox.mediumone.com/v2/login' -d '{"login_id":"john_doe_business", "password":"12345", "api_key":"ABCDEFGHIJKLMNOPabcdefghijklmnop1234567890"}'

#Request up to 10 recent values of the tag test in stream raw, for user john_doe
curl -b cookies.txt -X GET -k -H 'Content-Type: application/json' -i 'https://api-renesas-na-sandbox.mediumone.com/v2/analytics/last_n_values/john_doe?field=raw.test&limit=10'

Python

import certifi
import requests
import json
import urllib

login_headers = {'Content-Type': 'application/json', 'Accept': 'application/json'}
analytics_headers = {'Content-Type': 'application/json'}
data = {'login_id': 'john.doe@mediumone.com', 'password': '12345', 'api_key': 'ABCDEFGHIJKLmnopabcdefghijklmnop1234567890'}

session = requests.session()
response = session.post('https://api-renesas-na-sandbox.mediumone.com/v2/login', data=json.dumps(data), headers=headers, verify=certifi.where())

data = {"field":"raw.test", "limit": "10"}

url = 'https://api-renesas-na-sandbox.mediumone.com/v2/analytics/last_n_values?' + urllib.urlencode(data)

response = session.get(url=url, headers=analytics_headers, verify=certifi.where())


/v2/analytics/last_value/“login_id”

This endpoint returns the last value of one or more tags for the specified user.

Role permissions

This operation is permitted for both business users and regular users, but a regular user can only access its own data.


GET
Headers
Content-Type: application/json


Body
  • Required URL Encoded parameters:
    • field : The clean tag names for each field you want the data for. They must have the stream name before the tag, for example: raw.tag or processed.tag. This parameter can repeat multiple times in the url, once for each field you want.
  • Returns: a dictionary with each field and its respective most recent value.


HTTP Response

200 OK

  • Successfully received data

400 BAD REQUEST

  • The request had a syntax or type error cause before sending it to the server

401 UNAUTHORIZED

  • No authorized user is currently logged in

403 FORBIDDEN

  • Not authorized to post data for the given user

415 NOT FOUND

  • Unsupported Media Type; likely missing the header

500 SERVER ERROR

  • Could not complete the request due to an internal server error

503 SERVICE UNAVAILABLE

  • Temporarily unable to complete the request. Please try again


Examples

Curl

#Login as correct user
curl -c cookies.txt -X POST -k -H 'Content-Type:application/json' -H 'Accept: application/json' -i 'https://api-renesas-na-sandbox.mediumone.com/v2/login' -d '{"login_id":"john_doe", "password":"abcde", "api_key":"ABCDEFGHIJKLMNOPabcdefghijklmnop1234567890"}'

curl -b cookies.txt -X GET -k -H 'Content-Type: application/json' -i 'https://api-renesas-na-sandbox.mediumone.com/v2/analytics/last_value/john_doe?field=raw.test&field=processed.test2'

Python

import certifi
import requests
import json

login_headers = {'Content-Type': 'application/json', 'Accept': 'application/json'}
analytics_headers = {'Content-Type': 'application/json'}
data = {'login_id': 'john.doe@mediumone.com', 'password': '12345', 'api_key': 'ABCDEFGHIJKLmnopabcdefghijklmnop1234567890'}

session = requests.session()
response = session.post('https://api-renesas-na-sandbox.mediumone.com/v2/login', data=json.dumps(data), headers=headers, verify=certifi.where())

url = 'https://api-renesas-na-sandbox.mediumone.com/v2/analytics/last_value/john_doe?field=raw.test'

response = session.get(url=url, headers=analytics_headers, verify=certifi.where())


/v2/analytics/last_value/

This endpoint returns the last value of each tag for all users.


Role permissions

This operation is permitted only by business users.


GET
Headers
Content-Type: application/json


Body
  • Optional URL Encoded parameters:
    • order : The optional field for the tags to be sorted by, default is event timestamp (optional)
    • direction : the direction to be sorted, ASC or DESC, default is DESC (optional)
    • limit : the number of returned records, default to 1000
  • Returns: a list of lists where the first element of the list is the userID, second is a dictionary containing all the last values. For example, [["user", {last_values}]]


HTTP Response

200 OK

  • Successfully received data

400 BAD REQUEST

  • The request had a syntax or type error cause before sending it to the server

401 UNAUTHORIZED

  • No authorized user is currently logged in

403 FORBIDDEN

  • Not authorized to post data for the given user

415 NOT FOUND

  • Unsupported Media Type; likely missing the header

500 SERVER ERROR

  • Could not complete the request due to an internal server error

503 SERVICE UNAVAILABLE

  • Temporarily unable to complete the request. Please try again


Examples

Curl

#Login as business user
curl -c cookies.txt -X POST -k -H 'Content-Type:application/json' -H 'Accept: application/json' -i 'https://api-renesas-na-sandbox.mediumone.com/v2/login' -d '{"login_id":"john_doe", "password":"abcde", "api_key":"ABCDEFGHIJKLMNOPabcdefghijklmnop1234567890"}'

curl -b cookies.txt -X GET -k -H 'Content-Type: application/json' -i 'https://api-renesas-na-sandbox.mediumone.com/v2/analytics/last_value?limit=4'

Python

import certifi
import requests
import json

login_headers = {'Content-Type': 'application/json', 'Accept': 'application/json'}
analytics_headers = {'Content-Type': 'application/json'}
data = {'login_id': 'john.doe@mediumone.com', 'password': '12345', 'api_key': 'ABCDEFGHIJKLmnopabcdefghijklmnop1234567890'}

session = requests.session()
response = session.post('https://api-renesas-na-sandbox.mediumone.comv2/login', data=json.dumps(data), headers=headers, verify=certifi.where())

url = 'https://api-renesas-na-sandbox.mediumone.com/v2/analytics/last_value/?limit=4'

response = session.get(url=url, headers=analytics_headers, verify=certifi.where())



MQTT

  • To access in Workflows: [MQTT Workflow Library](?libraries/mqtt)


Definitions

Project hash and user hash are unique ASCII string identifiers for projects and users respectively that are legal MQTT topic levels (no control characters, or '#', '+' or '/' characters). Note that as they are used in MQTT topic levels, these are case sensitive.

Important Note: client_id is part the MQTT protocol. It’s required to be a unique string (up 32 characters). Most MQTT clients generate a unique ID. If your MQTT client does not generate a unique MQTT ID (ie. using Arduino, we’ll need to supply a unique client_id). We recommend using your username: /

Device IDs are identifiers assigned by you for individual devices (or possibly applications on a device). Device IDs must be valid MQTT topic levels (valid UTF-8 strings without the characters '+', '/' or '#" or any control characters). It's highly recommended that device IDs be restricted to ASCII alphanumeric characters and the characters '-' and '_'. Failing that, standard ASCII (again excluding control characters, '+', '/' or '#") , or finally normalized unicode strings.

Groups IDs are identifiers assigned by you that may cut across multiple users. Group IDs should follow the same rule as Device IDs. For instance there may be a "microwaves" group, a "2014-microwaves" group and a "MT-2014A" group for a specific model number. A MT-2014A microwave might listen to messages sent to all three groups.

Note: There are no formal controls for groups or device IDs, which groups a device should listen to are up to you. Nothing prevents a dishwasher from listening to the microwave group, and nothing prevents device A from sending messages as device B or listening to messages for device B.



Getting hash information

project_hash can be found at the Project MQTT ID page

user_hash can be found by grabbing user info from the REST API. It will return user_hash in the user info.



MQTT authentication

Device users authenticate with a username of the form "<project_hash>/<user_hash>" with a password of the form "<api_key>/<user_password>". Device users can send events associated with their user hash, receive messages associated with their user hash, and receive group messages associated with their project hash.



MQTT Servers

The server for MQTT is mqtt2.mediumone.com. For each environment there are four port numbers: one for standard non-encrypted MQTT, one for encrypted MQTT, one for unencrypted MQTT over websockets and one for encrypted MQTT over websockets.

Port number  
Unencrypted MQTT 61619
MQTT Over SSL 61620
Unencrypted websockets 80
Websockets over SSL 443


It is recommended that if at all possible, that the encrypted ports be used. Otherwise user information like passwords can be seen in the clear text.



MQTT topics

Basic topic formatting: first level is a message delivery classification. 0 indicates a message from device to the cloud. 1 indicates a message from the cloud to a specific device. 2 indicates a message from the cloud to a group of devices.

Messages from device:

  • Event data. Ex: temperature, light level
    • 0/<project_mqtt_id>/<user_mqtt_id>/<device_id>/
    • Here <device_id> may be a zero length string.
    • The message payload will be interpreted as a JSON dictionary that will be sent as the event. If <device_id> is not a zero length string, then "device": <device_id> will be added to the event_data dictionary. If "observed_at" is not part of the dictionary, server time will be added as the "observed_at" time.

Message to device:

  • Processed events from workflows. E.g.: signal to turn on light
    • 1/<project_mqtt_id>/<user_mqtt_id>/<device_id>/event
    • No constraints are made regarding the contents of the message sent to the device other than the payload constraints of MQTT.
  • Logic, data updates. These would likely be sent as retained messages so that a device would be able to receive messages sent when not connected. Ex: new filters, ML models
    • Could be user/device specific: such as ML model
      • 1/<project_mqtt_id>/<user_mqtt_id>/<device_id>/update/<update_type>
    • For updates for all devices for a user _all can be used as a device ID.
      • 1/<project_mqtt_id>/<user_mqtt_id>/_all/update/<update_type>
    • Could be general for all users for a project or a subset of the users (all users that share a device type, device model, firmware version, etc.)
      • 2/<project_mqtt_id>/_all/<update_type>
      • 2/<project_mqtt_id>/<group_id>/<update_type>

Device should subscribe to:

  • If the project uses device IDs:
    • 1/<project_mqtt_id>/<user_mqtt_id>/<device_id>/#
    • 1/<project_mqtt_id>/<user_mqtt_id>/_all/#
  • Otherwise:
    • 1/<project_mqtt_id>/<user_mqtt_id>/#
  • 2/<project_mqtt_id>/_all/#
  • For every relevant group:
    • 2/<project_mqtt_id>/<group_id>/#

Device registration:

  • Must be connected as an API Registration User
  • Subscribe to topic:
    • 5/<project_mqtt_id>/<desired_login_id>
  • Publish
    • 4/<project_mqtt_id>/<desired_login_id>
    • Message should be an empty JSON object {}
  • 'desired_login_id' is the username of the device you want to register
  • Once the user is created, you will receive a message to your subscription of the format:
    • { "mqtt_id" : "..." , "password" : "..." }