README.md

raptor-sdk

The Raptor Java SDK is part of the raptor platform and used extensively in the codebase.

It can be reused as a standalone library in external application for a direct integration to the exposed API

• Requirements
• Setup
• Authentication
• Inventory
  • List devices
  • Create a device
  • Update a device
  • Load a device
  • Search for devices
  • Events notifications
    • Watch device events
    • Watch data events
    • Watch action events
• Stream
  • Push data
  • Pull data
  • Last update
  • Drop data
  • Search for data
    • Search by time
    • Search by numeric range
    • Search by distance
    • Search by bounding box
• Action
  • Set status
  • Get status
  • Invoke an action
• Profile
  • Set a value
  • Get a value
  • Get all values
• Tree
  • Create a node
  • Create a device node
  • List trees
  • Delete a node
• Admin

Requirements

• Java 8 or higher
• Maven

Setup

Import in your project the raptor-sdk maven package.

Authentication

Let's start by initializing a raptor client instance

// login with username and password
Raptor raptor = new Raptor("http://raptor.local", "admin", "admin")

// alternatively, login with a token
// Raptor raptor = new Raptor("http://raptor.local", "..token..")


// login and retrieve a token
AuthClient.LoginState loginInfo = raptor.Auth().login();

log.debug("Welcome {} (token: {})", loginInfo.user.getUsername(), loginInfo.token);

// close the session and drop the login token
raptor.Auth().logout();

Inventory

The inventory API store device definitions

List devices

List devices owned by a user

List<Device> list = raptor.Inventory().list();
log.debug("found {} devices", list.size());

Create a device

Create a new device definition

Device dev = new Device();

dev.name("test device")
    .description("info about");
dev.properties().put("active", true);
dev.properties().put("cost", 15000L);
dev.properties().put("version", "4.0.0");

dev.validate();

raptor.Inventory().create(dev);

log.debug("Device created {}", dev.id());

Update a device

Update a device definition

// Create a data stream named ambient with a channel temperature of type number
Stream s = dev.addStream("ambient", "temperature", "number");

//Add further channels of different types
s.addChannel("info", "text")
s.addChannel("alarm", "boolean")

// add an action
Action a = dev.addAction("light-control");

raptor.Inventory().update(dev);

log.debug("Device updated: \n {}", dev.toJSON());

Load a device

Load a device definition

Device dev1 = raptor.Inventory().load(dev.id());

log.debug("Device loaded: \n {}", dev.toJSON());

Search for devices

Search for device definitions

DeviceQuery q = new DeviceQuery();

// all devices which name contains `test`
q.name.contains("test");
// and properties.version  equals to 4.0.0
q.properties.has("version", "4.0.0");

log.debug("Searching for {}", q.toJSON().toString());
List<Device> results = raptor.Inventory().search(q);

log.debug("Results found {}", results.stream().map(d -> d.name()).collect(Collectors.toList()));

Event notifications

When a device receive data, an action is triggered or the definition changes events are emitted over an asynchronous MQTT channel.

Watch device events

Device events are notified when a device definition changes

raptor.Inventory().subscribe(dev, new DeviceCallback() {
    @Override
    public void callback(Device obj, DevicePayload message) {
        log.debug("Device event received {}", message.toString());
    }
});

Watch data events

Data events are generated when a stream is updated

raptor.Inventory().subscribe(dev, new DataCallback() {
    @Override
    public void callback(Stream stream, RecordSet record) {
        log.debug("dev: Data received {}", record.toJson());
    }
});

Watch action events

Action events are generated when an action is triggered or the status changes

raptor.Inventory().subscribe(dev, new ActionCallback() {
    @Override
    public void callback(Action action, ActionPayload payload) {
        log.debug("dev: Data received  for {}: {}",
            payload.actionId,
            payload.data
        );
    }
});

Stream

The Stream API handles data push and retrieval

Push data

Send data based on a stream definition

Stream stream = dev.getStream("ambient")

RecordSet record = new RecordSet(stream)
    .channel("temperature", 5)
    .channel("info", "cold")
    .channel("alarm", true)
    .location(new GeoJsonPoint(11, 45))
    .timestamp(Instant.now())
    ;

raptor.Stream().push(record)

Pull data

Retrieve data

// return 100 records from 10
int from = 10,
    size = 100;

ResultSet results = raptor.Stream().pull(stream, from, size);

Last update

Retrieve the last record sent based on the timestamp

ResultSet results = raptor.Stream().lastUpdate(stream);

Drop data

Removed the data stored in a stream

raptor.Stream().delete(stream);

Search for data

Search by time

Search for a range in the data timestamp

Instant i = Instant.now()

DataQuery q = new DataQuery()
    .timeRange(
        i.plus(500, ChronoUnit.MILLIS),
        i.plus(2500, ChronoUnit.MILLIS)
    );

log.debug("Searching {}", q.toJSON().toString());
ResultSet results = raptor.Stream().search(stream, q);

Search by numeric range

Search for a range in a numeric field

DataQuery q = new DataQuery()
    .range("temperature", -10, 10);

log.debug("Searching {}", q.toJSON().toString());
ResultSet results = raptor.Stream().search(stream, q);

Search by distance

Search data by distance using the location field

DataQuery q = new DataQuery()
    .distance(new GeoJsonPoint(11.45, 45.11), 10000, Metrics.KILOMETERS);

log.debug("Searching {}", q.toJSON().toString());
ResultSet results = raptor.Stream().search(stream, q);

Search by bounding box

Search data within an area using the location field

DataQuery q = new DataQuery()
    .boundingBox(new GeoJsonPoint(12, 45), new GeoJsonPoint(10, 44)));

log.debug("Searching {}", q.toJSON().toString());
ResultSet results = raptor.Stream().search(stream, q);

Action

The Action API handles status and triggering of device defined actions

Set status

Store the current status of an action

Action a = dev.action("light-control");
ActionStatus status = raptor.Action()
    .setStatus(a, a.getStatus().status("on"));

Get status

Get the current stored status of an action

Action a = dev.action("light-control");
ActionStatus status = raptor.Action()
    .getStatus(a);

Invoke an action

Trigger an action on the remote device

Action a = dev.action("light-control");
ActionStatus status = raptor.Action()
    .invoke(a);

Set the status of an action

Profile

The Profile API handles a per-user key-value local store

Set a value

Set a value by key

ObjectNode json = r.Profile().newObjectNode();
json.put("test", "foo");
json.put("size", 1000L);
json.put("valid", true);

r.Profile().set("test1", json);

Get a value

Get a value by key

JsonNode response = r.Profile().get("test1");

Get all values

Get all values

JsonNode response = r.Profile().get();

Tree

The Tree API handles hierarchical data structures

Create a node

Create a generic (type group) node tree

TreeNode node1 = TreeNode.create("Root1");
raptor.Tree().create(node1);

TreeNode child1 = TreeNode.create("child1");
TreeNode child2 = TreeNode.create("child2");

raptor.Tree().add(node1, Arrays.asList(child1));
raptor.Tree().add(child1, Arrays.asList(child2));

Create a device node

Create a device references inside the tree. Events from that device will be propagated to the parent nodes up to the root

raptor.Tree().add(child2, dev);

List trees

List all the trees available

List<TreeNode> list = raptor.Tree().list();

Delete a node

Delete a node, causing all the leaves to be point to the parent. In case of device node references, this will not remove the device

// drop child1 from previous example, child2 will be now direct children of Root1
raptor.Tree().remove(
    node1 //Root1
        .children().get(0) // child1
);

Admin

Admin APIs allow the management of users, tokens and permissions

For an up to date reference see the tests

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.