com.lhings.java

Class LhingsDevice

java.lang.Object

com.lhings.java.LhingsDevice

All Implemented Interfaces:

Runnable

public abstract class LhingsDevice
extends Object
implements Runnable

This abstract class is the base class for all the Java devices. Any device implemented with this library must extend LhingsDevice. Developers must override the method setup(), called once by the library to perform all initialization tasks required by the implementation, and the method loop(), called repeatedly by the library to execute the logic of the device. Also, methods annotated with null Action, Event and StatusComponent must be implemented to define the actions, events and status components of the device. The frequency at which the loop() method is executed can be set using the method setLoopFrequency(float frequency). This class also provides convenience methods to interact with and obtain information about other devices that belong to the same Lhings account as this one. See methods getDevices(), requestAction() , storeStatus(), getStatus(), and statusRetrieve().

Field Summary

Fields

Modifier and Type	Field and Description
protected static org.apache.log4j.Logger	log
protected static Properties	uuids

Constructor Summary

Constructors

Constructor and Description
LhingsDevice(String username, String password, int port, String deviceName) Creates a new device in Lhings associated to the account with the given username and password.
LhingsDevice(String username, String password, String deviceName) Creates a new device in Lhings associated to the account with the given username and password.

Method Summary

Methods

Modifier and Type	Method and Description
String	apiKey() Returns the Api-Key the device is using to connect with Lhings.
List<com.lhings.java.model.Device>	getDevices() This method returns a list of all the other devices that belong to the same account as the calling device.
float	getLoopFrequency() Returns the number of times per second the method loop() is executed by the SDK.
String	getManufacturer() Override this method if you want to specify your own manufacturer.
String	getModelName() Override this method if you want to specify your own model name.
String	getName() Returns the name of the device.
int	getPort() Used to retrieve the port used by this device to communicate with Lhings.
String	getSerialNumber() Override this method if you want to specify your own serial number Default serial number is "000001"
Map<String,Object>	getStatus(String uuid) Retrieves the status of the given device.
String	getType() Override this method if you want to specify your own device type Default device type is "javavirtualdevice"
String	getUsername() Returns the username of the account to which the device belongs.
String	getVersion() Override this method if you want to specify your own device version Default device version is "1"
Boolean	isDeviceConnected() Returns true if the device was successful in setting up a permanent communication channel with the Lhings server.
Boolean	isLogged() Returns true if the username and password combination provided was correct and the device was able to start session in Lhings.
void	logout() This method is called to close the session with lhings.
abstract void	loop() Implementations must override this method and put in it the device logic.
String	requestAction(String uuid, String actionName, Map<String,Object> arguments) Request another device to perform one of its actions.Both the action name and argument names must have been declared by the other device in its descriptor file.
void	run()
protected void	sendEvent(String name) Sends an event without payload to Lhings.
protected void	sendEvent(String name, String payload) Sends an event with payload to Lhings.
void	setLoopFrequency(float loopFrequency) Sets the number of times per second the method loop() is executed by the SDK.
abstract void	setup() Implementation must override this method and put in it all the initialization code required by device.
void	start() Start the device.
void	stop() Stops the device
void	storeStatus() Stores the value of all the status components of this device in Lhings.
String	uuid() Returns the unique UUID Lhings assigned to this device.

Methods inherited from class java.lang.Object

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

Field Detail

log

protected static final org.apache.log4j.Logger log

uuids

protected static final Properties uuids

Constructor Detail

LhingsDevice

public LhingsDevice(String username,
            String password,
            String deviceName)
             throws IOException,
                    LhingsException

Creates a new device in Lhings associated to the account with the given username and password. Username and password will not be stored in any way, they will be used only at runtime. If the device is created for the first time, it will be registered in Lhings and its UUID will be stored for the next time it is launched.

Parameters:

username - Username of the Lhings account.

password - Password of the account.

deviceName - The name of the device.

Throws:

IOException - If a network or connectivity error occurs.

LhingsException

LhingsDevice

public LhingsDevice(String username,
            String password,
            int port,
            String deviceName)
             throws IOException,
                    LhingsException

Creates a new device in Lhings associated to the account with the given username and password. Username and password will not be stored in any way, they will be used only at runtime. If the device is created for the first time, it will be registered in Lhings and its UUID will be stored for the next time it is launched.

Parameters:

username - Username of the Lhings account.

password - Password of the account.

port - The port the device will use to connect to the Internet for non-http communications.

deviceName - The name of the device.

Throws:

IOException - If a network or connectivity error occurs.

LhingsException

Method Detail

start

public void start()

Start the device. The device starts session in Lhings and executes the loop() method periodically.

stop

public void stop()

Stops the device

run

public void run()

Specified by:

run in interface Runnable

sendEvent

protected void sendEvent(String name)

Sends an event without payload to Lhings.

Parameters:

name - The name of the event. If no such event is defined for this device no event is sent but a warning is shown in the log of the application.

sendEvent

protected void sendEvent(String name,
             String payload)

Sends an event with payload to Lhings.

Parameters:

name - The name of the event. If no such event is defined for this device no event is sent but a warning is shown in the log of the application.

payload - The payload of the event.

isLogged

public Boolean isLogged()

Returns true if the username and password combination provided was correct and the device was able to start session in Lhings.

isDeviceConnected

public Boolean isDeviceConnected()

Returns true if the device was successful in setting up a permanent communication channel with the Lhings server.

getManufacturer

public String getManufacturer()

Override this method if you want to specify your own manufacturer. Default manufacturer is "Lhings"

Returns:

getModelName

public String getModelName()

Override this method if you want to specify your own model name. Default model name is "prototype".

Returns:

getSerialNumber

public String getSerialNumber()

Override this method if you want to specify your own serial number Default serial number is "000001"

Returns:

getType

public String getType()

Override this method if you want to specify your own device type Default device type is "javavirtualdevice"

Returns:

getVersion

public String getVersion()

Override this method if you want to specify your own device version Default device version is "1"

Returns:

logout

public void logout()

This method is called to close the session with lhings.

apiKey

public String apiKey()

Returns the Api-Key the device is using to connect with Lhings.

uuid

public String uuid()

Returns the unique UUID Lhings assigned to this device.

setup

public abstract void setup()

Implementation must override this method and put in it all the initialization code required by device.

loop

public abstract void loop()

Implementations must override this method and put in it the device logic. This method will be called periodically by the SDK. The frequency at which it is called is set by the method setLoopFrequency().

getPort

public int getPort()

Used to retrieve the port used by this device to communicate with Lhings.

Returns:

The port number.

getName

public String getName()

Returns the name of the device.

Returns:

getUsername

public String getUsername()

Returns the username of the account to which the device belongs.

Returns:

getLoopFrequency

public float getLoopFrequency()

Returns the number of times per second the method loop() is executed by the SDK.

Returns:

setLoopFrequency

public void setLoopFrequency(float loopFrequency)

Sets the number of times per second the method loop() is executed by the SDK. The SDK will do its best to execute the loop() at the frequency requested, but it does not guarantee neither precision nor constant frequency. The default value is 10 Hz.

getDevices

public List<com.lhings.java.model.Device> getDevices()
                                              throws LhingsException,
                                                     IOException

This method returns a list of all the other devices that belong to the same account as the calling device. Since this method communicates with Lhings over the Internet, the call is blocking. If this is an issue consider executing this call in another thread.

Returns:

A list of Device instances, with the following information: name, uuid and type of the device, and online status.

Throws:

IOException

LhingsException

getStatus

public Map<String,Object> getStatus(String uuid)
                             throws DeviceDoesNotExistException,
                                    DeviceUnreachableException,
                                    UnauthorizedException,
                                    LhingsException,
                                    IOException

Retrieves the status of the given device.

Parameters:

uuid - The uuid of the device whose status is to be retrieved.

Returns:

A map whose keys are the names of the status components of the device, and whose values are the values of those status components. If the given uuid is the same as that of the calling device, null is returned. If the device whose status is requested is offline, only one the online status component is returned.

Throws:

DeviceDoesNotExistException - If no device exists with that uuid.

DeviceUnreachableException - If the device could not be contacted over the internet.

UnauthorizedException - If the device exists but the calling device is not authorized to access its status.

LhingsException

IOException

storeStatus

public void storeStatus()
                 throws IOException,
                        LhingsException

Stores the value of all the status components of this device in Lhings.

Throws:

LhingsException

IOException

requestAction

public String requestAction(String uuid,
                   String actionName,
                   Map<String,Object> arguments)
                     throws IOException,
                            LhingsException

Request another device to perform one of its actions.Both the action name and argument names must have been declared by the other device in its descriptor file.

Parameters:

uuid - The uuid of the device that will perform the action.

actionName - The name of the action to be performed.

arguments - A Map with the name of the arguments of the action as keys and the values of those arguments as values.

Returns:

Throws:

IOException

LhingsException