nodezestclient v0.0.13

Node Databox

A Nodejs library used by databox apps and drivers to interfac with Databox APIs.

Installation

To use this library in your node project, run:

npm install --save node-databox

and then within your project:

const databox = require('node-databox');

Usage

:warning: While this library is at 1.0.0 the API may change.

Examples of usage are provided in the https://github.com/me-box/databox-quickstart repository.

Helper Functions

These functions are useful for parsing the configuration data passed to your app or driver.

getHttpsCredentials()

Returns An object containing the HTTPS credentials to pass to https.createServer when offering an https server. These are read from /run/secrets/DATABOX.pem and are generated by the container-manager at run time. This is useful for apps and driver offering interfaces over https.

NewDataSourceMetadata ()

Returns An empty DataSourceMetadata object

DataSourceMetadata objects are used to describe your data source when creating a new one. They look like this:

    {
        Description:    "", // Text Description of your dataSource
        ContentType:    "", // The format the data is written in
                            // JSON,BINARY or TEXT.
        Vendor:         "", // Your company name.
        DataSourceType: "", // A short type string that represents your data
                            // it is used by apps to find the data you offer.
        DataSourceID:   "", // the ID of this data source, as the creator you
                            // are responsible for ensuring this is unique
                            // within your data store.
        StoreType:      "", // The type of store this uses
                            // (TS,TSBlob or KV)
        IsActuator:  false, // is this an IsActuator? it true other apps can
                            // request write access to this datasource
        Unit:           "", // Text representation of the units
        Location:       "", // Text representation of location Information
    };

DataSourceMetadataToHypercat (DataSourceMetadata)

Returns An object representing the hypercat item represented by DataSourceMetadata.

HypercatToSourceDataMetadata (hyperCatString)

Returns A promise that resolves to an object of the form { "DataSourceMetadata": , "DataSourceURL":store_url}

Using the databox core-store

The databox core-store supports the reading, writing, querying of time series and key value data. It is the default store for Databox version 0.3.0 and greater.

The time series API has support for writing generic JSON blobs (see TSBlob) or data in a specific format (see TS) which allows extra functionality such as joining, filtering and aggregation on the data. The key value API stores data against keys (see KV). All three type of data can be accessed through the databox.StoreClient.

databox.StoreClient (STORE_URI, ARBITER_URI, enableLogging)

Returns a new StoreClient that is connected to the provided store.

example To create a new client to access a store:

   let client = storeClient(STORE_URI, ARBITER_URI, false)

databox.StoreClient.RegisterDatasource (DataSourceMetadata)

This function registers your data sources with your store. Registering your data source makes them available to other databox apps.

Returns a Promise that resolves with "created" on success or rejects with error message on error.

storeClient.TS

These functions allow you to manage structured json data in the time series store and allow for filtering and aggregation of the data.

Data written into a TimeSeriesStore must contain, A value (integer or floating point number) and a tag is an identifier with corresponding string value. For example:{"room": "lounge", "value": 1}. Tagging a value provides a way to group values together when accessing them. In the example provided you could retrieve all values that are in a room called 'lounge'.

Data returned from a query is a JSON dictionary containing a timestamp in epoch milliseconds and the actual data. For example:{"timestamp":1513160985841,"data":{"foo":"bar","value":1}}. Data can also be aggregated by applying functions across values. Aggregation functions result in a response of a single value. For example: {"result":1}.

The storeClient.TS supports the following functions:

storeClient.TS.Write (dataSourceID, payload)

Data written to the store for the given dataSourceID data is timestamped with milliseconds since the unix epoch on insert.

Returns a Promise that resolves with "created" on success or rejects with error message on error.

storeClient.TS.WriteAt (dataSourceID, timestamp, payload)

Writes data to the store for the given dataSourceID at the given timestamp. Timestamp should be in milliseconds since the unix epoch.

Returns a Promise that resolves with "created" on success or rejects with error message on error.

storeClient.TS.Latest (dataSourceID)

Reads the latest data written to the provided dataSourceID.

Returns a Promise that resolves with an array of Objects of the form

   {
      timestamp: 1510768103558,
      data: { value:[numeric value] ,[tag name]:[tag value] }
   }

on success or rejects with error message on error.

storeClient.TS.LastN (dataSourceID,n)

Reads the last N items written to the provided dataSourceID.

Returns a Promise that resolves with an array of Objects of the form

   {
      timestamp: 1510768103558,
      data: { value:[numeric value] ,[tag name]:[tag value] }
   }

on success or rejects with error message on error.

storeClient.TS.Since (dataSourceID, sinceTimeStamp, aggregation, filterTagName, filterType, filterValue)

Read all entries since a time (inclusive)

Returns a Promise that resolves with an array of Objects of the form

   {
      timestamp: 1510768103558,
      data: { value:[numeric value] ,[tag name]:[tag value] }
   }

storeClient.TS.Range (dataSourceID, fromTimeStamp, toTimeStamp, aggregation, filterTagName, filterType, filterValue)

Read all entries in a time range (inclusive)

Returns a Promise that resolves with an array of Objects of the form

   {
      timestamp: 1510768103558,
      data: { value:[numeric value] ,[tag name]:[tag value] }
   }

storeClient.TS.Observe (dataSourceID,timeout)

This function allows you to receive data from a data source as soon as it is written.

Returns A Promise that resolves with an EventEmitter that emits data when data is written to the observed dataSourceID, the Promise rejects with an error. The data event will contain an Object of the form

   {
        "timestamp"    : 1510768103558,
        "datasourceid" : dataSourceID,
        "key"          : key name,
        "data"         : { value:[numeric value] ,[tag name]:[tag value] }
    }

storeClient.TS.StopObserving (dataSourceID)

Closes the connection to stop observing data on the provided dataSourceID.

Returns Void

StoreClient.TSBlob

These functions allow you to manage unstructured json data in the time series store.

:warning: If data is written into a TimeSeriesBlobStore filtering and aggregation functions are not supported.

The NewStoreClient.TSBlob supports the following functions:

databox.NewStoreClient.TSBlob (reqEndpoint, enableLogging)

Returns a new NewStoreClient.TSBlob that is connected to the provided store.

StoreClient.TSBlob.Write (dataSourceID, payload)

Writes data to the store for the given dataSourceID data is timestamped with milliseconds since the unix epoch on insert.

Returns a Promise that resolves with "created" on success or rejects with error message on error.

StoreClient.TSBlob.WriteAt (dataSourceID, timestamp, payload)

Writes data to the store for the given dataSourceID at the given timestamp. Timestamp should be in milliseconds since the unix epoch.

Returns a Promise that resolves with "created" on success or rejects with error message on error.

StoreClient.TSBlob.Latest (dataSourceID)

Reads the latest data written to the provided dataSourceID.

Returns a Promise that resolves with an Object of the form

   {
      timestamp: 1510768103558,
      data: { data written by driver }
   }

on success or rejects with error message on error.

StoreClient.TSBlob.LastN (dataSourceID,n)

Reads the last N items written to the provided dataSourceID.

Returns a Promise that resolves with an array of Objects of the form

   {
      timestamp: 1510768103558,
      data: { data written by driver }
   }

on success or rejects with error message on error.

StoreClient.TSBlob.Since (dataSourceID, sinceTimeStamp)

Read all entries since a time (inclusive)

Returns a Promise that resolves with an array of Objects of the form

   {
      timestamp: 1510768103558,
      data: { value:[numeric value] ,[tag name]:[tag value] }
   }

StoreClient.TSBlob.Range (dataSourceID, fromTimeStamp, toTimeStamp)

Read all entries in a time range (inclusive)

Returns a Promise that resolves with an array of Objects of the form

   {
      timestamp: 1510768103558,
      data: { value:[numeric value] ,[tag name]:[tag value] }
   }

StoreClient.TSBlob.Observe (dataSourceID,timeout)

This function allows you to receive data from a data source as soon as it is written.

Returns A Promise that resolves with an EventEmitter that emits data when data is written to the observed dataSourceID, the Promise rejects with an error. The data event will contain an Object of the form

   {
        "timestamp"  : 1510768103558,
        "datasourceid" : dataSourceID,
        "key"          : key name,
        "data"         : { data written by driver },
    }

StoreClient.TSBlob.StopObserving (dataSourceID)

Closes the connection to stop observing data on the provided dataSourceID.

Returns Void

StoreClient.KV

The Key Value Store allows the storage of TEXT, JSON and binary data agents keys. The default content format is JSON.

The StoreClient.KV encapsulates the following functions:

StoreClient.KV.Write (dataSourceID, KeyName, payload, contentFormat)

Writes data to the store for the given dataSourceID data. Writes to the same key overwrite the data.

Returns a Promise that resolves with "created" on success or rejects with error message on error.

StoreClient.KV.ListKeys (dataSourceID)

Lists the stored keys for this dataSourceID

Returns as Promise that resolves with the data on success or rejects with error message on error. The type of the returned data is an Array of Strings.

StoreClient.KV.Read (dataSourceID, KeyName, contentFormat)

Reads data from the store for the given dataSourceID. data is timestamped with milliseconds since the unix epoch on insert.

Returns a Promise that resolves with the data on success or rejects with error message on error. The type of the returned data depends on the contentFormat read.

StoreClient.KV.Observe (dataSourceID,timeout,contentFormat)

This function allows you to receive data from all keys under a data source as soon as it is written. This will observe all keys under a single data source

Returns A Promise that resolves with an EventEmitter that emits data when data is written to the observed dataSourceID, the Promise rejects with an error. The data event will contain data stored at the provided dataSourceID. The type of the return data depends on contentFormat.

   {
        "timestamp"  : 1510768103558,
        "datasourceid" : dataSourceID,
        "key"          : key name,
        "data"         : { data written by driver },
    }

StoreClient.KV.ObserveKey (dataSourceID,KeyName,timeout,contentFormat)

This function allows you to receive data from a data source as soon as it is written. This will observe a single key under a single data source

Returns A Promise that resolves with an EventEmitter that emits data when data is written to the observed dataSourceID, the Promise rejects with an error. The data event will contain data stored at the provided dataSourceID. The type of the return data depends on contentFormat.

   {
        "timestamp"  : 1510768103558,
        "datasourceid" : dataSourceID,
        "key"          : key name,
        "data"         : { data written by driver },
    }

StoreClient.KV.StopObserving (dataSourceID)

Closes the connection to stop observing data on the provided dataSourceID.

Returns Void

Development of databox was supported by the following funding

EP/N028260/1, Databox: Privacy-Aware Infrastructure for Managing Personal Data

EP/N028260/2, Databox: Privacy-Aware Infrastructure for Managing Personal Data

EP/N014243/1, Future Everyday Interaction with the Autonomous Internet of Things

EP/M001636/1, Privacy-by-Design: Building Accountability into the Internet of Things (IoTDatabox)

EP/M02315X/1, From Human Data to Personal Experience