Skip to content

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

Name Tag Summary
device2.addIdentities()
device2.addIdentity()
device2.addIdentityTag()
device2.countIdentities()
device2.getGatewayResource()
device2.getGatewaySettings()
device2.getIdentity()
device2.getIdentityState()
device2.getIdentityTag()
device2.listIdentities()
device2.listTagName()
device2.listTagNames()
device2.makeIdentity()
device2.removeIdentity()
device2.removeIdentityTag()
device2.setIdentityState()
device2.updateIdentities()
device2.updateIdentity()

Events

Name Summary
(deprecated) event Generic Device2 gateway event (deprecated, use specific event types).

| 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

Name Type Description
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.
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:
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.
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:
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.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. For Cloud-to-Cloud protocols, this property
will be forced 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

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

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

  • 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

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

  • 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

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

  • 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

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

  • 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

Name Type Description
alias [.$]+$ The name of this resource.

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

Name Type Description
identity string The identifier of a given device.

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

Name Type Description
identity string The device's identifier

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

Name Type Description
identity string The identifier of a given identity.
name string The name of a tag.

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

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

  • 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

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

  • 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

Name Type Description
identity string The identifier of a given device.

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

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

  • 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

Name Type Description
identity string The device's identifier
^(?!identity$).? string, boolean, number Values to be written in the resource

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

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

  • 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

Name Type Description
identity string The identifier of a given device.
auth object The authentication object for identities connecting to the gateway. An object populated with valid credentials, will either replace or update the current one, depending on which fields are present. An empty object will clear the authentication credentials, including the optional expiration time. For further details on the valid fields, values and allowed combinations, see below.
auth.key string, null The credential used to authenticate the identity.

The allowed 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".

If auth.key is set to null, it will clear the credentials including its optional expiration time auth.expire, i.e. the "auth" object becomes empty.
auth.type "certificate", "cik", "csr", "password", "token", "" The type of credential used to authenticate the identity or "null" if the intent is to clear the credentials in which case the "auth" object becomes empty.
auth.expire integer, null The expiration timestamp in seconds, milliseconds or microseconds, of this authentication object.

When the "expire" timestamp is surpassed, the status of a "whitelisted" identity becomes "expired" and a "provisioned" identity becomes "reprovision".

If auth.type and auth.key are updated or cleared, auth.expire will also be cleared unless auth.expire is also provided in the call. In that case, auth.expire will be set to the new value, effectively setting a timeout for the device to provision.

If auth.expire is set to a time in the past while a device is connected, the device will be disconnected immediately.

Note, that if an auth object with only the "expire" field is provided, it will leave the credential fields "type" and "key" unchanged, effectively setting an expiration time for the current credentials.
locked boolean Setting "locked" property of an identity to "true" will prevent the device from communicating with the gateway and cause a connected device to be disconnected immediately.

The default value is "false".

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

Name Type Description

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

Name Type Description
ip string Ip Address that the device connected to the gateway from.
tags nil The tags associated with the identity that triggered this event.
message object The MQTT topic and message. Only present in the publish message type.
message.topic string The MQTT topic to which the message was posted.
message.payload string The payload in the MQTT message that was sent.
payload [ object ] List of data transmitted by the identity. Only for events of type 'data_in' and 'data_out'.
payload[].values object Map of resources.
payload[].values.* string, boolean, number Resource value.
payload[].timestamp number The UNIX timestamp in micro-seconds at which the resource was updated.
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 device connection.
updated_resources [ string ] List of resource aliases from the payload which has been set as Identity state. Only present in the "data_in" event.

Example

function handle_device2_connect (event)

 -- Your logic comes here 

end

data_in

Description

Device2 gateway "data_in" event.

Arguments

Name Type Description
ip string Ip Address that the device connected to the gateway from.
tags nil The tags associated with the identity that triggered this event.
message object The MQTT topic and message. Only present in the publish message type.
message.topic string The MQTT topic to which the message was posted.
message.payload string The payload in the MQTT message that was sent.
payload [ object ] List of data transmitted by the identity. Only for events of type 'data_in' and 'data_out'.
payload[].values object Map of resources.
payload[].values.* string, boolean, number Resource value.
payload[].timestamp number The UNIX timestamp in micro-seconds at which the resource was updated.
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 device connection.
updated_resources [ string ] List of resource aliases from the payload which has been set as Identity state. Only present in the "data_in" event.

Example

function handle_device2_data_in (event)

 -- Your logic comes here 

end

deleted

Description

Device2 gateway "deleted" event.

Arguments

Name Type Description
ip string Ip Address that the device connected to the gateway from.
tags nil The tags associated with the identity that triggered this event.
message object The MQTT topic and message. Only present in the publish message type.
message.topic string The MQTT topic to which the message was posted.
message.payload string The payload in the MQTT message that was sent.
payload [ object ] List of data transmitted by the identity. Only for events of type 'data_in' and 'data_out'.
payload[].values object Map of resources.
payload[].values.* string, boolean, number Resource value.
payload[].timestamp number The UNIX timestamp in micro-seconds at which the resource was updated.
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 device connection.
updated_resources [ string ] List of resource aliases from the payload which has been set as Identity state. Only present in the "data_in" event.

Example

function handle_device2_deleted (event)

 -- Your logic comes here 

end

expired

Description

Device2 gateway "expired" event.

Arguments

Name Type Description
ip string Ip Address that the device connected to the gateway from.
tags nil The tags associated with the identity that triggered this event.
message object The MQTT topic and message. Only present in the publish message type.
message.topic string The MQTT topic to which the message was posted.
message.payload string The payload in the MQTT message that was sent.
payload [ object ] List of data transmitted by the identity. Only for events of type 'data_in' and 'data_out'.
payload[].values object Map of resources.
payload[].values.* string, boolean, number Resource value.
payload[].timestamp number The UNIX timestamp in micro-seconds at which the resource was updated.
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 device connection.
updated_resources [ string ] List of resource aliases from the payload which has been set as Identity state. Only present in the "data_in" event.

Example

function handle_device2_expired (event)

 -- Your logic comes here 

end

publish

Description

Device2 gateway "publish" event.

Arguments

Name Type Description
ip string Ip Address that the device connected to the gateway from.
tags nil The tags associated with the identity that triggered this event.
message object The MQTT topic and message. Only present in the publish message type.
message.topic string The MQTT topic to which the message was posted.
message.payload string The payload in the MQTT message that was sent.
payload [ object ] List of data transmitted by the identity. Only for events of type 'data_in' and 'data_out'.
payload[].values object Map of resources.
payload[].values.* string, boolean, number Resource value.
payload[].timestamp number The UNIX timestamp in micro-seconds at which the resource was updated.
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 device connection.
updated_resources [ string ] List of resource aliases from the payload which has been set as Identity state. Only present in the "data_in" event.

Example

function handle_device2_publish (event)

 -- Your logic comes here 

end

data_out

Description

Device2 gateway "data_out" event.

Arguments

Name Type Description
ip string Ip Address that the device connected to the gateway from.
tags nil The tags associated with the identity that triggered this event.
message object The MQTT topic and message. Only present in the publish message type.
message.topic string The MQTT topic to which the message was posted.
message.payload string The payload in the MQTT message that was sent.
payload [ object ] List of data transmitted by the identity. Only for events of type 'data_in' and 'data_out'.
payload[].values object Map of resources.
payload[].values.* string, boolean, number Resource value.
payload[].timestamp number The UNIX timestamp in micro-seconds at which the resource was updated.
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 device connection.
updated_resources [ string ] List of resource aliases from the payload which has been set as Identity state. Only present in the "data_in" event.

Example

function handle_device2_data_out (event)

 -- Your logic comes here 

end

content_in

Description

Device2 gateway "content_in" event.

Arguments

Name Type Description
ip string Ip Address that the device connected to the gateway from.
tags nil The tags associated with the identity that triggered this event.
message object The MQTT topic and message. Only present in the publish message type.
message.topic string The MQTT topic to which the message was posted.
message.payload string The payload in the MQTT message that was sent.
payload [ object ] List of data transmitted by the identity. Only for events of type 'data_in' and 'data_out'.
payload[].values object Map of resources.
payload[].values.* string, boolean, number Resource value.
payload[].timestamp number The UNIX timestamp in micro-seconds at which the resource was updated.
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 device connection.
updated_resources [ string ] List of resource aliases from the payload which has been set as Identity state. Only present in the "data_in" event.

Example

function handle_device2_content_in (event)

 -- Your logic comes here 

end

disconnect

Description

Device2 gateway "disconnect" event.

Arguments

Name Type Description
ip string Ip Address that the device connected to the gateway from.
tags nil The tags associated with the identity that triggered this event.
message object The MQTT topic and message. Only present in the publish message type.
message.topic string The MQTT topic to which the message was posted.
message.payload string The payload in the MQTT message that was sent.
payload [ object ] List of data transmitted by the identity. Only for events of type 'data_in' and 'data_out'.
payload[].values object Map of resources.
payload[].values.* string, boolean, number Resource value.
payload[].timestamp number The UNIX timestamp in micro-seconds at which the resource was updated.
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 device connection.
updated_resources [ string ] List of resource aliases from the payload which has been set as Identity state. Only present in the "data_in" event.

Example

function handle_device2_disconnect (event)

 -- Your logic comes here 

end

provisioned

Description

Device2 gateway "provisioned" event.

Arguments

Name Type Description
ip string Ip Address that the device connected to the gateway from.
tags nil The tags associated with the identity that triggered this event.
message object The MQTT topic and message. Only present in the publish message type.
message.topic string The MQTT topic to which the message was posted.
message.payload string The payload in the MQTT message that was sent.
payload [ object ] List of data transmitted by the identity. Only for events of type 'data_in' and 'data_out'.
payload[].values object Map of resources.
payload[].values.* string, boolean, number Resource value.
payload[].timestamp number The UNIX timestamp in micro-seconds at which the resource was updated.
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 device connection.
updated_resources [ string ] List of resource aliases from the payload which has been set as Identity state. Only present in the "data_in" event.

Example

function handle_device2_provisioned (event)

 -- Your logic comes here 

end