Difference between revisions of "WISE-PaaS/SRP Services"
(Add MatchGroup) |
|||
(25 intermediate revisions by 4 users not shown) | |||
Line 36: | Line 36: | ||
== COMMON DATABASE SCHEME == | == COMMON DATABASE SCHEME == | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
=== Common Database Scheme === | === Common Database Scheme === | ||
Line 52: | Line 42: | ||
=== Common Database Table Details === | === Common Database Table Details === | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
Table '''Device''' | Table '''Device''' | ||
Line 69: | Line 47: | ||
[[File:Device tbl.png|RTENOTITLE]] | [[File:Device tbl.png|RTENOTITLE]] | ||
− | |||
− | |||
=== Non-Structure Data (MongoDB/DocumentDB) === | === Non-Structure Data (MongoDB/DocumentDB) === | ||
Line 103: | Line 79: | ||
== API MANAGEMENT (RESTFUL APIS) == | == API MANAGEMENT (RESTFUL APIS) == | ||
− | === Common | + | === <span style="font-size:medium">'''Common RESTful APIs'''</span> === |
− | * | + | *<span style="font-size:larger">'''Device APIs'''</span> |
− | < | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | </ | ||
− | |||
<blockquote> | <blockquote> | ||
− | * | + | *'''Get Methods''' |
− | ** | + | **/common/v1/devices - Get Devices |
− | */ | + | **/common/v1/devices/<id> - Get Device |
− | **< | + | **/common/v1/devices/<id>/plugins - Get Plugins/Device |
− | **< | + | **/common/v1/devices/<id>/sensors - Get Sensors/Device |
− | ** | + | *'''Post Methods''' |
− | */ | + | **/common/v1/devices - Add Devices |
− | **< | + | *'''Put Methods''' |
+ | **/common/v1/devices - Edit Devices | ||
+ | *'''Delete Methods''' | ||
+ | **/common/v1/devices/<id> - Delete Device | ||
</blockquote> | </blockquote> | ||
− | * | + | *<span style="font-size:larger">'''Data APIs'''</span> |
− | < | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
<blockquote> | <blockquote> | ||
− | * | + | *'''Get Methods''' |
− | **< | + | **/common/v1/data/<id>/latestdata?<Parameter> - Get Latest Data |
− | + | **/common/v1/data/<id>/histdata?<Parameter> - Get Hist Data | |
− | */ | + | **/common/v1/data/<id>/statisticdata?<Parameter> - Get Statistic Data |
− | |||
− | |||
− | */ | ||
− | |||
</blockquote> | </blockquote> | ||
− | === | + | === <span style="font-size:medium">'''Customized RESTful APIs'''</span> === |
− | *'''RMM''' | + | *<span style="font-size:larger">'''RMM'''</span> |
<blockquote> | <blockquote> | ||
− | */ | + | *'''<span style="font-size:larger">Device Group APIs</span>''' |
− | */ | + | **'''Get Methods''' |
− | */ | + | ***/rmm/v1/devicegroups - Get DeviceGroups |
− | */ | + | ***/rmm/v1/devicegroups/<id> - Get DeviceGroup |
− | * | + | ***/rmm/v1/devicegroups/<id>/devices?<Parameter> - Get Devices/DeviceGroup |
+ | **'''Post Methods''' | ||
+ | ***/rmm/v1/devicegroups - Add DeviceGroups | ||
+ | **'''Put Methods''' | ||
+ | ***/rmm/v1/devicegroups - Edit DeviceGroups | ||
+ | **'''Delete Methods''' | ||
+ | ***/rmm/v1/devicegroups/<id> - Delete DeviceGroup | ||
+ | *'''<span style="font-size:larger">Device APIs</span>''' | ||
+ | **'''Get Methods''' | ||
+ | ***/rmm/v1/devices - Get Devices | ||
+ | ***/rmm/v1/devices/<id> - Get Device | ||
+ | ***/rmm/v1/devices/unassigned - Get UnAssigned Devices | ||
+ | ***/rmm/v1/devices/<id>/plugins_within_timerange - Get Plugins/Device within a time range | ||
+ | ***/rmm/v1/devices/<id>/plugins - Get Plugins/Device | ||
+ | ***/rmm/v1/devices/<id>/sensors - Get Sensors/Device | ||
+ | **'''Put Methods''' | ||
+ | ***/rmm/v1/devices - Edit Devices | ||
+ | *<span style="font-size:larger">'''Account APIs'''</span> | ||
+ | **'''Get Methods''' | ||
+ | ***/rmm/v1/accounts?<Parameter> - Get Accounts | ||
+ | ***/rmm/v1/accounts/<primary-key> - Get Account | ||
+ | ***/rmm/v1/accounts/login?<Parameter> - Login | ||
+ | ***/rmm/v1/accounts/<primary-key>/groups - Get Groups/Account | ||
+ | **'''Post Methods''' | ||
+ | ***/rmm/v1/accounts - Add Accounts | ||
+ | ***/rmm/v1/accounts/logout - Logout | ||
+ | **'''Put Methods''' | ||
+ | ***/rmm/v1/accounts - Edit Accounts | ||
+ | **'''Delete Methods''' | ||
+ | ***/rmm/v1/accounts/<id> - Delete Account | ||
+ | *'''<span style="font-size:larger">Role APIs</span>''' | ||
+ | **'''Get Methods''' | ||
+ | ***/rmm/v1/roles?<Parameter> - Get Roles | ||
+ | ***/rmm/v1/roles/<id> - Get Role | ||
+ | ***/rmm/v1/roles/<id>/Accounts?<Parameter> - Get Accounts/Role | ||
+ | **'''Post Methods''' | ||
+ | ***/rmm/v1/roles - Add Roles | ||
+ | **'''Put Methods''' | ||
+ | ***/rmm/v1/roles - Edit Roles | ||
+ | **'''Delete Methods''' | ||
+ | ***/rmm/v1/roles/<id> - Delete Role | ||
+ | *'''<span style="font-size:larger">Device Control APIs</span>''' | ||
+ | **'''Get Methods''' | ||
+ | ***/rmm/v1/devicetrl/<id>/latestdata?<Parameter> - Get Latest Data | ||
+ | ***/rmm/v1/devicetrl/<id>/data?<Parameter> - Get Real-time Data | ||
+ | **'''Post Methods''' | ||
+ | ***/rmm/v1/devicectrl/data - Set Data | ||
+ | ***/rmm/v1/devicectrl/intermittent_report - Intermittent Report | ||
+ | *<span style="font-size:larger">'''Power APIs'''</span> | ||
+ | **'''Post Methods''' | ||
+ | ***/rmm/v1/power/device - Power/Device | ||
+ | ***/rmm/v1/power/group - Power/Group | ||
+ | *'''<span style="font-size:larger">Process APIs</span>''' | ||
+ | **'''Post Methods''' | ||
+ | ***/rmm/v1/processes - Ctrl Process | ||
+ | ***/rmm/v1/processes/devices/<id> - Get Process | ||
</blockquote> | </blockquote> | ||
*'''IMM''' | *'''IMM''' | ||
Line 201: | Line 183: | ||
*… | *… | ||
</blockquote> | </blockquote> | ||
+ | |||
== DEVICE CONNECTIVITY == | == DEVICE CONNECTIVITY == | ||
Line 216: | Line 199: | ||
*'''MQTT Topic Define''' | *'''MQTT Topic Define''' | ||
− | **From Server to Agent:<br/>/wisepaas/<product>/<agentId>/<function>ack | + | **From Server to Agent:<br/>/wisepaas/<tenantId>/<product>/<agentId>/<function>ack |
− | **From Agent to Server:<br/>/wisepaas/<product>/<agentId>/<function>req | + | **From Agent to Server:<br/>/wisepaas/<tenantId>/<product>/<agentId>/<function>req |
[[File:Mes topic def.png|RTENOTITLE]] | [[File:Mes topic def.png|RTENOTITLE]] | ||
− | *'''Preserved Topic for Common use''' | + | *'''Preserved Topic for Common use, the product name "device" is preserved for common use.''' |
− | **Agent Registration Topic: /wisepaas/device/<agentId>/ | + | **Agent Registration Topic: /wisepaas/<tenantId>/'''device'''/<agentId>/'''agentinfo'''ack |
− | **Will Message Topic: /wisepaas/device/<agentId>/willmessage Or /wisepaas/device/<serverId>/willmessage | + | **Will Message Topic: /wisepaas/<tenantId>/'''device'''/<agentId>/'''willmessage''' Or /wisepaas/<tenantId>/'''device'''/<serverId>/'''willmessage''' |
− | **Command Topic: /wisepaas/device/<agentId>/ | + | **Command Topic: /wisepaas/<tenantId>/'''device'''/<agentId>/'''agentaction'''req |
− | **Response Topic: /wisepaas/device/<agentId>/ | + | **Response Topic: /wisepaas/<tenantId>/'''device'''/<agentId>/'''agentaction'''ack |
− | **Report Data Topic: /wisepaas/device/<agentId>/ | + | **Report Data Topic: /wisepaas/<tenantId>/'''device'''/<agentId>/'''devinfo'''ack |
*'''Custom Topic Sample''' | *'''Custom Topic Sample''' | ||
− | ** | + | **''''''For example, the product name is "custom" and function name is "powerctrl", the topic for Power ON/OFF control will be: |
− | + | ***Server send command with topic: /wisepaas/<tenantId>/'''custom'''/<agentId>/'''powerctrl'''req | |
− | Server send command with topic: /wisepaas/custom/<agentId>/ | + | ***Agent send response with topic: /wisepaas/<tenantId>/'''custom'''/<agentId>'''/powerctrl'''ack |
− | |||
− | Agent send response with topic: /wisepaas/custom/<agentId>/ | ||
=== Handshake Sequence === | === Handshake Sequence === | ||
Line 291: | Line 272: | ||
**handlerName: target device supported function block (Plugin or Handler) name, value type is string. | **handlerName: target device supported function block (Plugin or Handler) name, value type is string. | ||
**commCmd: the sub command ID in function block (Plugin or Handler), value type is unsigned integer. | **commCmd: the sub command ID in function block (Plugin or Handler), value type is unsigned integer. | ||
+ | **content: the contain data. | ||
+ | **opTS: message generated time stamp (optional), the unit is millisecond. | ||
+ | ***format: "opTS":{"$date":1494308768000} | ||
*Device Registration Format: | *Device Registration Format: | ||
− | {| border="1" cellspacing="0" cellpadding="0" | + | {| border="1" cellspacing="0" cellpadding="0" style="width: 675px;" |
|- | |- | ||
− | | style="width: | + | | style="width: 671px;" | |
{ | { | ||
− | "agentID":" | + | "agentID":"00000001-0000-0000-0000-000babbb7ef3", |
"handlerName":"general", //defined for device registration | "handlerName":"general", //defined for device registration | ||
Line 304: | Line 288: | ||
"commCmd":1, //defined for device registration | "commCmd":1, //defined for device registration | ||
− | "hostname":"PC001104", //target device name | + | "content": { |
+ | |||
+ | "parentID":"", //the parent device ID if the target device has parent device. | ||
+ | |||
+ | "hostname":"PC001104", //target device name | ||
+ | |||
+ | "sn":"14DAE996BE04", //target device serial number | ||
+ | |||
+ | "mac":"14DAE996BE04", //target device mac address | ||
− | " | + | "version":"1.0.0.0", //client application version |
− | " | + | "type":"IPC", //target device type |
− | " | + | "tag":"RMM,Custom", //target device tag for supported software product name. |
− | " | + | "product":"", //target device hardware product name |
− | " | + | "manufacture":"", //target device hardware manufacture |
− | " | + | "account":"anonymous", //bind target device to a specific account |
− | " | + | "password":"", //encrypt with DES and Base64 |
− | " | + | "status":1 //1: registration, 0: un-registration |
− | | + | } |
} | } | ||
Line 337: | Line 329: | ||
{ | { | ||
− | | + | "agentID":"00000001-0000-0000-0000-000babbb7ef3", |
− | | + | "handlerName":"custom", |
− | | + | "commCmd":123, |
− | | + | "content":{ |
− | | + | "opTS":{"$date":1494308768000}, |
− | | + | "custom_object":{ //User defined report data object. |
− | | + | "custom_data1":"string_value", |
+ | |||
+ | "custom_data2":123, | ||
+ | |||
+ | "custom_data3":false | ||
+ | |||
+ | } | ||
} | } | ||
Line 811: | Line 809: | ||
{ | { | ||
− | | + | "agentID":"00000001-0000-0000-0000-000babbb7ef3", |
− | | + | "handlerName":"custom", |
− | | + | "commCmd":123, |
− | | + | "content":{ |
− | | + | "opTS":{"$date":1494308768000}, |
− | | + | "custom_object":{ //User defined report data object in IPSO format. |
− | | + | "bn":"custom_object", |
− | | + | "e":[ |
− | + | {"n":"custom_data1","sv":"string_value"}, | |
− | ] | + | {"n":"custom_data2","v":123}, |
+ | |||
+ | {"n":"custom_data3","bv":false} | ||
+ | |||
+ | ] | ||
+ | |||
+ | } | ||
} | } | ||
Line 885: | Line 889: | ||
[TBD] | [TBD] | ||
− | === Common | + | === <span style="font-size:medium">'''Common RESTful APIs'''</span> === |
− | + | *<span style="font-size:larger">'''Device APIs'''</span> | |
+ | <blockquote> | ||
+ | *'''Get Methods''' | ||
+ | **/common/v1/devices - Get Devices | ||
+ | **/common/v1/devices/<id> - Get Device | ||
+ | **/common/v1/devices/<id>/plugins - Get Plugins/Device | ||
+ | **/common/v1/devices/<id>/sensors - Get Sensors/Device | ||
+ | *'''Post Methods''' | ||
+ | **/common/v1/devices - Add Devices | ||
+ | *'''Put Methods''' | ||
+ | **/common/v1/devices - Edit Devices | ||
+ | *'''Delete Methods''' | ||
+ | **/common/v1/devices/<id> - Delete Device | ||
+ | </blockquote> | ||
+ | *<span style="font-size:larger">'''Data APIs'''</span> | ||
+ | <blockquote> | ||
+ | *'''Get Methods''' | ||
+ | **/common/v1/data/<id>/latestdata?<Parameter> - Get Latest Data | ||
+ | **/common/v1/data/<id>/histdata?<Parameter> - Get Hist Data | ||
+ | **/common/v1/data/<id>/statisticdata?<Parameter> - Get Statistic Data | ||
+ | </blockquote> | ||
=== RMM/OTA/SCADA/IMM Integration === | === RMM/OTA/SCADA/IMM Integration === | ||
Line 898: | Line 922: | ||
*'''Scenario 1) RMM show more information about account''' | *'''Scenario 1) RMM show more information about account''' | ||
− | <blockquote>Due to common account’s fields not enough for more information on RMM, the RMM would have “AccountExt” table to extend and manage. <br/></blockquote><blockquote>Step 1) Get common account information via ZMQ then use primary-key to link these tables. <br/></blockquote><blockquote> [[File:Common account.png|RTENOTITLE]] <br/></blockquote><blockquote>Step 2) Merge the result common/custom account information, then return. </blockquote> | + | <blockquote>Due to common account’s fields not enough for more information on RMM, the RMM would have “AccountExt” table to extend and manage.<br/></blockquote><blockquote>Step 1) Get common account information via ZMQ then use primary-key to link these tables.<br/></blockquote><blockquote> [[File:Common account.png|RTENOTITLE]]<br/></blockquote><blockquote>Step 2) Merge the result common/custom account information, then return. </blockquote> |
*'''Scenario 2) OTA deploy a package for region devices''' | *'''Scenario 2) OTA deploy a package for region devices''' | ||
<blockquote>The OTA may deploy an update package to devices locate on America, and record the upgrade status. Step 1) Adopt common device information, use advSearch to get these devices on America. Step 2) For these agentId/deviceId to send the request and record the status on OTA database.</blockquote> | <blockquote>The OTA may deploy an update package to devices locate on America, and record the upgrade status. Step 1) Adopt common device information, use advSearch to get these devices on America. Step 2) For these agentId/deviceId to send the request and record the status on OTA database.</blockquote> | ||
+ | == WISEAgent Source Code == | ||
+ | |||
+ | *[https://github.com/ADVANTECH-Corp/WISE-PaaS-2.0-WISEAgent https://github.com/ADVANTECH-Corp/WISE-PaaS-2.0-WISEAgent] | ||
== Document == | == Document == | ||
− | |||
− |
Latest revision as of 08:09, 9 May 2017
Contents
OVERVIEW
- API Management
Adopt Azure API Management/Open-source (WSO2) to integrate various SRP services API.
- Common Service APIs/Lib
Basic Account/Device/Group/Role operation APIs, including Add/Edit/Delete/Search/Advance Search WISE-PaaS administration information (Product Support, version, capability…etc.)
- Custom/SRP Service
RMM/IMM/OTA/SCADA self-service APIs
- Common Data Workers
Including device basic information and sensor data from broker. (Common MQTT Topic) For structure info (device Info) store into PostgreSQL For non-structure (sensor Info) store into MongoDB/DocumentDB/...etc.
- Custom/SRP Data Workers
Process RMM/IMM/OTA/SCADA self-MQTT topic message and store into self-database (RMM/IMM/OTASCADA DB)
- Message Broker (RabbitMQ)
Adopt RabbitMQ as default cluster broker, and plugin MQTT as communication protocol.
- Device Agent
Define common MQTT topic handshake message and custom/SRP topic format.
- Database (SQL/NoSQL)
PostgreSQL as default relation database and including Common/RMM /SCADA/IMM/etc. MongoDB/DoucmentDB for sensor information collect.
COMMON DATABASE SCHEME
Common Database Scheme
Common Database Table Details
Table Device
Non-Structure Data (MongoDB/DocumentDB)
- Default Collections
{ "product": "RMM",
- Event
- WISE-PaaS platform event message
- Format
"type": "DEVICE",
"subtype": "DEVICE_DISCONNECTED",
"severity": "ERROR",
"message": "DEVICE_DISCONNECTED",
"extMsg": <JSONObject>,
"device_id": 2,
"device_name": "AC09",
"account_id": 2,
"account_name": "admin",
"ts": ISODate('2016-11-29T05:13:46.759Z') }
- Handler (Plugin)
- Handler (Plugin) report data (source data)
- Capability
- Handler capability structure
- Heartbeat
- WISE-PaaS device’s keepalive mechanism, ensure device connection state.
- Sensor Collections (Dynamic generate and transfer to key/value)
- SUSIControl
- HDDMonitor
- Modbus
- SenHub
- IoTGW
- …
API MANAGEMENT (RESTFUL APIS)
Common RESTful APIs
- Device APIs
- Get Methods
- /common/v1/devices - Get Devices
- /common/v1/devices/<id> - Get Device
- /common/v1/devices/<id>/plugins - Get Plugins/Device
- /common/v1/devices/<id>/sensors - Get Sensors/Device
- Post Methods
- /common/v1/devices - Add Devices
- Put Methods
- /common/v1/devices - Edit Devices
- Delete Methods
- /common/v1/devices/<id> - Delete Device
- Data APIs
- Get Methods
- /common/v1/data/<id>/latestdata?<Parameter> - Get Latest Data
- /common/v1/data/<id>/histdata?<Parameter> - Get Hist Data
- /common/v1/data/<id>/statisticdata?<Parameter> - Get Statistic Data
Customized RESTful APIs
- RMM
- Device Group APIs
- Get Methods
- /rmm/v1/devicegroups - Get DeviceGroups
- /rmm/v1/devicegroups/<id> - Get DeviceGroup
- /rmm/v1/devicegroups/<id>/devices?<Parameter> - Get Devices/DeviceGroup
- Post Methods
- /rmm/v1/devicegroups - Add DeviceGroups
- Put Methods
- /rmm/v1/devicegroups - Edit DeviceGroups
- Delete Methods
- /rmm/v1/devicegroups/<id> - Delete DeviceGroup
- Device APIs
- Get Methods
- /rmm/v1/devices - Get Devices
- /rmm/v1/devices/<id> - Get Device
- /rmm/v1/devices/unassigned - Get UnAssigned Devices
- /rmm/v1/devices/<id>/plugins_within_timerange - Get Plugins/Device within a time range
- /rmm/v1/devices/<id>/plugins - Get Plugins/Device
- /rmm/v1/devices/<id>/sensors - Get Sensors/Device
- Put Methods
- /rmm/v1/devices - Edit Devices
- Account APIs
- Get Methods
- /rmm/v1/accounts?<Parameter> - Get Accounts
- /rmm/v1/accounts/<primary-key> - Get Account
- /rmm/v1/accounts/login?<Parameter> - Login
- /rmm/v1/accounts/<primary-key>/groups - Get Groups/Account
- Post Methods
- /rmm/v1/accounts - Add Accounts
- /rmm/v1/accounts/logout - Logout
- Put Methods
- /rmm/v1/accounts - Edit Accounts
- Delete Methods
- /rmm/v1/accounts/<id> - Delete Account
- Role APIs
- Get Methods
- /rmm/v1/roles?<Parameter> - Get Roles
- /rmm/v1/roles/<id> - Get Role
- /rmm/v1/roles/<id>/Accounts?<Parameter> - Get Accounts/Role
- Post Methods
- /rmm/v1/roles - Add Roles
- Put Methods
- /rmm/v1/roles - Edit Roles
- Delete Methods
- /rmm/v1/roles/<id> - Delete Role
- Device Control APIs
- Get Methods
- /rmm/v1/devicetrl/<id>/latestdata?<Parameter> - Get Latest Data
- /rmm/v1/devicetrl/<id>/data?<Parameter> - Get Real-time Data
- Post Methods
- /rmm/v1/devicectrl/data - Set Data
- /rmm/v1/devicectrl/intermittent_report - Intermittent Report
- Power APIs
- Post Methods
- /rmm/v1/power/device - Power/Device
- /rmm/v1/power/group - Power/Group
- Process APIs
- Post Methods
- /rmm/v1/processes - Ctrl Process
- /rmm/v1/processes/devices/<id> - Get Process
- IMM
- /wise-paas/imm/apiInfo
- …
- SCADA
- /wise-paas/scada/apiInfo
- …
- OTA
- /wise-paas/ota/apiInfo
- …
DEVICE CONNECTIVITY
- Adopt open source RabbitMQ on server side to support both AMQP and MQTT protocol.
- Transportation supports MQTT, AMQP and HTTP (Websocket)
- Define the common communication APIs for our WISE Agent, we called WISE Connector APIs
- Implement the WISE Connector APIs with different communication protocol.
- WISE Agent can link different communication protocol at compile time.
- Supports secured connection (TLS/SSL) with anonymous and authenticated account
Message Topics
- MQTT Topic Define
- From Server to Agent:
/wisepaas/<tenantId>/<product>/<agentId>/<function>ack - From Agent to Server:
/wisepaas/<tenantId>/<product>/<agentId>/<function>req
- From Server to Agent:
- Preserved Topic for Common use, the product name "device" is preserved for common use.
- Agent Registration Topic: /wisepaas/<tenantId>/device/<agentId>/agentinfoack
- Will Message Topic: /wisepaas/<tenantId>/device/<agentId>/willmessage Or /wisepaas/<tenantId>/device/<serverId>/willmessage
- Command Topic: /wisepaas/<tenantId>/device/<agentId>/agentactionreq
- Response Topic: /wisepaas/<tenantId>/device/<agentId>/agentactionack
- Report Data Topic: /wisepaas/<tenantId>/device/<agentId>/devinfoack
- Custom Topic Sample
- For example, the product name is "custom" and function name is "powerctrl", the topic for Power ON/OFF control will be:
- Server send command with topic: /wisepaas/<tenantId>/custom/<agentId>/powerctrlreq
- Agent send response with topic: /wisepaas/<tenantId>/custom/<agentId>/powerctrlack
- For example, the product name is "custom" and function name is "powerctrl", the topic for Power ON/OFF control will be:
Handshake Sequence
- Normal sign in and sign out sequence:
- Agent lost connection with will message sequence:
- Server lost connection with will message sequence:
Data Format
- Agent ID Format
Agent ID Format is based on UUID format, which is represented as 32 characters, displayed in six groups separated by hyphens, in the form 8-4-4-4-12 for a total of 36 characters. In this format the UUID could map to Agent ID directly.
- Format define
For example:
The UUID is:
123e4567-e89b-12d3-a456-426655440000
Mapping to the Agent ID is:
123e4567-e89b-12d3-a456-426655440000
- Generate Agent ID
If the target device has it own unique ID, but less the 32 characters, then we could follow the steps to generate the Unique Agent ID:
For example:
- Retrieve Unique ID as key, for example: MAC address or IMEI.
- The first 8 digits is predefined to identify the Unique ID source.
- 00000001: MAC
- 00000002: IMEU
- 00000004: Hardware System config, ex: "/sys/fsl_otp/HW_OCOTP_CFG0"
- 00000005: Custom generates serial number. The serial number may not be unique, so we add the product or brand name before the serial number to make sure the ID is unique.
- Add 'Zero'(0) to extended to 24 lowercase hexadecimal digits as UUID format.
Unique ID with MAC address:
MAC:000babbb7ef3Agent ID:00000001-0000-0000-0000-000babbb7ef3
Custom Serial number:
Serial number for Advantech ARK 1120 :KSA0451097Agent ID:00000005-0000-0000-000a-rkksa0451097
- Basic JSON Format
- JSON (JavaScript Object Notation) is a lightweight data-interchange format.
- JSON is built on two structures:
- A collection of name/value pairs. In various languages, this is realized as an object, record, struct, dictionary, hash table, keyed list, or associative array.
- An ordered list of values. In most languages, this is realized as an array, vector, list, or sequence.
- JSON Forms:
- Object: { string : value}
- Array: [ value ]
- Value: string
number
object
array
true
false
null
- WISE-PaaS predefined string:
- agentID: target device ID, value type is string.
- handlerName: target device supported function block (Plugin or Handler) name, value type is string.
- commCmd: the sub command ID in function block (Plugin or Handler), value type is unsigned integer.
- content: the contain data.
- opTS: message generated time stamp (optional), the unit is millisecond.
- format: "opTS":{"$date":1494308768000}
- Device Registration Format:
{
"agentID":"00000001-0000-0000-0000-000babbb7ef3",
"handlerName":"general", //defined for device registration
"commCmd":1, //defined for device registration
"content": {
"parentID":"", //the parent device ID if the target device has parent device.
"hostname":"PC001104", //target device name
"sn":"14DAE996BE04", //target device serial number
"mac":"14DAE996BE04", //target device mac address
"version":"1.0.0.0", //client application version
"type":"IPC", //target device type
"tag":"RMM,Custom", //target device tag for supported software product name.
"product":"", //target device hardware product name
"manufacture":"", //target device hardware manufacture
"account":"anonymous", //bind target device to a specific account
"password":"", //encrypt with DES and Base64
"status":1 //1: registration, 0: un-registration
}
}
- Report Data Format:
{
"agentID":"00000001-0000-0000-0000-000babbb7ef3",
"handlerName":"custom",
"commCmd":123,
"content":{
"opTS":{"$date":1494308768000},
"custom_object":{ //User defined report data object.
"custom_data1":"string_value",
"custom_data2":123,
"custom_data3":false
}
}
}
- IPSO Format (Application Framework)
The IPSO Application Framework makes use of IETF standards as building blocks for a simple and efficient RESTful design model for IP smart objects. The framework may be used over either HTTP or CoAP web transfer protocols. HTTP, REST, XML, JSON, COAP and other key components of web technology are powerful mechanisms in an Internet of Things application.
Note: The objective of the Alliance is not to define technologies, but to document the use of IP-based technologies defined at the standard organizations such as IETF with focus on support by the Alliance of various use cases. Function Sets: The framework is organized into groups of resource types called Function Sets. A Function Set has a recommended root path, under which its sub-resources are organized. Each Function Set is assigned a Resource Type parameter, therefore making it possible to discover it.
Function Set
Root Path
Resource Type
General Purpose IO
/gpio
gpio
Power
/pwr
pwr
Load Control
/load
load
Sensors
/sen
sen
Light Control
/lt
lt
Message
/msg
msg
Location
/loc
loc
Configuration
/cfg
cfg
- IPSO Smart Object
IPSO Smart Object [2] Guidelines provide a common design pattern, an object model, which can effectively use the IETF CoAP protocol to provide high level interoperability between Smart Object devices and connected software applications on other devices and services
The common object model is based on the Lightweight M2M (LWM2M 1.0) specification from the Open Mobile Alliance. OMA LWM2M is a device management and service architecture specification based on IETF CoAP, and provides a simple and flexible object template (object model) for constrained device management.
The object model from OMA LWM2M is reused to define application level IPSO Smart Objects. This enables the OMA Name Authority (OMNA) to be used to register new objects, and enables existing LWM2M compliant device libraries and server software to be used as an infrastructure for IPSO Smart Objects
- Media Types for Sensor Markup Language (SENML)
- Semantics
SenML
JSON
Type
Description
Base Name
bn
String
This is a string that is prepended to the names found in the entries
Base Time
bt
Integer
A base time that is added to the time found in an entry
Base Units
bu
String
A base unit that is assumed for all entries, unless otherwise indicated
Version
ver
Number
Version number of media type format
Measurement or Parameters
e
Array
Array of values for sensor measurements or other generic parameters
Name
n
String
Name of the sensor or parameter
Units
u
String
Units for a measurement value
Value
v
Float
Value of the entry
String Value
sv
String
Boolean Value
bv
Boolean
Value Sum
s
Float
Integrated sum of the values over time
Time
t
Integer
Time when value was recorded
Update Time
ut
Integer
Update time. A time in seconds that represents the maximum time before this sensor will provide an updated reading for a measurement.
- The Data Type of Sensor Data Type
Data Type (type)
SenML Field
b (boolean)
bv
s (string)
s
e (enum)
e
i (integer)
v
d (decimal)
v
h(hexadecimal)
s
o(octet-stream)
s
- Advantech Sensor Semantics
SenML
JSON
Type
Description
Min Range Value
min
Float
The minimum value that can be measured by the sensor
Max Range Value
max
Float
The maximum value that can be measured by the sensor
Access Mode
asm
String
The access mode of the resource. Ex: read (r), write (w), read/write (rw)
Standard Format
st
String
The sensor format is which standard format
Health Status
Health
Integer
The health status of network or device. Range: -1 ~ 100
Good: > 80, Average: 60 ~ 80, Below Average: 40~60, Bad:0~40, -1: Off line or Fault
- IPSO Report Data Format:
{
"agentID":"00000001-0000-0000-0000-000babbb7ef3",
"handlerName":"custom",
"commCmd":123,
"content":{
"opTS":{"$date":1494308768000},
"custom_object":{ //User defined report data object in IPSO format.
"bn":"custom_object",
"e":[
{"n":"custom_data1","sv":"string_value"},
{"n":"custom_data2","v":123},
{"n":"custom_data3","bv":false}
]
}
}
}
DEVOPS MANAGEMENT
Continuous Integration & Continuous Delivery
Version Control
GitHub offers all of the distributed version control and source code management (SCM) functionality of Git. It provides access control and several collaboration features such as bug tracking, feature requests, task management, and wikis for every project. GitHub Flow is a lightweight, branch-based workflow that supports teams and projects where deployments are made regularly.
Build and Test
Add Jenkins script to check out and compile the source code. Then execute on a Docker container to verify the application. The Jenkins will send the report mail to notify pass or not.
Jenkins helps to automate the non-human part of the whole software development process, with now common things like continuous integration, but by further empowering teams to implement the technical part of a Continuous Delivery.
Docker is an open-source project that automates the deployment of applications inside software containers.
Release & Deploy
Add Jenkins script to release and deploy to target VM or upload the install packet to release folder.
CUSTOM SERVICE INTEGRATION
Access Methods
In the common services, there are 3 mechanisms for access these information, ZMQ is the most convenient to communication information between different services. Second, the Java library have a lot’s of interface to access common resources, also you would via Restful APIs to integrate.
Internal Messaging(ZMQ)
In the ZMQ mechanism, we adopt the most robust with load balancing model which called “Paranoid Pirate Pattern”. Based on the ZMQ to handshake message, provide high performance, stability, and cross-languages (Java/C#/C++/C/GO/Python/PHP/…etc.)
The message is adopt JSON format and similar to Restful API, reuse the translator. Format define guide as below.
Example: Get Device Information
- Request
"request":{
"ProductId":"<xxxx-xxx-yyyy-yyy>",
"resource":"/wise-paas/common/device/<id>",
"method":"GET"
}
}- Reply
"reply":{
"did":1,
"name":"ARK-1155",
"agentId":"0000BAB374520",
"isConnected":true,
"coordinates":"25.069439,121.582485",
"loginTS":"2017-1-10 12:30",
"createTS":"2017-1-5 11:00"
}
}Example: Add Account Information
{
- Request
"request":{
"ProductId":"<xxxx-xxx-yyyy-yyy>",
"resource":"/wise-paas/common/account",
"method":"POST",
"content":{
}
}
}- Reply
"reply":{
"result":true,
"aid":2
}
}
Java Library
[TBD]
Common RESTful APIs
- Device APIs
- Get Methods
- /common/v1/devices - Get Devices
- /common/v1/devices/<id> - Get Device
- /common/v1/devices/<id>/plugins - Get Plugins/Device
- /common/v1/devices/<id>/sensors - Get Sensors/Device
- Post Methods
- /common/v1/devices - Add Devices
- Put Methods
- /common/v1/devices - Edit Devices
- Delete Methods
- /common/v1/devices/<id> - Delete Device
- Data APIs
- Get Methods
- /common/v1/data/<id>/latestdata?<Parameter> - Get Latest Data
- /common/v1/data/<id>/histdata?<Parameter> - Get Hist Data
- /common/v1/data/<id>/statisticdata?<Parameter> - Get Statistic Data
RMM/OTA/SCADA/IMM Integration
Through ZMQ/library/Common Restful API get account/group/device information.
Join/Merge custom DB information for advanced usage.
- Scenario 1) RMM show more information about account
Due to common account’s fields not enough for more information on RMM, the RMM would have “AccountExt” table to extend and manage.
Step 1) Get common account information via ZMQ then use primary-key to link these tables.
Step 2) Merge the result common/custom account information, then return.
- Scenario 2) OTA deploy a package for region devices
The OTA may deploy an update package to devices locate on America, and record the upgrade status. Step 1) Adopt common device information, use advSearch to get these devices on America. Step 2) For these agentId/deviceId to send the request and record the status on OTA database.