VREEDA Api Basics

Before you start checking APIs, here some basics to get a better understanding.

1. Device types and device features

VREEDA IoT ecosystem uses a type system to define semantics and data formats related to devices. This is a feature based type system. A feature defines some functionality that is implemented on the device firmware. A device feature is directly related to some part of the message payload in this API.

For example a device feature defines the ability to switch on or off a device. This results in some on/off state in the message payload.

A client can retrieve the list of device features to check which features are implemented on the firmware of a device and thus derive how to parse messages and how to control the device.

Device features are grouped to device types to classify devices that have the same set of features.

For example RGB-Lamp and RGBCWW-Lamp are device types with a different feature set. RGB-Lamps offer the feature to control color by RGB values only and RGBCWW-Lamps offer additionally the feature to control a white light by color temperature.

See the following sections for more details about the VREEDA IoT ecosystem device type and device feature system.

1.1 List of device features

All features are versioned. To keep this document brief only latest version of feature is listed, and actual version is replaced by *.

Light related features use the concepts of programs. This means that the evaluation of state values depends on which program is currently active.

For example in program mode color the r, g, b statue values are used to set the color of the light, while in mode hsv the h, s, v state values are used.

1.1.1 Detailed description of custom program feature (deviceFeature.vreeda.lightSceneCustom)

EBNF of the custom program pattern;

<program> ::= <comment> "|" <instruction> | { "|" <instruction> } 
<instruction> ::= <scheduled_power_off> | <channel program> 
<scheduled_power_off> ::= "x:" <relative time in seconds> 
<channel program> ::= <channel> ":" <transitions> 
<channel> ::= "r" | "g" | "b" | "c" | "w" 
<transitions> ::= <transition> { ";" <transition> }; 
<transition> ::= <duration> "," <from> "," <to> [ "," <count> [ "," <next> ] ] 
<duration> ::= <floating number> 
<from> ::= <floating number between zero and one> 
<to> ::= <floating number between zero and one> 
<count> ::= <integer> 
<next> ::= <integer> 

All transitions (every channel) run simultaneously (in parallel).

comment - any text without | character. Used for client’s purpose and device ignores it

count - number, how many times a transition can be used since when it will be skipped. Use -1 for “forever” (default).

next - index of the next transition to execute (zero based). Default is index of the following one or zero if this is the last one.

duration is in seconds and negative value is treated as infinity (or actually 100 years which should be enough ).

Simple example:

"program":"custom","pattern": "r:100,0.5,1;-1,1,1|g:10,0,0.5;60,0.5,1"

This means: red goes linearly 100 seconds from 50% (0.5) to 100% (1) then forever (-1) from 100% (1) to 100% (1) - ie keeps full on. Green goes simultaneously from 0% (0) to 50% (0.5) in 10 seconds then one minute (60) from 50% (0.5) to 100% (1) and then loops.

Custom scenes can be used for custom effects like semaphores, beacons, thunderstorms, fireworks, volcanos but also timers (eg from
green to red).

For devices with custom program on board the client can get total duration and elapsed time of currently running custom pattern by direct method: GetCustomProgramProgress.

For example when program is running then the response will be:

{"duration": 10.0, "elapsed": 3.43}

When the program wasn’t initialized by the pattern the response will be:

{"duration": -1.0, "elapsed": 0.0}

1.1.2 Detailed description of cron scheduling feature (deviceFeature.vreeda.cronScheduling)

Adds the state crontab, location and tzSpec to the device states

1. crontab - each consisting of objects where key is the unique id of the individual schedule and value is object:

   1. name - User given nameof the schedule

   2. expr - Classic Cron Expressions

   3. year - number - limit crontab to specified year. Intented to be used for non-repeated schedulings as crontab doesn't supoprt year. Zero to disable.

   4. states - object - diff states to apply (you can schedule on/off, recording and even crontab change)

   5. disabled - boolean - use for pausing

   6. next - long int - REPORTED only - unix timestamp of next invocation

2. location - object with lat and lon - GPS location; used by some crontab expressions (This is only required if the sunrise/sunset feature is used)

3. tzSpec - string - timezone specification; see man tzset; used by some crontab expressions; example for CET/CEST: CET-1CEST,M3.5.0,M10.5.0/3 (timezone is used for all time-based operations to have precise definition of midnight. Default is CET CEST.

Simple example:

{
   "crontab": {
     "<random unique string>": {
       "name":"April Fools",
       "expr": "0 0 12 1 4 *",
       "year": 2021,
       "states": {
         "on": false,
         "crontab": {
           "<random unique string>": {
             "disabled": true //deactivate after the job is started
           }
         }
       },
       "disabled": true // deactivate immediatelly
     }
   }
} 

1.2 List of device types

This is the list of current device types. All device types and references to device features are versioned. To keep this document brief only latest version of device type is listed, and actual version is replaced by *. Related device feature version are replaced by ?.

2 Device related message payloads

Several APIs share the same concept to process device related messages. This concept is oriented towards device shadows or device twins and consists of following attributes and properties:

• devices

  • device

    • config - configuration values (read only)

      • deviceId: VREEDA platform unique device id

      • sn: serial number

      • fwVer: firmware version

      • mac: wifi mac adress of device

    • states - device state as defined by device type and device features (read/write)

    • tags (read only)

      • deviceTypeName: device type as described before

      • deviceManufacturer: device manufacturer name

      • customDeviceName: user specified device name

      • userId: user ID of owning user

Following is an example of a device payload in a response message:

 {
     "Vreeda-EaaS-lamp1-09EE7B": {
         "config": {
             "deviceId": "Vreeda-EaaS-lamp1-09EE7B",
             "sn": "12340000650875",
             "fwVer": "1.7.0",
             "mac": "CE50E309EE7B"
         },
         "states": {
             "on": {
                 "value": true,
                 "updatedAt": "2020-03-13T09:36:59.3935774Z"
             },
             "updateFirmware": {
                 "value": false,
                 "updatedAt": "2020-03-12T09:20:27.7664284Z"
             },
             "connected": {
                 "value": false,
                 "updatedAt": "2020-03-12T09:20:27.7664284Z"
             }
         },
         "tags": {
             "deviceTypeName": "neuhaus.deviceType.RGBLamp.1",
             "deviceManufacturer": "BlaBlaLamp",
             "customDeviceName": "FPT Lamp 1 White",
             "userId": 5
         }
     }
 }

2. Authentication

The VREEDA IoT ecosystem APIs provide third parties access to the devices of users in the VREEDA platform. To respect the privacy of our users, a user has to grant access to his devices. This is done with a typical a typical OAuth 2.0 flow. When user has granted access to his devices a third party is able to control devices and retrieve data from devices.

The OAuth 2.0 flow is controlled by the VREEDA identity management system, and after a successful grant, the third party client receives a bearer access token. All third party clients that want to access VREEDA IoT ecosystem APIs need a client registration at the VREEDA identity management system. Please contact elmar.zeeb@vreeda.com to get a client registration.

For development purpose you can simply use the client registration of the lola smart app to create such a token for your user with following steps:

2.1 Start auth flow

Open following url in a browser:

https://vreedaid.b2clogin.com/vreedaid.onmicrosoft.com/oauth2/v2.0/authorize?p=B2C_1A_VREELI_SIGNIN_SIGNUP_EMBEDDED_PROD&client_id=89a7cd0d-55db-4bcc-abcc-4e5eec656823&nonce=defaultNonce&redirect_uri=https%3A%2F%2Fjwt.ms%2F&scope=89a7cd0d-55db-4bcc-abcc-4e5eec656823%20offline_access&response_type=code&prompt=login

This will end in a redirect to:

https://jwt.ms/?code=[code token]

You have to retrieve the code token. This can be done with browser developer tools.

2.2 Retrieve bearer access token

The resulting token is called code token an can be used to retrieve the actual bearer access token:

$ curl \
   -H "Content-Type: application/x-www-form-urlencoded" \
   -d "grant_type=authorization_code&client_id=89a7cd0d-55db-4bcc-abcc-4e5eec656823&redirect_uri=https%3A%2F%2Fjwt.ms%2F&code=[code token]&resource=common" \
   -X POST https://vreedaid.b2clogin.com/vreedaid.onmicrosoft.com/B2C_1A_VREELI_SIGNIN_SIGNUP_EMBEDDED_PROD/oauth2/v2.0/token

This will result in a response like:

 {
   "access_token":"[bearer access token]",
   "token_type":"Bearer",
   "not_before":1619524935,
   "expires_in":3600,
   "expires_on":1619528535,
   "resource":"89a7cd0d-55db-4bcc-abcc-4e5eec656823",
   "id_token_expires_in":3600,
   "profile_info":"[profile info]",
   "scope":"/ offline_access openid",
   "refresh_token":"[refresh token]",
   "refresh_token_expires_in":1209600
 }

The access token will expire after one hour. You can either get a new token with refresh token, or start with step 2.1 again.

2.3 Use bearer access token

All requests to following API endpoints must include a HTTP header:

Authorization: Bearer [bearer access token]

Available APIs