Device Gateway & Connectivity Service¶

Summary¶

The Device2 gateway public API (Version 2) provides method for managing device identities and state, configure provisioning settings, and defining the gateway resources.

Operations

Events

| connect | Device2 gateway "connect" event. |

| data_in | Device2 gateway "data_in" event. |

| deleted | Device2 gateway "deleted" event. |

| expired | Device2 gateway "expired" event. |

| publish | Device2 gateway "publish" event. |

| data_out | Device2 gateway "data_out" event. |

| content_in | Device2 gateway "content_in" event. |

| disconnect | Device2 gateway "disconnect" event. |

| provisioned | Device2 gateway "provisioned" event. |

Configuration parameters¶

Operations¶

addIdentities¶

Description

Batch add identities to the gateway.

Add multiple device identities using a CSV format. The format consists of columns representing the identity ("ID") and the associated public certificate ("TLS Client Certificate"). The associated public certificate is optional and is intended to be used when the public certificates of a group of devices is known in advance. A device object is created for each entry with "identity" and "auth.key" (if provided) assigned; all other properties are given default values.

Note that the first line must specify the header format (e.g. "ID,TLS Client Certificate").

For a more general discussion and API, see "addIdentity".

Arguments

Responses

• Returns nil for All identities were successfully added to the gateway.

• Returns {object} when Invalid CSV entries encountered.Make sure the first line contains the appropriate header information("ID" or "ID,TLS Client Certificate"), and that valid identitieswere provided (they must match the gateway identity format).

  The error object {object}

  Name	Type	Description
  code	integer(int32)	The error code for this error
  message	string	The error message for this error

• Returns {object} when The gateway context does not exist.

  The error object {object}

  Name	Type	Description
  code	integer(int32)	The error code for this error
  message	string	The error message for this error

• Returns {object} when Failed to upload identities -- some already exist.

  The error object {object}

  Name	Type	Description
  code	integer(int32)	The error code for this error
  message	string	The error message for this error

addIdentity¶

Description

Adds {identity} to the gateway.

A device must have both an identity and be able to authenticate against the gateway before it can send updates, receive control requests, and download files. Such devices are considered "provisioned". These settings determine how the device is expected to authenticate.

If the gateway settings allow provisioning and accepts the device "presented" identity, whitelisting is unnecessary. In this case the device presents its identity (e.g. serial number, public certificate) and the gateway associates credentials used in subsequent connections.

The addIdentity operation establishes a new device identity. It may also assign the authentication credentials for the identity and set the "locked" value to temporarily prevent an identity from connecting.

Arguments

Responses

• Returns nil for Identity successfully added to the gateway with the provided properties.

• Returns {object} when The provided identity properties were invalid.

  The error object {object}

  Name	Type	Description
  code	integer(int32)	The error code for this error
  message	string	The error message for this error

• Returns {object} when The gateway context does not exist.

  The error object {object}

  Name	Type	Description
  code	integer(int32)	The error code for this error
  message	string	The error message for this error

• Returns {object} when Device object with this identity already exists.

  The error object {object}

  Name	Type	Description
  code	integer(int32)	The error code for this error
  message	string	The error message for this error

addIdentityTag¶

Description

Add an array of tags to the specified identity.

Arguments

Responses

• Returns nil for Tags sucessfully added to the identity with the provided properties.

• Returns {object} when The provided tags properties were invalid.

  The error object {object}

  Name	Type	Description
  code	integer(int32)	The error code for this error
  message	string	The error message for this error

• Returns {object} when The identity does not exist.

  The error object {object}

  Name	Type	Description
  code	integer(int32)	The error code for this error
  message	string	The error message for this error

countIdentities¶

Description

Returns the number of identities associated with the gateway.

Arguments

Responses

• Returns number for The number of identities.

• Returns {object} when Invalid query parameters.

  The error object {object}

  Name	Type	Description
  code	integer(int32)	The error code for this error
  message	string	The error message for this error

getGatewayResource¶

Description

Retrieve the definition of resource {alias}.

To Update resources from scripting use:

local parameters = Config.getParameters({ service = "device2" })
parameters.resources.newresource = { format = "string" }
Config.setParameters({
  service = "device2",
  parameters = { resources = parameters.resources }
})

Arguments

Responses

• Returns {object} when The resource definition object.

  The definition of a property that can be written to by devices and may beset from the cloud.Resources are formally defined properties whose published values are explicitlystored by the gateway as per identity state. Devices may however publish withany alias regardless of the existence of a resource definition for that alias. Allpublished data will be sent to the event mechanism (where they may be storedin a timeseries database or acted on in whatever manner is appropriate).For aliases with an associated resource definition the last-published, or "reported",value can be queried via the getIdentityState method. A "cloud modifiable" resourcecan also be "set" via the setIdentityState method to push data to a device. {object}

  Name	Type	Description
  sync	boolean	Indicates whether this resource needs to be synced with the device. After using setIdentityState: If true (default), the resource state will wait acknowledgment from the device to be applied. If false, the state value is changed immediately. Default: true
  unit	string	The unit of measure for this resource. Examples units include °C, mb, and rpm.
  format	"number", "string", "boolean"	The format that published data must adhere to. There are three possible formats: * "boolean": either be "true" or "false" * "number": whole (integers) or real numbers (floating point numbers) * "string": any UTF-8 encode string up to 2^16 bytes (64KB) in length.
  allowed	[ nil ]	A rule describing allowable values for the resource. If the value to write does not match a rule, it is not allowed and will be rejected.
  initial	nil	An initial "set" value to initialize each identity's state with. Only valid when "settable" is "true".
  settable	boolean	Indicates whether this resource's "set" value can be assigned via the setIdentityState method. If true, the setIdentityState method may be used to update the identity's state for the resource. Each resource has two assignable values, "reported" and "set". When a device publishes data, both "reported" and "set" are assigned the reported value; when calling the setIdentityState method, only the "set" value is assigned.

• Returns {object} when The provided resource name is invalid

  The error object {object}

  Name	Type	Description
  code	integer(int32)	The error code for this error
  message	string	The error message for this error

• Returns {object} when The gateway context or resource does not exist.

  The error object {object}

  Name	Type	Description
  code	integer(int32)	The error code for this error
  message	string	The error message for this error

getGatewaySettings¶

Description

Returns the current settings for the gateway.

The settings used to establish connectivity between devices and Murano. It includes the fully-qualified domain name used to establish a connection as well as the means by which devices are provisioned and authenticate.

To update settings from scripting use:

Config.setParameters({
    service = "device2",
    parameters = gatewaySettings
  })

Responses

• Returns {object} when The settings for the gateway.

  The gateway settings. {object}

  Name	Type	Description
  pki	object*, *null	The Public Key Interface configuration. If enabled, clients connecting with a client certificate will have to successfully validate their certificate against the configured Certificate Authority (client_ca), provided by the configured vendor.
  pki.vendor	object*, *null	The PKI vendor name and specific settings.
  pki.vendor.name	"DigiCert"	The name of the PKI vendor.
  pki.vendor.options	object	The settings specific to the configured PKI vendor.
  *	any	Any other properties are accepted.
  pki.enabled	boolean	Enables/disables client certificate validation for this domain.
  pki.client_ca	string	The Certificate Authority configured for this domain in PEM format.
  fqdn	string	The fully-qualified domain name to be used by devices connecting to the gateway. Devices will connect to the gateway using this domain, typically securely over port 443 using TLS. Example: A device uses this <fqdn> when using the HTTP Device API to write data to the "temp" resource: POST /onep:v1/stack/alias HTTP/1.1 Host: <fqdn> Content-Type: application/x-www-form-urlencoded; charset=utf-8 Content-Length: <length> temp=451 NOTE: Devices connecting to Murano with the "devmode" property enabled would use port 80 on the "devmode" specific domain.
  events	object	Specifies which events will be emitted.
  events.types	[ "connect", "content_in", "data_in", "data_out", "deleted", "disconnect", "expired", "provisioned", "publish" ]	The types of events listed in this array will be emitted. For allowed values, see "Events" chapter.
  protocol	object	The protocol specification for devices connecting to the gateway.
  protocol.tls	object	TLS specific settings.
  protocol.tls.policy	"custom", "tls_v1.0_legacy", "tls_v1.2_default"	The TLS policy to be used with this domain. See available policies by invoking the getConfig API. Besides those, "custom" can also be specified in which case the "ciphers" and "min_version" parameters can be specified.
  protocol.tls.ciphers	[ string ]	The list of cipher suites which connecting devices will be allowed to select. Only available if "custom" policy is selected.
  protocol.tls.min_version	"tlsv1.0", "tlsv1.1", "tlsv1.2"	The minimum TLS version which devices are allowed to use to connect. Only available if "custom" policy is selected.
  protocol.auth	object	The authentication object for remote clouds connecting to the gateway.
  protocol.auth.key	string	This is the Bearer token value that the remote cloud will have to send in the Authorization header, in the format of "Bearer H4sj8fbPFx86toDR".
  protocol.auth.type	"token"	The type of authentication the remote cloud will have to use to authenticate with Device2. Currently, only Bearer token is supported, hence this value must be set to token.
  protocol.mqtt	object	MQTT protocol specific settings.
  protocol.mqtt.topics	boolean	Controls whether clients in this domain are allowed to send messages to arbitrary topics vs. just the reserved ones.
  protocol.mqtt.revision	"0", "1"	Controls the protocol implementation revision.
  protocol.name	"cloudevents:v1/http", "onep:v1/http", "murano:v1/mqtt", "onep", "mqtt", "thingsnetwork:v1/http"	The protocol used by devices connecting to the gateway. Supported protocols: * "cloudevents:v1/http": Exosite's Cloud Federation protocol. * "onep:v1/http": Exosite OneP HTTP Device API. * "murano:v1/mqtt": Standard MQTT protocol. (http://mqtt.org) * "thingsnetwork:v1/http": Cloud Federation protocol for The Things Network. ('onep' & 'mqtt' values are deprecated and should not be used.)
  protocol.port	"443", "8883"	Optional field to specify the port which should be used for this protocol
  protocol.devmode	boolean	Enables/disables "development mode". When set to "true", devices connecting to the gateway may do so unencrypted (i.e. using HTTP instead of HTTPS). NOTE: enabling "devmode" is highly discouraged as all communication -- including that which is used to authenticate -- will be sent, unencrypted, in plain text. This property defaults to "false".
  protocol.murano_v1_mqtt	object	MQTT protocol specific settings.
  protocol.murano_v1_mqtt.topics	boolean	Controls whether clients in this domain are allowed to send messages to arbitrary topics vs. just the reserved ones.
  protocol.murano_v1_mqtt.revision	"0", "1"	Controls the protocol implementation revision.
  protocol.auto_provisioning	boolean	Controls whether a remote cloud can create identities by sending 'data_in' events without sending a 'created' event first. Default: true
  protocol.cloudevents_v1_http	object	Cloud Federation specific settings for the CloudEvents protocol.
  protocol.cloudevents_v1_http.origin	string	The value set here is expected to be used in all further requests originating from the remote cloud, sent in the WebHook-Request-Origin header. If the value of that header differs from what is set in this field, Device2 will reject the request.
  protocol.cloudevents_v1_http.vendor	string	This identifies the remote cloud, or if the remote cloud sends Exosite CloudEvents (as described later), vendor must be set to exosite.
  protocol.thingsnetwork_v1_http	object	Cloud Federation specific settings for The Things Network.
  resources	object	The resources of this device gateway
  resources.*	object	The definition of a property that can be written to by devices and may be set from the cloud. Resources are formally defined properties whose published values are explicitly stored by the gateway as per identity state. Devices may however publish with any alias regardless of the existence of a resource definition for that alias. All published data will be sent to the event mechanism (where they may be stored in a timeseries database or acted on in whatever manner is appropriate). For aliases with an associated resource definition the last-published, or "reported", value can be queried via the getIdentityState method. A "cloud modifiable" resource can also be "set" via the setIdentityState method to push data to a device.
  resources.*.sync	boolean	Indicates whether this resource needs to be synced with the device. After using setIdentityState: If true (default), the resource state will wait acknowledgment from the device to be applied. If false, the state value is changed immediately. Default: true
  resources.*.unit	string	The unit of measure for this resource. Examples units include °C, mb, and rpm.
  resources.*.format	"number", "string", "boolean"	The format that published data must adhere to. There are three possible formats: * "boolean": either be "true" or "false" * "number": whole (integers) or real numbers (floating point numbers) * "string": any UTF-8 encode string up to 2^16 bytes (64KB) in length.
  resources.*.allowed	[ nil ]	A rule describing allowable values for the resource. If the value to write does not match a rule, it is not allowed and will be rejected.
  resources.*.initial	nil	An initial "set" value to initialize each identity's state with. Only valid when "settable" is "true".
  resources.*.settable	boolean	Indicates whether this resource's "set" value can be assigned via the setIdentityState method. If true, the setIdentityState method may be used to update the identity's state for the resource. Each resource has two assignable values, "reported" and "set". When a device publishes data, both "reported" and "set" are assigned the reported value; when calling the setIdentityState method, only the "set" value is assigned.
  provisioning	object	The provisioning rules used to create and provision devices to the gateway. If enabled devices maybe connect and provision with the gateway associating its identity and credentials for use in subsequent connections. Once provisioned a device credentials are securely one-way hashed and can not be retrieved from the gateway.
  provisioning.enabled	boolean	Enables/disabling provisioning for this gateway context. If "true", devices are allowed to connect for provisioning. If "false", devices cannot provision. This property defaults to "true".
  provisioning.auth_type	"certificate", "cik", "domain", "token", "password"	The authentication method used when provisioning credentials for a device. Devices must authenticate when connecting to the gateway. This property specifies the expected authentication scheme devices must use when provisioning. Supported schemes are: * certificate: an X.509 keypair in which the device authenticates by presenting the public component of its cert and proving it possesses the private component when challenged. The certificate must encode its identity in the CN component of the certificate (i.e. public component. The public component alone is not sufficient to grant access, and the private component never leaves the device (that is, is never exchanged over-the-wire); consequently this is considered the most secure authentication mechanism and is preferred. * cik: Similar to token but only numbers and lower case characters from a-f can be part of a cik. This auth method is only supported with the OnePlatform HTTP protocol. * password: a string of at least 20 bytes. Any value of 0-255 can be used. Only the MQTT protocol supports this auth method. * token: a string representing both the identity and the password of a device. This token is granted to the device when it is activated as part of the provisioning process and presented by the device when it connects.
  provisioning.ip_whitelisting	object	Settings to manage allowed IP addresses of provisioning devices. These settings apply to devices requesting to provision. Once provisioned, devices may connect from any IP address regardless of these settings.
  provisioning.ip_whitelisting.allowed	[ string ]	An array of IPv4 addresses devices may connect from when provisioning. Devices must connect from an IP address in this list (assuming ip_whitelisting is enabled). Example: ["10.1.1.81","10.1.1.82"]
  provisioning.ip_whitelisting.enabled	boolean	Enables/disables restricting IP addresses that a device may connect from when provisioning. If "true", only devices connecting from the specified IP addresses will be allowed to provision (all others will be rejected). If "false", devices may provision from any IP address. This property defaults to "false".
  provisioning.presenter_identity	boolean	Enables/disables the acceptance of device-presented identities. This property is useful when identities are not whitelisted in advance, thereby allowing the connecting device to present its own identity at the time of connection. If "true", devices need not be whitelisted prior to connecting. The device, instead, connects with an identity and if the presented identity is not known to the gateway, the identity is added. If "false", only known (whitelisted) identities are allowed to connect to the gateway. This property defaults to true. For Cloud-to-Cloud protocols, this property will be forced to true.
  identity_format	object	The format specification for a device's identity. Device identities must adhere to the specified format. Any device identity not matching the format specification is rejected.
  identity_format.type	"mac:48", "mac-48", "mac.48", "uuidv4", "base10", "base16", "opaque"	The principle format for the identity. Murano supports MAC addresses in the following forms: * mac:48, a MAC address format using colons (MM:MM:MM:SS:SS:SS) * mac-48, a MAC address format using dashes (MM-MM-MM-SS-SS-SS) * mac.48, a MAC address format using dots (MMM.MMM.SSS.SSS) * uuidv4, a universally unique identifier format (with results akin to e5fa76f8-1220-45c9-b972-3e2345851677) * base10, a base-10 number format (0123456789) * base16, a base-16 (hexadecimal) number format (0123456789abcdef) * opaque, a free-form "format". Any UTF-8 encoded string.
  identity_format.prefix	string	An optional prefix that should be present at the beginning of the device's identity. The prefix is applicable only when the type is either "base10" or "base16". The prefix must conform to the "casing"'s value, but is not included when validating the length.
  identity_format.options	object	Additional identity format options.
  identity_format.options.casing	"lower", "upper", "mixed"	The string case. Applies to all types and validates against the entire identity (including the prefix). If unspecified, casing is assigned to "mixed".
  identity_format.options.length	number	The number of required digits when using base10 and base16.
  identity_format.options.mac_base	string	The first 3 octets of the MAC address of the device connecting to Murano. This can also be referred to as the Manufacturer ID. In the MAC address examples (mac:48, mac-48, and mac.48), the MAC base corresponds to the digits represented using the letter "M", whereas the letter "S" represents the unique ID of the connecting device.
  root_ca_fingerprint	string	The fingerprint of the root CA certificate that issued the intermediate CA or server certificate served by Okami for this domain.

• Returns {object} when The gateway context does not exist.

  The error object {object}

  Name	Type	Description
  code	integer(int32)	The error code for this error
  message	string	The error message for this error

getIdentity¶

Description

Retrieves the properties of the given {identity}.

Arguments

Responses

• Returns {object} when The properties and state of the identity.

  The representation of an identity.Every device known to the gateway has an identity object entry. Use the "listIdentities"method to query for a listing of all known identities and the "getIdentity" method toget the details for a specific identity. {object}

  Name	Type	Description
  auth	object	The authentication object for identities connecting to the gateway.
  auth.key	string	The credential used to authenticate the identity. The value and format of this "key" is dependent on the "type" field. If the auth.type field is set to "csr" and auth.key to a valid CSR in PEM format, it will trigger the process of getting the CSR signed by the PKI vendor set in the product configuration. Upon successfully having signed the CSR, the newly signed certificate will be saved as auth.key and auth.type will be set to "certificate". This field is optional but must exist if auth.type is provided. If both are absent, the identity will be in the "whitelisted" state.
  auth.type	"certificate", "cik", "csr", "password", "token"	The type of credential used to authenticate the identity. This field is optional but must exist if auth.key is provided. If both are absent, the identity will be in the "whitelisted" state.
  auth.expire	integer	The expiration timestamp in seconds, milliseconds or microseconds, of this authentication object. The time unit is automatically detected, as follows. Please note that the commas are there only for readability. A value in the 0 - 99,999,999,999 range will be interpreted as seconds, (1970.01.01 00:00:00 - 5138.11.16 09:46:39), a value in the 100,000,000,000 - 99,999,999,999,999 range as milliseconds, (1973.03.03 09:46:40.000 - 5138.11.16 09:46:39.999), and the value of and above 100,000,000,000,000 as microseconds, (1973.03.03 09:46:40.000000 - ). Note, the following limitations apply - - 1970.01.01 00:00:00 - 1973.03.03 09:46:39 can only be represented in seconds, - 5138.11.16 09:46:40.000000 and beyond can only be represented in microseconds. For example, 1905122480 seconds, 1905122480111 milliseconds or 1905122480111222 microseconds. If the "expire" timestamp is surpassed, the status of a "whitelisted" identity becomes "expired" and a "provisioned" identity becomes "reprovision". This field is optional. If not provided, the auth credentials, if provided, will never expire.
  tags	[ object ]	Array of tag pairs
  tags[].name	string	The tag name with a maximum length of 128 bytes.
  tags[].value	string	The tag value with a maximum length of 4096 bytes.
  state	object	The current state of the device as represented by assigned resources. For any resource with either a device-published ("reported") or cloud-assigned ("set") value, the value will appear here. Note that a device publishes to both the "reported" and the "set" value. An example follows: { "temp": { "timestamp": 1490392562583312, "set": 1591, "reported": 1591 } }
  state.*	object	The current set and reported values for a given resource.
  state.*.set	string*, boolean, *number	The last value set from the cloud.
  state.*.reported	string*, boolean, *number	The last value reported from the device.
  state.*.timestamp	number	The time this resource was set.
  lastip	string	The most recent IP address from which this device connected.
  locked	boolean	The "locked" value for this device. If set to "true", connection requests from this device are refused.
  online	boolean	Indicates whether the device is currently connected to the gateway.
  status	"locked", "reprovision", "devmode", "provisioned", "whitelisted", "expired"	The device's current status. The following status values are recognized: * A "locked" identity may not connect, even with valid authentication. * A "reprovision" status indicates the device must be re-provisioned because its authentication key has expired. * An "expired" status indicates that the identity provisioning window has expired and must be reset. * A "provisioned" identity has associated authentication credentials. * A "whitelisted" is an identity known to the gateway, but does not have authentication credentials associated and must be provisioned. * A "devmode" status indicates that the device that has authenticated over a non secure (unencrypted) transport. Its credentials have been flagged and are no longer considered secure.
  devmode	boolean	Indicates whether this device is a "development" device. By definitions, development devices have connected insecurely using HTTP rather than HTTPS. All communication -- including that which is necessary to authenticate the device -- has been sent "in the clear", interceptible by any third party.
  identity	string	The device's identity. Only one device with this identity may exist in a given gateway context.
  lastseen	number	The most recent timestamp at which this device connected or published data.
  lasttls_cipher	string	The IANA name of the TLS cipher the device used for its most recent connection.
  lasttls_version	"tlsv1.0", "tlsv1.1", "tlsv1.2"	The TLS version used for the most recent connection.

• Returns {object} when The gateway context or identity does not exist.

  The error object {object}

  Name	Type	Description
  code	integer(int32)	The error code for this error
  message	string	The error message for this error

getIdentityState¶

Description

Retrieves the state of resource(s) for the provided {identity}.

The state consists of the 'set' and 'report' values associated with the identity for all defined resources.

Arguments

Responses

• Returns {object} for The current state of the identity.A device-published ("reported") or cloud-assigned ("set") value willappear here. Note that a device publishes to both the "reported" andthe "set" value.Example:{ "temp": { "timestamp": 1490392562583312, "set": 1591, "reported": 1591 }}

  Name	Type	Description

• Returns {object} when The gateway context or identity does not exist.

  The error object {object}

  Name	Type	Description
  code	integer(int32)	The error code for this error
  message	string	The error message for this error

getIdentityTag¶

Description

Returns a tag values in the specified identity.

Arguments

Responses

• Returns [ string ] for List all the value in this tag name.

• Returns {object} when The provided properties were invalid.

  The error object {object}

  Name	Type	Description
  code	integer(int32)	The error code for this error
  message	string	The error message for this error

• Returns {object} when The identity does not exist.

  The error object {object}

  Name	Type	Description
  code	integer(int32)	The error code for this error
  message	string	The error message for this error

listIdentities¶

Description

Gets a list of the device identities associated with the gateway.

The returned device list is sorted (descending) by "lastseen" timestamp.

Arguments

Responses

• Returns {object} for Result object

  Name	Type	Description
  devices	[ object ]	A list of identities and their state.
  devices[].auth	object	The authentication object for identities connecting to the gateway.
  devices[].auth.key	string	The credential used to authenticate the identity. The value and format of this "key" is dependent on the "type" field. If the auth.type field is set to "csr" and auth.key to a valid CSR in PEM format, it will trigger the process of getting the CSR signed by the PKI vendor set in the product configuration. Upon successfully having signed the CSR, the newly signed certificate will be saved as auth.key and auth.type will be set to "certificate". This field is optional but must exist if auth.type is provided. If both are absent, the identity will be in the "whitelisted" state.
  devices[].auth.type	"certificate", "cik", "csr", "password", "token"	The type of credential used to authenticate the identity. This field is optional but must exist if auth.key is provided. If both are absent, the identity will be in the "whitelisted" state.
  devices[].auth.expire	integer	The expiration timestamp in seconds, milliseconds or microseconds, of this authentication object. The time unit is automatically detected, as follows. Please note that the commas are there only for readability. A value in the 0 - 99,999,999,999 range will be interpreted as seconds, (1970.01.01 00:00:00 - 5138.11.16 09:46:39), a value in the 100,000,000,000 - 99,999,999,999,999 range as milliseconds, (1973.03.03 09:46:40.000 - 5138.11.16 09:46:39.999), and the value of and above 100,000,000,000,000 as microseconds, (1973.03.03 09:46:40.000000 - ). Note, the following limitations apply - - 1970.01.01 00:00:00 - 1973.03.03 09:46:39 can only be represented in seconds, - 5138.11.16 09:46:40.000000 and beyond can only be represented in microseconds. For example, 1905122480 seconds, 1905122480111 milliseconds or 1905122480111222 microseconds. If the "expire" timestamp is surpassed, the status of a "whitelisted" identity becomes "expired" and a "provisioned" identity becomes "reprovision". This field is optional. If not provided, the auth credentials, if provided, will never expire.
  devices[].tags	[ object ]	Array of tag pairs
  devices[].tags[].name	string	The tag name with a maximum length of 128 bytes.
  devices[].tags[].value	string	The tag value with a maximum length of 4096 bytes.
  devices[].state	object	The current state of the device as represented by assigned resources. For any resource with either a device-published ("reported") or cloud-assigned ("set") value, the value will appear here. Note that a device publishes to both the "reported" and the "set" value. An example follows: { "temp": { "timestamp": 1490392562583312, "set": 1591, "reported": 1591 } }
  devices[].state.*	object	The current set and reported values for a given resource.
  devices[].state.*.set	string*, boolean, *number	The last value set from the cloud.
  devices[].state.*.reported	string*, boolean, *number	The last value reported from the device.
  devices[].state.*.timestamp	number	The time this resource was set.
  devices[].lastip	string	The most recent IP address from which this device connected.
  devices[].locked	boolean	The "locked" value for this device. If set to "true", connection requests from this device are refused.
  devices[].online	boolean	Indicates whether the device is currently connected to the gateway.
  devices[].status	"locked", "reprovision", "devmode", "provisioned", "whitelisted", "expired"	The device's current status. The following status values are recognized: * A "locked" identity may not connect, even with valid authentication. * A "reprovision" status indicates the device must be re-provisioned because its authentication key has expired. * An "expired" status indicates that the identity provisioning window has expired and must be reset. * A "provisioned" identity has associated authentication credentials. * A "whitelisted" is an identity known to the gateway, but does not have authentication credentials associated and must be provisioned. * A "devmode" status indicates that the device that has authenticated over a non secure (unencrypted) transport. Its credentials have been flagged and are no longer considered secure.
  devices[].devmode	boolean	Indicates whether this device is a "development" device. By definitions, development devices have connected insecurely using HTTP rather than HTTPS. All communication -- including that which is necessary to authenticate the device -- has been sent "in the clear", interceptible by any third party.
  devices[].identity	string	The device's identity. Only one device with this identity may exist in a given gateway context.
  devices[].lastseen	number	The most recent timestamp at which this device connected or published data.
  devices[].lasttls_cipher	string	The IANA name of the TLS cipher the device used for its most recent connection.
  devices[].lasttls_version	"tlsv1.0", "tlsv1.1", "tlsv1.2"	The TLS version used for the most recent connection.
  mayLoadMore	boolean	Additional, matching identities exist but were not returned. If "true", the query would have returned more devices, but the "limit" settings precluded it from doing so. Make additional queries with the "lastseen" timestamp set to the timestamp of the last identity in the result list.

• Returns {object} when Invalid query parameters.

  The error object {object}

  Name	Type	Description
  code	integer(int32)	The error code for this error
  message	string	The error message for this error

• Returns {object} when The gateway context does not exist.

  The error object {object}

  Name	Type	Description
  code	integer(int32)	The error code for this error
  message	string	The error message for this error

listTagName¶

Description

Returns all tag names in the gateway.

Responses

• Returns [ string ] for List of all tag names in this gateway.

• Returns {object} when The provided properties were invalid.

  The error object {object}

  Name	Type	Description
  code	integer(int32)	The error code for this error
  message	string	The error message for this error

listTagNames¶

Description

Returns all tag names in the gateway.

Responses

• Returns [ string ] for List all tag names in this gateway.

• Returns {object} when The provided properties were invalid.

  The error object {object}

  Name	Type	Description
  code	integer(int32)	The error code for this error
  message	string	The error message for this error

makeIdentity¶

Description

Generate a new identity.

Arguments

Responses

• Returns {object} when The viewable properties of the generated identity.

  The representation of an identity.Every device known to the gateway has an identity object entry. Use the "listIdentities"method to query for a listing of all known identities and the "getIdentity" method toget the details for a specific identity. {object}

  Name	Type	Description
  auth	object	The authentication object for identities connecting to the gateway.
  auth.key	string	The credential used to authenticate the identity. The value and format of this "key" is dependent on the "type" field. If the auth.type field is set to "csr" and auth.key to a valid CSR in PEM format, it will trigger the process of getting the CSR signed by the PKI vendor set in the product configuration. Upon successfully having signed the CSR, the newly signed certificate will be saved as auth.key and auth.type will be set to "certificate". This field is optional but must exist if auth.type is provided. If both are absent, the identity will be in the "whitelisted" state.
  auth.type	"certificate", "cik", "csr", "password", "token"	The type of credential used to authenticate the identity. This field is optional but must exist if auth.key is provided. If both are absent, the identity will be in the "whitelisted" state.
  auth.expire	integer	The expiration timestamp in seconds, milliseconds or microseconds, of this authentication object. The time unit is automatically detected, as follows. Please note that the commas are there only for readability. A value in the 0 - 99,999,999,999 range will be interpreted as seconds, (1970.01.01 00:00:00 - 5138.11.16 09:46:39), a value in the 100,000,000,000 - 99,999,999,999,999 range as milliseconds, (1973.03.03 09:46:40.000 - 5138.11.16 09:46:39.999), and the value of and above 100,000,000,000,000 as microseconds, (1973.03.03 09:46:40.000000 - ). Note, the following limitations apply - - 1970.01.01 00:00:00 - 1973.03.03 09:46:39 can only be represented in seconds, - 5138.11.16 09:46:40.000000 and beyond can only be represented in microseconds. For example, 1905122480 seconds, 1905122480111 milliseconds or 1905122480111222 microseconds. If the "expire" timestamp is surpassed, the status of a "whitelisted" identity becomes "expired" and a "provisioned" identity becomes "reprovision". This field is optional. If not provided, the auth credentials, if provided, will never expire.
  tags	[ object ]	Array of tag pairs
  tags[].name	string	The tag name with a maximum length of 128 bytes.
  tags[].value	string	The tag value with a maximum length of 4096 bytes.
  state	object	The current state of the device as represented by assigned resources. For any resource with either a device-published ("reported") or cloud-assigned ("set") value, the value will appear here. Note that a device publishes to both the "reported" and the "set" value. An example follows: { "temp": { "timestamp": 1490392562583312, "set": 1591, "reported": 1591 } }
  state.*	object	The current set and reported values for a given resource.
  state.*.set	string*, boolean, *number	The last value set from the cloud.
  state.*.reported	string*, boolean, *number	The last value reported from the device.
  state.*.timestamp	number	The time this resource was set.
  lastip	string	The most recent IP address from which this device connected.
  locked	boolean	The "locked" value for this device. If set to "true", connection requests from this device are refused.
  online	boolean	Indicates whether the device is currently connected to the gateway.
  status	"locked", "reprovision", "devmode", "provisioned", "whitelisted", "expired"	The device's current status. The following status values are recognized: * A "locked" identity may not connect, even with valid authentication. * A "reprovision" status indicates the device must be re-provisioned because its authentication key has expired. * An "expired" status indicates that the identity provisioning window has expired and must be reset. * A "provisioned" identity has associated authentication credentials. * A "whitelisted" is an identity known to the gateway, but does not have authentication credentials associated and must be provisioned. * A "devmode" status indicates that the device that has authenticated over a non secure (unencrypted) transport. Its credentials have been flagged and are no longer considered secure.
  devmode	boolean	Indicates whether this device is a "development" device. By definitions, development devices have connected insecurely using HTTP rather than HTTPS. All communication -- including that which is necessary to authenticate the device -- has been sent "in the clear", interceptible by any third party.
  identity	string	The device's identity. Only one device with this identity may exist in a given gateway context.
  lastseen	number	The most recent timestamp at which this device connected or published data.
  lasttls_cipher	string	The IANA name of the TLS cipher the device used for its most recent connection.
  lasttls_version	"tlsv1.0", "tlsv1.1", "tlsv1.2"	The TLS version used for the most recent connection.

• Returns {object} when The provided identity properties were invalid.

  The error object {object}

  Name	Type	Description
  code	integer(int32)	The error code for this error
  message	string	The error message for this error

• Returns {object} when The gateway context does not exist.

  The error object {object}

  Name	Type	Description
  code	integer(int32)	The error code for this error
  message	string	The error message for this error

• Returns {object} when Could not generate identity; the range is exhausted.

  The error object {object}

  Name	Type	Description
  code	integer(int32)	The error code for this error
  message	string	The error message for this error

removeIdentity¶

Description

Delete the given {identity}.

Remove everything that is known about the given {identity} including its state, authentication, and status. Future queries for this identity will return a 404 (not found).

Arguments

Responses

• Returns nil for The device was successfully deleted.

• Returns {object} when The gateway context or identity does not exist.

  The error object {object}

  Name	Type	Description
  code	integer(int32)	The error code for this error
  message	string	The error message for this error

removeIdentityTag¶

Description

Remove given tag from the Identity. Specific values to be removed can be provided. In such case the tag will remain with other values if any.

Arguments

Responses

• Returns nil for Delete tags was successful.

• Returns {object} when The provided properties were invalid.

  The error object {object}

  Name	Type	Description
  code	integer(int32)	The error code for this error
  message	string	The error message for this error

• Returns {object} when The identity does not exist.

  The error object {object}

  Name	Type	Description
  code	integer(int32)	The error code for this error
  message	string	The error message for this error

setIdentityState¶

Description

When sync=true(default behavior) in the resource, assign only the "set" value of a resource or set of resources for a device. If sync=false, assign both the "set" and "reported" value in the state for a device.

Note that when a device reports a new value to the resource, the effect is to assign both the "reported" and the "set" value; if the device reports a new value prior to reading the requested "set" value, the "set" value will be discarded in favor of the new "reported" value.

Arguments

Responses

• Returns nil for The new value was successfully "set".

• Returns {object} when The "set" object is invalid.

  The error object {object}

  Name	Type	Description
  code	integer(int32)	The error code for this error
  message	string	The error message for this error

• Returns {object} when The gateway context or identity does not exist.

  The error object {object}

  Name	Type	Description
  code	integer(int32)	The error code for this error
  message	string	The error message for this error

• Returns {object} when The state is not settable.

  The error object {object}

  Name	Type	Description
  code	integer(int32)	The error code for this error
  message	string	The error message for this error

Example

return Device2.setIdentityState({
  identity="xxxxxxxxxxxxx",
  temp=123,
  humidity=456
})

updateIdentities¶

Description

Update identities with provided update instructions that match the provided query.

Arguments

Responses

• Returns nil for The properties in identities matching the query, were successfully updated in the device gateway

• Returns {object} when The provided device identity properties were invalid.

  The error object {object}

  Name	Type	Description
  code	integer(int32)	The error code for this error
  message	string	The error message for this error

• Returns {object} when The device gateway context or identity does not exist.

  The error object {object}

  Name	Type	Description
  code	integer(int32)	The error code for this error
  message	string	The error message for this error

updateIdentity¶

Description

Update {identity} properties.

Arguments

Responses

• Returns nil for The identity properties were successfully updated in the device gateway

• Returns {object} when The provided device identity properties were invalid

  The error object {object}

  Name	Type	Description
  code	integer(int32)	The error code for this error
  message	string	The error message for this error

• Returns {object} when The device gateway context or identity does not exist

  The error object {object}

  Name	Type	Description
  code	integer(int32)	The error code for this error
  message	string	The error message for this error

Events¶

event [deprecated]¶

Description

Specific transactions cause the Device2 gateway to emit events with the event.type field set to one of the following:

• connect - A device has successfully authenticated to the gateway. Only sent for long lived connections, such as MQTT and HTTP long poll.
• content_in - An authenticated device has uploaded a content item. The 'event.payload' field contains information about the uploaded content.
• data_in - An authenticated device has published data as included in the 'event.payload' field.
• data_out - Data has been sent to a connected device as indicated in the 'event.payload' field.
• deleted - A device has been deleted.
• disconnect - An authenticated device has disconnected. Only sent when a corresponding connect message has also been sent.
• expired - An identity failed to provision because its provisioning window has expired.
• provisioned - An identity has successfully provisioned.
• publish - An MQTT device has sent a message to an arbitrary topic as indicated in the 'event.message' field.

Arguments

Example

-- Data are in the 'event' argument.
-- See http://docs.exosite.com/reference/services/device2/#event

if event.type ~= "data_in" then
  return -- Only for incoming data
end

local metrics = {}
for i, data in ipairs(event.payload) do
  for resource, value in pairs(data.values) do
    metrics[event.identity .. "-" .. resource] = value
  end
end

-- Write all device data to Murano Time-Series database.
-- See http://docs.exosite.com/reference/services/tsdb/#write

Tsdb.write({ metrics = metrics})

connect¶

Description

Device2 gateway "connect" event.

Arguments

Example

function handle_device2_connect (event)

 -- Your logic comes here 

end

data_in¶

Description

Device2 gateway "data_in" event.

Arguments

Example

function handle_device2_data_in (event)

 -- Your logic comes here 

end

deleted¶

Description

Device2 gateway "deleted" event.

Arguments

Example

function handle_device2_deleted (event)

 -- Your logic comes here 

end

expired¶

Description

Device2 gateway "expired" event.

Arguments

Example

function handle_device2_expired (event)

 -- Your logic comes here 

end

publish¶

Description

Device2 gateway "publish" event.

Arguments

Example

function handle_device2_publish (event)

 -- Your logic comes here 

end

data_out¶

Description

Device2 gateway "data_out" event.

Arguments

Example

function handle_device2_data_out (event)

 -- Your logic comes here 

end

content_in¶

Description

Device2 gateway "content_in" event.

Arguments

Example

function handle_device2_content_in (event)

 -- Your logic comes here 

end

disconnect¶

Description

Device2 gateway "disconnect" event.

Arguments

Example

function handle_device2_disconnect (event)

 -- Your logic comes here 

end

provisioned¶

Description

Device2 gateway "provisioned" event.

Arguments

Example

function handle_device2_provisioned (event)

 -- Your logic comes here 

end