DeviceHive Java Client Library & Examples
DeviceHive
DataArt
DeviceHive Client Library is an open source project based on Java. It can be used to build Android or Java applications.
DeviceHive turns any connected device into the part of Internet of Things.
It provides the communication layer, control software and multi-platform
libraries to bootstrap development of smart energy, home automation, remote
sensing, telemetry, remote control and monitoring software and much more.
devicehive-java-client
Creating client
Creating a client with a new version of library is very simple. First of all you need to initiate DeviceHive client:
DeviceHive deviceHive = DeviceHive.getInstance()
.init("http://devicehive.server.rest.url", "refreshToken", "accessToken");
or you can initiate the client without Access token. In this case DeviceHive will automaticaly get it:
DeviceHive deviceHive = DeviceHive.getInstance()
.init("http://devicehive.server.rest.url", "refreshToken");
DeviceHive class methods
getInfo() - gets server info
getClusterInfo() - gets cluster info
createToken(List<String> actions, Long userId, List<String> networkIds, List<String> deviceIds, DateTime expiration) - creates token
refreshToken() - refreshes token
getProperty(String name) - gets property by name
setProperty(String name, String value) - creates property
removeProperty(String name) - removes property by name
subscribeCommands(List<String> ids, CommandFilter commandFilter, DeviceCommandsCallback commandsCallback) - subcribes on specific commands by device ids and command filter parameters
subscribeNotifications(List<String> ids, NotificationFilter notificationFilter, notificationsCallback) - subcribes on specific notifications by device ids and notification filter parameters
unsubscribeCommands(List<String> ids, CommandFilter commandFilter) - updates current subcription or unsubscribes at all
unsubscribeNotifications(List<String> ids, NotificationFilter notificationFilter) - updates current subcription or unsubscribes at all
listNetworks(NetworkFilter filter) - gets list of Network
getNetwork(long id) - gets Network by network's id
removeNetwork(long id) - removes Network by id
createNetwork(String name, String description) - creates Network by id
listDevices(DeviceFilter filter) - gets list of Device
removeDevice(String id) - removes Device by id
getDevice(String id) - gets existing Device by id or creates new Device
putDevice(String id, String name) - creates Device
Creating device
To create device you just need an instance of DeviceHive and getDevice(String deviceId) that returns DHResponse<Device> object where will be FailureData object in case of any errors or Device object:
DHResponse<Device> devicehiveResponse = deviceHive.getDevice("example-device-Id");
if(devicehiveResponse.isSuccessful(){
Device device = devicehiveResponse.getData();
}else{
FailureData failureData = devicehiveResponse.getFailureData();
int code = failureData.getCode();
String message = failureData.getMessage();
}
Device class properties and methods
Device contains such properties and methods:
Properties:
id (read only)
name
data
network_id
is_blocked
Methods:
save() - updates Device
getCommands(DateTime startTimestamp, DateTime endTimestamp, int maxNumber) - gets Device's DeviceCommands
getNotifications(DateTime startTimestamp, DateTime endTimestamp) - gets Device's DeviceNotifications
sendCommand(String command, List<Parameter> parameters) - sends DeviceCommand
sendNotification(String notification, List<Parameter> parameters) - sends DeviceNotification
subscribeCommands(CommandFilter commandFilter, DeviceCommandsCallback commandCallback) - subscribes for DeviceCommands
subscribeNotifications(NotificationFilter notificationFilter, DeviceNotificationsCallback notificationCallback) - subscribes for DeviceNotifications
unsubscribeCommands(CommandFilter commandFilter) - unsubscribes from DeviceCommands that are not meeting filter criteria
unsubscribeAllCommands() - subscribes from all DeviceCommands
unsubscribeNotifications(NotificationFilter notificationFilter) - subscribes for DeviceNotifications that are not meeting filter criteria
unsubscribeAllNotifications() - subscribes from all DeviceNotifications
Working with Device Commands
To create command you just need to call
sendCommand(String command, List<Parameter> parameters) method that will return DHResponse<DeviceCommand> with DeviceCommand in case of success or FailureData with error message and HTTP response code in case of failure:
DHResponse<DeviceCommand> response = device.sendCommand("command name", parameters);
To subscribe on commands you just need to create CommandFilter where you can set all needed parameters and call subscribeCommands(CommandFilter commandFilter, final DeviceCommandsCallback commandCallback) method:
CommandFilter commandFilter = new CommandFilter();
commandFilter.setCommandNames(COM_A, COM_B);
commandFilter.setStartTimestamp(DateTime.now());
commandFilter.setMaxNumber(30);
device.subscribeCommands(commandFilter, new DeviceCommandsCallback() {
public void onSuccess(List<DeviceCommand> commands) {
}
}
public void onFail(FailureData failureData) {
}
});
DeviceCommand class properties and methods
DeviceCommand contains such properties:
id (read only)
user_id (read only)
command (read only)
parameters (read only)
lifetime (read only)
timestamp (read only)
last_updated (read only)
status
result
DeviceCommand contains such methods:
updateCommand - updates current command
fetchCommandStatus - gets command status
fetchCommandResult - gets command result
Working with Device Notifications
There us the same logic regarding DeviceNotification to create notification you just need to call
sendNotification(String notification, List<Parameter> parameters) method that will return DHResponse<DeviceNotification> with DeviceNotification in case of success or FailureData with error message and HTTP response code in case of failure:
DHResponse<DeviceNotification> response = device.sendNotification("notification name", parameters);
To subscribe on notifications you just need to create NotificationFilter where you can set all needed parameters and call subscribeNotifications(NotificationFilter notificationFilter, DeviceNotificationsCallback notificationCallback) method:
NotificationFilter notificationFilter = new NotificationFilter();
notificationFilter.setNotificationNames(NOTIFICATION_A, NOTIFICATION_B);
notificationFilter.setStartTimestamp(DateTime.now());
notificationFilter.setEndTimestamp(DateTime.now().plusSeconds(10));
device.subscribeNotifications(notificationFilter, new DeviceNotificationsCallback(){
public void onSuccess(List<DeviceNotification> notifications) {
}
public void onFail(FailureData failureData) {
}
});
DeviceNotification class properties
DeviceNotification contains such properties:
device_id (read only)
id (read only)
notification (read only)
parameters (read only)
timestamp (read only)
Working with Network
To create Network you just need to call createNetwork(String name, String description) method of DeviceHive class
DHResponse<Network> response = deviceHive.createNetwork("My Network's name", "My network's description");
also you can get Network by id deviceHive.getNetwork(long id) or get list of Network with deviceHive. listNetworks(NetworkFilter filter)
DHResponse<NetworkVO> response = deviceHive.getNetwork(response.getData().getId());
Network class properties and methods
Properties:
id (read only)
name
description
Methods:
Working with User
To create User you just need to call createUser(String lastLogin, String password, User.RoleEnum role, StatusEnum status, JsonObject data) method of DeviceHive class
DHResponse<User> response = deviceHive.createUser("javaLibTest", "123456", RoleEnum.ADMIN, StatusEnum.ACTIVE, null);
also you can get User by critria deviceHive.getUsers(UserFilter filter) or just get current User deviceHive.getCurrentUser()
DHResponse<User> response = deviceHive.getCurrentUser();
User class properties and methods
Properties:
id (read only)
lastLogin
role
password (write only)
data
Methods:
save() - updates User
getNetworks() - gets list of Networks assigned to this user
assignNetwork(long networkId) - assigns Network to this user
unassignNetwork(long networkId) - unassigns Network to this user
Download
Add the JitPack repository to your project build file
allprojects {
repositories {
...
maven { url 'https://jitpack.io' }
}
}
Gradle is the only supported build configuration, so just add the dependency to your project build.gradle file:
dependencies {
compile 'com.github.devicehive:devicehive-java:3.1.2'
}
DeviceHive Server
Java Server code was moved to a separate repository: https://github.com/devicehive/devicehive-java-server
DeviceHive license
[DeviceHive] is developed by [DataArt] Apps and distributed under Open Source
Apache 2.0. This basically means
you can do whatever you want with the software as long as the copyright notice
is included. This also means you don't have to contribute the end product or
modified sources back to Open Source, but if you feel like sharing, you are
highly encouraged to do so!
© Copyright 2018 DataArt Apps © All Rights Reserved