Raptor javascript SDK
Raptor IoT platform javascript SDK
Topics
Introduction
Raptor.js exposes the feature from the Raptor platform as a convenient javascript API.
This branch is pair with the Raptor API v4.x
Installation
Node.js
Install the module from the git repository
npm i raptorbox/raptorjs
and then import it in your code
const Raptor =
Browser
To generate a build use webpack
inside the repository directory. A generated build is made available under dist for stable releases.
Library configuration
The minimum configuration required is the token to access the API.
const raptor = 'your api key 1';
Login with user and password (will fetch a session apiKey automatically). An additional url
can be provided to use a personalized endpoint
const raptor = username: "admin" password: "admin" url: "http://raptor.local";
Example usage
List all devices
raptor
Delete an device with
raptor
Delete all the devices instances with
raptor
Search for devices
To perform a search at least one option is required, multiple option will be AND-ed together
-
Field
id
,name
,description
supports text-based queries, with those optional params// one of those valuesin: "value1" "value2"// contains stringcontains: "some string"// exactly match the stringmatch: "exact match" -
Field
properties
supports object-based queries, with those optional params// has a keycontainsKey: "my_key"// has a valuecontainsValue: 1001// contains those key-valueshas:field1: truefield2: 1001
var params = // short format for contains id: "1111-3333-4444-5555" name: in: "My device" "quadcopter_1" description: contains: "example" // short format for has: {...} properties: model: "a4b2788" // paging supportvar limit = 1000 // get 1000 results offset = 10; // starting from record 10 raptor
Create a device
var definition = "name": "Robot" "description": "My device" "streams": "sensing": "light": "number" "alarm": "boolean" "message": "string" "actions": "take-photo" "beep" "properties": "model": 'robot-001' "colors": 'red' 'blue'
Create the device in Raptor
raptor ;
Sending data update
First you have to select the stream you want to use, sensing
in our case, and send the data with the push
method.
const record = device raptor
To store a searchable location in the stream use the special location
field. The timestamp
field allow to specify the date/time of the record
const record = device raptor
Loading a device by ID
Let's load an instance of a Drone from it's definition
let deviceId = "the device id"; raptor
Retrieving data from a device
The returned value is an array of records from the device
// paging supportvar offset = 0 limit = 500 raptor ;
Search for data in a Stream
Methods to search for data in a stream
Available search types are
Numeric Range
Search for data in a stream matching a numeric range constrain
raptor
Time Range
Search for data in a time range, creation date (lastUpdate
) value will be used to match the search
const to = Math // now, in UNIX seconds from = to - 60*60*24 // -1 day raptor
Match
Search for a matching value in a provided channel
raptor
Bounding box
Search by a delimiting bounding box
This search type will look to match a channel named location
with a geojson value. See API docs
raptor
Distance
Search data by distance
raptor
Combining searches
To combine multiple filters
Notice that distance
is incompatible with bbox
, if both provided bbox
will be used
raptor
Getting realtime updates
Updates are delivered over MQTT subscriptions
Connecting to the broker
Connection can be done by providing the username
and password
or with an empty username
and a valid apiKey as the password
.
Those configuration are automatically taken from the configuration object provided by the library
Listening for updates to a stream
Get realtime updates from data streams
device
To stop listening
device
Listening for events
In some case could be useful to receive all the notifications available, to do so use listen to the data
event on the device
device
Unregister from events subscription with
device
Actions
Actions allow to invoke virtual operations on an device.
Invoking an actuation
To invoke an actuation use the invoke
method and provide additional parameters as argument
Note that the argument passed to invoke
must be a string, so to send JSON take care of serializing it accordingly
var status = JSON; // must be a string!raptor
Listening for actions
On the device side you can listen for specific actions and implement actuations on their arrival.
raptor
Contributing
Feel free to open an issue or contact us to discuss the library status and future development.
Adding a release
Currently we use standard-version
to tag version
npm run release
for a minor relasenpm run release-major
for a major relase
Docs
API docs can be generated using jsdoc
./node_modules/jsdoc/jsdoc.js ./ -c ./jsdoc.json -l -r
License
Apache2
Copyright FBK/CREATE-NET
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.