Back to top

Preface

Visionect Server is a part of the Visionect electronic paper digital signage platform; a thin-client server which is capable of taking any HTML based dynamic web application, rendering it to graphical data and streaming it to a thin-client. Applications can be developed with any backend technology such as node.js, .net, Java, Python, Ruby and others. Any changes to the application code are done centrally on the application server, which removes the need to push new software to end user devices themselves.

For most cases administration cases, we provide our default administration interface to access the server configuration, but you might be inclined to integrate the management features in your own application. The most basic reason might be the requirement to display the battery status of each device inside their own backend app.

Before You Get Started

This documentation covers the RESTful JSON API, which can be used to build full analog of the Visionect Server management GUI - all API interfaces are accessible for integration into your backend. To get started, you’ll need to know your server IP, make sure that port 8081 is accessible for you app and you’ve created an API key. After that’s done, you’ll be able to use the API interfaces below as long as you authenticate every request.

Python library

To ease development in Python, developers can use our library. Library covers all api calls and is Python 2 and 3 compatible.

Authentication

We are using HMAC for REST authentication that is implemented similarly as AWS authentication.

Every request must include Authorization header that is calculated as so:

APIKey + ":" + base64(hmac-sha256(APISecret,
                                        HTTP-verb + "\n" +
                                        Content-Sha256 + "\n" +
                                        Content-Type + "\n" +
                                        Date + "\n" +
                                        RequestPath))

Fields

Field Required Example Value
APIKey yes d4508ad5491f14df
APISecret yes 0S1MVZyXfUMoBGQxGhWkkEGl8QAxZMt2gZtKkOPn5Is
HTTP-verb yes GET
Content-Sha256 no
Content-Type no application/json
Date yes Fri, 18 Jul 2014 08:57:09 GMT
RequestPath yes /api/user/

Warning

  • Make sure you add a trailing slash to the RequestPath.

  • Make sure you actually use the same headers in the request and authorization calculation.

  • Do not rely that your http client library will automatically use the same Date as you used for calculating authorization header. You probably should manually add Date header to the request.

  • Content-Sha256 and Content-Type are optional, but if included in the response headers they need to be added to authorization header.

General example:

If you use the example values from the table above and calculate Authorization header:

"d4508ad5491f14df:" + base64(hmac-sha256("0S1MVZyXfUMoBGQxGhWkkEGl8QAxZMt2gZtKkOPn5Is",
"GET\n\napplication/json\nFri, 18 Jul 2014 08:57:09 GMT\n/api/user/")

you get the value for Authorization header: d4508ad5491f14df:6umW5dQj8WfPZWlMjwmnMbJ/whgtA7ghtC/Na/X2nSY=

Python example

import requests, base64, hmac, hashlib, time, wsgiref.handlers

headers = {
   'Date': wsgiref.handlers.format_date_time(time.time()),
   'Content-Type': 'application/json'
}

h = hmac.new('0S1MVZyXfUMoBGQxGhWkkEGl8QAxZMt2gZtKkOPn5Is', 'GET\n\n' + headers['Content-Type'] + '\n' + headers['Date'] + '\n/api/user/', hashlib.sha256)
headers['Authorization'] = 'd4508ad5491f14df:' + base64.encodestring(h.digest()).strip()
r = requests.get('http://localhost:8081/api/user/', headers=headers)

print r.text

The above example would generate the following HTTP request:

GET /api/user/ HTTP/1.0
Date: Tue, 19 Apr 2016 08:43:59 GMT
Content-Type: application/json
Authorization: d4508ad5491f14df:xGbKYNvrNNuIK8lhBpHVB+WsAlP/32xilDy0ZKI05Mw=

Go example

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/base64"
    "fmt"
    "io/ioutil"
    "net/http"
    "time"
)

func main() {
    apiKey := "7fce10d4da4c915d"
    apiSecret := "Wg1bHa7JvbrLg40DcWkjn8VlPrQaBuj0XPreukfeZtM"
    date := time.Now().Format(time.RFC1123)
    headerData := fmt.Sprintf("GET\n\napplication/json\n%s\n/api/user", date)

    h := hmac.New(sha256.New, []byte(apiSecret))
    h.Write([]byte(headerData))
    client := &http.Client{}
    req, err := http.NewRequest("GET", "http://localhost:8081/api/user", nil)
    req.Header.Add("Date", date)
    req.Header.Add("Content-Type", "application/json")
    req.Header.Add("Authorization", apiKey+":"+base64.StdEncoding.EncodeToString(h.Sum(nil)))

    resp, err := client.Do(req)
    if err != nil {
        fmt.Printf("Error: %v", err)
        return
    }
    body, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        fmt.Printf("Error reading body: %v", err)
        return
    }
    fmt.Println(string(body))
}

Devices 

Device 

Device object contains settings and status of a single device.

It has the following attributes:

  • Uuid (unique identifier) - read only

  • SessionId (WebKit session id - multiple devices can have the same SessionId)

  • State (offline or online) - read only

  • Displays (array of device displays) Each display contains the following fields:

    • Id (display number from 0 - number of displays)
    • Width (display width in px)
    • Height (display height in px)
    • X (display offset on X axis in px)
    • Y (display offset on Y axis in px)
    • Rotation (display rotation - number from 0 - 3):
      • 0: Portrait
      • 1: Landscape (90°)
      • 2: Portrait (180°)
      • 3: Landscape (270°)
  • Options

    • Firmware (firmware number or name) - read only
    • RequestedFirmware (use this field to flash the device with new firmware)
    • Revision (hardware revision name)
    • PollingTime (get or set polling time for devices that use polling, otherwise it’s set to -1)
    • SleepSchedule (set when device will wake up - in minutes)
    • PeriodicSleep (set if sleep is periodic)
    • ScheduledWakeup (when device should wakeup) - read only
  • Status (read only informations about device - all are optional)

    • Battery
    • Charger
    • RSSI
    • Temperature
    • ExternalBattery
    • ConnectReason
    • ConnectivityUsed
    • ErrorCode
    • NumSupportedDisplays
Retrieve a Device
/api/device/{Uuid}
  • Parameters
  • Uuid
    UUID (required) Example: 28002100-1447-3330-3135-353800000000

    Device Uuid.

  • Request
  • Headers
    Authorization: calculated_HMAC
  • Response  200
  • Body
    {
      "Uuid": "28002100-1447-3330-3135-353800000000",
      "SessionId": "28002100-1447-3330-3135-353800000000",
      "Options": {
        "Firmware": "n/a",
        "PeriodicSleep": "false",
        "PollingTime": "-1",
        "Push": "true",
        "Revision": "Panda DS V1.00",
        "ScheduledWakeup": "2014-12-16 00:00:00 +0000 UTC",
        "SleepSchedule": "0"
      },
      "Displays": [
        {
          "Id": 0,
          "Width": 600,
          "Height": 800,
          "X": 0,
          "Y": 0,
          "Rotation": 0
        }
      ],
      "Status": {
        "ApplicationVersion": "141262193",
        "Battery": "0",
        "BootloaderVersion": "196864",
        "ConnectReason": "wakeup",
        "ConnectivityUsed": "1",
        "DisplayStateCRC": "0",
        "ErrorCode": "0x0",
        "ExternalBattery": "855",
        "LastStatus": "287454020",
        "NumSupportedDisplays": "4",
        "Push": "true",
        "RSSI": "0",
        "Temperature": "26"
      },
      "State": "offline"
    }
Update a Device
/api/device/{Uuid}
  • Parameters
  • Uuid
    UUID (required) Example: 28002100-1447-3330-3135-353800000000

    Device Uuid.

  • Request
  • Headers
    Authorization: calculated_HMAC
    Body
    {
      "Uuid": "28002100-1447-3330-3135-353800000000",
      "SessionId": "28002100-1447-3330-3135-353800000000",
      "Options": {
        "Firmware": "n/a",
        "PeriodicSleep": "false",
        "PollingTime": "-1",
        "Push": "true",
        "Revision": "Panda DS V1.00",
        "ScheduledWakeup": "2014-12-16 00:00:00 +0000 UTC",
        "SleepSchedule": "0"
      },
      "Displays": [
        {
          "Id": 0,
          "Width": 600,
          "Height": 800,
          "X": 0,
          "Y": 0,
          "Rotation": 0
        }
      ],
      "Status": {
        "ApplicationVersion": "141262193",
        "Battery": "0",
        "BootloaderVersion": "196864",
        "ConnectReason": "wakeup",
        "ConnectivityUsed": "1",
        "DisplayStateCRC": "0",
        "ErrorCode": "0x0",
        "ExternalBattery": "855",
        "LastStatus": "287454020",
        "NumSupportedDisplays": "4",
        "Push": "true",
        "RSSI": "0",
        "Temperature": "26"
      },
      "State": "offline"
    }
  • Response  204
Remove a Device
/api/device/{Uuid}
  • Parameters
  • Uuid
    UUID (required) Example: 28002100-1447-3330-3135-353800000000

    Device Uuid.

  • Request
  • Headers
    Authorization: calculated_HMAC
  • Response  204

Devices Collection 

List all Devices
/api/device
  • Request
  • Headers
    Authorization: calculated_HMAC
  • Response  200
  • Returns a list of Device objects.

    Headers
    Content-Type: application/json
    Body
    [
      {
        "Uuid": "28002100-1447-3330-3135-353800000000",
        "SessionId": "28002100-1447-3330-3135-353800000000",
        "Options": {
          "Push": "false",
          "Revision": "2"
        },
        "Displays": [
          {
            "Id": 0,
            "Width": 600,
            "Height": 800,
            "X": 0,
            "Y": 0,
            "Rotation": 0
          }
        ],
        "Status": {
          "ApplicationVersion": "141262193",
          "Battery": "0",
          "BootloaderVersion": "196864",
          "ConnectReason": "wakeup",
          "ConnectivityUsed": "1",
          "DisplayStateCRC": "0",
          "ErrorCode": "0x0",
          "ExternalBattery": "855",
          "LastStatus": "287454020",
          "NumSupportedDisplays": "4",
          "Push": "true",
          "RSSI": "0",
          "Temperature": "26"
        },
        "State": "offline"
      },
      {
        "Uuid": "28002000-1447-3330-3135-353800000000",
        "SessionId": "28002000-1447-3330-3135-353800000000",
        "Options": {
          "Push": "false",
          "Revision": "2"
        },
        "Displays": [
          {
            "Id": 0,
            "Width": 600,
            "Height": 800,
            "X": 0,
            "Y": 0,
            "Rotation": 0
          }
        ],
        "Status": {
          "ApplicationVersion": "141262193",
          "Battery": "0",
          "BootloaderVersion": "196864",
          "ConnectReason": "wakeup",
          "ConnectivityUsed": "1",
          "DisplayStateCRC": "0",
          "ErrorCode": "0x0",
          "ExternalBattery": "3383",
          "LastStatus": "287454020",
          "NumSupportedDisplays": "4",
          "PrematureWakeup": "true",
          "Push": "true",
          "RSSI": "0",
          "Temperature": "29"
        },
        "State": "offline"
      }
    ]
Update a list of Devices
/api/device
  • Request
  • Requires a list of Device objects that will be updated.

    Headers
    Content-Type: application/json
    Authorization: calculated_HMAC
    Body
    [
      {
        "Uuid": "28002100-1447-3330-3135-353800000000",
        "SessionId": "28002100-1447-3330-3135-353800000000",
        "Options": {
          "Push": "false",
          "Revision": "2"
        },
        "Displays": [
          {
            "Id": 0,
            "Width": 600,
            "Height": 800,
            "X": 0,
            "Y": 0,
            "Rotation": 0
          }
        ],
        "Status": {
          "ApplicationVersion": "141262193",
          "Battery": "0",
          "BootloaderVersion": "196864",
          "ConnectReason": "wakeup",
          "ConnectivityUsed": "1",
          "DisplayStateCRC": "0",
          "ErrorCode": "0x0",
          "ExternalBattery": "855",
          "LastStatus": "287454020",
          "NumSupportedDisplays": "4",
          "Push": "true",
          "RSSI": "0",
          "Temperature": "26"
        },
        "State": "offline"
      },
      {
        "Uuid": "28002000-1447-3330-3135-353800000000",
        "SessionId": "28002000-1447-3330-3135-353800000000",
        "Options": {
          "Push": "false",
          "Revision": "2"
        },
        "Displays": [
          {
            "Id": 0,
            "Width": 600,
            "Height": 800,
            "X": 0,
            "Y": 0,
            "Rotation": 0
          }
        ],
        "Status": {
          "ApplicationVersion": "141262193",
          "Battery": "0",
          "BootloaderVersion": "196864",
          "ConnectReason": "wakeup",
          "ConnectivityUsed": "1",
          "DisplayStateCRC": "0",
          "ErrorCode": "0x0",
          "ExternalBattery": "3383",
          "LastStatus": "287454020",
          "NumSupportedDisplays": "4",
          "PrematureWakeup": "true",
          "Push": "true",
          "RSSI": "0",
          "Temperature": "29"
        },
        "State": "offline"
      }
    ]
  • Response  204

Device Configuration 

  • TCLV (Type, Control, Length, Value) is a data protocol for machine to machine communication. Used for configuration and communication.
Get Configuration List
/api/devicetclv/{Uuid}

Python example

def get_tclv_list(key, secret, url, uuid):
            headers = {
                'Date': wsgiref.handlers.format_date_time(time.time()),
                'Content-Type': 'application/json'
            }
            h = hmac.new(secret, 'GET\n\n' + headers['Content-Type'] + '\n' + headers['Date'] + '\n/api/devicetclv/'+uuid, hashlib.sha256)
            headers['Authorization'] = key + ':' + base64.encodestring(h.digest()).strip()
            r = requests.get(url + 'api/devicetclv/'+uuid, headers=headers)
            return r.content
  • Parameters
  • Uuid
    UUID (required) Example: 28002100-1447-3330-3135-353800000000

    Device Uuid.

  • Request
  • Headers
    Authorization: calculated_HMAC
  • Response  200
  • Body
    [{
        "ID": 0,
        "Name": "TAG",
        "ReadOnly": true
    },
    
    {
        "ID": 1,
        "Name": "VER",
        "ReadOnly": true
    },
    
    {
        "ID": 2,
        "Name": "CONN_TYPE",
        "ReadOnly": true
    },
    
    ...
    
    {
        "ID": 51,
        "Name": "SYS_SHIP_MODE",
        "ReadOnly": false
    },
    {
        "ID": 52,
        "Name": "SLEEP_MODE",
        "ReadOnly": false
    },
    {
        "ID": 53,
        "Name": "CMD_FLASH_SAVE",
        "ReadOnly": false
    }]
Get Configuration
/api/devicetclv/{Uuid}
  • Note that api entry point is different [/api/cmd/Param/+{Uuid}]

Python example

def get_tclv(key, secret, url, uuid, type):
                headers = {
                    'Date': wsgiref.handlers.format_date_time(time.time()),
                    'Content-Type': 'application/json'
                }
                tclv_to_send = '{"Data": [{"Type": '+str(type)+',"Control": 0, "Value": ""}]}'
                h = hmac.new(secret, 'POST\n\n' + headers['Content-Type'] + '\n' + headers['Date'] + '\n/api/cmd/Param/'+uuid, hashlib.sha256)
                headers['Authorization'] = key + ':' + base64.encodestring(h.digest()).strip()
                r = requests.post(url + 'api/cmd/Param/'+uuid, headers=headers, data=tclv_to_send)
                return r.json()
  • Parameters
  • Uuid
    UUID (required) Example: 28002100-1447-3330-3135-353800000000

    Device Uuid.

  • Request
  • Headers
    Authorization: calculated_HMAC
  • Response  200
  • Body
    {u'47003900-1351-3432-3434-373300000000': [{u'Control': 0, u'Type': 29, u'Value': u'1'}]}
Set Configuration
/api/devicetclv/{Uuid}
  • Note that api entry point is different [/api/cmd/Param/+{Uuid}]

Python example

def set_tclv(key, secret, url, uuid, type, value):
                headers = {
                    'Date': wsgiref.handlers.format_date_time(time.time()),
                    'Content-Type': 'application/json'
                }
                tclv_to_send = '{"Data": [{"Type": '+str(type)+',"Control": 1, "Value": "'+str(value)+'"}]}'
                h = hmac.new(secret, 'POST\n\n' + headers['Content-Type'] + '\n' + headers['Date'] + '\n/api/cmd/Param/'+uuid, hashlib.sha256)
                headers['Authorization'] = key + ':' + base64.encodestring(h.digest()).strip()
                r = requests.post(url + 'api/cmd/Param/'+uuid, headers=headers, data=tclv_to_send)
                return r.json()
  • Parameters
  • Uuid
    UUID (required) Example: 28002100-1447-3330-3135-353800000000

    Device Uuid.

  • Request
  • Headers
    Authorization: calculated_HMAC
  • Response  200
  • Body
    {u'47003900-1351-3432-3434-373300000000': []}

Reboot Device 

If device is online you can reboot it.

/api/device/{Uuid}/reboot
  • Request
  • Headers
    Authorization: calculated_HMAC
  • Response  204

Reboot a list of Devices 

/api/device/reboot

Requires a list of device Uuids.

  • Request
  • Headers
    Content-Type: application/json
    Authorization: calculated_HMAC
    Body
    [
      "28002100-1447-3330-3135-353800000000",
      "28002000-1447-3330-3135-353800000000"
    ]
  • Response  204

Sessions 

Session 

Session object contains settings for WebKit session.

It has the following attributes:

  • Uuid (unique identifier)

  • Options:

    • DefaultDithering (dithering method, it can be overriden with JS calls) - possible values:
      • none
      • bayer
      • floyd-steinberg
    • DefaultEncoding (default display mode) - posible values:
      • 1: black & white
      • 4: black & white + 14 shades of gray
  • Backend:

    • Name (name of the used backend) - possible values:
      • HTML: (webkit HTML renderer)
      • HTTP: (simple backend that display images posted through http)
    • Fields (configuration fields for backend) - example:
      • url (session url for HTML backend) - It can contain {uuid} that will get replaced with Device Uuid.
Retrive a Session
/api/session/{Uuid}
  • Parameters
  • Uuid
    UUID (required) Example: 28002100-1447-3330-3135-353800000000

    Session Uuid.

  • Request
  • Headers
    Authorization: calculated_HMAC
  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
      "Uuid": "28002100-1447-3330-3135-353800000000",
      "Options": {
        "DefaultDithering": "none",
        "DefaultEncoding": "4"
      },
      "Backend": {
        "Name": "HTML",
        "Fields": {
          "url": "http://localhost:8000/uuid/{uuid}"
        }
      }
    }
Update a Session
/api/session/{Uuid}
  • Parameters
  • Uuid
    UUID (required) Example: 28002100-1447-3330-3135-353800000000

    Session Uuid.

  • Request
  • Headers
    Content-Type: application/json
    Authorization: calculated_HMAC
    Body
    {
      "Uuid": "28002100-1447-3330-3135-353800000000",
      "Options": {
        "DefaultDithering": "none",
        "DefaultEncoding": "4"
      },
      "Backend": {
        "Name": "HTML",
        "Fields": {
          "url": "http://localhost:8000/uuid/{uuid}"
        }
      }
    }
  • Response  201
Remove a Session
/api/session/{Uuid}
  • Parameters
  • Uuid
    UUID (required) Example: 28002100-1447-3330-3135-353800000000

    Session Uuid.

  • Request
  • Headers
    Authorization: calculated_HMAC
  • Response  204

Sessions Collection 

List all Sessions
/api/session
  • Request
  • Headers
    Authorization: calculated_HMAC
  • Response  200
  • Returns a list of Sessions objects.

    Headers
    Content-Type: application/json
    Body
    [
      {
        "Uuid": "28002100-1447-3330-3135-353800000000",
        "Options": {
          "DefaultDithering": "none",
          "DefaultEncoding": "4"
        },
        "Backend": {
          "Name": "HTML",
          "Fields": {
            "url": "http://localhost:8000/uuid/{uuid}"
          }
        }
      },
      {
        "Uuid": "28002000-1447-3330-3135-353800000000",
        "Options": {
          "DefaultDithering": "none",
          "DefaultEncoding": "4"
        },
        "Backend": {
          "Name": "HTTP",
          "Fields": {}
        }
      }
    ]
Create a Session
/api/session
  • Request
  • Headers
    Content-Type: application/json
    Authorization: calculated_HMAC
    Body
    {
      "Uuid": "28002100-1447-3330-3135-353800000000",
      "Options": {
        "DefaultDithering": "none",
        "DefaultEncoding": "4"
      },
      "Backend": {
        "Name": "HTML",
        "Fields": {
          "url": "http://localhost:8000/uuid/{uuid}"
        }
      }
    }
  • Response  201
Update a list of Sessions
/api/session
  • Request
  • Requires a list of Sessions objects.

    Headers
    Content-Type: application/json
    Authorization: calculated_HMAC
    Body
    [
      {
        "Uuid": "28002100-1447-3330-3135-353800000000",
        "Options": {
          "DefaultDithering": "none",
          "DefaultEncoding": "4"
        },
        "Backend": {
          "Name": "HTML",
          "Fields": {
            "url": "http://localhost:8000/uuid/{uuid}"
          }
        }
      },
      {
        "Uuid": "28002000-1447-3330-3135-353800000000",
        "Options": {
          "DefaultDithering": "none",
          "DefaultEncoding": "4"
        },
        "Backend": {
          "Name": "HTTP",
          "Fields": {}
        }
      }
    ]
  • Response  201

Restart Session 

This will reload WebKit session.

/api/session/{Uuid}/restart
  • Request
  • Headers
    Authorization: calculated_HMAC
  • Response  204

Restart a list of Sessions 

/api/session/restart

Requires a list of session Uuids.

  • Request
  • Headers
    Content-Type: application/json
    Authorization: calculated_HMAC
    Body
    [
      "28002100-1447-3330-3135-353800000000",
      "28002000-1447-3330-3135-353800000000"
    ]
  • Response  204

Users 

User 

User object contains settings and credentials for users and API keys.

It has the following attributes:

  • Username (username for login or API key)

  • Password (hashed password or API secret)

  • IsActive (determines if user/API key can access and modify data)

  • IsAPI (determines if this object is user or API key)

Retrive a User
/api/user/{Username}
  • Parameters
  • Username
    string (required) 
  • Request
  • Headers
    Authorization: calculated_HMAC
  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
      "Username": "admin",
      "Password": "9a1b23c8b31ae7b3:6f31c2ff4c7a143e30a63b3b0a204410affa58973d1499cd896c432cd59fa772",
      "IsActive": true,
      "IsAPI": false
    }
Update a User
/api/user/{Username}
  • Parameters
  • Username
    string (required) 
  • Request
  • Headers
    Content-Type: application/json
    Authorization: calculated_HMAC
    Body
    {
      "Username": "admin",
      "Password": "9a1b23c8b31ae7b3:6f31c2ff4c7a143e30a63b3b0a204410affa58973d1499cd896c432cd59fa772",
      "IsActive": true,
      "IsAPI": false
    }
  • Response  201
Remove a User
/api/user/{Username}
  • Parameters
  • Username
    string (required) 
  • Request
  • Headers
    Authorization: calculated_HMAC
  • Response  204

Users Collection 

List all Users
/api/user
  • Request
  • Headers
    Authorization: calculated_HMAC
  • Response  200
  • Returns a list of User objects.

    Headers
    Content-Type: application/json
    Body
    [
      {
        "Username": "7775695259cef06f",
        "Password": "FL3QEYlRl4m1iungMQp9xsV5GYAm5dh0BpubnjXvrsc",
        "IsActive": true,
        "IsAPI": true
      },
      {
        "Username": "admin",
        "Password": "9a1b23c8b31ae7b3:6f31c2ff4c7a143e30a63b3b0a204410affa58973d1499cd896c432cd59fa772",
        "IsActive": true,
        "IsAPI": false
      }
    ]
Create a User
/api/user
  • Request
  • Headers
    Content-Type: application/json
    Authorization: calculated_HMAC
    Body
    {
      "Username": "admin",
      "Password": "9a1b23c8b31ae7b3:6f31c2ff4c7a143e30a63b3b0a204410affa58973d1499cd896c432cd59fa772",
      "IsActive": true,
      "IsAPI": false
    }
  • Response  201
Update a list of Users
/api/user
  • Request
  • Requires a list of User objects.

    Headers
    Content-Type: application/json
    Authorization: calculated_HMAC
    Body
    [
      {
        "Username": "7775695259cef06f",
        "Password": "FL3QEYlRl4m1iungMQp9xsV5GYAm5dh0BpubnjXvrsc",
        "IsActive": true,
        "IsAPI": true
      },
      {
        "Username": "admin",
        "Password": "9a1b23c8b31ae7b3:6f31c2ff4c7a143e30a63b3b0a204410affa58973d1499cd896c432cd59fa772",
        "IsActive": true,
        "IsAPI": false
      }
    ]
  • Response  201

Config 

Configuration API gets and sets config.json file. Documentation about that file and its contents is located on Visionect Server documentation.

Configuration 

Example configuration:

{ “Global” : { “EmailConfig” : { “Sender” : “koala@localhost”, “Host” : “localhost”, “Port” : “25”, “Username” : “”, “Password” : “” }, “AdminEmails” : [ "xxx@yyy.com", "zzz@qqq.com" ], “MasterHost” : “127.0.0.1”, “OnCrash” : “email”, “DeploymentName” : “Example deployment”, “DeploymentKey” : “use uuidgen to generate”, “ExposePolling” : false }, “Okular”: { “RenderTimeout” : 100, “FontAntialias” : false, “WebkitRSSLimit” : 187, “WebkitUserAgent”: “WebKit-VisionectOkular-1”, “IgnoreInputIfDeviceNotSync”: false, “MaxSessions” : 100, “PageCaching” : false, “Defaults”: { “URI” : "http://localhost:8000/uuid/{uuid}", “Encoding” : 4, “Resolution” : “600x800”, “PageLayout” : “0”, “DitheringMethod”: “none” } } }

Global - EmailConfig: configure the email server to be used for important notifications from the Visionect Server, - AdminEmails: an array to add recipient email addresses for email notifications, - MasterHost: the host where Visionect Server is running, - OnCrash: if set to email, a notification to all recipient addresses is sent if the Visionect Server fails (eg. in case of a program crash for some reason), - DeploymentName: the name of the deployment, - DeploymentKey:a unique identifier for the current Visionect Server installation. It is generated automatically upon installation, - ExposePolling: enables control over polling from Network Manager. Dynamic polling is disabled by default, as it overrides the setting configured on the device,

… TODO: - potreben update! Novi features in imena! (Napsy will help)

Okular - RenderTimeout: How long HTML rendering engine (formerly Okular) should wait for a rectangle region (in milliseconds) to be rendered before preprocessing the data for the device. Longer intervals are usually needed for rectangles with complex graphics, or if running HTML rendering engine on a slow machine, - FontAntialias: configures if the fonts displayed on the device should be anti-aliased by the standard GTK+ anti-aliasing process. Set to disabled if you’re using your pixel perfect fonts, - WebKitRSSLimit: now called Web Session Memory Limit; it set an upper limit of available RAM memory (in MiB) that a webkit instance should use. If the limit is reached, the session is restarted. This protects the system from running out of memory in case of a memory leak in the application, - WebkitUserAgent: configure the HTTP user agent header, so that the web applications can detect the presence of HTML rendering engine and reconfigure accordingly, - IgnoreInputIfDeviceNotSync: ignores any new click requests from the device in case there’s unsent data in the device session. This means new clicks won’t affect the application and the old response will be sent instead, - MaxSessions: maximum number of sessions for the HTML rendering engine. New session requests will be ignored if the number exceeds the limit, - PageCaching: should the loaded pages and resources be cached, - Defaults: default settings for devices that connect for the first time,

  • URI: the default URI to open, - Encoding: now called Bit depth; it configures the default display bit-depth. Valid values are 1 and 4. 1-bit encoding reduces the refresh rate to 250msec (E Ink technology limitation), while 4-bit is the maximum bit depth. This value can be overridden by HTML rendering backend (formerly Okular) Javascript Extensions in the web application, - Resolution: display resolution to use, - PageLayout: now called Display rotation; it is default screen rotation. Relevant if device screen autodetection fails. Available options are: 0 (no rotation), 1 (90-degree rotation), 2 (180-degree rotation), 3 (270-degree rotation) - DitheringMethod: every web page has to be converted from color to grayscale or black and white (according to the Graphics Engine setting). You can choose the type of dithering based on performance and quality requirements. Currently supported (in order of quality): none, bayer and floyd-steinberg. Noise dithers will not be supported, as they negate the Graphics Engine render caching infrastructure.
Retrieve Configuration
/api/config
  • Request
  • Headers
    Authorization: calculated_HMAC
  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
      "Global": {
        "EmailConfig": {
          "Sender": "koala@localhost",
          "Host": "localhost",
          "Port": "25",
          "Username": "",
          "Password": ""
        },
        "AdminEmails": [
          "xxx@yyy.com",
          "zzz@qqq.com"
        ],
        "MasterHost": "127.0.0.1",
        "OnCrash": "email",
        "DeploymentName": "Example deployment",
        "DeploymentKey": "use uuidgen to generate",
        "ExposePolling": false,
        "PacketTimeout": 300
      },
      "Okular": {
        "Host": "",
        "RenderTimeout": 100,
        "FontAntialias": false,
        "WebkitSessionMemoryLimit": 120,
        "WebkitUserAgent": "WebKit-VisionectOkular-1",
        "IgnoreInputIfDeviceNotSync": false,
        "MaxSessions": 100,
        "ImageCacheSize": 16,
        "PageCaching": false,
        "Defaults": {
          "Backend": {
            "Name": "HTML",
            "Fields": {
              "url": "http://demo.visionect.com/clock/"
            }
          },
          "Encoding": 4,
          "PageLayout": "0",
          "DitheringMethod": "none"
        },
        "ImageFlags": 0,
        "RectangleFlags": 0
      },
      "Storage": {
        "Backend": "couchdb",
        "Database": "koala",
        "Username": "visionect",
        "Password": "postgres"
      },
      "Features": []
    }
Update Configuration
/api/config
  • Request
  • Headers
    Content-Type: application/json
    Authorization: calculated_HMAC
    Body
    {
      "Global": {
        "EmailConfig": {
          "Sender": "koala@localhost",
          "Host": "localhost",
          "Port": "25",
          "Username": "",
          "Password": ""
        },
        "AdminEmails": [
          "xxx@yyy.com",
          "zzz@qqq.com"
        ],
        "MasterHost": "127.0.0.1",
        "OnCrash": "email",
        "DeploymentName": "Example deployment",
        "DeploymentKey": "use uuidgen to generate",
        "ExposePolling": false,
        "PacketTimeout": 300
      },
      "Okular": {
        "Host": "",
        "RenderTimeout": 100,
        "FontAntialias": false,
        "WebkitSessionMemoryLimit": 120,
        "WebkitUserAgent": "WebKit-VisionectOkular-1",
        "IgnoreInputIfDeviceNotSync": false,
        "MaxSessions": 100,
        "ImageCacheSize": 16,
        "PageCaching": false,
        "Defaults": {
          "Backend": {
            "Name": "HTML",
            "Fields": {
              "url": "http://demo.visionect.com/clock/"
            }
          },
          "Encoding": 4,
          "PageLayout": "0",
          "DitheringMethod": "none"
        },
        "ImageFlags": 0,
        "RectangleFlags": 0
      },
      "Storage": {
        "Backend": "couchdb",
        "Database": "koala",
        "Username": "visionect",
        "Password": "postgres"
      },
      "Features": []
    }
  • Response  204

Live View 

Live View 

/api/live/device/{Uuid}/{+type}{+file_type}

If file_type is set to .png the server will responde with png encoded image. If it is not set to anything it will respond with lz4 compressed bmp image.

We use that because lz4 compression is much faster and generates smaller files, even though it requires extra processing on client side.

  • Parameters
  • Uuid
    UUID (required) Example: 28002100-1447-3330-3135-353800000000

    Device Uuid.

    type
    string (required) Example: image

    If the type is set to image it will return current image that is displayed on the device. If the type is set to cached it will return the server side image for the device. cached image changes before image

    Choices: image cached

    file_type
    string (optional) Example: .png

    Image file type

    Choices: .png <empty>

  • Response  200
  • Headers
    Content-Type: image/png

Device Status 

Device status 

Retrieve Device Statuses for Time Range
/api/devicestatus/{Uuid}{?from,to,group}

Retrieves device statuses for the given time range. If status field has value of 999 or -999 it means that there was no data for that field.

Parameter group enables data grouping - the data will be reported in cumulative for a certain time range (ie hourly, daily, weekly). If you require all events as they were logged by server, then set group to false.

  • Parameters
  • Uuid
    UUID (required) Example: 28002100-1447-3330-3135-353800000000

    Device Uuid or comma-separated list of Uuids.

    from
    UNIX timestamp (required) Example: 1420978653
    to
    UNIX timestamp (required) Example: 1423657053
    group
    boolean (optional) Example: true
  • Request
  • Headers
    Authorization: calculated_HMAC
  • Response  200
  • Headers
    Content-Type: application/json
    Body
    [
      {
        "Status": {
          "Battery": 57,
          "Clicks": 0,
          "Connects": 0,
          "Disconnects": 65,
          "ExternalBattery": 999,
          "Images": 115,
          "RSSI": -75,
          "Temperature": 25
        },
        "Date": [
          2015,
          1,
          12,
          0,
          0,
          0
        ],
        "DeviceID": "35002c00-0e47-3130-3830-333200000000"
      },
      {
        "Status": {
          "Battery": 95,
          "Clicks": 0,
          "Connects": 0,
          "Disconnects": 245,
          "ExternalBattery": 999,
          "Images": 199,
          "RSSI": -76,
          "Temperature": 25
        },
        "Date": [
          2015,
          1,
          13,
          0,
          0,
          0
        ],
        "DeviceID": "35002c00-0e47-3130-3830-333200000000"
      }
    ]

Backends 

HTTP Backend 

This only works for devices that have HTTP backend selected in settings.

Update image for device
/backend/{Uuid}

With this request you set the image that will be displayed on the device.

  • Parameters
  • Uuid
    UUID (required) Example: 28002100-1447-3330-3135-353800000000

    Device Uuid or comma-separated list of Uuids.

  • Request
  • Headers
    Content-Type: multipart/form-data
    Authorization: calculated_HMAC
    Body
    multipart form with filed image in png or jpg format
  • Response  200
  • Headers
    Content-Type: text/plain

Generated by aglio on 05 Nov 2018