Definition

Neuron supports 3 kinds of Internet protocols, HTTP API, MQTT and Websockets. They are widely used in Internet and web applications. MQTT protocol will be more specific for communicating with cloud application or IIoT platform. Meanwhile, the Websockets and HTTP API protocols are used for HMI program or web browsers. These protocols share same JSON data structure and have same handshake communication processes. These data structure and handshake communication processes are what we would talk in details in below.

UUID

All Neuron instances have its own identity UUID (Universal Unique Identity) for IIoT platform. There are two ways to give UUID to a Neuron. First, the UUID can be automatically generated by Neuron when starting at the first time. Second, This UUID can be assigned in command line to start Neuron. Neuron will present this UUID to IIoT platform as a unique ID for the communication token. The UUID MUST be 36 characters or less.

For example, UUID: 03c844fc-e381-11e6-b133-000c29158b55

Note: %UUID% represents the UUID string of a Neuron.

MQTT Protocol

Neuron is 100% MQTT compatible. A MQTT broker must be employed in the communication. Generally, any standard MQTT broker can be used for communication. However, the following brokers have been well tested for Neuron and therefore recommended for using in project.

  1. EMQ www.emqx.io

  2. Mosquitto www.mosquitto.org

For the port number setup, if you use port number 8880-9 to connect to broker, Neuron will treat the connection as SSL secured MQTT protocol connection. If using port number 1880-9, the gateway will connect to broker through MQTT protocol without SSL protection.

The last connection details would be username, password and ClientID. Username and password would be defined by broker. But Client ID would be filled with UUID automatically by Neuron.

MQTT topic string list

Neuron/Broadcast

Neuron/Heartbeat/%UUID%

Neuron/Telemetry/%UUID%

Neuron/Request/%UUID%

Neuron/Response/%UUID%

where %UUID% is a 36 characters UUID string of Neuron.

Neuron gateways subscribe topics

Neuron/Broadcast

Neuron/Request/%UUID%

Neuron gateway publish topics

Neuron/Broadcast

Neuron/Heartbeat/%UUID%

Neuron/Telemetry/%UUID%

Neuron/Request/%UUID%

Neuron/Response/%UUID%

IIoT Platform subscribe topics

Neuron/Broadcast

Neuron/Heartbeat/%UUID%

Neuron/Telemetry/%UUID%

Neuron/Response/%UUID%

IIoT Platform publish topics

Neuron/Request/%UUID%

During registration process, Neuron will publish repeatedly its UUID to Neuron/Broadcast topic until it gets back the response from IIoT platform thought the %UUID%/Request topic. If registration success, it will publish the Heartbeat information on Neuron/Heartbeat/%UUID% topic as well as data will be sent though the Neuron/Telemetry/%UUID% topic to IIoT platform. Meanwhile, it will subscribe the %UUID%/Request topic to listen command from the IIoT platform. If request comes, the Neuron would perform the request and send back the answer thought the %UUID%/Response topic. The topic Neuron/Broadcast are used for Neuron group internal communication.

Websockets Protocol

Websockets Protocol is usually used for Neuron user interfaces. Of course, you may have other communication purpose. The Neuron program doesn’t deny any possibility from implementation. The only thing you must comply is using below JSON structure for communication. However, Neuron indeed has provided a web service for users to access the data and configuration thought the web browser. Type the IP address and Port 7000 in the web browser on the same network. The port no. MUST be 7000 and have no way to be modified.

Websockets connection command in javascript

websocket = new WebSocket(wsUri, “datathread”);

where wsUri are the IP address of Neuron.

Here is an HTML example for Websockets connection

  1. <!DOCTYPE html>
  3. <meta charset="utf-8">
  5. <title>WebSocket Test</title>
  7. <script language="javascript" type="text/javascript">
  9. var wsUri = "ws://192.168.1.106:7000/";
  11. var output;
  13. var temp = 0;
  15. function init()
  17. {
  19. output = document.getElementById("output");
  21. testWebSocket();
  23. }
  25. function testWebSocket()
  27. {
  29. websocket = new WebSocket(wsUri, "datathread");
  31. websocket.onopen = function(evt) { onOpen(evt) };
  33. websocket.onclose = function(evt) { onClose(evt) };
  35. websocket.onmessage = function(evt) { onMessage(evt) };
  37. websocket.onerror = function(evt) { onError(evt) };
  39. }
  41. function onOpen(evt)
  43. {
  45. writeToScreen("CONNECTED");
  47. var j={func: 10, wtrm: 'neuron-test-xxx-yyy', name:'root',
  48. pass:'0000'};
  50. var txt = JSON.stringify(j);
  52. doSend(txt);
  54. }
  56. function onClose(evt)
  58. {
  60. writeToScreen("DISCONNECTED");
  62. }
  64. function onMessage(evt)
  66. {
  68. writeToScreen('<span style="color: blue;">RESPONSE: ' + evt.data
  69. +'</span>');
  71. if (temp < 5) {
  73. switch (temp) {
  75. case 1: // read user list
  77. var j1 = {func:13, "wtrm":"DEMO-Neuron-1001"};
  79. break;
  81. case 2: // read user info
  83. var j1 = {func:14, "wtrm":"DEMO-Neuron-1001", name:'joey'};
  85. break;
  87. case 3: // read user list
  89. var j1 = {func:13, "wtrm":"DEMO-Neuron-1001"};
  91. break;
  93. case 4: // read configuration
  95. var j1 = {func:22, "wtrm":"DEMO-Neuron-1001"};
  97. break;
  99. }
  101. var txt1 = JSON.stringify(j1);
  103. doSend(txt1);
  105. }
  107. temp++;
  109. }
  111. function onError(evt)
  113. {
  115. writeToScreen('<span style="color: red;">ERROR:</span> ' +
  116. evt.data);
  118. }
  120. function doSend(message)
  122. {
  124. writeToScreen("SENT: " + message);
  126. websocket.send(message);
  128. }
  130. function writeToScreen(message)
  132. {
  134. var pre = document.createElement("p");
  136. pre.style.wordWrap = "break-word";
  138. pre.innerHTML = message;
  140. output.appendChild(pre);
  142. }
  144. window.addEventListener("load", init, false);
  147. </script>
  149. <h2>WebSocket Test</h2>
  151. <div id="output"></div>