NovaStar Reference / Data Formats / Stevens Connect

Overview

The Stevens Connect web services provide access to data from Stevens Connect sensors and DCUs, in JSON format.

Stevens Connect website
At the time of this writing, no formal documentation exists for the Stevens API

Data Structure

Based on interactions with the API, it appears that the data structure looks like the following:
Data->Projects->Stations->Sensors->Channels

Steps to retrieve data from the Stevens API

  1. Make a request to the log in to the authenticate URL with your email and password
    Auth Request
    curl -d "email=youremail@email.com&password=thisiswherethepasswordgoes" -X POST http://api.stevens-connect.com/authenticate
  2. A Javascript Web Token is provided on successful login. All future requests will return a new token in the response X-Token header. Each token will expire 60 seconds after use.
    Auth Response
    {"errors":false,"data":{"token":"eyJ0eXAiOiJ.......blah","user":{"id":1,"company_id":1,"name":"Mike", "email":"youremail@email.com","phone":"5555555555","sms":"+1 555 555 5555","alarm_email":1,"alarm_sms":1,"alarm_voice":0, "member_level_id":2,"status":1}}}

  3. Make a request for the configuration packet, which will contain an object describing all projects, stations, sensors, channels, plus a couple of data dictionaries for Units, etc.
    Configuration Request
    curl -H 'Authorization: bearer eyJ0eXAiOiJ.......blah' http://api.stevens-connect.com/config-packet

  4. Receive the configuration packet. This can be parsed to extract useful information to be used in data requests
    Configuration Response
    { "config_packet": { "projects": [ { "id": 1, "company_id": 1, "name": "Project Name", "public_key": "...", "status": 1, "stations": [ { "id": 1, "project_id": 1, "sui": "....", "name": "Bodie Hills", "sensors": [ { "id": 1, "station_id": 1, "name": "Sensor name", "status": 1, "reporting": 3600, "logging": 3600, "channels": [ { "id": 1, "sensor_id": 1, "name": "Air Temperature Minimum (degF)", "unit_id": 1 }, ] ], "units": [ { "id": 58, "name": "Acre Feet", "unit": "AcFt", "company_id": 0 }, ], } }

  5. Once the configuration packet has been retrieved, you can parse the JSON (Using, for example: jq library) and gather a list of channel IDs that you are interested in. In order to make a data request, you will also need to specify the following parameters:
    Data Request Parameters

    1. 'channel_ids' (required): one or more channel ids to get readings for. If more than one, seperate with commas. (ie 1,2,3)
    2. 'range_type' (required): either relative or absolute
    3. 'start_date' (required if range_type is absolute): start date of query. (ie 2018-04-17 13:00:00)
    4. 'end_date' (required if range_type is absolute): end date of query. (ie 2018-04-18 13:00:00)
    5. 'minutes' (required if range_type is relative): number of minutes to query (ie 1440 for 24 hours)
    6. 'user_time' (required): local time of query (ie 2018-04-18 13:00:00)

  6. Once a list of Channel IDs has been retrieved, a data request can be made.
    Data Request
    curl -H 'Authorization: bearer eyJ0eXAiOiJKV1Q.......blah' http://api.stevens-connect.com/project/45/readings?channel_ids=8043&range_type=relative&start_date=null&end_date=null&minutes=1440&transformation=none&user_time=2018-04-18%2013:00:00

  7. The actual data readings response will contain entries for the channels requested based on the query parameters (see #5)
    Data Response
    {"errors":false,"data":{"readings":{"8043":[{"channel_id":8043,"reading":14.06,"timestamp":"2018-04-17 13:00:00"},{"channel_id":8043,"reading":13.97,"timestamp":"2018-04-17 14:00:00"}....}}}

Stevens <-> NovaStar Data Correlation

It is helpful to follow normal NovaStar naming conventions, while clearly indicating Stevens Station and Sensor Identifiers.

  1. Stevens station id may be correlated to NovaStar Station Remote Tag
  2. Stevens channel id may be correlated to NovaStar Point Remote ID
  3. The nspollstevensapi counts on a correlation between the channel IDs and NovaStar Point Remote ID.
  4. The script will file data for any NovaStar Points that have Point Remote IDs matching the Stevens Connect Channel IDs.

Limitations

  1. Data is received in the time zone that the transmitter lives in. NovaStar will file it as-is.
  2. sendrpt offers a time offset paramter that could be utilized to shift data into appropriate time zones, but this will be on client-by-client basis
    -s #[smhd] Add time offset to report time (Default: 0)

Importing Data into NovaStar

Stevens data can be imported into NovaStar using the nspollstevensapi program.

Exporting Data from NovaStar

Exporting data from NovaStar into Stevens is not implemented