Skip to content

Device Gateway & Connectivity Service

The Device-to-Cloud (Device2) service provides connectivity and fleet management capability for handling digital twins identities, defining data behavior and configure device life-cycle settings.

Operations

Data query
Data restore
Device metrics
Identity
Identity state
Identity tags
Permission
Publish data
Solution
Solution resource

Events

  • event - Device2 gateway event.

Configuration parameters

Please note that bold arguments are required, while italic arguments are optional.

Name Type Description
enable_signal_parser boolean When signal parser is enabled, the server will parse the payload of config_io/data_in,
translate them into signal data and save them into database.
permission object Solution level permission for all devices
permission.gateway [ ^[\w-_:\.]+$ ] A gateway device is allowed to publish as other devices within this solution
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.
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", "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.
 password: a string of at least 20 bytes. Any value of 0-255 can be used.
Only the MQTT protocol supports this auth method.
* token: a string representing both the identity and the password of a
device. This token is granted to the device when it is activated as
part of the provisioning process and presented by the device when it
connects.
provisioning.ip_whitelisting object Settings to manage allowed IP addresses of provisioning devices.

These settings apply to devices requesting to provision. Once provisioned,
devices may connect from any IP address regardless of these settings.
provisioning.ip_whitelisting.allowed [ string ] An array of IPv4 addresses devices may connect from when provisioning.

Devices must connect from an IP address in this list (assuming
ip_whitelisting is enabled).

Example:

["10.1.1.81","10.1.1.82"]
provisioning.ip_whitelisting.enabled boolean Enables/disables restricting IP addresses that a device may connect
from when provisioning.

If "true", only devices connecting from the specified IP addresses
will be allowed to provision (all others will be rejected). If "false",
devices may provision from any IP address.

This property defaults to "false".
provisioning.generate_identity boolean Enables/disables the gateway to generate the identity for a device connecting
without one.

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

This property defaults to "false".
provisioning.presenter_identity boolean Enables/disables the acceptance of device-presented identities.

This property is useful when identities are not whitelisted in advance,
thereby allowing the connecting device to present its own identity at
the time of connection. If "true", devices need not be whitelisted prior
to connecting. The device, instead, connects with an identity and if the
presented identity is not known to the gateway, the identity is added. If
"false", only known (whitelisted) identities are allowed to connect
to the gateway.

This property defaults to true.
fqdn string The fully-qualified domain name to be used by devices connecting to the
gateway.

Devices will connect to the gateway using this domain, typically
securely over port 443 using TLS.
identity_format object The format specification for a device's identity.

Device identities must adhere to the specified format. Any
device identity not matching the format specification is rejected.
identity_format.type "mac:48", "mac-48", "mac.48", "uuidv4", "base10", "base16", "opaque" The principle format for the identity.

West Connectivity 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
West Connectivity. 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.
solution_sync object The solution sync linking information.
source is the upsteam linking
target is the downsteam linking
solution_sync.source object The solution sync linking configuration.
solution_sync.target object The solution sync linking configuration.

Operations

Please note that bold arguments are required, while italic arguments are optional.

aggrqueryResource

Retrieves the aggrgate dataset of the given {resource} based on time bucket given. default fields are min, max, sum, count. the result is sorted by report time desc.

SRS-ID: CHUB-INT-016

Arguments

parameters (object) - Object containing service call parameters.

Name Type Description
resource string The identifier of a given resource.
bucket "1m", "5m", "1h" The continuous aggregates query time chunk
start_time number The start of time range to filter data. Formatted as UNIX timestamp with fraction digits representing millisecond and microsecond. The precision is specified by epoch parameter.
data reported_time >= start_time
Maximum: 9999999999
Minimum: 1000000000
end_time number The end of time range to filter data. Formatted as UNIX timestamp with fraction digits representing millisecond and microsecond. The precision is specified by epoch parameter.
data reported_time < end_time
Maximum: 9999999999
Minimum: 1000000000
limit integer Approximate number of items to return (Default = 1000).
Maximum: 10000
Minimum: 1
Default: 1000
page integer Filter the starting index to start returning object for pagination purpose.
Maximum: 999999999999999
Minimum: 1
epoch "s", "ms", "us" Unix timestamp precision
identities string The identities list concat by ",".
fields [ "count", "max", "min", "sum" ] One to many aggregation function results in return.
group boolean Merge signal data result by id

Responses

Code Body Type Description
200 object The dataset of the signal.
404 object The gateway context does not exist.

Object Parameter of 200 response:

Name Type Description
q object -
q.page integer Filter the starting index to start returning object for pagination purpose.
Minimum: 1
q.sort string Sort
q.epoch "s", "ms", "us" Unix timestamp format
q.group boolean Merge signal data result by id
q.limit integer Approximate number of items to return (Default = 1000).
Maximum: 2000
Minimum: 1
Default: 1000
q.order string Order
q.total integer Total results
q.bucket string Bucket
q.fields [ "count", "max", "min", "sum" ] -
q.signals [ string ] The identifier of a given signals array.
q.end_time integer Filter the time range to query to returning object (formatted as UNIX timestamp)
q.resource string Resource
q.identities [ string ] Filter by device identity
q.start_time integer Filter the time range to query to returning object (formatted as UNIX timestamp)
data [ object ] -

Object Parameter of 404 response:

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

aggrquerySignal

Retrieves the aggrgate dataset of the given {signal} based on time bucket given. default fields are min, max, sum, count. the result is sorted by report time desc.

SRS-ID: CHUB-INT-016

Arguments

parameters (object) - Object containing service call parameters.

Name Type Description
identity ^[a-zA-Z0-9_-]+$ The identifier of a given identity.
signal ^[a-zA-Z0-9_%-]+$ The definition of a given signal.
bucket "1m", "5m", "1h" The continuous aggregates query time chunk
start_time number The start of time range to filter data. Formatted as UNIX timestamp with fraction digits representing millisecond and microsecond. The precision is specified by epoch parameter.
data reported_time >= start_time
Maximum: 9999999999
Minimum: 1000000000
end_time number The end of time range to filter data. Formatted as UNIX timestamp with fraction digits representing millisecond and microsecond. The precision is specified by epoch parameter.
data reported_time < end_time
Maximum: 9999999999
Minimum: 1000000000
limit integer Approximate number of items to return (Default = 1000).
Maximum: 10000
Minimum: 1
Default: 1000
page integer Filter the starting index to start returning object for pagination purpose.
Maximum: 999999999999999
Minimum: 1
epoch "s", "ms", "us" Unix timestamp precision
fields [ "count", "max", "min", "sum" ] One to many aggregation function results in return.
group boolean Merge signal data result by id

Responses

Code Body Type Description
200 object The dataset of the signal.
404 object The gateway context does not exist.

Object Parameter of 200 response:

Name Type Description
q object -
q.page integer Filter the starting index to start returning object for pagination purpose.
Minimum: 1
q.sort string Sort
q.epoch "s", "ms", "us" Unix timestamp format
q.group boolean Merge signal data result by id
q.limit integer Approximate number of items to return (Default = 1000).
Maximum: 2000
Minimum: 1
Default: 1000
q.order string Order
q.total integer Total results
q.bucket string Bucket
q.fields [ "count", "max", "min", "sum" ] -
q.signals [ string ] The identifier of a given signals array.
q.end_time integer Filter the time range to query to returning object (formatted as UNIX timestamp)
q.resource string Resource
q.identities [ string ] Filter by device identity
q.start_time integer Filter the time range to query to returning object (formatted as UNIX timestamp)
data [ object ] -

Object Parameter of 404 response:

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

aggrquerySignals

Retrieves the aggrgate dataset of the given {signals} based on time bucket given. default fields are min, max, sum, count. the result is merged and sorted by create time desc.

SRS-ID: CHUB-INT-016

Arguments

parameters (object) - Object containing service call parameters.

Name Type Description
identity ^[a-zA-Z0-9_-]+$ The identifier of a given identity.
bucket "1m", "5m", "1h" The continuous aggregates query time chunk
page integer Filter the starting index to start returning object for pagination purpose.
Maximum: 999999999999999
Minimum: 1
epoch "s", "ms", "us" Unix timestamp precision
group boolean Merge signal data result by id
limit integer Approximate number of items to return (Default = 1000).
Maximum: 10000
Minimum: 1
Default: 1000
fields [ "count", "max", "min", "sum" ] -
signals [ string ] The identifier of a given signals array.
end_time number The end of time range to filter data (formatted as UNIX timestamp with fraction digits). The precision can be second, millisecond or microsecond, as specified by epoch parameter.
data reported_time < end_time
Maximum: 9999999999
Minimum: 1000000000
start_time number The start of time range to filter data (formatted as UNIX timestamp with fraction digits). The precision can be second, millisecond or microsecond, as specified by epoch parameter.
data reported_time >= start_time
Maximum: 9999999999
Minimum: 1000000000

Responses

Code Body Type Description
200 object The dataset of the signal.
404 object The gateway context does not exist.

Object Parameter of 200 response:

Name Type Description
q object -
q.page integer Filter the starting index to start returning object for pagination purpose.
Minimum: 1
q.sort string Sort
q.epoch "s", "ms", "us" Unix timestamp format
q.group boolean Merge signal data result by id
q.limit integer Approximate number of items to return (Default = 1000).
Maximum: 2000
Minimum: 1
Default: 1000
q.order string Order
q.total integer Total results
q.bucket string Bucket
q.fields [ "count", "max", "min", "sum" ] -
q.signals [ string ] The identifier of a given signals array.
q.end_time integer Filter the time range to query to returning object (formatted as UNIX timestamp)
q.resource string Resource
q.identities [ string ] Filter by device identity
q.start_time integer Filter the time range to query to returning object (formatted as UNIX timestamp)
data [ object ] -

Object Parameter of 404 response:

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

latestSignalsSearch

Retrieves the latest signals of the given {context_id}.

SRS-ID: CHUB-INT-009

Arguments

parameters (object) - Object containing service call parameters.

Name Type Description
page integer Pagination number
Maximum: 999999999999999
Minimum: 1
Default: 1
limit integer Number of items to return
Maximum: 2000
Minimum: 1
Default: 100
reverse boolean The order to sort by specific column
signals [ string ] Filter by signal name
sort_key "identity", "signal" Sort by specific column
Default: "identity"
identities [ string ] Filter by device identity

Responses

Code Body Type Description
200 object The latest signals of the context.
400 object Database query error
404 object The gateway context does not exist.

Object Parameter of 200 response:

Name Type Description
q object -
q.page integer The pagination number
q.limit integer The return number of item
q.reverse boolean The order to sort
q.signals [ string ] Name of signals
q.sort_key string Sort by specific column
q.identities [ string ] Name of devices
data [ object ] -
data[].identity string Name of device
data[].resource string Resource name (resource name or data_in)
data[].signal_id string Id of signal
data[].last_value string The most recent value of signal data by last_update time
data[].last_insert string Last update time of signal reported by server
data[].last_update string Last update time of signal reported by device
data[].signal_name string Name of signal (resource name)
total integer Total number of data

Object Parameter of 400 response:

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

Object Parameter of 404 response:

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

queryResource

Retrieves the dataset of the given {resource}. By default, the result is sorted by reported_time descend ordering, 1000 data point limit, and latest 7-day data received.

SRS-ID: CHUB-INT-016

Arguments

parameters (object) - Object containing service call parameters.

Name Type Description
resource string The identifier of a given resource.
start_time number The start of time range to filter data. Formatted as UNIX timestamp with fraction digits representing millisecond and microsecond. The precision is specified by epoch parameter.
data reported_time >= start_time
Maximum: 9999999999
Minimum: 1000000000
end_time number The end of time range to filter data. Formatted as UNIX timestamp with fraction digits representing millisecond and microsecond. The precision is specified by epoch parameter.
data reported_time < end_time
Maximum: 9999999999
Minimum: 1000000000
limit integer Approximate number of items to return (Default = 1000).
Maximum: 10000
Minimum: 1
Default: 1000
page integer Filter the starting index to start returning object for pagination purpose.
Maximum: 999999999999999
Minimum: 1
epoch "s", "ms", "us" Unix timestamp precision
identities string The identities list concat by ",".
group boolean Merge signal data result by id
sort "report", "server" Signal data query sort by options, default value is report.
order "desc", "asc" Signal data query sort order, default value is desc.

Responses

Code Body Type Description
200 object The dataset of the signal.
404 object The gateway context does not exist.

Object Parameter of 200 response:

Name Type Description
q object -
q.page integer Filter the starting index to start returning object for pagination purpose.
Minimum: 1
q.sort string Sort
q.epoch "s", "ms", "us" Unix timestamp format
q.group boolean Merge signal data result by id
q.limit integer Approximate number of items to return (Default = 1000).
Maximum: 2000
Minimum: 1
Default: 1000
q.order string Order
q.total integer Total results
q.bucket string Bucket
q.fields [ "count", "max", "min", "sum" ] -
q.signals [ string ] The identifier of a given signals array.
q.end_time integer Filter the time range to query to returning object (formatted as UNIX timestamp)
q.resource string Resource
q.identities [ string ] Filter by device identity
q.start_time integer Filter the time range to query to returning object (formatted as UNIX timestamp)
data [ object ] -

Object Parameter of 404 response:

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

Example

return Device2.queryResource({ identities="mockdevice", resource="temp", start_time=1703575524, end_time=1704180324 })

querySignal

Retrieves the dataset of the given {signal}. The result is sorted by reported_time desc by default

SRS-ID: CHUB-INT-016

Arguments

parameters (object) - Object containing service call parameters.

Name Type Description
identity ^[a-zA-Z0-9_-]+$ The identifier of a given identity.
signal ^[a-zA-Z0-9_%-]+$ The definition of a given signal.
start_time number The start of time range to filter data. Formatted as UNIX timestamp with fraction digits representing millisecond and microsecond. The precision is specified by epoch parameter.
data reported_time >= start_time
Maximum: 9999999999
Minimum: 1000000000
end_time number The end of time range to filter data. Formatted as UNIX timestamp with fraction digits representing millisecond and microsecond. The precision is specified by epoch parameter.
data reported_time < end_time
Maximum: 9999999999
Minimum: 1000000000
limit integer Approximate number of items to return (Default = 1000).
Maximum: 10000
Minimum: 1
Default: 1000
page integer Filter the starting index to start returning object for pagination purpose.
Maximum: 999999999999999
Minimum: 1
epoch "s", "ms", "us" Unix timestamp precision
group boolean Merge signal data result by id
sort "report", "server" Signal data query sort by options, default value is report.
order "desc", "asc" Signal data query sort order, default value is desc.

Responses

Code Body Type Description
200 object The dataset of the signal.
404 object The gateway context does not exist.

Object Parameter of 200 response:

Name Type Description
q object -
q.page integer Filter the starting index to start returning object for pagination purpose.
Minimum: 1
q.sort string Sort
q.epoch "s", "ms", "us" Unix timestamp format
q.group boolean Merge signal data result by id
q.limit integer Approximate number of items to return (Default = 1000).
Maximum: 2000
Minimum: 1
Default: 1000
q.order string Order
q.total integer Total results
q.bucket string Bucket
q.fields [ "count", "max", "min", "sum" ] -
q.signals [ string ] The identifier of a given signals array.
q.end_time integer Filter the time range to query to returning object (formatted as UNIX timestamp)
q.resource string Resource
q.identities [ string ] Filter by device identity
q.start_time integer Filter the time range to query to returning object (formatted as UNIX timestamp)
data [ object ] -

Object Parameter of 404 response:

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

querySignalSubscribers

Retrieves the subscribers of the given {signal}.

Arguments

parameters (object) - Object containing service call parameters.

Name Type Description
identity ^[a-zA-Z0-9_-]+$ The identifier of a given identity.
signal ^[a-zA-Z0-9_%-]+$ The definition of a given signal.

Responses

Code Body Type Description
200 object The subscribers of the signal.
404 object The gateway context does not exist.

Object Parameter of 200 response:

Name Type Description
q object -
q.signals [ string ] List of signal or resource names
q.identity string Name of device
data [ object ] -
data.offset string Last sync time of signal data
data.status string Current error or status of the session
data.identity string Name of device
data.session_id string Id of session
data.last_update string Last update time of suscriber session
data.signal_name string Name of signal or resource
data.session_type "sync_to_cloud", "script_async", "mqtt_qos1" Type of session, one of sync-to-cloud, script-async and mqtt-qos1

Object Parameter of 404 response:

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

querySignals

Retrieves the dataset of the given {signals}. The result is merged and sorted by reported_time desc by default

SRS-ID: CHUB-INT-016

Arguments

parameters (object) - Object containing service call parameters.

Name Type Description
identity ^[a-zA-Z0-9_-]+$ The identifier of a given identity.
page integer Filter the starting index to start returning object for pagination purpose.
Maximum: 999999999999999
Minimum: 1
sort "report", "server" Signal data query sort by options, default value is report.
epoch "s", "ms", "us" Unix timestamp precision
group boolean Merge signal data result by id
limit integer Approximate number of items to return (Default = 1000).
Maximum: 10000
Minimum: 1
Default: 1000
order "desc", "asc" Signal data query sort order, default value is desc.
signals [ string ] The identifier of a given signals array.
end_time number The end of time range to filter data. Formatted as UNIX timestamp with fraction digits representing millisecond and microsecond. The precision is specified by epoch parameter.
data reported_time < end_time
Maximum: 9999999999
Minimum: 1000000000
start_time number The start of time range to filter data. Formatted as UNIX timestamp with fraction digits representing millisecond and microsecond. The precision is specified by epoch parameter.
data reported_time >= start_time
Maximum: 9999999999
Minimum: 1000000000

Responses

Code Body Type Description
200 object The dataset of the signal.
404 object The gateway context does not exist.

Object Parameter of 200 response:

Name Type Description
q object -
q.page integer Filter the starting index to start returning object for pagination purpose.
Minimum: 1
q.sort string Sort
q.epoch "s", "ms", "us" Unix timestamp format
q.group boolean Merge signal data result by id
q.limit integer Approximate number of items to return (Default = 1000).
Maximum: 2000
Minimum: 1
Default: 1000
q.order string Order
q.total integer Total results
q.bucket string Bucket
q.fields [ "count", "max", "min", "sum" ] -
q.signals [ string ] The identifier of a given signals array.
q.end_time integer Filter the time range to query to returning object (formatted as UNIX timestamp)
q.resource string Resource
q.identities [ string ] Filter by device identity
q.start_time integer Filter the time range to query to returning object (formatted as UNIX timestamp)
data [ object ] -

Object Parameter of 404 response:

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

querySignalsSubscribers

Retrieves the subscribers of the given list of {signals}.

Arguments

parameters (object) - Object containing service call parameters.

Name Type Description
identity ^[a-zA-Z0-9_-]+$ The identifier of a given identity.
signals [ string ] A given array of signal or resource names.

Responses

Code Body Type Description
200 object The subscribers of the signal.
404 object The gateway context does not exist.

Object Parameter of 200 response:

Name Type Description
q object -
q.signals [ string ] List of signal or resource names
q.identity string Name of device
data [ object ] -
data.offset string Last sync time of signal data
data.status string Current error or status of the session
data.identity string Name of device
data.session_id string Id of session
data.last_update string Last update time of suscriber session
data.signal_name string Name of signal or resource
data.session_type "sync_to_cloud", "script_async", "mqtt_qos1" Type of session, one of sync-to-cloud, script-async and mqtt-qos1

Object Parameter of 404 response:

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

getRestoreStatus

get the restore status

Responses

Code Body Type Description
200 [ object ] Get status success.
500 object DB error.

Object Parameter of 200 response:

Name Type Description
done integer Number of files that restored
total integer Total number of file to restore
config string Task config
failed integer Number of files that restored failed
status string Restore status
task_id string Unique task id
created_at string Task created time
finished_at string Task completed time

Object Parameter of 500 response:

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

Example

return Device2.getRestoreStatus()

getRestoreTaskStatus

get the restore status

Arguments

parameters (object) - Object containing service call parameters.

Name Type Description
task_id string Restore task id

Responses

Code Body Type Description
200 [ object ] Get status success.
400 object Task id no found.
500 object DB error.

Object Parameter of 200 response:

Name Type Description
status string Restore status
signals [ object ] Restored signals in the file
signals[].device string -
signals[].signal string -
signals[].resource string -
file_name string Restore file name or restore url
finished_at string Task completed time

Object Parameter of 400 response:

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

Object Parameter of 500 response:

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

Example

return Device2.getRestoreTaskStatus({task_id="task_id"})

restoreTime

restore data from archived file by time range

Arguments

parameters (object) - Object containing service call parameters.

Name Type Description
note string Note for restore task
signals [ string ] Array for resotre signals
end_date string Restore end date with ISO 8601 date format YYYY-MM-DD
retention "0", "3", "6", "12", "36", "60", "120" Retention to change, 0 means temporary restore
identities [ string ] Array for resotre devices
start_date string Restore start date with ISO 8601 date format YYYY-MM-DD

Responses

Code Body Type Description
200 object Get status success.
400 object Parameter error.
500 object DB error.

Object Parameter of 200 response:

Name Type Description
total integer Numer og files to restore in this task
task_id string Unique task id

Object Parameter of 400 response:

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

Object Parameter of 500 response:

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

Example

return Device2.restoreTime({start_date="YYYY-MM-DD", end_date="YYYY-MM-DD"})

restoreUrl

restore data from archived file by urls

Arguments

parameters (object) - Object containing service call parameters.

Name Type Description
note string Note for restore task
urls array URL array for source daily archive files
signals [ string ] Array for resotre signals
retention "0", "3", "6", "12", "36", "60", "120" Retention to change, 0 means temporary restore
identities [ string ] Array for resotre devices

Responses

Code Body Type Description
200 object Get status success.
400 object Parameter error.
500 object DB error.

Object Parameter of 200 response:

Name Type Description
total integer Numer og files to restore in this task
task_id string Unique task id

Object Parameter of 400 response:

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

Object Parameter of 500 response:

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

Example

return Device2.restoreUrl({urls={"url1","url2"}})

retryTask

retry the failed files for the task

Arguments

parameters (object) - Object containing service call parameters.

Name Type Description
task_id string Retry task id

Responses

Code Body Type Description
200 object Retry success.
400 object Not able to find the failed file for the task id
500 object DB error.

Object Parameter of 200 response:

Name Type Description
message string Success message

Object Parameter of 400 response:

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

Object Parameter of 500 response:

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

Example

return Device2.retryTask({task_id="task_id"})

getDeviceMetrics

Retrieve aggregated device metrics.
It provides an overview of devices's status within any given period (1m/5m/1h).
Users have the flexibility to apply different functions such as count, max, min, sum, and avg to obtain pertinent results.
The metrics include:
1. Connection Metrics: Connected, Connection, Disconnection, Connection Error
2. Provision Metrics: Deleted, Whitelisted, Expired, Locked, Reprovision
3. Publish Metrics: Publish Count, Publish Size, Publish Resource Count

SRS-ID: CHUB-INT-021

Arguments

parameters (object) - Object containing service call parameters.

Name Type Description
aggregate_window "1m", "5m", "1h" Aggregate window.
Default: "1h"
aggregate_fn "count", "max", "min", "sum", "avg" Aggregate function.
Default: "count"
start_time integer Start time, formatted as UTC timestamp in second, default will be end_time - 1h.
Maximum: 9999999999
Minimum: 1000000000
end_time integer End time, formatted as UTC timestamp in second, default will be now
Maximum: 9999999999
Minimum: 1000000000
metric_name "connected", "connection", "disconnection", "deleted", "whitelisted", "provisioned", "expired", "locked", "reprovision", "publish_count", "publish_size", "publish_resource_count", "connection_error" Metric name.
Default: "connected"
limit integer Query limit.
Maximum: 2000
Minimum: 1
Default: 200
offset integer Query offset.
distinct boolean Query group by device id.

Responses

Code Body Type Description
200 [ object ] Aggregated metric data.
400 object Error.

Object Parameter of 200 response:

Name Type Description
time string UTC Time.
value number Aggregated value.
connection_error string Provide reason for error connections, only valid when metric is connection_error.

Object Parameter of 400 response:

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

Example

local body = {}
body.metric_name = "connection"
body.aggregate_fn = "count"
body.aggregate_window = "5m"
local ret = Device2.getDeviceMetrics(body)
print(ret)
-- Expected Result --
-- [
--   {
--     "time": "2024-07-29T07:40:00.000000Z",
--     "value": 1
--   },
--   {
--     "time": "2024-07-29T08:10:00.000000Z",
--     "value": 2
--   },
--   {
--     "time": "2024-07-29T08:15:00.000000Z",
--     "value": 2
--   }
-- ]

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.

SRS-ID: CHUB-INT-008

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.

Notes: because certificate needs to know the identity name beforehead, so makeIdentity
will not work if auth type is set to certificate.
auth.type "certificate", "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

Code Body Type Description
204 nil Identity successfully added to the gateway with the provided properties.
400 object The provided identity properties were invalid.
404 object The gateway context does not exist.
409 object Device object with this identity already exists.

Object Parameter of 400 response:

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

Object Parameter of 404 response:

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

Object Parameter of 409 response:

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

Example

return Device2.addIdentity({ identity="mockdevice" })

countIdentities

Returns the number of identities associated with the gateway.

SRS-ID: CHUB-INT-007

Arguments

parameters (object) - Object containing service call parameters.

Name Type Description
before number Filter identities whose "lastseen" timestamp is smaller than the given value.
status string Filter identities by provided status.

The following status are recognized:

a "locked" identity may not connect, even with valid authentication.
 a "reprovision" identity must be re-provisioned because
its authentication key has expired.
an "expired" identity has missed its provisioning window and must be reset.
 a "provisioned" identity has associated authentication credentials and is ready for use.
a "whitelisted" identity does not have authentication credentials
associated and must be provisioned.
 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

Code Body Type Description
200 object The number of identities.
400 object Invalid query parameters.

Object Parameter of 200 response:

Name Type Description
count number -

Object Parameter of 400 response:

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

Example

return Device2.countIdentities({
  identity="^mock."
})

getIdentity

Retrieves the properties of the given {identity}.

SRS-ID: CHUB-INT-008

Arguments

parameters (object) - Object containing service call parameters.

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

Responses

Code Body Type Description
200 object The properties and state of the identity.
404 object The gateway context or identity does not exist.

Object Parameter of 200 response:

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.

Notes: because certificate needs to know the identity name beforehead, so makeIdentity
will not work if auth type is set to certificate.
auth.type "certificate", "password", "token" The type of credential used to authenticate the identity.
auth.expire integer The expiration timestamp of this authentication object.

If the "expire" timestamp is surpassed, the status of a "whitelisted" identity
becomes "expired" and a "provisioned" identity becomes "reprovision".
tags [ object ] Array of tag pairs
tags[].name string The tag name with a maximum length of 128 bytes.
tags[].value string The tag value with a maximum length of 4096 bytes.
state object The current state of the device as represented by assigned resources.

For any resource with either a device-published ("reported") or
cloud-assigned ("set") value, the value will appear here. Note that a
device publishes to both the "reported" and the "set" value. An example
follows:

{
"temp": {
"timestamp": 1490392562583312,
"set": 1591,
"reported": 1591
}
}
state.*** object The current set and reported values for a given resource.
state..set* string, boolean, number The last value set from the cloud.
state..reported* string, boolean, number The last value reported from the device.
state..timestamp* number The time this resource was set.
lastip string The most recent IP address from which this device connected.
locked boolean The "locked" value for this device.

If set to "true", connection requests from this device are refused.
online boolean Indicates whether the device is currently connected to the gateway.
status "locked", "reprovision", "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.
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.

Object Parameter of 404 response:

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

Example

return Device2.getIdentity({
  identity="mockdevice"
})

listIdentities

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

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

SRS-ID: CHUB-INT-007

Arguments

parameters (object) - Object containing service call parameters.

Name Type Description
limit integer Limit the number of returned identities to indicated value (default 50).
Maximum: 2000
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)(\.(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.
after number Filter identities whose "lastseen" timestamp is greater 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.
 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.
tags string The criteria to filter identities using tag.

It should be arranged as an array of JSON objects, with each JSON object representing an individual criterion, and then converted into a string format.

The JSON object includes properties such as name, operator, and value.
{
name: "tag name"
operator: "filter operator"
value: "tag value"
}

supported filter operator:
gt: greater than
gte: greater than or equal
lt: less than
lte: less than or equal
eq: equals
ne: not equals

The comparison between the values is performed according to the alphabetical order of the strings.

The search result will match only if all criteria are met (logical AND).

Note: If "tags" is provided, then neither "tag.name" nor "tag.value" should be supplied.

Responses

Code Body Type Description
200 object Result object
400 object Invalid query parameters.
404 object The gateway context does not exist.

Object Parameter of 200 response:

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.

Notes: because certificate needs to know the identity name beforehead, so makeIdentity
will not work if auth type is set to certificate.
devices[].auth.type "certificate", "password", "token" The type of credential used to authenticate the identity.
devices[].auth.expire integer The expiration timestamp of this authentication object.

If the "expire" timestamp is surpassed, the status of a "whitelisted" identity
becomes "expired" and a "provisioned" identity becomes "reprovision".
devices[].tags [ object ] Array of tag pairs
devices[].tags[].name string The tag name with a maximum length of 128 bytes.
devices[].tags[].value string The tag value with a maximum length of 4096 bytes.
devices[].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", "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.
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.

Object Parameter of 400 response:

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

Object Parameter of 404 response:

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

Example

local tag_critera = {
  {
    name = "installed-date",
    operator = "gte",
    value = "20010101"
  },
  {
    name = "installed-date",
    operator = "lte",
    value = "20030101"
  },
  {
    name = "device-type",
    operator = "eq",
    value = "camera"
  },
}

local jsonString = to_json(tag_critera)

return Device2.listIdentities(
  {
     identity = "^mock.",
     tags = jsonString  
  }
)

makeIdentity

Generate a new identity.

SRS-ID: CHUB-INT-007

Arguments

parameters (object) - Object containing service call parameters.

Name Type Description
auth object The authentication object for identities connecting to the gateway.
auth.key string, null The credential used to authenticate the identity.

The value and format of this "key" is dependent on the "type" field.

Notes: because certificate needs to know the identity name beforehead, so makeIdentity
will not work if auth type is set to certificate.
auth.type "certificate", "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

Code Body Type Description
200 object The viewable properties of the generated identity.
400 object The provided identity properties were invalid.
404 object The gateway context does not exist.
409 object Could not generate identity; the range is exhausted.

Object Parameter of 200 response:

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.

Notes: because certificate needs to know the identity name beforehead, so makeIdentity
will not work if auth type is set to certificate.
auth.type "certificate", "password", "token" The type of credential used to authenticate the identity.
auth.expire integer The expiration timestamp of this authentication object.

If the "expire" timestamp is surpassed, the status of a "whitelisted" identity
becomes "expired" and a "provisioned" identity becomes "reprovision".
tags [ object ] Array of tag pairs
tags[].name string The tag name with a maximum length of 128 bytes.
tags[].value string The tag value with a maximum length of 4096 bytes.
state object The current state of the device as represented by assigned resources.

For any resource with either a device-published ("reported") or
cloud-assigned ("set") value, the value will appear here. Note that a
device publishes to both the "reported" and the "set" value. An example
follows:

{
"temp": {
"timestamp": 1490392562583312,
"set": 1591,
"reported": 1591
}
}
state.*** object The current set and reported values for a given resource.
state..set* string, boolean, number The last value set from the cloud.
state..reported* string, boolean, number The last value reported from the device.
state..timestamp* number The time this resource was set.
lastip string The most recent IP address from which this device connected.
locked boolean The "locked" value for this device.

If set to "true", connection requests from this device are refused.
online boolean Indicates whether the device is currently connected to the gateway.
status "locked", "reprovision", "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.
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.

Object Parameter of 400 response:

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

Object Parameter of 404 response:

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

Object Parameter of 409 response:

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

Example

return Device2.makeIdentity()

removeIdentities

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

For each identity in list, remove everything that is known about the identity including its state, authentication, and status. Future queries for these identities will return a 404 (not found).

SRS-ID: CHUB-INT-007

Arguments

parameters (object) - Object containing service call parameters.

Name Type Description
identities string A list of identities to delete, concatenated with ",".
The format: "[,, ...]".
For example: "mockdevice" or "mockdevice1,mockdevice2".

Responses

Code Body Type Description
204 nil All devices were successfully deleted.
400 object The provided identity list was invalid.
404 object The gateway context does not exist.

Object Parameter of 400 response:

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

Object Parameter of 404 response:

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

Example

return Device2.removeIdentities({
  identities="mockdevice1,mockdevice2"
})

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

SRS-ID: CHUB-INT-007

Arguments

parameters (object) - Object containing service call parameters.

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

Responses

Code Body Type Description
205 nil The device was successfully deleted.
404 object The gateway context or identity does not exist.

Object Parameter of 404 response:

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

Example

return Device2.removeIdentity({
  identity="mockdevice"
})

updateIdentities

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

SRS-ID: CHUB-INT-007

Arguments

parameters (object) - Object containing service call parameters.

Name Type Description
before number Filter identities whose "lastseen" timestamp is smaller than the given value.
status string Filter identities by provided status.

The following status are recognized:

a "locked" identity may not connect, even with valid authentication.
 a "reprovision" identity must be re-provisioned because
its authentication key has expired.
an "expired" identity has missed its provisioning window and must be reset.
 a "provisioned" identity has associated authentication credentials and is ready for use.
a "whitelisted" identity does not have authentication credentials
associated and must be provisioned.
 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

Code Body Type Description
204 nil The properties in identities matching the query, were successfully updated in the device gateway
400 object The provided device identity properties were invalid.
404 object The device gateway context or identity does not exist.

Object Parameter of 400 response:

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

Object Parameter of 404 response:

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

Example

return Device2.updateIdentities({
  identity="^mock.",
  add={
    tags = {
      {name="test1",value="test_value1"},
      {name="test2",value="test_value2"}
    }
  }
})

updateIdentity

Update {identity} properties.

SRS-ID: CHUB-INT-007

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.

Notes: because certificate needs to know the identity name beforehead, so makeIdentity
will not work if auth type is set to certificate.
auth.type "certificate", "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

Code Body Type Description
204 nil The identity properties were successfully updated in the device gateway
400 object The provided device identity properties were invalid
404 object The device gateway context or identity does not exist

Object Parameter of 400 response:

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

Object Parameter of 404 response:

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

Example

return Device2.updateIdentity({
  identity="mockdevice",
  locked=true
})

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.

SRS-ID: CHUB-INT-009

Arguments

parameters (object) - Object containing service call parameters.

Name Type Description
identity string The device's identifier

Responses

Code Body Type Description
200 object 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 }}
404 object The gateway context or identity does not exist.

Object Parameter of 200 response:

Name Type Description

Object Parameter of 404 response:

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

setIdentityState

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

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

SRS-ID: CHUB-INT-010

Arguments

parameters (object) - Object containing service call parameters.

Name Type Description
identity string The device's identifier
simulate boolean If set to 'true', force to trigger event as real device.
^(?!identity|simulate$).? string, boolean, number Values to be written in the resource

Responses

Code Body Type Description
204 nil The new value was successfully "set".
400 object The "set" object is invalid.
404 object The gateway context or identity does not exist.
409 object The state is not settable.

Object Parameter of 400 response:

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

Object Parameter of 404 response:

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

Object Parameter of 409 response:

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

addIdentityTag

Add an array of tags to the specified identity.

SRS-ID: CHUB-INT-011

Arguments

parameters (object) - Object containing service call parameters.

Name Type Description
identity string The identifier of a given identity.
replace boolean If set to 'true', any 'name' in the given 'tags' already exist, they are replaced.
tags [ object ] An array of tag pairs to add to the identity
tags[].name string The tag name with a maximum length of 128 bytes.
tags[].value string The tag value with a maximum length of 4096 bytes.

Responses

Code Body Type Description
204 nil Tags sucessfully added to the identity with the provided properties.
400 object The provided tags properties were invalid.
404 object The identity does not exist.

Object Parameter of 400 response:

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

Object Parameter of 404 response:

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

getIdentityTag

Returns a tag values in the specified identity.

SRS-ID: CHUB-INT-011

Arguments

parameters (object) - Object containing service call parameters.

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

Responses

Code Body Type Description
200 [ string ] List all the value in this tag name.
400 object The provided properties were invalid.
404 object The identity does not exist.

Object Parameter of 400 response:

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

Object Parameter of 404 response:

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

listTagNames

Returns all tag names in the gateway.

SRS-ID: CHUB-INT-011

Responses

Code Body Type Description
200 [ string ] List all tag names in this gateway.
400 object The provided properties were invalid.

Object Parameter of 400 response:

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

removeIdentityTag

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

SRS-ID: CHUB-INT-011

Arguments

parameters (object) - Object containing service call parameters.

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

Responses

Code Body Type Description
204 nil Delete tags was successful.
400 object The provided properties were invalid.
404 object The identity does not exist.

Object Parameter of 400 response:

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

Object Parameter of 404 response:

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

getDevicePermission

Retrieves the permission setting of the given {identity}.

SRS-ID: CHUB-INT-017

Arguments

parameters (object) - Object containing service call parameters.

Name Type Description
identity ^[a-zA-Z0-9_-]+$ The identifier of a given identity.

Responses

Code Body Type Description
200 object The permission setting of the device.
404 object The gateway context does not exist.

Object Parameter of 200 response:

Name Type Description

Object Parameter of 404 response:

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

updateDevicePermission

update the permission setting of the {identity}.

SRS-ID: CHUB-INT-017

Arguments

parameters (object) - Object containing service call parameters.

Name Type Description
identity ^[a-zA-Z0-9_-]+$ The identifier of a given identity.
permission object -
permission.subscript object The permission of subscript entity.
permission.publish_as object The permission of publish_as entity.

Responses

Code Body Type Description
204 nil The settings were updated successfully.
404 object The gateway context does not exist.

Object Parameter of 404 response:

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

publishData

Adds desired existing resource/signal data or dataset into database directly

SRS-ID: CHUB-EXT-004

Arguments

parameters (object) - Object containing service call parameters.

Name Type Description
payload [ object ] A batch of data to be published.
payload[].values object Key value pair, the key is the resource name, value is the resource value.
payload[].timestamp number Unix timestamp in microsecond, example -> 1693297066429357, need to be
within 1 day in future and 10 years in past.
identity string The device name.

Responses

Code Body Type Description
204 nil The batch data was successfully processed.
400 object Wrong parameters or headers.

Object Parameter of 400 response:

Name Type Description
message string The error message for this error

Example

return Device2.publishData({
  identity = "mockdevice",
  payload = {
    {
      -- Please select a valid timestamp
      timestamp = 1704178234,
      values = {
        -- Resource key value pair
        temp = 30
      }
    },
    {
      timestamp = 1704178240,
      values = {
        temp = 7
      }
    }
  }
})

getGatewaySettings

Returns the current settings for the gateway.

The settings used to establish connectivity between devices and West Connectivity. 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
  })

SRS-ID: CHUB-INT-006

Responses

Code Body Type Description
200 object The settings for the gateway.
404 object The gateway context does not exist.

Object Parameter of 200 response:

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 /api:v1/stack/alias HTTP/1.1
Host: <fqdn>
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Content-Length: <length>

temp=451
permission object Solution level permission for all devices
permission.gateway [ ^[\w-_:\.]+$ ] A gateway device is allowed to publish as other devices within this solution
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", "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.
 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.
solution_sync object The solution sync linking information.
source is the upsteam linking
target is the downsteam linking
solution_sync.source object The solution sync linking configuration.
solution_sync.target object The solution sync linking configuration.
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.

West Connectivity 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
West Connectivity. 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.
partition_key_level string Partition key level
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.
enable_signal_parser boolean When signal parser is enabled, the server will parse the payload of config_io/data_in,
translate them into signal data and save them into database.

Object Parameter of 404 response:

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

addResource

Create the definition of resource {alias}. To add resources from scripting use

Arguments

parameters (object) - Object containing service call parameters.

Name Type Description
alias [.$]+$ The name of this resource.
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 "boolean", "number", "string" 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.
script object Enable scripting execution and its qos level.
script.qos integer -
script.enable boolean DEPRECATED, use 'enabled' instead
script.enabled boolean -
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".
timeout integer Resource timeout event duration.
Maximum: 86400
Minimum: 30
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.
retention "0", "3", "6", "12", "36", "60", "120" The period of incoming data keeping at cloud/local storage.
Default: 12
cloud_sync object Enable resource incoming data steaming to cloud site storage as backup, or not. DEPRECATED, use 'replication' instead
cloud_sync.enable boolean -
replication object Enable replication of resource data to paired connector. Needs to be enabled on both connectors.
replication.enabled boolean -

Responses

Code Body Type Description
204 nil The resource was successfully added.
400 object The provided resource definition is invalid.
404 object The gateway context does not exist.
409 object The resource already exists.

Object Parameter of 400 response:

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

Object Parameter of 404 response:

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

Object Parameter of 409 response:

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

Example

return Device2.addResource({alias="temp",format="number"})

getGatewayResource

Retrieve the definition of resource {alias}.

To Update resources from scripting use:

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

SRS-ID: CHUB-INT-012

Arguments

parameters (object) - Object containing service call parameters.

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

Responses

Code Body Type Description
200 object The resource definition object.
400 object The provided resource name is invalid
404 object The gateway context or resource does not exist.

Object Parameter of 200 response:

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 "boolean", "number", "string" 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.
script object Enable scripting execution and its qos level.
script.qos integer -
script.enable boolean DEPRECATED, use 'enabled' instead
script.enabled boolean -
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".
timeout integer Resource timeout event duration.
Maximum: 86400
Minimum: 30
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.
retention "0", "3", "6", "12", "36", "60", "120" The period of incoming data keeping at cloud/local storage.
Default: 12
cloud_sync object Enable resource incoming data steaming to cloud site storage as backup, or not. DEPRECATED, use 'replication' instead
cloud_sync.enable boolean -
replication object Enable replication of resource data to paired connector. Needs to be enabled on both connectors.
replication.enabled boolean -

Object Parameter of 400 response:

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

Object Parameter of 404 response:

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

getGatewayResourceList

Retrieve the list of resource.

SRS-ID: CHUB-INT-012

Responses

Code Body Type Description
200 object The resource definition object.

Object Parameter of 200 response:

Name Type Description
*** 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.
.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* "boolean", "number", "string" 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.
.script* object Enable scripting execution and its qos level.
.script.qos* integer -
.script.enable* boolean DEPRECATED, use 'enabled' instead
.script.enabled* boolean -
.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".
.timeout* integer Resource timeout event duration.
Maximum: 86400
Minimum: 30
.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.
.retention* "0", "3", "6", "12", "36", "60", "120" The period of incoming data keeping at cloud/local storage.
Default: 12
.cloud_sync* object Enable resource incoming data steaming to cloud site storage as backup, or not. DEPRECATED, use 'replication' instead
.cloud_sync.enable* boolean -
.replication* object Enable replication of resource data to paired connector. Needs to be enabled on both connectors.
.replication.enabled* boolean -

updateResource

Update the definition of resource {alias}. To Update resources from scripting use:

return Device2.updateResource({alias="temp5",format="boolean"})

Arguments

parameters (object) - Object containing service call parameters.

Name Type Description
alias [.$]+$ The name of this resource.
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 "boolean", "number", "string" 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.
script object Enable scripting execution and its qos level.
script.qos integer -
script.enable boolean DEPRECATED, use 'enabled' instead
script.enabled boolean -
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".
timeout integer Resource timeout event duration.
Maximum: 86400
Minimum: 30
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.
retention "0", "3", "6", "12", "36", "60", "120" The period of incoming data keeping at cloud/local storage.
Default: 12
cloud_sync object Enable resource incoming data steaming to cloud site storage as backup, or not. DEPRECATED, use 'replication' instead
cloud_sync.enable boolean -
replication object Enable replication of resource data to paired connector. Needs to be enabled on both connectors.
replication.enabled boolean -

Responses

Code Body Type Description
204 nil The resource was successfully updated.
400 object The provided resource definition is invalid.
404 object The gateway context or resource does not exist.

Object Parameter of 400 response:

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

Object Parameter of 404 response:

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:

  • connect - A device has successfully authenticated to the gateway
  • disconnect - An authenticated device has disconnected

  • data_in - An authenticated device has published data. The event.payload field contains an array of objects in the form of:

    {"timestamp": <timestamp>, "values":[{"<alias>": <value>}]}

  • content_in - An authenticated device has uploaded file in content store. The event.payload field contains an Json objects in the form of:

    {"id": <id>, "length": <length>, "tags": <tags>, "type": <type>}

  • deleted - A device has been deleted.

  • provisioned - An identity has successfully provisioned.
  • expired - An identity failed to provision because its provisioning window has expired.

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", "content_in", "deleted", "provisioned", "expired" The event type
payload [ object ] List of data transmitted by the identity. Only for events of type 'data_in'
payload[].values object Map of resources
payload[].values.*** string, boolean, number Resource value
payload[].timestamp number Update time in epoch micro-seconds
identity string The authenticated identity of the connected device
protocol string Specifies the protocol that the device connected with.
timestamp integer The UNIX timestamp at which the event was generated
connection_id string A unique id shared across all events generated from the same network connection
updated_resources [ string ] List of resource aliases from the payload which has been set as Identity state.

Example

-- Data are in the 'event' argument.

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 West Connectivity Time-Series database.

Tsdb.write({ metrics = metrics})

Service Health Check

Operations

/api/v1/health

Enable the hosting system to check if service is active and running

SRS-ID: CHUB-INT-021

Arguments

No Content

Responses

Name Type Description
200 string OK

Errors

No content