Device Gateway Service Version 2

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

Operations

Events

Operations


addGatewayResource

Create the definition of resource {alias}.

Arguments

parameters - object - Object containing service call parameters.
Name Type Description
alias ^[^.$]+$ The name of this resource.
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 Indicate 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.

Responses

The resource was successfully added.

Content: nil

The provided resource definition 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 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 resource 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

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

getGatewayResource

Retrieve the definition of resource {alias}.

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

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", "mqtt" The protocol used by devices connecting to the gateway.
Supported protocols:

onep: Exosite OneP HTTP Device API.
mqtt: Standard MQTT protocol. (http://mqtt.org)
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.*.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 Indicate 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.
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".
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

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 Returns device identities whose "lastseen" before timestamp.
status string Restrict the list of identities to only those with provided statuses.

The following states 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" identity 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.
identity string(regex) Returns only device identities that matches given regex.

To restrict the list to only those devices beginning with the letter
"a", for example, use the following regular expression: "^a.*".
ipaddress string Returns only device identities whose "lastip" matches given IP address.
version string Not implemented.

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

removeGatewayResource

Remove the resource {alias}.

Arguments

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

Responses

The resource was successfully removed.

Content: nil

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

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

setIdentityState

Assign the "set" value of a resource or set of resources 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
})


updateGatewayResource

Update the definition of resource {alias}.

Arguments

parameters - object - Object containing service call parameters.
Name Type Description
alias ^[^.$]+$ The name of this resource.
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 Indicate 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.

Responses

The resource was successfully updated.

Content: nil

The provided resource definition 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

updateGatewaySettings

Update the gateway settings.

Arguments

parameters - object - Object containing service call 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.
* 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.
protocol object The protocol specification for devices connecting to the gateway.
protocol.name "onep", "mqtt" The protocol used by devices connecting to the gateway.
Supported protocols:

onep: Exosite OneP HTTP Device API.
mqtt: Standard MQTT protocol. (http://mqtt.org)
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 When devices publish data or read and subscribe to data, they do so
using a resource alias.

Resources are used by devices (HTTP Device API) and by Murano (Device2
Lua API) to exchange information, respond to events and otherwise serve
as the inputs and outputs between devices and Murano.
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.*.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 Indicate 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.

Responses

The gateway settings were updated successfully.

Content: nil

The provided gateway settings 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

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

function handle_device2_event (event)

 -- Your logic comes here 

end