com.ibm.wiotp.sdk.device

Class ManagedDevice

java.lang.Object

com.ibm.wiotp.sdk.AbstractClient

com.ibm.wiotp.sdk.device.DeviceClient

com.ibm.wiotp.sdk.device.ManagedDevice

All Implemented Interfaces:

Runnable, org.eclipse.paho.client.mqttv3.IMqttMessageListener, org.eclipse.paho.client.mqttv3.MqttCallback, org.eclipse.paho.client.mqttv3.MqttCallbackExtended

public class ManagedDevice
extends DeviceClient
implements org.eclipse.paho.client.mqttv3.IMqttMessageListener, Runnable

A managed device class, used by device, that connects the device as managed device to IBM Watson IoT Platform and enables devices to perform one or more Device Management operations,

The device management feature enhances the Watson IoT Platform service with new capabilities for managing devices.

What does Device Management add?

• Control and management of device lifecycles for both individual and batches of devices.
• Device metadata and status information, enabling the creation of device dashboards and other tools.
• Diagnostic information, both for connectivity to the Watson IoT Platform service, and device diagnostics.
• Device management commands, like firmware update, and device reboot.

This is a derived class from DeviceClient and can be used by embedded devices to perform both Device operations and Device Management operations, i.e, the devices can use this class to do the following,

• Publish device events
• Subscribe to commands from application
• Perform Device management operations like, manage, unmanage, firmware update, reboot, update location, Diagnostics informations, Factory Reset and etc..

Field Summary

Fields inherited from class com.ibm.wiotp.sdk.device.DeviceClient

commandCallbacks, messageCodecs, messageCodecsByFormat

Fields inherited from class com.ibm.wiotp.sdk.AbstractClient

CLIENT_ID_DELIMITER, config, DEFAULT_ACTION_TIMEOUT, DEFAULT_DISCONNECTED_BUFFER_SIZE, DEFAULT_MAX_CONNECT_ATTEMPTS, DEFAULT_MAX_INFLIGHT_MESSAGES, DEFAULT_MESSAGING_QOS, disconnectRequested, gson, messageCount, mqttAsyncClient, mqttCallback, mqttClient, mqttClientOptions, persistence

Constructor Summary

Constructors

Constructor and Description
ManagedDevice(DeviceConfig config, DeviceData deviceData) Constructor that creates a ManagedDevice object, but does not connect to IBM Watson IoT Platform connect yet

Method Summary

Modifier and Type	Method and Description
void	addCustomActionHandler(CustomActionHandler actionHandler) Adds a device action handler which is of type CustomActionHandler
void	addDeviceActionHandler(DeviceActionHandler actionHandler) Adds a device action handler which is of type DeviceActionHandler
int	addErrorCode(int errorCode) Adds the current errorcode to IBM Watson IoT Platform.
void	addFirmwareHandler(DeviceFirmwareHandler fwHandler) Adds a firmware handler for this device, that is of type DeviceFirmwareHandler
int	addLog(String message, Date timestamp, LogSeverity severity) Appends a Log message to the Watson IoT Platform.
int	addLog(String message, Date timestamp, LogSeverity severity, String data) The Log message that needs to be added to the Watson IoT Platform.
int	clearErrorCodes() Clear the Error Codes from IBM Watson IoT Platform for this device
int	clearLogs() Clear the Logs from IBM Watson IoT Platform for this device
void	connect() This method just connects to the IBM Watson IoT Platform, Device needs to make a call to manage() to participate in Device Management activities.
void	disconnect() Disconnects from IBM Watson IoT Platform
DeviceData	getDeviceData()
void	messageArrived(String topic, org.eclipse.paho.client.mqttv3.MqttMessage message) The Device client does not currently support subscriptions.
void	publish(String topic, com.google.gson.JsonObject payload)
void	publish(String topic, com.google.gson.JsonObject payload, int qos) Publish the Device management response to IBm Watson IoT Platform
protected org.eclipse.paho.client.mqttv3.IMqttDeliveryToken	publish(String topic, org.eclipse.paho.client.mqttv3.MqttMessage message)
void	run()
com.google.gson.JsonObject	sendAndWait(String topic, com.google.gson.JsonObject jsonPayload, long timeout) Send the message and waits for the response from IBM Watson IoT Platform
boolean	sendManageRequest(long lifetime, boolean supportFirmwareActions, boolean supportDeviceActions) Send a device manage request to Watson IoT Platform
boolean	sendManageRequest(long lifetime, boolean supportFirmwareActions, boolean supportDeviceActions, List<String> bundleIds) Send a device manage request to Watson IoT Platform
boolean	sendManageRequest(long lifetime, boolean supportFirmwareActions, boolean supportDeviceActions, String bundleId) Send a device manage request to Watson IoT Platform
boolean	sendUnmanageRequest() Moves the device from managed state to unmanaged state A device uses this request when it no longer needs to be managed.
void	subscribe(String[] topics, int[] qos, org.eclipse.paho.client.mqttv3.IMqttMessageListener[] listeners) Subscribe the given listeners to the given topics
void	subscribe(String topic, int qos, org.eclipse.paho.client.mqttv3.IMqttMessageListener listener) Subscribe the given listener to the given topic
void	unsubscribe(String topic) UnSubscribe the library from the given topic
void	unsubscribe(String[] topics) UnSubscribe the library from the given topics
int	updateLocation(Double latitude, Double longitude, Double elevation) Update the location.
int	updateLocation(Double latitude, Double longitude, Double elevation, Date measuredDateTime) Update the location of the device.
int	updateLocation(Double latitude, Double longitude, Double elevation, Date measuredDateTime, Double accuracy) Update the location of the device.

Methods inherited from class com.ibm.wiotp.sdk.device.DeviceClient

connectComplete, connectionLost, deliveryComplete, publishEvent, publishEvent, reconnect, registerCodec, registerCommandCallback

Methods inherited from class com.ibm.wiotp.sdk.AbstractClient

close, configureMqttClient, getConfig, isConnected, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ManagedDevice

public ManagedDevice(DeviceConfig config,
                     DeviceData deviceData)
              throws Exception

Constructor that creates a ManagedDevice object, but does not connect to IBM Watson IoT Platform connect yet

Parameters:

config - Configuration for the device

deviceData - The Device Model

Throws:

Exception - If the essential parameters are not set

Method Detail

getDeviceData

public DeviceData getDeviceData()

connect

public void connect()
             throws org.eclipse.paho.client.mqttv3.MqttException,
                    KeyManagementException,
                    NoSuchAlgorithmException

This method just connects to the IBM Watson IoT Platform, Device needs to make a call to manage() to participate in Device Management activities.

This method does nothing if the device is already connected. Also, this method does not retry when the following exceptions occur.

• MqttSecurityException - One or more credentials are wrong
• UnKnownHostException - Host doesn't exist. For example, a wrong organization name is used to connect.

Overrides:

connect in class DeviceClient

Throws:

org.eclipse.paho.client.mqttv3.MqttException - see above

NoSuchAlgorithmException - TLS issues

KeyManagementException - TLS issues

sendManageRequest

public boolean sendManageRequest(long lifetime,
                                 boolean supportFirmwareActions,
                                 boolean supportDeviceActions,
                                 List<String> bundleIds)
                          throws org.eclipse.paho.client.mqttv3.MqttException

Send a device manage request to Watson IoT Platform

A Device uses this request to become a managed device. It should be the first device management request sent by the Device after connecting to the IBM Watson IoT Platform. It would be usual for a device management agent to send this whenever is starts or restarts.

This method connects the device to Watson IoT Platform connect if its not connected already

Parameters:

lifetime - The length of time in seconds within which the device must send another Manage device request. if set to 0, the managed device will not become dormant. When set, the minimum supported setting is 3600 (1 hour).

supportFirmwareActions - Tells whether the device supports firmware actions or not. The device must add a firmware handler to handle the firmware requests.

supportDeviceActions - Tells whether the device supports Device actions or not. The device must add a Device action handler to handle the reboot and factory reset requests.

bundleIds - List of Device Management Extension bundleIds

Returns:

boolean response containing the status of the manage request

Throws:

org.eclipse.paho.client.mqttv3.MqttException - When there is a failure

sendManageRequest

public boolean sendManageRequest(long lifetime,
                                 boolean supportFirmwareActions,
                                 boolean supportDeviceActions,
                                 String bundleId)
                          throws org.eclipse.paho.client.mqttv3.MqttException

Send a device manage request to Watson IoT Platform

A Device uses this request to become a managed device. It should be the first device management request sent by the Device after connecting to the IBM Watson IoT Platform. It would be usual for a device management agent to send this whenever is starts or restarts.

This method connects the device to Watson IoT Platform connect if its not connected already

Parameters:

lifetime - The length of time in seconds within which the device must send another Manage device request. if set to 0, the managed device will not become dormant. When set, the minimum supported setting is 3600 (1 hour).

supportFirmwareActions - Tells whether the device supports firmware actions or not. The device must add a firmware handler to handle the firmware requests.

supportDeviceActions - Tells whether the device supports Device actions or not. The device must add a Device action handler to handle the reboot and factory reset requests.

bundleId - Unique identifier for a device management extension

Returns:

boolean response containing the status of the manage request

Throws:

org.eclipse.paho.client.mqttv3.MqttException - When there is a failure

sendManageRequest

public boolean sendManageRequest(long lifetime,
                                 boolean supportFirmwareActions,
                                 boolean supportDeviceActions)
                          throws org.eclipse.paho.client.mqttv3.MqttException

Send a device manage request to Watson IoT Platform

A Device uses this request to become a managed device. It should be the first device management request sent by the Device after connecting to the IBM Watson IoT Platform. It would be usual for a device management agent to send this whenever is starts or restarts.

This method connects the device to Watson IoT Platform connect if its not connected already

Parameters:

lifetime - The length of time in seconds within which the device must send another Manage device request. if set to 0, the managed device will not become dormant. When set, the minimum supported setting is 3600 (1 hour).

supportFirmwareActions - Tells whether the device supports firmware actions or not. The device must add a firmware handler to handle the firmware requests.

supportDeviceActions - Tells whether the device supports Device actions or not. The device must add a Device action handler to handle the reboot and factory reset requests.

Returns:

boolean response containing the status of the manage request

Throws:

org.eclipse.paho.client.mqttv3.MqttException - When there is a failure

updateLocation

public int updateLocation(Double latitude,
                          Double longitude,
                          Double elevation)

Update the location.

Parameters:

latitude - Latitude in decimal degrees using WGS84

longitude - Longitude in decimal degrees using WGS84

elevation - Elevation in meters using WGS84

Returns:

code indicating whether the update is successful or not (200 means success, otherwise unsuccessful)

updateLocation

public int updateLocation(Double latitude,
                          Double longitude,
                          Double elevation,
                          Date measuredDateTime)

Update the location of the device. This method converts the date in the required format. The caller just need to pass the date in java.util.Date format

Parameters:

latitude - Latitude in decimal degrees using WGS84

longitude - Longitude in decimal degrees using WGS84

elevation - Elevation in meters using WGS84

measuredDateTime - When the location information is retrieved

Returns:

code indicating whether the update is successful or not (200 means success, otherwise unsuccessful)

updateLocation

public int updateLocation(Double latitude,
                          Double longitude,
                          Double elevation,
                          Date measuredDateTime,
                          Double accuracy)

Update the location of the device. This method converts the date in the required format. The caller just need to pass the date in java.util.Date format

Parameters:

latitude - Latitude in decimal degrees using WGS84

longitude - Longitude in decimal degrees using WGS84

elevation - Elevation in meters using WGS84

measuredDateTime - When the location information is retrieved

accuracy - Accuracy of the position in meters

Returns:

code indicating whether the update is successful or not (200 means success, otherwise unsuccessful)

clearErrorCodes

public int clearErrorCodes()

Clear the Error Codes from IBM Watson IoT Platform for this device

Returns:

code indicating whether the clear operation is successful or not (200 means success, otherwise unsuccessful)

clearLogs

public int clearLogs()

Clear the Logs from IBM Watson IoT Platform for this device

Returns:

code indicating whether the clear operation is successful or not (200 means success, otherwise unsuccessful)

addErrorCode

public int addErrorCode(int errorCode)

Adds the current errorcode to IBM Watson IoT Platform.

Parameters:

errorCode - The "errorCode" is a current device error code that needs to be added to the Watson IoT Platform.

Returns:

code indicating whether the update is successful or not (200 means success, otherwise unsuccessful)

addLog

public int addLog(String message,
                  Date timestamp,
                  LogSeverity severity)

Appends a Log message to the Watson IoT Platform.

Parameters:

message - The Log message that needs to be added to the Watson IoT Platform.

timestamp - The Log timestamp

severity - the Log severity

Returns:

code indicating whether the update is successful or not (200 means success, otherwise unsuccessful)

addLog

public int addLog(String message,
                  Date timestamp,
                  LogSeverity severity,
                  String data)

The Log message that needs to be added to the Watson IoT Platform.

Parameters:

message - The Log message that needs to be added to the Watson IoT Platform.

timestamp - The Log timestamp

severity - The Log severity

data - The optional diagnostic string data - The library will encode the data in base64 format as required by the Platform

Returns:

code indicating whether the update is successful or not (200 means success, otherwise unsuccessful)

sendUnmanageRequest

public boolean sendUnmanageRequest()
                            throws org.eclipse.paho.client.mqttv3.MqttException

Moves the device from managed state to unmanaged state A device uses this request when it no longer needs to be managed. This means Watson IoT Platform will no longer send new device management requests to this device and device management requests from this device will be rejected apart from a Manage device request

Returns:

True if the unmanage command is successful

Throws:

org.eclipse.paho.client.mqttv3.MqttException - When failure

subscribe

public void subscribe(String topic,
                      int qos,
                      org.eclipse.paho.client.mqttv3.IMqttMessageListener listener)
               throws org.eclipse.paho.client.mqttv3.MqttException

Subscribe the given listener to the given topic

This method is used by the library to subscribe to each of the topic where IBM Watson IoT Platform will send the DM requests

Parameters:

topic - topic to be subscribed

qos - Quality of Service for the subscription

listener - The IMqttMessageListener for the given topic

Throws:

org.eclipse.paho.client.mqttv3.MqttException - When subscription fails

subscribe

public void subscribe(String[] topics,
                      int[] qos,
                      org.eclipse.paho.client.mqttv3.IMqttMessageListener[] listeners)
               throws org.eclipse.paho.client.mqttv3.MqttException

Subscribe the given listeners to the given topics

This method is used by the library to subscribe to each of the topic where IBM Watson IoT Platform will send the DM requests

Parameters:

topics - List of topics to be subscribed

qos - Quality of Service for the subscription

listeners - The list of IMqttMessageListeners for the given topics

Throws:

org.eclipse.paho.client.mqttv3.MqttException - When subscription fails

unsubscribe

public void unsubscribe(String topic)
                 throws org.eclipse.paho.client.mqttv3.MqttException

UnSubscribe the library from the given topic

This method is used by the library to unsubscribe each of the topic where IBM Watson IoT Platform will send the DM requests

Parameters:

topic - topic to be unsubscribed

Throws:

org.eclipse.paho.client.mqttv3.MqttException - when unsubscribe fails

unsubscribe

public void unsubscribe(String[] topics)
                 throws org.eclipse.paho.client.mqttv3.MqttException

UnSubscribe the library from the given topics

This method is used by the library to unsubscribe each of the topic where IBM Watson IoT Platform will send the DM requests

Parameters:

topics - topics to be unsubscribed

Throws:

org.eclipse.paho.client.mqttv3.MqttException - when unsubscribe fails

publish

protected org.eclipse.paho.client.mqttv3.IMqttDeliveryToken publish(String topic,
                                                                    org.eclipse.paho.client.mqttv3.MqttMessage message)
                                                             throws org.eclipse.paho.client.mqttv3.MqttException

Throws:

org.eclipse.paho.client.mqttv3.MqttException

publish

public void publish(String topic,
                    com.google.gson.JsonObject payload,
                    int qos)
             throws org.eclipse.paho.client.mqttv3.MqttException

Publish the Device management response to IBm Watson IoT Platform

This method is used by the library to respond to each of the Device Management commands from IBM Watson IoT Platform

Parameters:

topic - Topic where the response to be published

payload - the Payload

qos - The Quality Of Service

Throws:

org.eclipse.paho.client.mqttv3.MqttException - When MQTT operation fails

publish

public void publish(String topic,
                    com.google.gson.JsonObject payload)
             throws org.eclipse.paho.client.mqttv3.MqttException

Throws:

org.eclipse.paho.client.mqttv3.MqttException

sendAndWait

public com.google.gson.JsonObject sendAndWait(String topic,
                                              com.google.gson.JsonObject jsonPayload,
                                              long timeout)
                                       throws org.eclipse.paho.client.mqttv3.MqttException

Send the message and waits for the response from IBM Watson IoT Platform

This method is used by the library to send following messages to IBM Watson IoT Platform

• Manage
• Unmanage
• Location update
• Diagnostic update/clear

Parameters:

topic - Topic where the message to be sent

jsonPayload - The message

timeout - How long to wait for the response

Returns:

response in Json format

Throws:

org.eclipse.paho.client.mqttv3.MqttException - when MQTT operation fails

disconnect

public void disconnect()

Disconnects from IBM Watson IoT Platform

Overrides:

disconnect in class AbstractClient

messageArrived

public void messageArrived(String topic,
                           org.eclipse.paho.client.mqttv3.MqttMessage message)

Description copied from class: DeviceClient

The Device client does not currently support subscriptions.

Specified by:

messageArrived in interface org.eclipse.paho.client.mqttv3.IMqttMessageListener

Specified by:

messageArrived in interface org.eclipse.paho.client.mqttv3.MqttCallback

Overrides:

messageArrived in class DeviceClient

run

public void run()

Specified by:

run in interface Runnable

addFirmwareHandler

public void addFirmwareHandler(DeviceFirmwareHandler fwHandler)
                        throws Exception

Adds a firmware handler for this device, that is of type DeviceFirmwareHandler

If the device supports firmware update, the abstract class DeviceFirmwareHandler should be extended by the device code. The DeviceFirmwareHandler.downloadFirmware(com.ibm.wiotp.sdk.devicemgmt.DeviceFirmware) and DeviceFirmwareHandler.updateFirmware(com.ibm.wiotp.sdk.devicemgmt.DeviceFirmware) must be implemented to handle the firmware actions.

Parameters:

fwHandler - DeviceFirmwareHandler that handles the Firmware actions

Throws:

Exception - throws an exception if a handler is already added

addDeviceActionHandler

public void addDeviceActionHandler(DeviceActionHandler actionHandler)
                            throws Exception

Adds a device action handler which is of type DeviceActionHandler

If the device supports device actions like reboot and factory reset, the abstract class DeviceActionHandler should be extended by the device code. The DeviceActionHandler.handleReboot(com.ibm.wiotp.sdk.devicemgmt.DeviceAction) and DeviceActionHandler.handleFactoryReset(com.ibm.wiotp.sdk.devicemgmt.DeviceAction) must be implemented to handle the actions.

Parameters:

actionHandler - DeviceActionHandler that handles the Reboot and Factory reset actions

Throws:

Exception - throws an exception if a handler is already added

addCustomActionHandler

public void addCustomActionHandler(CustomActionHandler actionHandler)
                            throws Exception

Adds a device action handler which is of type CustomActionHandler

If a Gateway or Device supports custom actions, this abstract class CustomActionHandler should be extended by the Gateway or Device code.

The method CustomActionHandler.handleCustomAction(com.ibm.wiotp.sdk.CustomAction) must be implemented by the subclass to handle the actions sent by the IBM Watson IoT Platform.

Parameters:

actionHandler - Handler to handle the custom action

Throws:

Exception - Thrown if an error occurs when setting action handler