Device Gateway & Connectivity Service

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


Configuration parameters

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.
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.
protocol object The protocol specification for devices connecting to the gateway.
Default: {"name":"onep:v1/http"}
protocol.name "onep:v1/http", "murano:v1/mqtt", "onep", "mqtt" The protocol used by devices connecting to the gateway.

Supported protocols:
"onep:v1/http": Exosite OneP HTTP Device API.
"murano:v1/mqtt": Standard MQTT protocol. (http://mqtt.org)
('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.client_ca string, null The client certificate authority configured for this domain IN PEM format (https://tools.ietf.org/html/rfc7468).
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.
Default: {"auth_type":"token"}
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", "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.generate_identity boolean Enables/disables the gateway to generate the identity for a device connecting
without one.

If "true", the gateway will generate an identity for the connecting device
if it doesn't have one. If "false", devices are expected to connect with
an identity.

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.
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.
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.
resources object The resources of this device gateway
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.

Operations

addIdentities

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

parameters - object - Object containing service call parameters.
Name Type Description
expire number Assign each identity's "auth.expire" to the specified value. This field
is used to specify the amount of time a given identity is given to
register its credentials with Murano (a.k.a. provision). If the amount
of time provided is exceeded then the device with the given identity
is not allowed to communicate with Murano unless this expiration window
is re-opened.
identities file A list of identities to create in CSV format.

Responses

All identities were successfully added to the gateway.

Content: nil

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).

Content: object The error object

Name Type Description
code integer(int32) The error code for this error
message string The error message for this error
The gateway context does not exist.

Content: object The error object

Name Type Description
code integer(int32) The error code for this error
message string The error message for this error
Failed to upload identities -- some already exist.

Content: object The error object

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

addIdentity

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

parameters - object - Object containing service call parameters.
Name Type Description
identity string The identifier of a given device.
auth object The authentication object for identities connecting to the gateway.
auth.key string, null 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".
auth.type "certificate", "cik", "csr", "password", "token", "" The type of credential used to authenticate the identity.
auth.expire integer The expiration timestamp of this authentication object.

If the "expire" timestamp is surpassed, the status of a "whitelisted" identity
becomes "expired" and a "provisioned" identity becomes "reprovision".
locked boolean Setting "locked" property of an identity to "true" will prevent the device
from communicating with the gateway.

The default value is "false".

Responses

Identity successfully added to the gateway with the provided properties.

Content: nil

The provided identity properties were invalid.

Content: object The error object

Name Type Description
code integer(int32) The error code for this error
message string The error message for this error
The gateway context does not exist.

Content: object The error object

Name Type Description
code integer(int32) The error code for this error
message string The error message for this error
Device object with this identity already exists.

Content: object The error object

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

addIdentityTag

Add an array of tags to the specified identity.

Arguments

parameters - object - Object containing service call parameters.
Name Type Description
identity string The identifier of a given identity.
replace boolean If set to 'true', any 'name' in the given 'tags' already exist, they are replaced.
tags [ object ] An array of tag pairs to add to the identity
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.

Responses

Tags sucessfully added to the identity with the provided properties.

Content: nil

The provided tags properties were invalid.

Content: object The error object

Name Type Description
code integer(int32) The error code for this error
message string The error message for this error
The identity does not exist.

Content: object The error object

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

countIdentities

Returns the number of identities associated with the gateway.

Arguments

parameters - object - Object containing service call parameters.
Name Type Description
before number Filter identities whose "lastseen" timestamp is smaller than the given value.
status string Filter identities by provided status.

The following status are recognized:

a "locked" identity may not connect, even with valid authentication.
a "reprovision" identity must be re-provisioned because
its authentication key has expired.
an "expired" identity has missed its provisioning window and must be reset.
a "provisioned" identity has associated authentication credentials and is ready for use.
a "whitelisted" identity does not have authentication credentials
associated and must be provisioned.
a "devmode" identity has authenticated
over a non secure (unencrypted) transport. Its credentials have
been flagged and are no longer considered secure.
an "online" identity is currently connected.
an "offline" identity is currently disconnected.

Multiple status can be provided, separated by a comma.
Example: status=locked,expired,...
identity string(regex) Filter identities by regular expression match on their Id.

Example: Return devices beginning with the letter "a" with filter "^a.".
"a", for example, use the following regular expression: "^a.
".
ipaddress string Filter identities with last seen IP address ("lastip") matching given value.
version string Not implemented.
tag.name string Filter identities matching the given tag name.
tag.value string Filter identities matching the given tag name and value.

Note: the tag name must be provided when using a tag value.

Responses

The number of identities.

Content: number

Invalid query parameters.

Content: object The error object

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

getGatewayResource

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

parameters - object - Object containing service call parameters.
Name Type Description
alias ^[^.$]+$ The name of this resource.

Responses

The resource definition object.

Content: 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.

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.
The provided resource name is invalid

Content: object The error object

Name Type Description
code integer(int32) The error code for this error
message string The error message for this error
The gateway context or resource does not exist.

Content: object The error object

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

getGatewaySettings

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

The settings for the gateway.

Content: object The gateway settings.

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.
protocol object The protocol specification for devices connecting to the gateway.
protocol.name "onep:v1/http", "murano:v1/mqtt", "onep", "mqtt" The protocol used by devices connecting to the gateway.

Supported protocols:
"onep:v1/http": Exosite OneP HTTP Device API.
"murano:v1/mqtt": Standard MQTT protocol. (http://mqtt.org)
('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.client_ca string, null The client certificate authority configured for this domain IN PEM format (https://tools.ietf.org/html/rfc7468).
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", "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.generate_identity boolean Enables/disables the gateway to generate the identity for a device connecting
without one.

If "true", the gateway will generate an identity for the connecting device
if it doesn't have one. If "false", devices are expected to connect with
an identity.

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.
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.
The gateway context does not exist.

Content: object The error object

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

getIdentity

Retrieves the properties of the given {identity}.

Arguments

parameters - object - Object containing service call parameters.
Name Type Description
identity string The identifier of a given device.

Responses

The properties and state of the identity.

Content: object The representation of an identity.Every device known to the gateway has a 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.

Name Type Description
auth object The authentication object for identities connecting to the gateway.
auth.key string, null 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".
auth.type "certificate", "cik", "csr", "password", "token", "" The type of credential used to authenticate the identity.
auth.expire integer The expiration timestamp of this authentication object.

If the "expire" timestamp is surpassed, the status of a "whitelisted" identity
becomes "expired" and a "provisioned" identity becomes "reprovision".
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.
The gateway context or identity does not exist.

Content: object The error object

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

getIdentityState

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

parameters - object - Object containing service call parameters.
Name Type Description
identity string The device's identifier

Responses

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 }}

Content: object

Name Type Description
The gateway context or identity does not exist.

Content: object The error object

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

getIdentityTag

Returns a tag values in the specified identity.

Arguments

parameters - object - Object containing service call parameters.
Name Type Description
identity string The identifier of a given identity.
name string The name of a tag.

Responses

List all the value in this tag name.

Content: [ string ]

The provided properties were invalid.

Content: object The error object

Name Type Description
code integer(int32) The error code for this error
message string The error message for this error
The identity does not exist.

Content: object The error object

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

listIdentities

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

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

Arguments

parameters - object - Object containing service call parameters.
Name Type Description
limit integer Limit the number of returned identities to indicated value (default 50).
Default: 50
offset integer When set the query returns 'limit' number of devices but skip
'offset' number of devices at the beginning. This is useful in
combination with the 'before' field when more than 'limit' of
identities "lastseen" are all the same.
order [ ^(identity|lastseen|lastip|state\.[^.$]+)(\.(desc|asc))?$ ] Sort identities by attribute values. Use '.desc' postfix to indicate descending order.
You also can order by specific resources state value reported by the identity, with 'state.resource_name'.
before number Filter identities whose "lastseen" timestamp is smaller than the given value.
status string Filter identities by provided status.

The following status are recognized:

a "locked" identity may not connect, even with valid authentication.
a "reprovision" identity must be re-provisioned because
its authentication key has expired.
an "expired" identity has missed its provisioning window and must be reset.
a "provisioned" identity has associated authentication credentials and is ready for use.
a "whitelisted" identity does not have authentication credentials
associated and must be provisioned.
a "devmode" identity has authenticated
over a non secure (unencrypted) transport. Its credentials have
been flagged and are no longer considered secure.
an "online" identity is currently connected.
an "offline" identity is currently disconnected.

Multiple status can be provided, separated by a comma.
Example: status=locked,expired,...
identity string(regex) Filter identities by regular expression match on their Id.

Example: Return devices beginning with the letter "a" with filter "^a.".
"a", for example, use the following regular expression: "^a.
".
ipaddress string Filter identities with last seen IP address ("lastip") matching given value.
version string Not implemented.
tag.name string Filter identities matching the given tag name.
tag.value string Filter identities matching the given tag name and value.

Note: the tag name must be provided when using a tag value.

Responses

Result object

Content: 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, null 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".
devices[].auth.type "certificate", "cik", "csr", "password", "token", "" The type of credential used to authenticate the identity.
devices[].auth.expire integer The expiration timestamp of this authentication object.

If the "expire" timestamp is surpassed, the status of a "whitelisted" identity
becomes "expired" and a "provisioned" identity becomes "reprovision".
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.
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.
Invalid query parameters.

Content: object The error object

Name Type Description
code integer(int32) The error code for this error
message string The error message for this error
The gateway context does not exist.

Content: object The error object

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

listTagName

Returns all the tag name in the gateway.

Responses

List all the value in this gateway.

Content: [ string ]

The provided properties were invalid.

Content: object The error object

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

makeIdentity

Generate a new identity.

Arguments

parameters - object - Object containing service call parameters.
Name Type Description
auth object The authentication object for identities connecting to the gateway.
auth.key string, null 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".
auth.type "certificate", "cik", "csr", "password", "token", "" The type of credential used to authenticate the identity.
auth.expire integer The expiration timestamp of this authentication object.

If the "expire" timestamp is surpassed, the status of a "whitelisted" identity
becomes "expired" and a "provisioned" identity becomes "reprovision".
locked boolean Setting "locked" property of an identity to "true" will prevent the device
from communicating with the gateway.

The default value is "false".

Responses

The viewable properties of the generated identity.

Content: object The representation of an identity.Every device known to the gateway has a 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.

Name Type Description
auth object The authentication object for identities connecting to the gateway.
auth.key string, null 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".
auth.type "certificate", "cik", "csr", "password", "token", "" The type of credential used to authenticate the identity.
auth.expire integer The expiration timestamp of this authentication object.

If the "expire" timestamp is surpassed, the status of a "whitelisted" identity
becomes "expired" and a "provisioned" identity becomes "reprovision".
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.
The provided identity properties were invalid.

Content: object The error object

Name Type Description
code integer(int32) The error code for this error
message string The error message for this error
The gateway context does not exist.

Content: object The error object

Name Type Description
code integer(int32) The error code for this error
message string The error message for this error
Could not generate identity; the range is exhausted.

Content: object The error object

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

removeIdentity

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

parameters - object - Object containing service call parameters.
Name Type Description
identity string The identifier of a given device.

Responses

The device was successfully deleted.

Content: nil

The gateway context or identity does not exist.

Content: object The error object

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

removeIdentityTag

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

parameters - object - Object containing service call parameters.
Name Type Description
identity string The identifier of a given identity.
name string The name of a tag.
value string Filter one or more tag value to delete when multiple tags with the same name exist.
Split the string by "," to provide multiple tag value.
The format: "[,, ...]".
For example: "value" or "value1,value2".

Responses

Delete tags was successful.

Content: nil

The provided properties were invalid.

Content: object The error object

Name Type Description
code integer(int32) The error code for this error
message string The error message for this error
The identity does not exist.

Content: object The error object

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

setIdentityState

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

parameters - object - Object containing service call parameters.
Name Type Description
identity string The device's identifier
^(?!identity$).? string, boolean, number Values to be written in the resource

Responses

The new value was successfully "set".

Content: nil

The "set" object is invalid.

Content: object The error object

Name Type Description
code integer(int32) The error code for this error
message string The error message for this error
The gateway context or identity does not exist.

Content: object The error object

Name Type Description
code integer(int32) The error code for this error
message string The error message for this error
The state is not settable.

Content: object The error 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

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

Arguments

parameters - object - Object containing service call parameters.
Name Type Description
before number Filter identities whose "lastseen" timestamp is smaller than the given value.
status string Filter identities by provided status.

The following status are recognized:

a "locked" identity may not connect, even with valid authentication.
a "reprovision" identity must be re-provisioned because
its authentication key has expired.
an "expired" identity has missed its provisioning window and must be reset.
a "provisioned" identity has associated authentication credentials and is ready for use.
a "whitelisted" identity does not have authentication credentials
associated and must be provisioned.
a "devmode" identity has authenticated
over a non secure (unencrypted) transport. Its credentials have
been flagged and are no longer considered secure.
an "online" identity is currently connected.
an "offline" identity is currently disconnected.

Multiple status can be provided, separated by a comma.
Example: status=locked,expired,...
identity string(regex) Filter identities by regular expression match on their Id.

Example: Return devices beginning with the letter "a" with filter "^a.".
"a", for example, use the following regular expression: "^a.
".
ipaddress string Filter identities with last seen IP address ("lastip") matching given value.
tag.name string Filter identities matching the given tag name.
tag.value string Filter identities matching the given tag name and value.

Note: the tag name must be provided when using a tag value.
add object Identity object fields and associated values to be added.
add.tags [ nil ] -
remove object Identity object fields (with values optionally specified) to be removed.
remove.tags [ nil ] -
update object Identity object fields to be updated with given values.
update.state object The device resource values to "set", as demonstrated by the
following example:

{
"temp": 123,
"humidity": 456
}
update.state.^(?!identity$).? string, boolean, number Values to be written in the resource

Responses

The properties in identities matching the query, were successfully updated in the device gateway

Content: nil

The provided device identity properties were invalid.

Content: object The error object

Name Type Description
code integer(int32) The error code for this error
message string The error message for this error
The device gateway context or identity does not exist.

Content: object The error object

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

updateIdentity

Update {identity} properties.

Arguments

parameters - object - Object containing service call parameters.
Name Type Description
identity string The identifier of a given device.
auth object The authentication object for identities connecting to the gateway.
auth.key string, null 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".
auth.type "certificate", "cik", "csr", "password", "token", "" The type of credential used to authenticate the identity.
auth.expire integer The expiration timestamp of this authentication object.

If the "expire" timestamp is surpassed, the status of a "whitelisted" identity
becomes "expired" and a "provisioned" identity becomes "reprovision".
locked boolean Setting "locked" property of an identity to "true" will prevent the device
from communicating with the gateway.

The default value is "false".

Responses

The identity properties were successfully updated in the device gateway

Content: nil

The provided device identity properties were invalid

Content: object The error object

Name Type Description
code integer(int32) The error code for this error
message string The error message for this error
The device gateway context or identity does not exist

Content: object The error object

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

Events

event

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

Arguments

event - object - The event table
Name Type Description
ip string Ip Address that the device connected to the gateway from
type "connect", "disconnect", "data_in", "deleted", "provisioned", "expired" The event type
payload [ object ] List of data transmitted by the identity. Only for events of type 'data_in'
payload[].values object Map of resources
payload[].values.* string, boolean, number Resource value
payload[].timestamp number Update time in epoch micro-seconds
identity string The authenticated identity of the connected device
protocol string Specifies the protocol that the device connected with.
timestamp integer The UNIX timestamp at which the event was generated
connection_id string A unique id shared across all events generated from the same network connection
updated_resources [ string ] List of resource aliases from the payload which has been set as Identity state.

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})