Reference

API Layer

Implementation of the relayr HTTP RESTful API as individual endpoints.

This module contains the API class with one method for each API endpoint. All method names start with the HTTP method followed by the resource name used in that endpoint e.g. post_user_app for the endpoint POST /users/<id>/apps/<id> with minor modifications.

relayr.api.create_logger(sender)

Create a logger for the requesting object.

relayr.api.build_curl_call(method, url, data=None, headers=None)

Build and return a curl command for use on the command-line.

Parameters:

• method (string) – HTTP request method, GET, POST, etc.
• url (string) – Full HTTP path.
• data (object serializable as JSON) – Data to be transmitted, usually posted.
• headers (dictionary) – Additional HTTP request headers.

Return type:

string

Example:

cmd = build_curl_call('POST', 'http://foo.com/bar', data={'x': 42},
        headers={'SUPER_SECRET_KEY': '123'})
print(cmd)
curl -X POST "http://foo.com/bar" -H "SUPER_SECRET_KEY: 123" --data "{"x": 42}"

class relayr.api.Api(token=None)

This class provides direct access to the relayr API endpoints.

Examples:

# Create an anonymous client and call simple API endpoints:
from relayr.api import Api
a = Api()
assert a.get_server_status() == {'database': 'ok'}
assert a.get_users_validate('god@in.heaven') == {'exists': False}
assert a.get_public_device_model_meanings() > 0

__init__(token=None)

Object construction.

Parameters:token (string) – A token generated on the relayr platform for a combination of a relayr user and application.

perform_request(method, url, data=None, headers=None)

Perform an API call and return a JSON result as Python data structure.

Parameters:

• method (string) – HTTP request method, GET, POST, etc.
• url (string) – Full HTTP path.
• data (object serializable as JSON) – Data to be transmitted, usually posted.
• headers (dictionary) – Additional HTTP request headers.

Return type:

string

Query parameters are expected in the url parameter. For returned status codes other than 2XX a RelayrApiException is raised which contains the API call (method and URL) plus a curl command replicating the API call for debugging reuse on the command-line.

get_users_validate(userEmail)

Get a user email address validation.

Parameters:userEmail (string) – The user email address to be validated. Return type:A dict with an exists field and a Boolean result value.

Sample result:

{"exists": True}

get_server_status()

Get server status.

Return type:A dict with certain fields describing the server status.

Sample result:

{"database": "ok"}

post_oauth2_token(clientID, clientSecret, code, redirectURI)

Generate and return an OAuth2 access token from supplied parameters.

Parameters:

• clientID (string) – The client’s UUID.
• clientSecret (string) – The OAuth client secret.
• code (string) – The OAuth authorization code (valid for five minutes).
• redirectURI (string) – The redirect URI.

Return type:

dict with two fields, “access_token” and “token_type” (with string values for both)

get_oauth2_appdev_token(appID)

Get a token representing a specific relayr application and user.

Parameters:appID (string) – The application’s UUID. Return type:A dict with fields describing the token.

Sample result (anonymized token value):

{
    "token": "...",
    "expiryDate": "2014-10-08T10:14:07.789Z"
}

post_oauth2_appdev_token(appID)

Generate a new token representing a user and a relayr application.

Parameters:appID (string) – The application’s UUID. Return type:A dict with fields describing the token.

delete_oauth2_appdev_token(appID)

Revoke token for an application with given UUID.

Parameters:appID (string) – The application’s UUID.

get_oauth2_user_info()

Return information about the user initiating the request.

Return type:A dictionary with fields describing the user.

Sample result (partly anonymized values):

{
    "email": "joe@foo.com",
    "id": "...",
    "name": "joefoo"
}

patch_user(userID, name=None, email=None)

Update user’s name or email attribute, or both.

Parameters:

• userID (string) – the users’s UUID
• name (string) – the user name to be set
• email (string) – the user email to be set

Return type:

dict with user info fields

post_user_app(userID, appID)

Install a new app for a specific user.

Parameters:

• userID (string) – the users’s UUID
• appID (string) – The application’s UUID.

delete_user_app(userID, appID)

Uninstall an app of a user with the respective UUIDs.

Parameters:

• userID (string) – the users’s UUID
• appID (string) – the app’s UUID

get_user_publishers(userID)

Get all publishers owned by a user with a specific UUID.

Parameters:userID (string) – the users’s UUID Return type:list of dicts representing publishers

get_user_apps(userID)

Get all apps installed for a user with a specific UUID.

Parameters:userID (string) – the users’s UUID Return type:list of dicts ... with UUIDs and secrets

get_user_transmitters(userID)

Get all transmitters for a user with a specific UUID.

Parameters:userID (string) – the users’s UUID Return type:list of dicts with UUIDs and secrets

get_user_devices(userID)

Get all devices registered for a user with a specific UUID.

Parameters:userID (string) – the users’s UUID Return type:list of dicts ...

get_user_devices_bookmarks(userID)

Get a list of devices bookmarked by a specific user.

Parameters:userID (string) – the users’s UUID Return type:list of dicts, each representing a device

Sample result (anonymized UUIDs):

[{u'firmwareVersion': u'1.0.0',
  u'id': '...',
  u'model': '...',
  u'name': 'My Wunderbar Microphone',
  u'owner': '...',
  u'public': True,
  u'secret': '238885'}]

post_user_devices_bookmark(userID, deviceID)

Bookmark a specific public device for a specific user.

Parameters:

• userID (string) – the users’s UUID
• deviceID (string) – the UUID of the device to be bookmarked

Return type:

list of dicts ...

Sample result (anonymized UUIDs):

{'createdAt': '2014-11-05T16:31:06.429Z',
 'deviceId': '...',
 'userId': '...'}

delete_user_devices_bookmark(userID, deviceID)

Delete a bookmark for a specific user and device.

Parameters:

• userID (string) – the users’s UUID
• deviceID (string) – the device’s UUID

Return type:

None

post_user_wunderbar(userID)

Get the UUIDs and secrets of the master module and sensor modules.

Parameters:userID (string) – the users’s UUID Return type:dict with information about master and sensor modules/devices

Sample result (abbreviated, some values anonymized):

{
    "bridge": { ... },
    "microphone": {
        "name": "My Wunderbar Microphone",
        "public": False,
        "secret": "......",
        "owner": "...",
        "model": {
            "readings": [
                {
                    "meaning": "noise_level",
                    "unit": "dba"
                }
            ],
            "manufacturer": "Relayr GmbH",
            "id": "...",
            "name": "Wunderbar Microphone"
        },
        "id": "...",
        "firmwareVersion": "1.0.0"
    },
    "light": { ... },
    "masterModule": {
        "owner": "...",
        "secret": "............",
        "id": "...",
        "name": "My Wunderbar Master Module"
    },
    "infrared": { ... },
    "thermometer": { ... },
    "gyroscope": { ... }
}

delete_wunderbar(transmitterID)

Delete a WunderBar identified by its master module from the relayr cloud. This means that in addition to the transmitter (the master module) all devices (sensors) associated with it are being deleted.

Parameters:transmitterID (string) – the UUID of the master module

post_users_destroy(userID)

Delete all WunderBars associated with a specific user from the relayr cloud.

Parameters:userID (string) – the users’s UUID

get_user_device_models(userID)

Get all device models of a specific user from the relayr cloud.

Parameters:userID (string) – the users’s UUID

get_user_device_model(userID, modelID)

Get a specific device model of a specific user from the relayr cloud.

Parameters:

• userID (string) – the users’s UUID
• modelID (string) – the model’s UUID

get_user_device_model_component(userID, modelID, component)

get_user_device_groups(userID)

Get all device groups of a specific user from the relayr cloud.

delete_user_device_groups(userID)

Delete all device groups of a specific user from the relayr cloud.

post_user_device_group(name)

Create one device group with given name for the implied owner in the relayr cloud.

get_user_device_group(groupID)

Get one device group with a specific id from the relayr cloud.

Parameters:groupID (string) – the group’s UUID

delete_user_device_group(groupID)

Delete one device group with a specific id from the relayr cloud.

Parameters:groupID (string) – the group’s UUID

patch_user_device_group(groupID, name=None, position=None)

Patch one device group with a specific id from the relayr cloud.

Parameters:

• groupID (string) – the group’s UUID
• name (integer) – the group’s new name
• position (integer) – the group’s new position

post_user_device_group_device(groupID, deviceIDs=None)

Add a list of existing device ids to a device group.

Parameters:

• groupID (string) – the group’s UUID
• deviceIDs (list of UUIDs) – devices to be added to the group

delete_user_device_group_device(groupID, deviceID)

Delete a device from a device group.

patch_user_device_group_device(groupID, deviceID, position)

Change a device position inside a device group.

get_public_apps()

Get a list of all public relayr applications on the relayr platform.

Return type:list of dicts, each representing a relayr application

post_app(appName, publisherID, redirectURI, appDescription)

Register a new application on the relayr platform.

Return type:list of dicts, each representing a relayr application

get_app_info(appID)

Get information about an app with a specific UUID.

Parameters:appID (string) – the app’s UUID

Sample result (anonymized token value):

{
    "id": "...",
    "name": "My App",
    "description": "My Wunderbar app",
    ...
}

get_app_info_extended(appID)

Get extended information about the app with a specific UUID.

Parameters:appID (string) – the app’s UUID

Sample result (some values anonymized):

{
    "id": "...",
    "name": "My App",
    "publisher": "...",
    "clientId": "...",
    "clientSecret": "...",
    "description": "My Wunderbar app",
    "redirectUri": https://relayr.io
}

patch_app(appID, description=None, name=None, redirectUri=None)

Update one or more attributes of an app with a specific UUID.

Parameters:

• appID (string) – the application’s UUID
• description (string) – the user name to be set
• name (string) – the user email to be set
• redirectUri (string) – the redirect URI to be set

Sample result (some values anonymized):

{
    "id": "...",
    "name": "My App",
    "publisher": "...",
    "clientId": "...",
    "clientSecret": "...",
    "description": "My Wunderbar app",
    "redirectUri": https://relayr.io
}

delete_app(appID)

Delete an application from the relayr platform.

Parameters:appID (string) – the application’s UUID

get_oauth2_app_info()

Get info about the app initiating the request (the one in the token).

Sample result (anonymized token value):

{
    "id": "...",
    "name": "My App",
    "description": "My Wunderbar app"
}

get_public_publishers()

Get a list of all publishers on the relayr platform.

Return type:list of dicts, each representing a relayr publisher

post_publisher(userID, name)

Register a new publisher.

Parameters:

• userID (string) – the user UUID of the publisher
• name (string) – the publisher name

Return type:

a dict with fields describing the new publisher

delete_publisher(publisherID)

Delete a specific publisher from the relayr platform.

Parameters:publisherID (string) – the publisher UUID Return type:an empty dict(?)

get_publisher_apps(publisherID)

Return a list of apps published by a specific publisher.

Parameters:publisherID (string) – the publisher UUID Return type:A list of apps.

get_publisher_apps_extended(publisherID)

Return a list with extended information about the publisher’s apps.

Parameters:publisherID (string) – the publisher UUID Return type:A list of apps.

patch_publisher(publisherID, name=None)

Update name attribute of a specific publisher.

Parameters:

• publisherID (string) – the publisher’s UUID
• name (string) – the publisher name to be set

Return type:

True, if successful, False otherwise

get_device_configuration(*args, **kwargs)

Get configuration, default values and schema of a specific device.

Example result:

{
    "version": "1.0.0",
    "configuration": {
        "defaultValues": {
            "frequency": 1000
        },
        "schema": {
            "required": [
                "frequency"
            ],
            "type": "object",
            "properties": {
                "frequency": {
                    "minimum": 5,
                    "type": "integer",
                    "description": "Frequency of the sensor updates in milliseconds"
                }
            },
            "title": "Relayr configuration schema"
        }
    }
}

param deviceID:the device UUID type deviceID:string

Deprecated method. Please use get_device_configurations() instead.

post_device_configuration(*args, **kwargs)

Modify the configuration of a specific device facillitated by a schema.

param deviceID:the device UUID type deviceID:string param frequency:  the number of milliseconds between two sensor transmissions type frequency:integer

Deprecated method. Please use post_device_configurations() instead.

post_device_configurations(deviceID, config=None)

Modify the configuration of a specific device facillitated by a schema.

The config must be a dictionary with three keys, path, name and value, where path is optional.

Parameters:

• deviceID (dict) – the device UUID
• config – the configuration to be saved

get_public_devices()

Get list of all public devices on the relayr platform filtered by meaning.

Parameters:meaning (string) – required meaning in the device model’s readings attribute Return type:list of dicts, each representing a relayr device

post_device(name, ownerID, modelID, firmwareVersion)

Register a new device on the relayr platform.

Parameters:

• name (string) – the device name
• ownerID (string) – the device owner’s UUID
• modelID (string) – the device model’s UUID
• firmwareVersion (string) – the device’s firmware version

Return type:

list of dicts, each representing a relayr device

post_device_wb2(name, ownerID, modelID, firmwareVersion, mac, transmitterId)

Register a new device on the relayr platform.

Parameters:

• name (string) – the device name
• ownerID (string) – the device owner’s UUID
• modelID (string) – the device model’s UUID
• firmwareVersion (string) – the device’s firmware version

Return type:

list of dicts, each representing a relayr device

get_device(deviceID)

Get information about a specific device.

Parameters:deviceID (string) – the device UUID Return type:a dict with fields containing information about the device

Raises exceptions.RelayrApiException for invalid UUIDs or missing credentials.

patch_device(deviceID, name=None, description=None, modelID=None, public=None)

Update one or more attributes of a specific device.

Parameters:

• deviceID (string) – the device UUID
• name (string) – the device name
• description (string) – the device description
• modelID (string) – the device model UUID
• public (boolean) – the device state (public or not)

Return type:

a dict with fields containing information about the device

Raises exceptions.RelayrApiException for invalid UUIDs or missing credentials.

delete_device(deviceID)

Delete a specific device from the relayr platform.

Parameters:deviceID (string) – the device UUID Return type:a dict with fields containing information about the device

post_channel(deviceID, transport)

Create a new channel to let the current user receive device data.

The return value is a channel UUID plus credentials to connect to it.

Parameters:

• deviceID (string) – the device UUID
• transport (string) – transport for channel (mqtt, websockets, etc.)

Return type:

dict with channel credentials to connect to the device

Example result (for transport=’mqtt’):

{
    'channelId': u'62e2ceb8-a63f-11e4-8792-6c400890724a',
    'credentials': {
        'password': '012345678901',
        'topic': '/v1/62e2ceb8-a63f-11e4-8792-6c400890724a',
        'user': '62e2ceb8-a63f-11e4-8792-6c400890724a'
    }
}

delete_channel_id(channelID)

Delete an existing specific channel.

Parameters:channelID (string) – the UUID of the channel Return type:None

Raises exceptions.RelayrApiException for non-existing channelID.

delete_channels_device_transport(deviceID=None, transport=None)

Delete all existing channels for the given device ID and/or transport.

Parameters:

• deviceID (string) – the device UUID
• transport (string) – transport for channel (mqtt, websockets, etc.)

Return type:

list of deleted channelIDs

get_device_channels(deviceID)

Get all existing channels for a specific device.

Parameters:deviceID (string) – the device UUID Return type:dict with a list of attributes for each existing channel

Example output:

{
  'deviceId': '...',
  'channels': [
    {
      'channelId': '...',
      'transport': 'mqtt',
      'appId': '...'
    },
    {
      'channelId': '...',
      'transport': 'mqtt',
      'appId': '...'
    }
  ]
}

post_device_command_led(*args, **kwargs)

Send a command to a specific device’s LED.

param deviceID:the device’s UUID type deviceID:string param data:the data to be sent, here {‘cmd’: true/false} type data:dict rtype:dict with connection credentials

Deprecated method. Please use post_device_commands() instead.

post_device_command(*args, **kwargs)

Send a command to a specific device.

param deviceID:the device’s UUID type deviceID:string param command:the command to be sent type command:dict rtype:dict with connection credentials

Deprecated method. Please use post_device_commands() instead.

post_device_commands(deviceID, command=None)

Send a command to a specific device.

The command must be a dictionary with three keys, path, name and value, where path is optional.

Parameters:

• deviceID (string) – the device’s UUID
• command (dict) – the command to be sent

Return type:

dict with connection credentials

post_device_data(deviceID, data)

Send JSON formatted data to a device (eg. temperature readings).

Parameters:

• deviceID (string) – the device’s UUID
• data (anything serializable as JSON) – the command data

Return type:

string

get_device_reading(deviceID, path=None, meaning=None)

This endpoint returns only the reading part. Path and meaning are optional. If a path is not provided only readings with empty paths are returned. If meaning is not provided all the matched readings with {path} are returned.

Parameters:

• deviceID (string) – the device UUID
• path (string) – the reading’s path
• meaning (string) – the reading’s meaning

Return type:

a dict with desired readings as specified.

Example:

{
    "version": {
        "number": 100,
        "ts": 1452525615741
    },
    "readings": [
        {
            "path": "fridge",
            "meaning": "temperature",
            "ts": 1452525615741,
            "value": 1000
        }
    ]
}

get_device_metadata(deviceID, key=None)

Get the device metadata with given key.

The key is a multi-level string like this “my.custom.metadata” where each dot identifies a deeper level in the hierarchy. Wrong keys result in an empty JSON.

Parameters:

• deviceID (string) – the device UUID
• key (string) – the reading’s key

Return type:

a dict with desired key as specified.

Example:

{
    "version": {
        "number": 100,
        "ts": 1452525615741
    },
    "metadata": {
        "my": {
            "custom": {
                "metadata": 100
            }
        }
    }
}

get_device_commands(deviceID, path=None, name=None)

Get the device commands with given path and name.

Same as get_devices_readings(), only with a different key. Name is used instead of meaning.

Parameters:

• deviceID (string) – the device UUID
• path (string) – the reading’s path
• name (string) – the reading’s name

Return type:

a dict with desired readings as specified.

Example:

{
    "commands": [
        {
            "path": "door",
            "name": "led",
            "value": 1000,
            "ts": 1452525615741
        }
    ],
    "version": {
        "number": 100,
        "ts": 1452525615741
    }
}

get_device_state(deviceID)

Get the whole saved state of a specific device.

This includes readings, commands, configurations, and metadata, as well as simple version numbers for these items.

Parameters:deviceID (string) – the device UUID Return type:a dict with entire device state.

Example:

?

get_device_configurations(deviceID, path=None, name=None)

Get the device configurations with given path and name.

Parameters:

• deviceID (string) – the device UUID
• path (string) – the configuration’s path
• name (string) – the configuration’s name

Return type:

a dict with desired configuration as specified.

Example:

{

“commands”: [

{

“path”: “door”, “name”: “led”, “value”: 1000, “ts”: 1452525615741

}

], “version”: {

“number”: 100, “ts”: 1452525615741

}

}

post_device_metadata(deviceID, key=None, data=None)

Save some metadata for the specified device.

The key is used as prefix. Note that is not possible to send a value (instead of a JSON object) without a key, but a (key, value) pair is fine. So no json=1 and key=EMPTY, but this works: json=1 key=meta. (???)

Parameters:

• deviceID (string) – the device UUID
• key (string) – the metadata key
• data (a JSON-serializable object) – the actual metadata data

Return type:

None

get_device_credentials(deviceID)

Get credentials for a specific device.

Parameters:deviceID (string) – the device UUID Return type:dict with credentials info

post_device_credentials(deviceID, data)

Post credentials for a specific device.

Parameters:

• deviceID (string) – the device UUID
• data (dict) – the credentials

Return type:

string

get_history_devices(deviceID, start=None, end=None, sample=None, meaning=None, path=None, offset=None, limit=None)

Return past data for a specific device after a given starting point.

Parameters:

• deviceID (string) – the device UUID
• start (long) – unix datetime in ms
• end (long) – unit datetime in ms
• meaning (string) – meaning filter
• path (string) – path filter
• offset (integer) – pagination offset
• limit (integer) – limit for returned values

Return type:

history response with pagination info

get_public_device_models(headers={'Content-Type': 'application/json'})

Get list of all device models available on the relayr platform.

Parameters:headers (dict) – additional HTTP headers (default: {'Content-Type': 'application/json'}) Return type:list or dict, depening on the Content-Type field in headers

get_device_model(devicemodelID)

Get information about a specific device model.

Parameters:devicemodelID (string) – the device model’s UUID Return type:A nested dictionary structure with fields describing the DM.

get_public_device_model_meanings()

Get list of all device model meanings (no credentials needed).

Return type:list of dicts, each representing a relayr device model meaning

get_transmitter(transmitterID)

Get information about a transmitter with a specific UUID.

Parameters:transmitterID (string) – the transmitter UUID Return type:a dict with fields describing the transmitter

post_transmitter(ownerID=None, name=None, integrationType=None)

Register a new transmitter on the relayr platform.

Parameters:

• ownerID (string) – the transmitter owner’s UUID
• name (string) – the transmitter name
• integrationType (string) – the transmitter integration type

Return type:

an empty dict(?)

patch_transmitter(transmitterID, name=None)

Update the name attribute of a specific transmitter.

Parameters:

• transmitterID (string) – the transmitter UUID
• name (string) – the transmitter name

Return type:

an empty dict(?)

delete_transmitter(transmitterID)

Delete a specific transmitter from the relayr platform.

Parameters:transmitterID (string) – the transmitter UUID Return type:an empty dict(?)

post_transmitter_device(transmitterID, deviceID)

Connect a specific transmitter to a specific device.

Parameters:

• transmitterID (string) – the transmitter UUID
• deviceID (string) – the device UUID

Return type:

an empty dict(?)

get_transmitter_devices(transmitterID)

Get a list of devices connected to a specific transmitter.

Parameters:transmitterID (string) – the transmitter UUID Return type:a list of devices

delete_transmitter_device(transmitterID, deviceID)

Disconnect a specific transmitter from a specific device.

Parameters:

• transmitterID (string) – the transmitter UUID
• deviceID (string) – the device UUID

Return type:

an empty dict(?)

API Client

class relayr.client.Client(token=None)

A client providing a higher level interface to the relayr cloud platform.

Example:

c = Client(token='...')
info = c.get_oauth2_user_info()
usr = User(info['id'], client=c)
devs = usr.get_devices()
d = next(devs)
apps = usr.get_apps()

__init__(token=None)

Parameters:token (A string.) – A token generated on the relayr site for the combination of a user and an application.

get_public_apps()

Returns a generator for all apps on the relayr platform.

A generator is returned since the called API method always returns the entire results list and not a paginated one.

Return type:A generator for relayr.resources.App objects.

c = Client(token='...')
apps = c.get_public_apps()
for app in apps:
    print('%s %s' % (app.id, app.name))

get_public_publishers()

Returns a generator for all publishers on the relayr platform.

A generator is returned since the called API method always returns the entire results list and not a paginated one.

Return type:A generator for relayr.resources.Publisher objects.

get_public_devices(meaning='')

Returns a generator for all devices on the relayr platform.

A generator is returned since the called API method always returns the entire results list and not a paginated one.

Parameters:meaning (string) – The meaning (type) of the desired devices. Return type:A generator for relayr.resources.Device objects.

get_public_device_models()

Returns a generator for all device models on the relayr platform.

A generator is returned since the called API method always returns the entire results list and not a paginated one.

Return type:A generator for relayr.resources.DeviceModel objects.

get_public_device_model_meanings()

Returns a generator for all device models’ meanings on the relayr platform.

A device model meaning is a simple dictionary with a key and value field.

A generator is returned since the called API method always returns the entire results list and not a paginated one.

Return type:A device model meaning (as a dictionary) generator.

{'key': 'humidity', 'value': 'humidity'}

get_user()

Returns the relayr user owning the API client.

Return type:A relayr.resources.User object.

get_app()

Returns the relayr application of the API client.

Return type:A relayr.resources.App object.

get_device(id)

Returns the device with the specified ID.

Parameters:id (string) – the unique ID for the desired device. Return type:A relayr.resources.Device object.

get_device_groups()

Returns a generator for all device groups on the relayr platform.

A device group is a simple dictionary with a key and value field.

A generator is returned since the called API method always returns the entire results list and not a paginated one.

Return type:A relayr.resources.Group object.

API Resources

This module contains abstractions for relayr API resources.

Resources may be entities such as users, publishers, applications, devices, device models and transmitters.

class relayr.resources.User(id=None, client=None)

A Relayr user.

__init__(id=None, client=None)

get_publishers()

Return a generator of the publishers of the user.

get_apps()

Returns a generator of the apps of the user.

get_transmitters()

Returns a generator of the transmitters of the user.

get_devices()

Returns a generator of the devices of the user.

update(name=None, email=None)

register_wunderbar()

Returns registered Wunderbar devices (master and sensor modules).

Return type:A generator over the registered devices and one transmitter.

remove_wunderbar()

Removes all Wunderbars associated with the user.

get_bookmarked_devices()

Retrieves a list of bookmarked devices.

Return type:list of device objects

bookmark_device(device)

delete_device_bookmark(device)

class relayr.resources.Publisher(id=None, client=None)

A relayr publisher.

A publisher has a few attributes, which can be updated. It can be registered to and deleted from the relayr platform. It can list all applications it has published on the relayr platform.

__init__(id=None, client=None)

get_apps(extended=False)

Get list of apps for this publisher.

If the optional parameter extended is False (default) the response will contain only the fields id, name and description. If it is True it will contain additional fields: publisher, clientId, clientSecret and redirectUri.

Parameters:extended (booloean) – Flag indicating if the info should be extended. Return type:A list of relayr.resources.App objects.

update(name=None)

Updates certain information fields of the publisher’s.

Parameters:name (string) – the user email to be set

register(name, id, publisher)

Adds the publisher to the relayr platform.

Parameters:

• name (string) – the publisher name to be set
• id (string) – the publisher UID to be set

delete()

Deletes the publisher from the relayr platform.

class relayr.resources.App(id=None, client=None)

A relayr application.

An application has a few attributes, which can be updated. It can be registered to and deleted from the relayr platform. it can be connected to and disconnected from devices.

__init__(id=None, client=None)

get_info(extended=False)

Get application info.

If the optional parameter extended is False (default) the result will contain only the fields id, name and description. If it is True it will contain additional fields: publisher, clientId, clientSecret and redirectUri.

Parameters:extended (booloean) – flag indicating if the info should be extended Return type:A dict with certain fields.

update(description=None, name=None, redirectUri=None)

Updates certain fields in the application’s description.

Parameters:

• description (string) – the user name to be set
• name (string) – the user email to be set
• redirectUri (string) – the redirect URI to be set

delete()

Deletes the app from the relayr platform.

register(name, publisher)

Adds the app to the relayr platform.

Parameters:

• name (string) – the app name to be set
• publisher (string(?)) – the publisher to be set

class relayr.resources.Group(id=None, client=None)

A relayr device group.

A device group is simply an ordered list of devices with its own ID, name and owner. The position of the group is the one where it appears when asking for the list of all groups. This position can be changed.

__init__(id=None, client=None)

Instantiate new device group with given UUID and API client.

Parameters:

• id (string) – the UUID of this group
• client (relayr.client.Client) – the the user’s UUID who is the owner of this group

Return type:

self

create(name)

Create new device group with given name.

Parameters:name (string) – the name of this group Return type:self

get_info()

Retrieves device group info and stores it as instance attributes.

Return type:self.

update(name=None, position=None)

Updates position of this group in the list of all groups.

Parameters:

• name (string) – the new name of this group
• position (integer) – the new position of this group in the list of all groups

Return type:

self

delete()

Deletes the group from the relayr platform.

Return type:self

add_device(device)

Add a device from the relayr platform to this device group.

Parameters:device (relayr.resources.Device) – a relayr device object Return type:self

remove_device(device)

Remove a device from the relayr platform from this device group.

Parameters:device (relayr.resources.Device) – a relayr device object Return type:self

update_device(device, position=None)

Update a device inside this device group (now only the position field).

Parameters:

• device (relayr.resources.Device) – a relayr device object
• position (integer) – the new position of the device in the list of all devices

Return type:

self

class relayr.resources.Device(id=None, client=None)

A relayr device.

__init__(id=None, client=None)

get_info()

Retrieves device info and stores it as instance attributes.

Return type:self.

update(description=None, name=None, modelID=None, public=None)

Updates certain fields in the device information.

Parameters:

• description (string) – the description to be set
• name (string) – the user name to be set
• modelID (string?) – the device model to be set
• public (bool) – a Boolean flag for making the device public

Return type:

self

get_connected_apps()

Retrieves all apps connected to the device.

Return type:A list of apps.

send_command(command)

Sends a command to the device.

Parameters:command (dict) – the command to be sent (containing three key strings: ‘path’, ‘command’ and ‘value’, ‘path’ being optional)

send_data(data)

Sends a data package to the device.

Parameters:data (dict) – the data to be sent

send_config(config)

Sends a config package to configure the device.

Parameters:config – the configuration to be sent (containing three key strings: ‘path’, ‘command’ and ‘value’, ‘path’ being optional)

get_config(path=None, name=None)

Get a device’s configuration.

Parameters:

• path (string) – the configuration’s path
• name (string) – the configuration’s name

delete()

Deletes the device from the relayr platform.

switch_led_on(*args, **kwargs)

Switches on device’s LED for ca. 10 seconds or switches it off.

param bool:the desired state, on if True (default), off if False type bool:boolean rtype:self

Deprecated method. Please use send_command() instead.

received_data(data)

A callback for live data received for this device.

The default implementation is to append the reading to an instance attribute, self.buffered_readings. More customized functionality can be implemented in a subclass or by using an other callable.

This is slightly experimental and subject to change!

Parameters:reading (whatever is returned by the transport mechanism (usually a dictionary)) – a callable that will be called for each new device reading Return type:self

get_live_data(callback=None, duration=None, transport='mqtt')

Get a stream of current data for this device.

This is slightly experimental and subject to change!

Parameters:

• callback (callable Python function or method) – a callable that will be called for each new device reading
• duration (string) – duration until the callable is no longer called
• transport – transport method to be used (currently only ‘mqtt’ which is default)

Return type:

self

stop_live_data(transport='mqtt')

Stop receiving live data.

This is slightly experimental and subject to change!

get_past_data(start=None, end=None, duration=None, meaning=None, sample=None, offset=None, limit=None)

Get a chunk of historical data recorded in the past for this device.

Exactly one of the parameters start, end and duration must be None, else an AssertionError is raised. The data will be fetched using a paging mechanism with up to 10000 data points per page (limit). The data will not be stored inside this object.

This is slightly experimental and subject to change!

Parameters:

• start (ISO 8601 string or datetime.datetime instance or milliseconds or None) – datetime value
• end (ISO 8601 string or datetime.datetime instance or milliseconds or None) – datetime value
• duration (ISO 8601 duration string or datetime.timedelta instance or milliseconds or None) – time duration
• meaning (string) – a single device meaning (if unspecified all meanings will be reported)
• sample (string) –

  ...

• offset (integer >= 0) – offset in the list of returned data points
• limit (integer >= 0 (max. 10000)) – max. total number of returned data points

Return type:

a dict with historical data plus meta-information

get_data(*args, **kwargs)

Deprecated method, to be superseeded by get_past_data().

create_channel(transport)

delete_channel(channelID)

delete_channels()

list_channels()

class relayr.resources.DeviceModel(id=None, client=None)

A relayr device model.

__init__(id=None, client=None)

get_info()

Returns device model info and stores it as instance attributes.

Return type:self.

class relayr.resources.Transmitter(id=None, client=None)

A relayr transmitter, The Master Module, for example.

__init__(id=None, client=None)

get_info()

Retrieves transmitter info.

Return type:self

delete()

Deletes the transmitter from the relayr platform.

Return type:self

update(name=None)

Updates transmitter info.

Return type:self

get_connected_devices()

Returns a list of devices connected to the specific transmitter.

Return type:A list of devices.

Data Access

Data Connection Classes

This module provide connection classes for accessing device data.

class relayr.dataconnection.MqttStream(callback, devices, transport='mqtt')

MQTT stream reading data from devices in the relayr cloud.

__init__(callback, devices, transport='mqtt')

Opens an MQTT connection with a callback and one or more devices.

Parameters:

• callback (A function/method or object implementing the __call__ method.) – A callable to be called with two arguments: the topic and payload of a message.
• devices (list) – Device objects from which to receive data.
• transport (string) – Name of the transport method, right now only ‘mqtt’.

run()

Thread method, called implicitly after starting the thread.

stop()

Mark the connection/thread for being stopped.

on_connect(client, userdata, flags, rc)

on_disconnect(client, userdata, rc)

on_subscribe(client, userdata, mid, granted_qos)

on_unsubscribe(client, userdata, mid)

on_message(client, userdata, msg)

Pass the message topic and payload as strings to our callback.

add_device(device)

Add a specific device to the MQTT connection to receive data from.

remove_device(device)

Remove a specific device from the MQTT connection to no longer receive data from.

Exceptions

This module contains exceptions raised when an operation on the relayr API or the relayr platform fails due to, for example: missing credentials, invalid UIDs, etc.

At the moment two exception classes are provided:

• RelayrApiException: raised for exceptions caused by API calls
• RelayrException: raised for other exceptions

exception relayr.exceptions.RelayrApiException

exception relayr.exceptions.RelayrException