devicehive
a Twisted implementation of Device-Hive client protocol v8
What's new in 0.0.2
devicehive.DeviceDelegate
class was replaced withdevicehive.interfaces.IProtoHandler
interface.- long polling transport related classes were moved into separate module (
devicehive.poll
). - web-socket transport support has been added (
devicehive.ws
module). devicehive.auto.AutoFactory
was added - factory which select devicehive transport depends on info-call result.- under
devicehive.gateway
a few classes have been added which support creation of a custom gateway. - gateway's binary protocol has been added
- an IProtoHandler instance can implement logic for a few devices at once.
Prerequisites
Before reading this tutorial you should know a bit of Python. If you wish to work example in this tutorial you also have to install some software on your computer or target device:
- Python 2.7 http://python.org
- Twisted http://twistedmatrix.com
- devicehive python library http://devicehive.com
Installation
Certainly, you may skip this section and bundle entire devicehive library with your application. In some situations it may be a case. But more common way to work with devicehive library is to install it first. The simplest way to do this is to run command:
python setup.py install
In case if setuptools is installed on your computer the command above will automatically install devicehive library itself and all necessary dependencies (actually there is only one dependency - twisted). Otherwise you should to download and install dependencies manually or use one of methods described in Python Package Index tutorial http://wiki.python.org/moin/CheeseShopTutorial.
Creating a simple client
Creating a simple application using new version of library is not much harder then is was before.
The only difference is that now you need to implement devicehive.interfaces.IProtoHandler
interface
instead of overriding devicehive.DeviceDelegate
class methods.
This way now your application class has to implement all methods which IProtoHandler
interface defines.
This means that you class most likly will look like this:
class YourApplicationClass(object):
zope.interface.implements(devicehive.interfaces.IProtoHandler)
def on_apimeta(self, websocket_server, server_time):
pass
def on_connected(self):
pass
def on_connection_failed(self, reason) :
pass
def on_closing_connection(self):
pass
def on_failure(self, device_id, reason):
pass
def on_command(self, device_id, command, finished):
pass
For instance, if your application does not requires to handle transport failures then you
may leave on_failure
method empty.
Here I need to mention that during protocol-factory initialization it will set a reference to itself in
YourApplication.factory
attribute. And every devicehive protocol-factory implements
devicehive.interfaces.IProtoFactory
interface. And using factory methods an application of yours can
interact upon underlying devicehive protocol. For example, it can send a notification
message using self.factory.notify(...)
call. Or it can register one or more devices
using self.factory.device_save
method. For a simple application the most appropriate place to register
device would be on_connected method.
def on_connected(self):
self.factory.device_save(iDeviceInfoInstance)
A class which you pass into device_save method has to conform to devicehive.interfaces.IDeviceInfo
interface.
We suggested that implementation of IDeviceInfo
interface will not differ to much from application to application,
that is why we included it's typical implementation into devicehive.DeviceInfo
class. Also under devicehive.*
namespace
you will find a few other classes which will be helpfull during constuction of IDeviceInfo
object. These are:
devicehive.Network
is a typical implementation ofdevicehive.interfaces.INetwork
interface.devicehive.DeviceClass
- implementsdevicehive.interfaces.IDeviceClass
.- and
devicehive.Equipment
which implementsdevicehive.interfaces.IEquipment
interface. Please see complete description ofIProtoFactory
methods indevicehive.interfaces
module's documentation.
I would also like to note that protocol factories do not do any additional verifications and will allow you, lets say,
to call notify()
method even before devicehive connection had been established. Application of yours has to implement
all neccessary logic to avoid such situations.
In order to handle device-hive command your application has to allow it for specific device by
calling factory.subscribe method. Command handling should be done in on_command method. The procedure of command
handling in the new version of the library did not changed much. Except that in the new version on_command
method
expects device_info
variable and command
parameter now implements devicehive.interfaces.ICommand
interface.
The device_info
variable specifies for which device a command was sent.
Using device-hive gateway API
Device-Hive gateway is built on the same principles as the client API. devicehive.gateway.IGateway
defines the
interface to which every custom gateway has to be conformed to. Although in most cases it would be appropriate to
use devicehive.BaseGateway
class as a starting point of your custom implementation.
In file basic_gateway_example.py
you can see such an implementation. This example creates Gateway class instance.
A constructor of this class expects devicehive URL as it's first parameter and a class of protocol-factory as it's
second parameter. This protocol-factory will be used to form transport layer between gateway and device-hive server.
A end point and it's protocol factory define a channel and a protocol which will be used to transfer commands
between gateway and end device.
Thus to customize Gateway's behaviuor you need to override BaseGateway's class methods. An if you want to change
device-to-gateway transport you will need to provide a protocol-factory implementation of that transport into
gateway 'run' method.
Conclusion
In this tutorial we have implemented the simplest Device-Hive application. For more examples please see examples subdirectory under devicehive python library distribution. And of cause you may use python build-in help system to take a closer look at library's API. For further reading please see examples under examples folder.