iotery-python-server-sdk 0.1.5

iotery.io python server SDK

iotery.io Python Server SDK

The python iotery.io SDK is intended to be used on your server or in your data processing apps to interact with the itoery.io IoT Platform. The SDK is a fully featured wrapper for the REST API.

Getting Started

Setup your free account on iotery.io and go to your settings dashboard to get your server API Key.

After you get your key, install the SDK:

pip install iotery-python-server-sdk

Note: Make sure you are using Python 3.5+!

And finally, some simple example usage:

from iotery_python_server_sdk import Iotery


iotery = Iotery("my-key")

# find the exact `data` specification at https://iotery.io/v1/docs#createDeviceType
device_type = iotery.createDeviceType(
    data={"name": "My Device Type", "enum": "MY_DEVICE_TYPE", ...})

device_type_by_uuid = iotery.getDeviceTypeByUuid(
    deviceTypeUuid=device_type["uuid"], opts={"limit": 1})

The above code connects you to the iotary.io platform, creates a device type and then gets that device type.

Next, you might want to create a data type for the the device type you created...here's an example snippet:

temperature_data_type = iotery.createDataType(
  deviceTypeUuid=device_type_by_uuid["uuid"],
  data = {
    name: "Temperature",
    enum: "TEMPERATURE",
    units: "C",
    isNumber: true
  }
)

To have a "thing" (like a Raspberry Pi) create data, you will want to check out the iotery.io thing client.

For a tutorial on setting up a full stack system in 15 minutes using iotery.io, check this link out.

API

This SDK simply wraps the REST API, so more information and specifics can be found there. Since the API is a wrapper around the REST API, the syntax is standard for each of the Create, Read, Update, and Delete operations on iotery.io resources. All methods return a dictonary containing the API response. If there is an error, the method will raise an expection.

Creating Resources

The generalized syntax for creating resources in iotery.io python sdk looks like:

iotery.methodName(inputParameter="parameter", data={ "data": "variables" })

For example, to create a device, the javascript would look like

createDevice(
  deviceTypeUuid="a-valid-device-type-uuid",
  data={ "name": "My Device", "other": "parameter" }
)

where createDevice maps to methodName, deviceTypeUuid maps to inputParameter, and name and other map to the dictonary {data : "variables"} in the generalized form given above.

The available resource creation methods are

methodName	input	link	description
createAccountManager		link	Create an account manager.
createConsumer		link	Create a consumer.
linkConsumerToDevice	consumerUuid	link	Link a consumer to a device.
linkConsumerToNetwork	consumerUuid	link	Link a consumer to a network.
createConsumerSecret	consumerUuid	link	Create a consumer secret for authentication.
createDeviceType		link	Create a device type.
createSettingType		link	Create a setting type.
createDefaultSetting		link	Create a default setting.
createDataType		link	Create a data type.
createDevice		link	Create a device.
createBatchedCommandInstances		link	Create a set of batched command instances.
clearUnexecutedDeviceCommandInstances	deviceUuid	link	Clear all unexecuted command instance for a device.
createDeviceCommandInstance	deviceUuid	link	Create a command instance for a device.
createDeviceNotificationInstance	deviceUuid	link	Create a notification instance for a device.
createSetting	deviceUuid	link	Create a setting for a device.
createFirmwareRecord		link	Create a firmware record.
createSeverityType		link	Create a severity type.
createNotificationType		link	Create a notification type.
createNotificationField		link	Create a notification field.
createPriorityType		link	Create a priority type.
createCommandType		link	Create a command type.
createCommandField		link	Create a command field.
createEventType		link	Create an event type.
createEvent		link	Create an event.
createGroupingType		link	Create a grouping type.
createTeam		link	Create a team.
linkAccountManagerToTeam	userUuid	link	Link account manager to a team.
resetTeam	teamUuid	link	Reset a team by uuid.
createGroupingBatchedCommands	groupingUuid	link	Create a set of batched commands for a grouping and all child grouping devices.
moveDeviceToGrouping	groupingUuid	link	Move a device to a grouping.
createNetwork		link	Create a network.
createNetworkBatchedCommands	networkUuid	link	Create a set of batched commands for a network's devices.
createGrouping	networkUuid	link	Create a network grouping.
addChildGrouping	networkUuid,groupingUuid	link	Add a child grouping.
createNetworkLocation	networkUuid	link	Create a network location.
createSchedule	networkUuid	link	Create a schedule.
executeNetworkSchedule	networkUuid,scheduleUuid	link	Execute a schedule.
deprovisionNetwork	networkUuid	link	Deprovision a network.
provisionNetwork		link	Provision a network.
provisionDevice	networkUuid,deviceUuid	link	Provision a device.
deprovisionDevice	networkUuid,deviceUuid	link	Deprovision a device.
executeSchedule	scheduleUuid	link	Execute a schedule.
createGroupingDevice		link	Create a GroupingDevice link.
createGroupingLink		link	Create a GroupingLink.
createWebhookAction		link	Create a webhook action.

Reading Resources

The generalized syntax for reading (getting) resources in iotery.io python sdk looks like:

iotery.methodName(inputParameter="parameter", opts={"query":"parameter"})

For example, to get a device by it's unique identifier uuid, the python would look like

getDeviceByUuid(
  deviceUuid="a-valid-device-uuid",
  opts={ "limit": 1 }
)

where getDeviceByUuid maps to methodName, deviceUuid maps to inputParameter, and { "limit": 1 } maps to the dictonary {"query" : "parameters"} in the generalized form given above.

The limit option is for instructive purposes only. By definition, a uuid is unique and so there will never be more than one device for a given uuid.

For more advanced queries, some parameters allow for an array of values to be passed in. Two options available are $in and $btwn, which allows a user to specify a set or range of values, respectively. For example, when requesting for data for a device, one may use the SDK as follows:

iotery.getDeviceDataList(
    opts={
        "dataTypeEnum": {"$in": ["ENUM_1","ENUM_2","ENUM_3"]},
        "timestamp": {"$btwn": [1562759000, 1562759500]},
        "limit": 5
      },
    deviceUuid="a-valid-device-uuid")

Refer to the iotery REST API docs to see when options such as $in and $btwn are available for a given query parameter.

The available resource creation methods are

methodName	input	link	description
getHealthCheckResult		link	Get the result of a server health check.
getAccountManager	userUuid	link	Get an account manager by uuid.
getConsumerList		link	Get a list of available consumers.
getConsumer	consumerUuid	link	Get a consumer by uuid.
getDeviceTypeList		link	Get a list of available device types.
getDeviceType	deviceTypeUuid	link	Get a device type by uuid.
getSettingTypeList		link	Get a list of available setting types.
getSettingType	settingTypeUuid	link	Get a setting type by uuid.
getDefaultSettingList		link	Get a list of default settings.
getDefaultSetting	defaultSettingUuid	link	Get a default setting by uuid.
getDataTypeList		link	Get a list of available data types.
getDataType	dataTypeUuid	link	Get a data type by uuid.
getCommandInstanceList		link	Get a list of command instances.
getDeviceList		link	Get a list of devices.
getDevice	deviceUuid	link	Get a device by uuid.
getDeviceDataList	deviceUuid	link	Get a list of data for a device.
getDeviceEventList	deviceUuid	link	Get a list of events for a device.
getDeviceIsppConfiguration	deviceUuid	link	Get an ISPP configuration for a device.
getDeviceNotificationInstanceList	deviceUuid	link	Get a list of notification instances for a device.
getDeviceSettingList	deviceUuid	link	Get a list of settings for a device.
getNotificationInstance	notificationInstanceUuid	link	Get a notification instance by uuid.
getSetting	settingUuid	link	Get a setting by uuid.
getFirmwareRecordList		link	Get a list of firmware records.
getFirmwareRecord	firmwareUuid	link	Get a firmware record by uuid.
getSeverityTypeList		link	Get a list of available severity types.
getSeverityType	severityTypeUuid	link	Delete a severity type by uuid.
getNotificationTypeList		link	Get a list of available notification types.
getNotificationType	notificationTypeUuid	link	Get a notification type by uuid.
getNotificationFieldList		link	Get a list of available notification fields.
getNotificationField	notificationFieldUuid	link	Get a notification field by uuid.
getPriorityTypeList		link	Get a list of available priority types.
getPriorityType	priorityTypeUuid	link	Get a priority type by uuid.
getCommandTypeList		link	Get a list of available command types.
getCommandType	commandTypeUuid	link	Get a command type by uuid.
getCommandFieldList		link	Get a list of available command fields.
getCommandField	commandFieldUuid	link	Get a command field by uuid.
getEventTypeList		link	Get a list of available event types.
getEventType	eventTypeUuid	link	Get an event type by uuid.
getEventList		link	Get a list of events.
getEvent	eventUuid	link	Get an event by uuid.
getGroupingTypeList		link	Get a list of available grouping types.
getGroupingType	groupingTypeUuid	link	Get a grouping type by uuid.
getTeamList		link	Get a list of available teams.
getTeam	teamUuid	link	Get a team by uuid.
getGrouping	groupingUuid	link	Get a grouping by uuid.
getChildGroupingList	groupingUuid	link	Get a list of child groupings for a grouping.
getDeviceListForGrouping	groupingUuid	link	Get a list of devices for a grouping.
getNetworkList		link	Get a list of networks.
getNetwork	networkUuid	link	Get a network by uuid.
getNetworkDeviceList	networkUuid	link	Get a network's devices.
getNetworkGroupingList	networkUuid	link	Get a network's groupings.
getNetworkGrouping	networkUuid,groupingUuid	link	Get a network's grouping by uuid.
getNetworkLocationList	networkUuid	link	Get a network's locations.
getNetworkLocation	networkUuid,networkLocationUuid	link	Get a network location by uuid.
getNetworkScheduleList	networkUuid	link	Get a list of a network's schedules.
getNetworkSchedule	networkUuid,scheduleUuid	link	Get a schedule by uuid.
getSchedule	scheduleUuid	link	Get a schedule by uuid.
getGroupingDeviceList		link	Get a list of GroupingDevice links.
getGroupingDevice	groupingDeviceUuid	link	Get a GroupingDevice link by uuid.
getGroupingLinkList		link	Get a list of GroupingLinks.
getGroupingLink	groupingLinkUuid	link	Get a GroupingLink by uuid.
getWebhookActionList		link	Get a list of webhook actions.
getWebhookAction	webhookActionUuid	link	Get a webhook action by uuid.
getWebhookActionTypeList		link	Get a list of webhook action types.
getWebhookActionType	webhookActionTypeUuid	link	Get a webhook action type by uuid.

Updating Resources

The generalized syntax for updating resources in iotery.io python sdk looks like:

iotery.methodName(inputParameter="parameter", data={ "data": "variables" })

For example, to update a device type, the javascript would look like

updateDeviceType(
  deviceTypeUuid="a-valid-device-type-uuid",
  data={ "name": "My New Name" }
)

where updateDevice maps to methodName, deviceTypeUuid maps to inputParameter, and { "name": "My New Name" } maps to the dictonary {data : "variables"} in the generalized form given above.

The available update methods are

methodName	input	link	description
updateAccountManager	userUuid	link	Update an account manager by uuid.
updateConsumer	consumerUuid	link	Update a consumer by uuid.
updateDeviceType	deviceTypeUuid	link	Update a device type by uuid.
updateSettingType	settingTypeUuid	link	Update a setting type by uuid.
updateDefaultSetting	defaultSettingUuid	link	Update a default setting by uuid.
updateDataType	dataTypeUuid	link	Update a data type by uuid.
updateDevice	deviceUuid	link	Update a device by uuid.
updateNotificationInstance	notificationInstanceUuid	link	Update a notification instance.
updateSetting	settingUuid	link	Update a setting.
updateFirmwareRecord	firmwareUuid	link	Update a firmware record by uuid.
updateSeverityType	severityTypeUuid	link	Update a severity type by uuid.
updateNotificationType	notificationTypeUuid	link	Update a notification type by uuid.
updateNotificationField	notificationFieldUuid	link	Update a notification field by uuid.
updatePriorityType	priorityTypeUuid	link	Update a priority type by uuid.
updateCommandType	commandTypeUuid	link	Update a command type by uuid.
updateCommandField	commandFieldUuid	link	Update a command field by uuid.
updateEventType	eventTypeUuid	link	Update an event type by uuid.
updateEvent	eventUuid	link	Update an event by uuid.
updateGroupingType	groupingTypeUuid	link	Update a grouping type by uuid.
updateTeam	teamUuid	link	Update a team by uuid.
updateGrouping	groupingUuid	link	Update a grouping.
updateNetworkLocation	networkLocationUuid	link	Update a network location by uuid.
updateNetwork	networkUuid	link	Update a network by uuid.
updateNetworkGrouping	networkUuid,groupingUuid	link	Update a network grouping.
updateNetworkNetworkLocation	networkUuid,networkLocationUuid	link	Update a network location.
updateNetworkSchedule	networkUuid,scheduleUuid	link	Update a schedule.
updateSchedule	scheduleUuid	link	Update a schedule.
updateGroupingDevice	groupingDeviceUuid	link	Update a GroupingDevice link by uuid.
updateGroupingLink	groupingLinkUuid	link	Update a GroupingLink by uuid.
updateWebhookAction	webhookActionUuid	link	Update a webhook action by uuid.

Deleting Resources

The generalized syntax for reading (getting) resources in iotery.io python sdk looks like:

iotery.methodName(inputParameter="parameter", opts={"query":"parameter"})

For example, to get a device by it's unique identifier uuid, the python would look like

deleteDevice(
  deviceUuid="a-valid-device-uuid",
  opts={ "some": "option" }
)

where deleteDevice maps to methodName, deviceUuid maps to inputParameter, and { "some": "option" } maps to the dictonary {"query" : "parameters"} in the generalized form given above.

The available resource creation methods are

methodName	input	link	description
deleteAccountManager	userUuid	link	Delete an account manager by uuid.
deleteConsumer	consumerUuid	link	Delete a consumer by uuid.
unlinkConsumerFromDevice	consumerUuid,deviceUuid	link	Unlink a consumer from a device.
unlinkConsumerFromNetwork	consumerUuid,networkUuid	link	Unlink a consumer from a network.
deleteConsumerSecretList	consumerUuid	link	Delete all stored consumer secrets.
deleteDeviceType	deviceTypeUuid	link	Delete a device type by uuid.
deleteSettingType	settingTypeUuid	link	Delete a setting type by uuid.
deleteDefaultSetting	defaultSettingUuid	link	Delete a default setting by uuid.
deleteDataType	dataTypeUuid	link	Delete a data type by uuid.
deleteDevice	deviceUuid	link	Delete a device by uuid.
deleteNotificationInstance	notificationInstanceUuid	link	Delete a notification instance by uuid.
deleteSetting	settingUuid	link	Delete a setting by uuid.
deleteFirmwareRecord	firmwareUuid	link	Delete a firmware record by uuid.
deleteSeverityType	severityTypeUuid	link	Delete a severity type by uuid.
deleteNotificationType	notificationTypeUuid	link	Delete a notification type by uuid.
deleteNotificationField	notificationFieldUuid	link	Delete a notification field by uuid.
deletePriorityType	priorityTypeUuid	link	Delete a priority type by uuid.
deleteCommandType	commandTypeUuid	link	Delete a command type by uuid.
deleteCommandField	commandFieldUuid	link	Delete a command field by uuid.
deleteEventType	eventTypeUuid	link	Delete an event type by uuid.
deleteEvent	eventUuid	link	Delete an event by uuid.
deleteGroupingType	groupingTypeUuid	link	Delete a grouping type by uuid.
deleteTeam	teamUuid	link	Delete a team by uuid.
unlinkAccountManagerFromTeam	userUuid	link	Unlink account manager from a team.
deleteGrouping	groupingUuid	link	Delete a grouping by uuid.
deleteNetwork	networkUuid	link	Delete a network by uuid.
deleteNetworkGrouping	networkUuid,groupingUuid	link	Delete a network's grouping by uuid.
removeDeviceFromGrouping	networkUuid,groupingUuid,deviceUuid	link	remove a device from a grouping
deleteNetworkLocation	networkUuid,networkLocationUuid	link	Delete a network location by uuid.
deleteNetworkSchedule	networkUuid,scheduleUuid	link	Delete a schedule by uuid.
deleteSchedule	scheduleUuid	link	Delete a schedule by uuid.
deleteGroupingDevice	groupingDeviceUuid	link	Delete a GroupingDevice link by uuid.
deleteGroupingLink	groupingLinkUuid	link	Delete a GroupingLink by uuid.
deleteWebhookAction	webhookActionUuid	link	Delete a webhook action type by uuid.

Simple Getting Data Example

from iotery_python_server_sdk import Iotery
import json

API_KEY = "MY_TEAM_API_KEY"

DEVICE_UUID = "MY_DEVICE_UUID"
DATA_TYPE_ENUM = "MY_DATA_TYPE_ENUM"

iotery = Iotery(API_KEY)

device_data_list = iotery.getDeviceDataList(
    opts={"dataTypeEnum": DATA_TYPE_ENUM, "limit": 5}, deviceUuid=DEVICE_UUID)

print(json.dumps(device_data_list["results"], indent=2))

Contributing

We welcome contributors and PRs! Let us know if you are interested.