Device Gateway Service

API allowing communication with IoT devices.

Operations

Device

Product

Other

Events

Operations

Device


create

Creates a device with the given serial number (assumed not to exist)

Enables the serial number

Returns the client resource id of the new serial number.

Arguments
parameters - object - Object containing service call parameters.
Name Type Description
pid string Product ID
device_sn string Device serial number
Responses
The client resource ID - string

The client resource ID

Example
return Device.create({
  pid="xxxxxxxxxxxxx",
  ["device_sn"]="1"
})

list

Returns list of devices for a given product. By default, only 50 devices are returned. You can fetch up to 100 devices per call.

Arguments
parameters - object - Object containing service call parameters.
Name Type Description
pid string Product ID
offset integer Offset in device list to start returning from.
limit integer {5..100} Maximum number of devices to return.
Default: 50
Responses
List of devices of this product. - [ object ]
Name Type Description
sn string Device serial number unique withing the product scope.
rid string Resource Identifier (RID) of the device.
status "notactivated", "activated", "expired" Device provisionning status.
Example
local devices = Device.list({ pid="xxxxxxxxxxxxx" }) for k,device in pairs(devices) do
  print(device.sn)
end

write

Writes values to serial number resources. Returns, for each key, whether the write was successful (ok) or not (invalid).

Arguments
parameters - object - Object containing service call parameters.
Name Type Description
pid string Product ID
device_sn string Device identity
<keys> string, boolean, number Values to be written in the key
Responses
Returns, for each key, whether the write was successful (ok) or not (invalid) - object
Name Type Description
<keys> "ok", "invalid" Whether the write was successful (ok) or not (invalid) for this key.
Example
return Device.write({
  pid="xxxxxxxxxxxxx",
  ["device_sn"]="1",
  state="1"
})

Product


productInfo

get product information

Arguments
parameters - object - Object containing service call parameters.
Name Type Description
pid string Product ID
Responses
Product information object. - object
Name Type Description
id string Identifier of the product.
rid string Resource Identifier (RID) of the product.
label string Display name of the product.
endpoint string URL of the device data endpoint.

Other


(deprecated) rpcCall

Convert the Product ID ({pid}) to its CIK, add the CIK as the rpc auth object, and forward the request.
See http://docs.exosite.com/rpc/ for argument and response details.

WARNING this operation is deprecated and will be removed soon.. Please use Device.write() instead. (http://docs.exosite.com/murano/services/device/#write)

Arguments
parameters - object - Object containing service call parameters.
Name Type Description
pid string Product ID: needs to be found in Product ID list of solution service config for access rights.
auth object Murano user authentication options. The request is always authenticated with the user business ID.
More info on Murano OneP documentation page.
auth.client_id string Client context RID. Authenticates as the given client if the CIK identifies an ancestor of the given client.
calls [ object ] List of PRC definitions.
calls[].id string Response mapping ID of the call, return in the response
calls[].arguments [ string, object, number ] List of argument corresponding to the target procedure.
calls[].procedure "read", "write", "writegroup", "record", "recordbatch", "flush", "wait", "create", "move", "update", "info", "listing", "drop", "usage", "map", "lookup", "unmap", "share", "revoke", "activate", "deactivate" Name of the remote procedure to be executed.
Responses
List of RPC calls results - [ object ]
Name Type Description
id string {..40} RPC request ID
error object RPC call errors
error.code integer RPC error code
error.context "arguments", "auth", "calls", "procedure" RPC error data
error.message string RPC error message
result [ object ] RPC arguments, defined by the RPC call
status "ok", "fail" RPC call status

Events


datapoint

This event is triggered by data generated by devices and transmitted by the One Platform device API. More information about how to send data to the OneP API on http://docs.exosite.com/murano/products/device_api/http/#write

Arguments
data - object - The data from the device
Name Type Description
api "write", "record" Provider API
pid string Device Product ID
rid string Unique device resource ID
seq integer The message sequence number for specific resource ID
alias string Device resource alias
value [ integer
or number
or string ] {..2}
Data transmitted by the device.
If API == write, the first value is "live",
If API == record, the first value is the event timestamp as integer.
The second value is always the data transmitted, either number or string.
device_sn string Device serial number
source_ip string The device source IP
timestamp integer Server recording time for the event
Example
function handle_device_datapoint (data)

 ... 

end