IoT Platform Integration
YuDash LYNX IoT platform Integration Guide is now moved
The IoT platform Integration Guide is now moved within YuDash Documentation portal.
YuDash LYNX IoT platform Integration
YuDash IoT gateways (LYNX and ZENYX) can be easily integrated with any IoT platform on cloud. It can be integrated with on-premise server. This is enabled by flexible, no-code features:
Support of MQTT and HTTP/S protocol (REST APIs) for connection to IoT platform
Choice of connectivity through 4G/LTE, WiFi and Ethernet.
Flexible Payload formats in JSON and TXT formats for smooth plug and play with servers.
Support of Time Stamp in payload with RTC enabled versions
Support of backfill in server through flexible Time formats to suite all platforms.
Besides process information, support of device status to monitor health of device.
LYNX also support FTP protocol for enterprise customers with legacy servers. Please contact us if you wish to add FTP support for your server.
Following are main steps to connect to external IoT platform:
1) Selection of Cloud Protocol
2) IoT platform server details and credentials under Custom Cloud Server Settings in LYNX.
3) Payload Configuration:
1) Selection of Cloud Server in LYNX
By default, YuDash LYNX is configured to connect to YuDash cloud. This is subject to purchase of YuDash cloud or YuReCon subscription. In such cases, "Use YuDash Cloud " is check marked. In this case, all custom cloud settings are ignored. LYNX will attempt to connect pre-configured device credentials on YuDash Cloud. For using external cloud (or on-premise) server, the applicable cloud protocol has been selected.
1) Selection of Cloud Protocol
Uncheck "User YuDash Cloud". This will disable use of YuDash cloud.
Select the Cloud protocol: MQTT or HTTP
The Offline mode is used when no cloud server is applicable. This is applicable for (a) LYNX or Yureca is used as on-premise remote display units and (b) debugging and setup purpose with field instruments for modbus.
2) MQTT Broker Configuration in LYNX
MQTT is a popular, lightweight cloud protocol used in IoT. Following are settings in LYNX to configure connection to MQTT server:
MQTT Server (Broker) : The URL of MQTT broker accessible on network. Alternately, unique IP address can be provided. This may be required for a local deployment.
MQTT Port: The IP port running MQTT server.
MQTT User name: Client User name for MQTT broker. Based on server, it may be blank or Access Tokens are used as user name.
MQTT Password : Client password for MQTT broker. Based on server, it may be blank or Access Tokens are given in password.
MQTT Client Name: Client name for MQTT broker. It may be simply blank is most cases, unless specified by server.
MQTT Publish Topic: The MQTT topic to publish data to. In many cases, it will contain and API name and may include unique serial number of device or variable.
MQTT Platform Name: Generic platform name. It is for information or display purpose only. It is not used in communication.
Actual usage details are covered in integration guide with popular IoT platforms in subsequent section.
3) HTTP Server Configuration in LYNX
HTTP is a defacto TCP/IP protocol for cloud communication. YuDash LYNX supports POST REST API for sending data to HTTP Server. Both HTTP and HTTPS versions are supported. The HTTP headers can be configured to support various authentication types.
Following are settings in LYNX to configure connection to MQTT server:
HTTP Server : The URL of HTTP server accessible on the network. Alternately, unique IP address can be provided. This may be required for a local deployment.
Remove any prefixes (http:// or https://) in the server name.
Remove any suffix APIs from server name. They are provided in API below.
HTTP API : The API name (similar to subdirectory) which will accept POST request. This will typically start with "/".
HTTP Port: The port on which HTTP server is running.
HTTP SSL Enabled: Check this box for enabling HTTPS using SSL. This is recommended for production applications.
HTTP Headers for Authentication: HTTP supports various authentication options. The authentication header keys and values are filled in section.
These are sent as HTTP headers to server for handshake.
The UI supports two headers. In case multiple custom headers are required, it can be configured in JSON configuration.
Actual usage details are covered in integration guide with popular IoT platforms in subsequent section.
4) Payload Configuration in LYNX
HTTP/MQTT configuration defines the credentials and API to connect to server. Next step is to define the format in which process data will be sent to cloud.
JSON is a popular format for data exchange on cloud. LYNX supports JSON and TEXT formats to send data to cloud servers. LYNX has pre-configured JSON templates to suite popular IoT platforms. In some cases, TEXT payload over MQTT is also popular. For this, we have inbuilt YuDash Text Generator.
4.1) Payload Components
In principal, following are main information components that are packaged in payload:
4.1.1) Process Data
Process data is key-value pair information collected from the instruments by LYNX. Let's understand this with an example: LYNX reads a field instrument and receive a numeric value. For example: Voltage read as volt1 with value 224.45. Or a furnace temperature: variable temp_furnace1 with value 598.0. So, we have volt1=224.45 and and temp_furnace1=598.0.
So, the key is the variable name defined in MODBUS (or similar) setting and the value is floating point number read from instrument. These key-value pairs have to pushed to cloud, encapsulated in selected JSON format.
In many cases, there may be 80-90 such key value pairs read in a given cycle. Depending on server or protocol architecture, we have to be send 8, 16 or even just 1 key-value pair in a single communication. All these variations are handled by LYNX through dpPerPacket. This will be explained later.
In princical, this is the main
4.1.2) Device Headers/Identifiers
For generic IoT platforms, typically one field gateway is uniquely identified by a credential (Access Token). But in many servers (typically HTTP), there may be a single API and credential handling data for multiple devices. In this case, the device information is passed in the payload to uniquely identify the field asset/machine/instrument.
Let's understand this by an example: There is a MES server (on premise or on-cloud) for a manufacturing firm. Manual entries are being done by operators and executived. Now, some of machines are IoT enabled to push machine process data periodically. In such cases, typically a user name is created, which will be shared across all machine. And each machine name (unique identified as per MES) will be added in payload. For example: machine_number has a value YDPL/FRN/402 for a given machine. So, this key value pair will be sent along (1). And server API will process accordingly.
In other words, it is kind of meta-data, which is part device (remains fixed for a device) and sent along with real-time process information.
LYNX supports two device headers (key and value pairs). They will be added in payload similar to process data.
The checkbox "Send Device Headers" has to be checked to enable sending of headers. If it is not checked, device headers are not sent to server.
4.1.3) Time Stamp Information
In most of servers, the time of receipt of a data packet received at server is taken as its time-stamp.
LYNX process and send the data packets immediately to cloud. So, delay in packet transmission and multiple register reads may add very small time delay between actual capture of data and time stamp recorded on server. In most of cases, this is very much non-critical and ignored.
In most cases, the cloud servers store time-stamp in UTC (universal time) and they are displayed in local time on web browsers. So, there is no concern or error about time zones.
Most of cloud servers accepts options of accepting time-stamp along with process data. This may be the case when we want to populate a data point from history.
For RTC enabled LYNX variants, LYNX supports sending of Time Stamps in a flexible matter.
4.1.4) Payload JSON Keys
All information in JSON is sent has key-value pairs. In many cases, the key names are defined in JSON format by platforms for categorization.
For this purpose, LYNX has two user provided input strings (Payload Gen Key#1 and Payload Gen Key#2). These will be used by JSON payload generator engine depending on format.
4.2) JSON Payload formats in LYNX
LYNX supports following JSON payload formats of payload. Each format has unique number (starting with 10).
We explain each JSON format with an example of energy monitoring:
There are three process variables/tags. Voltage, frequency and energy, namely: volt1_in freq_in and kwhr_in
Numerical values (Floating point) are read by LYNX for reach variable.
There is a string variable status_var1 used to capture device status information. This is an optional variable in which LYNX sends in device information at bootup and periodically.
The variable names for device information are treated just like process variables.
The timestamp variables are process as per given JSON format. It is purely optional parameter and should only be when back-fill feature is required.
LYNX has two user provided input strings (Payload Gen Key#1 and Payload Gen Key#2). We will call them plKey1 and plKey2.
1) JSON_Format_10
This simplest JSON format with key value pairs.
plKey1 and plKey2 are not used.
Data Payload
{
"volt1_in": 237.67,
"freq_in": 49.98,
"kwhr_in": 1792.17
}
Status Variable Payload:
{
"status_var1":"LYNX rebooted. count=7700. reason=0"
}
2) JSON_FORMAT_11
This two level JSON format with variable names as main key.
plKey1 is not used. plKey2 is used. This is set as "value" in below example.
Data Payload
{
"volt1_in": {
"value": 244.4
},
"freq_in": {
"value": 50
},
"kwhr_in": {
"value": 1792.17
}
}
3) JSON_FORMAT_12
This JSON array with data points for each variables.
plKey1 is used (set to field in example). plKey2 is used and set as value in below example.
Data Payload
[
{
"field": "volt1_in",
"value": 242.34
},
{
"field": "freq_in",
"value": 49.92
},
{
"field": "kwhr_in",
"value": 1792.17
}
]
Status Variable Payload:
[
{
"field": "status_var1",
"value": "status: RSS: -60 db, wifi_name: ***, wifi_ip:***"
}
]
4) JSON_FORMAT_13
This two level JSON structure.
plKey1 is used (set to data in example). plKey2 is not used.
Data Payload
{
"data": {
"volt1_in": 241.65,
"freq_in": 49.99,
"kwhr_in": 1792.17
}
}
Status Variable Payload:
{
"data": {
"status_var1": "status: RSS: -62 db, wifi_name: ***, wifi_ip:###"
}
}
4.3) TimeStamp formats in LYNX
LYNX supports following timestamp formats to send to cloud server when timestamp has been enabled.
The time displayed on YuDash LYNX is local time (based on time-zone provided). In most cases, it is advised to store/send UTC time stamps.
Following are UTC time stamps options:
Time Stamp Format Sample Time-Stamp Value
TS_50 (UTC Seconds) 1675630526
TS_51 (UTC MilliSeconds) 1675630526000
TS_52 (UTC YYYY-MM-DDTHH:MM:SS) 2023-02-05T20:55:26Z
TS_53 (UTC YYYY-MM-DD HH:MM:SS) 2023-02-05 20:55:26
Local time stamps, similar to above are supported as below:
TS_60 (LocalTime Seconds)
TS_61 (LocalTime MilliSeconds)
TS_62 (LocalTime YYYY-MM-DDTHH:MM:SS)
TS_63 (LocalTime YYYY-MM-DD HH:MM:SS)
The time stamp are sent along with Time Stamp Key (tsKey). They are grouped in within json format depending on JSON_FORMAT_. The timestamp key is set as timestamp in all examples. Typically, based on server requirement timestamp, ts or time keywords are used.
1) JSON_FORMAT_10, TS_50
{
"volt1_in": 247.55,
"freq_in": 49.94,
"kwhr_in": 1792.17,
"timestamp": "1675630887"
}
2) JSON_FORMAT_11, TS_51
{
"volt1_in": {
"value": 244.15,
"timestamp": "1675611242000"
},
"freq_in": {
"value": 49.84,
"timestamp": "1675611242000"
},
"kwhr_in": {
"value": 1792.17,
"timestamp": "1675611242000"
}
}
3) JSON_FORMAT_12, TS_52
[
{
"data": "volt1_in",
"value": 249.97,
"timestamp": "2023-02-05T15:36:42Z"
},
{
"data": "freq_in",
"value": 49.89,
"timestamp": "2023-02-05T15:36:42Z"
},
{
"data": "kwhr_in",
"value": 1792.17,
"timestamp": "2023-02-05T15:36:42Z"
}
]
4) JSON_FORMAT_10, TS_53
{
"volt1_in": 251.51,
"freq_in": 50.01,
"kwhr_in": 1792.17,
"timestamp": "2023-02-05 15:41:42"
}
4.4) TEXT formats supported in LYNX
LYNX is powered with YuDash Text Generator engine. We can generate any kind of text string containing variables, measurements.
User need to select TEXT_FORMAT_20 to enable this feature.