The simplest way to create a client is to use DeviceHiveApi
class.
If you need to handle server events such as handle_command_insert
,
handle_command_update
or handle_notification
you'll have to extend Handler
class and use DeviceHive
class for it.
First of all you need to create DeviceHiveApi
object. Then you can use this
object for for API calls.
Example:
from devicehive import DeviceHiveApi
url = 'http://playground.devicehive.com/api/rest'
refresh_token = 'SOME_REFRESH_TOKEN'
device_hive_api = DeviceHiveApi(url, refresh_token=refresh_token)
If you want to use Websocket
protocol you need only to specify the url:
url = 'ws://playground.devicehive.com/api/websocket'
There are three ways of initial authentication:
- Using refresh token
- Using access token
- Using login and password
Examples:
from devicehive import DeviceHiveApi
url = 'ws://playground.devicehive.com/api/websocket'
device_hive_api = DeviceHiveApi(url, refresh_token='SOME_REFRESH_TOKEN')
from devicehive import DeviceHiveApi
url = 'ws://playground.devicehive.com/api/websocket'
device_hive_api = DeviceHiveApi(url, access_token='SOME_ACCESS_TOKEN')
from devicehive import DeviceHiveApi
url = 'ws://playground.devicehive.com/api/websocket'
device_hive_api = DeviceHiveApi(url, login='SOME_LOGIN', password='SOME_PASSWORD')
get_info()
method returns dict
with the next fields:
api_version
server_timestamp
rest_server_url
websocket_server_url
get_cluster_info()
method returns dict
with the next fields:
bootstrap.servers
zookeeper.connect
Example:
from devicehive import DeviceHiveApi
url = 'http://playground.devicehive.com/api/rest'
refresh_token = 'SOME_REFRESH_TOKEN'
device_hive_api = DeviceHiveApi(url, refresh_token=refresh_token)
info = device_hive_api.get_info()
print(info)
cluster_info = device_hive_api.get_cluster_info()
print(cluster_info)
get_property(name)
method returns dict
with the next fields:
entity_version
name
value
set_property(name, value)
method returns entity version.
delete_property(name)
method does not return anything.
Example:
from devicehive import DeviceHiveApi
url = 'http://playground.devicehive.com/api/rest'
refresh_token = 'SOME_REFRESH_TOKEN'
device_hive_api = DeviceHiveApi(url, refresh_token=refresh_token)
name = 'user.login.lastTimeoutSent'
entity_version = device_hive_api.set_property(name, 'value')
print(entity_version)
prop = device_hive_api.get_property(name)
print(prop)
device_hive_api.delete_property(name)
create_token(user_id, expiration, actions, network_ids, device_ids)
method
returns dict
with the next fields:
access_token
refresh_token
only user_id
is required.
refresh_token()
method refreshes the access token and returns it.
Example:
from devicehive import DeviceHiveApi
url = 'http://playground.devicehive.com/api/rest'
refresh_token = 'SOME_REFRESH_TOKEN'
device_hive_api = DeviceHiveApi(url, refresh_token=refresh_token)
tokens = device_hive_api.create_token(1)
print(tokens)
access_token = device_hive_api.refresh_token()
print(access_token)
list_devices(name, name_pattern, network_id, network_name, sort_field, sort_order, take, skip)
method returns list of Device
objects. All args are optional.
get_device(device_id)
method returns Device
object.
put_device(device_id, name, data, network_id, is_blocked)
method returns Device
object. Only device_id
is required.
list_commands(device_id, start, end, command, status, sort_field, sort_order, take, skip)
method returns list of Command
objects. Only device_id
is required.
send_command(device_id, command_name, parameters, lifetime, timestamp, status, result)
method returns Command
object.
Only device_id
and command_name
are required.
list_notifications(device_id, start, end, notification, sort_field, sort_order, take, skip)
method returns list of Notification
object. Only device_id
is required.
send_notification(device_id, notification_name, parameters, timestamp)
method returns Notification
object.
Only device_id
and notification_name
are required.
Properties:
id
(read only)name
data
network_id
device_type_id
is_blocked
Methods:
save()
method does not return anything.remove()
method does not return anything.list_commands(start, end, command, status, sort_field, sort_order, take, skip)
method returns list ofCommand
objects. All args are optional.send_command(command_name, parameters, lifetime, timestamp, status, result)
method returnsCommand
object. Onlycommand_name
is required.list_notifications(start, end, notification, sort_field, sort_order, take, skip)
method returns list ofNotification
objects. All args are optional.send_notification(notification_name, parameters, timestamp)
method returnsNotification
object. Onlynotification_name
is required.
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
Methods:
save()
method does not return anything.
Properties:
device_id
(read only)id
(read only)notification
(read only)parameters
(read only)timestamp
(read only)
Example:
from devicehive import DeviceHiveApi
url = 'http://playground.devicehive.com/api/rest'
refresh_token = 'SOME_REFRESH_TOKEN'
device_hive_api = DeviceHiveApi(url, refresh_token=refresh_token)
device_id = 'example-device'
device = device_hive_api.put_device(device_id)
device.name = 'new-device-name'
device.data = {'key': 'value'}
device.save()
devices = device_hive_api.list_devices()
for device in devices:
print('Device: %s, name: %s, data: %s' % (device.id, device.name,
device.data))
device.remove()
list_networks(name, name_pattern, sort_field, sort_order, take, skip)
method returns list of Network
objects. All args are optional.
get_network(network_id)
method returns Network
object.
create_network(name, description)
method returns Network
object.
Properties:
id
(read only)name
description
Methods:
save()
method does not return anything.remove(force)
method does not return anything. All args are optional.
Example:
from devicehive import DeviceHiveApi
url = 'http://playground.devicehive.com/api/rest'
refresh_token = 'SOME_REFRESH_TOKEN'
device_hive_api = DeviceHiveApi(url, refresh_token=refresh_token)
network_name = 'example-name'
network_description = 'example-description'
network = device_hive_api.create_network(network_name, network_description)
print(network.name)
list_device_types(name, name_pattern, sort_field, sort_order, take, skip)
method returns list of DeviceType
objects. All args are optional.
get_device_type(device_type_id)
method returns DeviceType
object.
create_device_type(name, description)
method returns DeviceType
object.
Properties:
id
(read only)name
description
Methods:
save()
method does not return anything.remove(force)
method does not return anything. All args are optional.
Example:
from devicehive import DeviceHiveApi
url = 'http://playground.devicehive.com/api/rest'
refresh_token = 'SOME_REFRESH_TOKEN'
device_hive_api = DeviceHiveApi(url, refresh_token=refresh_token)
device_type_name = 'example-name'
device_type_description = 'example-description'
device_type = device_hive_api.create_device_type(device_type_name,
device_type_description)
print(device_type.name)
list_users(login, login_pattern, role, status, sort_field, sort_order, take, skip)
method returns list of User
objects. All args are optional.
get_current_user()
method returns User
object.
get_user(user_id)
method returns User
object.
create_user(self, login, password, role, data, all_device_types_available)
method returns User
object.
Properties:
id
(read only)login
(read only)last_login
(read only)intro_reviewed
(read only)all_device_types_available
(read only)role
status
data
Methods:
save()
method does not return anything.update_password(password)
method does not return anything.remove()
method does not return anything.list_networks()
method Returns list ofNetwork
objects.list_device_types()
method Returns list ofDeviceType
objects.assign_network(network_id)
method does not return anything.unassign_network(network_id)
method does not return anything.assign_device_type(device_type_id)
method does not return anything.unassign_device_type(device_type_id)
method does not return anything.allow_all_device_types()
method does not return anything.disallow_all_device_types()
method does not return anything.
Example:
from devicehive import DeviceHiveApi
from devicehive.user import User
url = 'http://playground.devicehive.com/api/rest'
refresh_token = 'SOME_REFRESH_TOKEN'
device_hive_api = DeviceHiveApi(url, refresh_token=refresh_token)
login = 'example-login'
password = 'example-password'
role = User.CLIENT_ROLE
data = {'key': 'value'}
user = device_hive_api.create_user(login, password, role, data)
print(user.login)
First of all you need to create custom Handler
class.
Example of creating custom Handler
class:
from devicehive import Handler
class SimpleHandler(Handler):
def handle_connect(self):
info = self.api.get_info()
print(info)
self.api.disconnect()
handle_connect
is the only one required method. If you want to handle server
events you'll heed to implement handle_command_insert
, handle_command_update
and handle_notification
methods.
Example:
from devicehive import Handler
class SimpleHandler(Handler):
def handle_connect(self):
device_ids = ['example-device-1', 'example-device-2']
for device_id in device_ids:
device = self.api.put_device(device_id)
device.subscribe_insert_commands()
device.subscribe_update_commands()
device.subscribe_notifications()
def handle_command_insert(self, command):
print(command.command)
def handle_command_update(self, command):
print(command.command)
def handle_notification(self, notification):
print(notification.notification)
The second step is to use DeviceHive
class for creating connection to the
server.
Example:
from devicehive import Handler
from devicehive import DeviceHive
class SimpleHandler(Handler):
def handle_connect(self):
device_ids = ['example-device-1', 'example-device-2']
for device_id in device_ids:
device = self.api.put_device(device_id)
device.subscribe_insert_commands()
device.subscribe_update_commands()
device.subscribe_notifications()
def handle_command_insert(self, command):
print(command.command)
def handle_command_update(self, command):
print(command.command)
def handle_notification(self, notification):
print(notification.notification)
url = 'http://playground.devicehive.com/api/rest'
refresh_token = 'SOME_REFRESH_TOKEN'
dh = DeviceHive(SimpleHandler)
dh.connect(url, refresh_token=refresh_token)
If you need to initialize your handler you can do it the next way:
from devicehive import Handler
from devicehive import DeviceHive
class SimpleHandler(Handler):
def __init__(self, api, some_arg, some_kwarg):
Handler.__init__(self, api)
self._some_arg = some_arg
self._some_kwarg = some_kwarg
def handle_connect(self):
info = self.api.get_info()
print(info)
self.api.disconnect()
device_hive = DeviceHive(SimpleHandler, 'some_arg', some_kwarg='some_kwarg')
If you want to use Websocket
protocol you need only to specify the url:
url = 'ws://playground.devicehive.com/api/websocket'
There are three ways of initial authentication:
- Using refresh token
- Using access token
- Using login and password
Examples:
url = 'ws://playground.devicehive.com/api/websocket'
device_hive.connect(url, refresh_token='SOME_REFRESH_TOKEN')
url = 'ws://playground.devicehive.com/api/websocket'
device_hive.connect(url, access_token='SOME_ACCESS_TOKEN')
url = 'ws://playground.devicehive.com/api/websocket'
device_hive.connect(url, login='SOME_LOGIN', password='SOME_PASSWORD')
All api calls may be done via api
object. This object available inside
custom handler with self.api
property.
self.api.get_info()
method returns dict
. get_info
method of DeviceHiveApi
class is the wrapper on top of this call.
self.api.get_cluster_info()
method returns dict
. get_cluster_info
method of DeviceHiveApi
class is the wrapper on top of this call.
See the description of DeviceHiveApi
info methods for more details.
Example:
from devicehive import Handler
class SimpleHandler(Handler):
def handle_connect(self):
info = self.api.get_info()
print(info)
cluster_info = self.api.get_cluster_info()
print(cluster_info)
self.api.disconnect()
self.api.get_property(name)
method returns dict
. get_property
method of DeviceHiveApi
class is the wrapper on top of this call.
self.api.set_property(name, value)
method returns entity version. set_property
method of DeviceHiveApi
class is the wrapper on top of this call.
self.api.delete_property(name)
method does not return anything. delete_property
method of DeviceHiveApi
class is the wrapper on top of this call.
See the description of DeviceHiveApi
property methods for more details.
Example:
from devicehive import Handler
class SimpleHandler(Handler):
def handle_connect(self):
name = 'user.login.lastTimeoutSent'
prop = self.api.get_property(name)
print(prop)
entity_version = self.api.get_property(name, 'value')
print(entity_version)
self.api.delete_property(name)
self.api.disconnect()
self.api.create_token(user_id, expiration, actions, network_ids, device_ids)
method returns dict
. create_token
method of DeviceHiveApi
class is the wrapper on top of this call.
self.api.refresh_token()
method refreshes the access token and returns it. refresh_token
method of DeviceHiveApi
class is the wrapper on top of this call.
See the description of DeviceHiveApi
token methods for more details.
Example:
from devicehive import Handler
class SimpleHandler(Handler):
def handle_connect(self):
tokens = self.api.create_token(1)
print(tokens)
access_token = self.api.refresh_token()
print(access_token)
self.api.disconnect()
self.api.subscribe_insert_commands(device_id, network_ids, device_type_ids, names, timestamp)
method returns CommandsSubscription
object.
self.api.subscribe_update_commands(device_id, network_ids, device_type_ids, names, timestamp)
method returns CommandsSubscription
object.
Properties:
id
(read only)
Methods:
remove()
method does not return anything.
Example:
from devicehive import Handler
class SimpleHandler(Handler):
insert_subscription = None
update_subscription = None
def handle_connect(self):
device_id = 'example-device'
device = self.api.put_device(device_id)
command_name = 'example-command'
self.insert_subscription = self.api.subscribe_insert_commands(
device_id, [command_name])
self.update_subscription= self.api.subscribe_update_commands(
device_id, [command_name])
command = device.send_command(command_name)
command.status = 'new-status'
command.save()
def handle_command_insert(self, command):
print('Command insert: %s, status: %s.' % (command.command,
command.status))
def handle_command_update(self, command):
print('Command update: %s, status: %s.' % (command.command,
command.status))
self.insert_subscription.remove()
self.update_subscription.remove()
self.api.subscribe_notifications(device_id, network_ids, device_type_ids, names, timestamp)
method returns NotificationsSubscription
object.
Properties:
id
(read only)
Methods:
remove()
method does not return anything.
Example:
from devicehive import Handler
class SimpleHandler(Handler):
notification_subscription = None
def handle_connect(self):
device_id = 'example-device'
device = self.api.put_device(device_id)
notification_name = 'example-notification'
self.notification_subscription = self.api.subscribe_notifications(
device_id, [notification_name])
device.send_notification(notification_name)
def handle_notification(self, notification):
print('Notification: %s.' % notification.notification)
self.notification_subscription.remove()
self.api.list_devices(name, name_pattern, network_id, network_name, sort_field, sort_order, take, skip)
method returns list of Device
objects. list_devices
method of DeviceHiveApi
class is the wrapper on top of this call.
self.api.get_device(device_id)
method returns Device
object. get_device
method of DeviceHiveApi
class is the wrapper on top of this call.
self.api.put_device(device_id, name, data, network_id, device_type_id, is_blocked)
method does not return anything. put_device
method of DeviceHiveApi
class is the wrapper on top of this call.
self.api.list_commands(device_id, start, end, command, status, sort_field, sort_order, take, skip)
method returns list of Command
objects. list_commands
method of DeviceHiveApi
class is the wrapper on top of this call.
self.api.send_command(device_id, command_name, parameters, lifetime, timestamp, status, result)
method returns Command
object.
send_command
method of DeviceHiveApi
class is the wrapper on top of this call.
self.api.list_notifications(device_id, start, end, notification, sort_field, sort_order, take, skip)
method returns list of Notification
objects. list_notifications
method of DeviceHiveApi
class is the wrapper on top of this call.
self.api.send_notification(device_id, notification_name, parameters, timestamp)
method returns Notification
object.
send_notification
method of DeviceHiveApi
class is the wrapper on top of this call.
See the description of DeviceHiveApi
device methods for more details.
API device object has the same properties as device object.
API device object has all methods from device object and extends these methods with:
subscribe_insert_commands(names, timestamp)
method returnsCommandsSubscription
object. All args are optional.subscribe_update_commands(names, timestamp)
method returnsCommandsSubscription
object. All args are optional.subscribe_notifications(names, timestamp)
method returnsNotificationsSubscription
object. All args are optional.
API command object has the same properties as command object.
API command object has the same methods as command object.
API notification object has the same properties as notification object
Example:
from devicehive import Handler
class SimpleHandler(Handler):
def handle_connect(self):
device_id = 'example-device'
device = self.api.put_device(device_id)
device.name = 'new-device-name'
device.data = {'key': 'value'}
device.save()
devices = self.api.list_devices()
for device in devices:
print('Device: %s, name: %s, data: %s' % (device.id, device.name,
device.data))
device.remove()
self.api.disconnect()
self.api.list_networks(name, name_pattern, sort_field, sort_order, take, skip)
method returns list of Network
objects. list_networks
method of DeviceHiveApi
class is the wrapper on top of this call.
self.api.get_network(network_id)
method returns Network
object. get_network
method of DeviceHiveApi
class is the wrapper on top of this call.
self.api.create_network(name, description)
method returns Network
object. create_network
method of DeviceHiveApi
class is the wrapper on top of this call.
See the description of DeviceHiveApi
network methods for more details.
API network object has the same properties as network object.
API network object has all methods from network object and extends these methods with:
list_devices(name, name_pattern, sort_field, sort_order, take, skip)
method returns list ofDevice
objects. All args are optional.subscribe_insert_commands(names, timestamp)
method returnsCommandsSubscription
object. All args are optional.subscribe_update_commands(names, timestamp)
method returnsCommandsSubscription
object. All args are optional.subscribe_notifications(names, timestamp)
method returnsNotificationsSubscription
object. All args are optional.
Example:
from devicehive import Handler
class SimpleHandler(Handler):
def handle_connect(self):
network_name = 'example-name'
network_description = 'example-description'
network = self.api.create_network(network_name, network_description)
print(network.name)
self.api.disconnect()
self.api.list_device_types(name, name_pattern, sort_field, sort_order, take, skip)
method returns list of DeviceType
objects. list_device_types
method of DeviceHiveApi
class is the wrapper on top of this call.
self.api.get_device_type(device_type_id)
method returns DeviceType
object. get_device_type
method of DeviceHiveApi
class is the wrapper on top of this call.
self.api.create_device_type(name, description)
method returns DeviceType
object. create_device_type
method of DeviceHiveApi
class is the wrapper on top of this call.
See the description of DeviceHiveApi
device types methods for more details.
API device type object has the same properties as device type object.
API device type object has all methods from device type object and extends these methods with:
list_devices(name, name_pattern, sort_field, sort_order, take, skip)
method returns list ofDevice
objects. All args are optional.subscribe_insert_commands(names, timestamp)
method returnsCommandsSubscription
object. All args are optional.subscribe_update_commands(names, timestamp)
method returnsCommandsSubscription
object. All args are optional.subscribe_notifications(names, timestamp)
method returnsNotificationsSubscription
object. All args are optional.
Example:
from devicehive import Handler
class SimpleHandler(Handler):
def handle_connect(self):
device_type_name = 'example-name'
device_type_description = 'example-description'
device_type = self.api.create_device_type(device_type_name, device_type_description)
print(device_type.name)
self.api.disconnect()
self.api.list_users(login, login_pattern, role, status, sort_field, sort_order, take, skip)
method returns list of User
objects. list_users
method of DeviceHiveApi
class is the wrapper on top of this call.
self.api.get_current_user()
method returns User
object. get_current_user
method of DeviceHiveApi
class is the wrapper on top of this call.
self.api.get_user(user_id)
method returns User
object. get_user
method of DeviceHiveApi
class is the wrapper on top of this call.
self.api.create_user(self, login, password, role, data, all_device_types_available)
method returns User
object. create_user
method of DeviceHiveApi
class is the wrapper on top of this call.
See the description of DeviceHiveApi
user methods for more details.
API user object has the same properties as user object.
API user object has the same methods as user object.
Example:
from devicehive import Handler
from devicehive.user import User
class SimpleHandler(Handler):
def handle_connect(self):
login = 'example-login'
password = 'example-password'
role = User.CLIENT_ROLE
data = {'key': 'value'}
user = self.api.create_user(login, password, role, data)
print(user.login)
self.api.disconnect()
Here we will create one endpoint which sends notifications and other endpoint which receives these notifications.
On the first we will create receiver.py
:
from devicehive import Handler
from devicehive import DeviceHive
class ReceiverHandler(Handler):
def __init__(self, api, device_id='simple-example-device',
accept_command_name='accept_notifications'):
Handler.__init__(self, api)
self._device_id = device_id
self._accept_command_name = accept_command_name
self._device = None
def handle_connect(self):
self._device = self.api.put_device(self._device_id)
self._device.subscribe_insert_commands([self._accept_command_name])
self._device.subscribe_notifications()
def handle_command_insert(self, command):
print('Accept command "%s"' % self._accept_command_name)
command.status = 'accepted'
command.save()
def handle_notification(self, notification):
print('Notification "%s" received' % notification.notification)
url = 'ws://playground.devicehive.com/api/websocket'
refresh_token = 'SOME_REFRESH_TOKEN'
dh = DeviceHive(ReceiverHandler)
dh.connect(url, refresh_token=refresh_token)
On the next step we will create sender.py
from devicehive import Handler
from devicehive import DeviceHive
class SenderHandler(Handler):
def __init__(self, api, device_id='simple-example-device',
accept_command_name='accept_notifications',
num_notifications=10):
Handler.__init__(self, api)
self._device_id = device_id
self._accept_command_name = accept_command_name
self._num_notifications = num_notifications
self._device = None
def _send_notifications(self):
for num_notification in range(self._num_notifications):
notification = '%s-notification' % num_notification
self._device.send_notification(notification)
print('Sending notification "%s"' % notification)
self.api.disconnect()
def handle_connect(self):
self._device = self.api.get_device(self._device_id)
self._device.send_command(self._accept_command_name)
print('Sending command "%s"' % self._accept_command_name)
self._device.subscribe_update_commands([self._accept_command_name])
def handle_command_update(self, command):
if command.status == 'accepted':
print('Command "%s" accepted' % self._accept_command_name)
self._send_notifications()
url = 'http://playground.devicehive.com/api/rest'
refresh_token = 'SOME_REFRESH_TOKEN'
dh = DeviceHive(SenderHandler)
dh.connect(url, refresh_token=refresh_token)
Run python receiver.py
in the first terminal. And python sender.py
in the
second. The order of run is important. receiver.py
must be started first.
docker build -f Dockerfile.tests -t devicehive-tests .
You can run tests with refresh_token by setting ADMIN_REFRESH_TOKEN
and/or CLIENT_REFRESH_TOKEN
variable:
docker run -it -e ADMIN_REFRESH_TOKEN='SOME_ADMIN_REFRESH_TOKEN' devicehive-tests
Or with access_token by setting ADMIN_ACCESS_TOKEN
and/or CLIENT_ACCESS_TOKEN
variable:
docker run -it -e ADMIN_ACCESS_TOKEN='SOME_ADMIN_ACCESS_TOKEN' devicehive-tests
Or with user login and password by setting ADMIN_LOGIN
and ADMIN_PASSWORD
for admin account and/or CLIENT_LOGIN
and CLIENT_PASSWORD
for client account.
docker run -it -e ADMIN_LOGIN='SOME_ADMIN_LOGIN' -e ADMIN_PASSWORD='SOME_ADMIN_PASSWORD' devicehive-tests
To run tests with enabled requests logging you need to change LOG_LEVEL
variable:
docker run -it -e ADMIN_REFRESH_TOKEN='SOME_ADMIN_REFRESH_TOKEN' -e LOG_LEVEL='DEBUG' devicehive-tests
To run the specific test you need to set TEST
variable:
docker run -it -e TEST=test_api.py::test_get_info -e ADMIN_REFRESH_TOKEN='SOME_ADMIN_REFRESH_TOKEN' devicehive-tests