databoom.js
Version:
Client functionalities to send data to DATABOOM.
268 lines (215 loc) • 10.1 kB
Markdown
<a href='https://databoom.com/'></a>
# databoom.js: client functionalities to send data to [DATABOOM].
databoom.js is a simple Node.js module that helps you in sending your data to Databoom in an easy, intuitive, fast way. To date, the following protocols and services are available:
- HTTP
- MQTT
- PubNub
### Dependencies
databoom.js uses a number of modules to work properly:
* [mqtt] - A library for the MQTT protocol
* [pubnub] - Publish & Subscribe Real-time Messaging with PubNub
* [request] - Simplified HTTP request client
[databoom.js] is open source with a public repository on GitHub.
### Installation
You need first to install package with [npm]:
```sh
$ npm install databoom.js
```
In your Node.js script you just need the following line to access the different functionalities databoom.js offers.
```sh
var db = require('databoom.js');
```
### Functions
* <a href='#initialize'>db.initialize(token, APIkey)</a>
* <a href='#setDevice'>db.setDevice(token)</a>
* <a href='#setAPIKey'>db.setAPIKey(APIkey)</a>
* <a href='#getSettings'>db.getSettings()</a>
* <a href='#addSignals'>db.addSignals(signal 1, signal 2, ...)]
* <a href='#getSignals'>db.getSignals()</a>
* <a href='#deleteSignals'>db.deleteSignals([index])</a>
* <a href='#publishHTTP'>db.publishHTTP([signals], [date])</a>
* <a href='#startMQTTClient'>db.startMQTTClient()</a>
* <a href='#endMQTTClient'>db.endMQTTClient()</a>
* <a href='#getMQTTClient'>db.getMQTTClient()</a>
* <a href='#publishMQTT'>db.publishMQTT([signals], [date])</a>
* <a href='#initPubNub'>db.initPubNub()</a>
* <a href='#publishPubNub'>db.publishPubNub([signals], [date])</a>
### Databoom APIs
* <a href='#APIgetAlarms'>db.APIgetAlarms(callback)</a>
* <a href='#APIgetAlarmById'>db.APIgetAlarmById(idAlarm, callback)</a>
* <a href='#APIgetChartSignal'>db.APIgetChartSignal(idSignal, callback)</a>
* <a href='#APIgetDashboards'>db.APIgetDashboards(callback)</a>
* <a href='#APIgetDashboardById'>db.APIgetDashboardById(idDashboard, callback)</a>
* <a href='#APIgetWidgets'>db.APIgetWidgets(callback)</a>
* <a href='#APIgetWidgetById'>db.APIgetWidgetById(idWidget, callback)</a>
* <a href='#APIgetDevices'>db.APIgetDevices(callback)</a>
* <a href='#APIgetDeviceById'>db.APIgetDeviceById(idDevice, callback)</a>
* <a href='#APIgetDeviceByToken'>db.APIgetDeviceByToken(tokenDevice, callback)</a>
* <a href='#APIgetDevicesTypes'>db.APIgetDevicesTypes(callback)</a>
* <a href='#APIgetRules'>db.APIgetRules(callback)</a>
* <a href='#APIgetRuleById'>db.APIgetRuleById(idRule, callback)</a>
* <a href='#APIgetUnits'>db.APIgetUnits(callback)</a>
* <a href='#APIgetSignals'>db.APIgetSignals(callback)</a>
* <a href='#APIgetSignalById'>db.APIgetSignalById(idSignal, callback)</a>
* <a href='#APIgetTeams'>db.APIgetTeams(callback)</a>
* <a href='#APIgetTeamById'>db.APIgetTeamById(idTeam, callback)</a>
-------------------------------------------------------
<a name='initialize'></a>
### db.initialize(token, APIkey)
To initialize both the device token and the API key.
`token` is your Databoom device token, while `APIkey` is your personal Databoom API key.
You need to set these values to use other functionalities.
<a name='setDevice'></a>
### db.setDevice(token)
To set the device you are working with.
`token` is your Databoom device token.
You need also to `setAPIKey` to access other functionalities.
<a name='setAPIKey'></a>
### db.setAPIKey(APIkey)
To set the API key.
`APIkey` is your personal Databoom API key.
You need also to `setDevice` to access other functionalities.
<a name='getSettings'></a>
### db.getSettings()
Returns an objects with the settings you provided.
```sh
{
deviceToken: DEVICE TOKEN,
userAPIKey: USER API KEY
}
```
<a name='addSignals'></a>
### db.addSignals(signal 1, signal 2, ...)
To add signals before publishing/posting them. At least a signal as argument is required.
A signal is an object structured as follows:
```sh
{
name: YOUR SIGNAL NAME,
value: YOUR SIGNAL VALUE
}
```
<a name='getSignals'></a>
### db.getSignals()
Returns the signals list you already added, which are ready to be published/posted.
<a name='deleteSignals'></a>
### db.deleteSignals([index])
Specifying an `index`, the corresponding signal is removed from the list.
If no index is provided, `db.deleteSignals()` removes all the stored signals.
<a name='publishHTTP'></a>
### db.publishHTTP([signals], [date])
* `db.publishHTTP()` sends an HTTP post request to Databoom with the signals you added before, if any. Uses the current date.
* `db.publishHTTP(signals)` sends an HTTP post request to Databoom with the signals specified as arguments. `signals` can be a single signal
```sh
{ name: YOUR SIGNAL NAME, value: YOUR SIGNAL VALUE}
```
or a signals array
```sh
[{ name: YOUR SIGNAL1 NAME, value: YOUR SIGNAL1 VALUE }, { name: YOUR SIGNAL2 NAME, value: YOUR SIGNAL2 VALUE }, ... ]
```
Uses the current date.
* `db.publishHTTP(signals, date)` works as `db.publishHTTP(signals)`, but uses the specified date.
<a name='startMQTTClient'></a>
### db.startMQTTClient()
Creates and starts a client MQTT. You need it to publish your device data on databoom topic.
<a name='endMQTTClient'></a>
### db.endMQTTClient()
To close the client MQTT after the data are sent.
<a name='getMQTTClient'></a>
### db.getMQTTClient()
Returns all the available client details.
<a name='publishMQTT'></a>
### db.publishMQTT([signals], [date])
* `db.publishMQTT()` publishes on Databoom topic the signals you added before, if any. Uses the current date.
* `db.publishMQTT(signals)` publishes on Databoom topic the signals specified as arguments. `signals` can be a single signal
```sh
{ name: YOUR SIGNAL NAME, value: YOUR SIGNAL VALUE}
```
or a signals array
```sh
[{ name: YOUR SIGNAL1 NAME, value: YOUR SIGNAL1 VALUE }, { name: YOUR SIGNAL2 NAME, value: YOUR SIGNAL2 VALUE }, ... ]
```
Uses the current date.
* `db.publishMQTT(signals, date)` works as `db.publishMQTT(signals)`, but uses the specified date.
<a name='initPubNub'></a>
### db.initPubNub()
Creates a PubNub instance. You need it to publish your device data on databoom channel.
<a name='publishPubNub'></a>
### db.publishPubNub([signals], [date])
* `db.publishPubNub()` publishes on Databoom channel the signals you added before, if any. Uses the current date.
* `db.publishPubNub(signals)` publishes on Databoom channel the signals specified as arguments. `signals` can be a single signal
```sh
{ name: YOUR SIGNAL NAME, value: YOUR SIGNAL VALUE}
```
or a signals array
```sh
[{ name: YOUR SIGNAL1 NAME, value: YOUR SIGNAL1 VALUE }, { name: YOUR SIGNAL2 NAME, value: YOUR SIGNAL2 VALUE }, ... ]
```
Uses the current date.
* `db.publishPubNub(signals, date)` works as `db.publishPubNub(signals)`, but uses the specified date.
-------------------------------------------------------
To use any of the APIs, you need to `setAPIKey` first.
<a name='APIgetAlarms'></a>
### db.APIgetAlarms(callback)
Callback returns as argument the alarms list matching the setted API key.
<a name='APIgetAlarmById'></a>
### db.APIgetAlarmById(idAlarm, callback)
Callback returns as argument the alarm matching the id, if any.
<a name='APIgetChartSignal'></a>
### db.APIgetChartSignal(idSignal, callback)
Callback returns as argument the chart values of the signal matching the id, if any.
<a name='APIgetDashboards'></a>
### db.APIgetDashboards(callback)
Callback returns as argument the dashboards list matching the setted API key.
<a name='APIgetDashboardById'></a>
### db.APIgetDashboardById(idDashboard, callback)
Callback returns as argument the dashboard matching the id, if any.
<a name='APIgetWidgets'></a>
### db.APIgetWidgets(callback)
Callback returns as argument the widgets list matching the setted API key.
<a name='APIgetWidgetById'></a>
### db.APIgetWidgetById(idWidget, callback)
Callback returns as argument the widget matching the id, if any.
<a name='APIgetDevices'></a>
### db.APIgetDevices(callback)
Callback returns as argument the devices list matching the setted API key.
<a name='APIgetDeviceById'></a>
### db.APIgetDeviceById(idDevice, callback)
Callback returns as argument the device matching the id, if any.
<a name='APIgetDeviceByToken'></a>
### db.APIgetDeviceByToken(tokenDevice, callback)
Callback returns as argument the device matching the token, if any.
<a name='APIgetDevicesTypes'></a>
### db.APIgetDevicesTypes(callback)
Callback returns as argument the devices types list.
<a name='APIgetRules'></a>
### db.APIgetRules(callback)
Callback returns as argument the rules list matching the setted API key.
<a name='APIgetRuleById'></a>
### db.APIgetRuleById(idRule, callback)
Callback returns as argument the rule matching the id, if any.
<a name='APIgetUnits'></a>
### db.APIgetUnits(callback)
Callback returns as argument the units list.
<a name='APIgetSignals'></a>
### db.APIgetSignals(callback)
Callback returns as argument the signals list matching the setted API key.
<a name='APIgetSignalById'></a>
### db.APIgetSignalById(idSignal, callback)
Callback returns as argument the signal matching the id, if any.
<a name='APIgetTeams'></a>
### db.APIgetTeams(callback)
Callback returns as argument the teams list matching the setted API key.
<a name='APIgetTeamById'></a>
### db.APIgetTeamById(idTeam, callback)
Callback returns as argument the team matching the id, if any.
-------------------------------------------------------
### Version
1.1.2
### License
MIT
[databoom.js]: <https://github.com/rickymarchiori/databoom.js>
[mqtt]: <https://www.npmjs.com/package/mqtt>
[pubnub]: <https://www.npmjs.com/package/pubnub>
[request]: <https://www.npmjs.com/package/request>
[npm]: <https://www.npmjs.com/>
[DATABOOM]: <https://databoom.com/>