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:

• save() - updates Network

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