uBridge Server

uBridge server

uBridge runs as a daemon (systemd service), which constanly monitors the machine's USB ports for new enumerated devices.

If the detected device is a uThing™, the server notifies the connected plugins, optionally configures the new device, and listen for incoming data from the uThing™'s.

Each new sensor message is then streamed to the subscribed plugins.

The messsaging model is build on top of the socket library NNG (Nanomessage New Generation). NNG is an evolution of Nanomessage and ZeroMQ.

The uBridge can be configured to use two different transports:

• IPC: Uses Linux Message Queues for efficient communication when the uBridge and plugin applications run on the same machine.
• TCP: Uses TCP sockets, in case that the client (plugin) applications run on different machines.

All messages between Server and Clients are encapsulated into JSON objects.

The uBridge server communicates with the clients (plugins) via two sockets:

Config socket

The Config socket uses the Request / Response model. The clients send Requests to uBridge (i.e. setConfig, getConfig, getDevices, queryDevice, sendCommand, getStatistics) and get the corresponding responses with status or information.

Here is an example of a response message to a getDevices request:

{
    "channelID": "uThing::MNL_D657",
    "fwVersion": "1.0.3",
    "name": "uThing::MNL rev.A",
    "serialNumber": "28AE9B9745B5D657"
},
{
    "channelID": "uThing::VOC_F8B6",
    "fwVersion": "1.3.2",
    "name": "uThing::VOC rev.2",
    "serialNumber": "7F8D2D3FEF89F8B6"
}

And an example response to a getStatistics request:

{
  "bridgeUpTime": 1764846,
  "devices": {
    "uThing::MNL_D657": {
      "msgReceived": 1771,
      "msgSent": 4,
      "upTime": 262823477
    },
    "uThing::VOC_F8B6": {
      "msgReceived": 592,
      "msgSent": 4,
      "upTime": 443589765
    }
  },
  "numConnectedDevices": 2,
  "receivedMsgPerSec": 1.34,
  "sentMsgPerSec": 0.01
}

Stream socket

The Stream socket is used for the uBridge to stream sensor data to the plugins. The plugins can subscribe to specific "topics" (for example a single sensor), or to all the incoming sensor data:

    uBridgeClient.subscribe("/sensors", subsMessageHandler); //subscribe to all sensors
    uBridgeClient.subscribe("/sensors/uThing::VOC_9142", subsMessageHandler); //specific unit

The assigned names ("channelID") can be obtained with from the config socket with a getDevices request.

The sensors are identified by their type and the 4 last characters of their serial number in order to differentiate multiple sensors of the same type connected.

Source code & Installation

Using with the InfluxDB plugin in a RaspberryPi

At the moment of writing, InfluxDB 2.0 hasn't been released for the armhf port yet, so check the InfluxDB plugin documentation for instructions of installing the arm64 Raspbian version before starting. NOTE: This is only required if InfluxDB will be installed locally.

The source code and installation instructions are located here.

Configuration

All the configuration files are installed under /etc/ubridge

Here is the default configuration file for the uBridge component:

Note that the format is JSON-like, with added comments enclosed in "/* */" blocks

{
    "devNameBase":"",/* If this field is left empty, the bridge will try to find devices
                    in '/dev/ttyACM*' and '/dev/ttyUSB*' - For MacOS, use '/dev/cu'*/
    "configSockUrl":"ipc:///tmp/ubridgeReqResp",/* The sockets for the Request Response Server and data Streamer*/
    "streamSockUrl":"ipc:///tmp/ubridgeStream",/* If the client app runs in the same machine, IPC is 
                    more efficient. If a different host is used (as with a client running in a Docker instance)
                    use TCP host:port ("tcp://localhost:8001")*/
    "maxDevices":10/* Maximum number of devices supported */
}

• "devNameBase": each Linux distribution assigns different base names for the Virtual Serial Ports.

  For example, Debian assigns /dev/ACM0 to the first VCP device enumerated. By default (leave this field empty), uBridge will look into /dev/ttyACM* and /dev/ttyUSB* devices.

• "configSockUrl": Socket name for the configuration Request/Respond messages.

  Using ipc:///tmp/*, NNG will use Linux Message Queues when the client/s are running on the same machine, this is more efficient than TCP sockets.

  For TCP transport, use tcp://server:port (i.e. tcp://localhost:8001). This can be handy if the plugins are running inside a Docker container, or in a remote server.

• "streamSockUrl": Socket name for the message streaming (Publish / Subscribe model).

• "maxDevices": This will limit the maximum number of devices supported if needed (extra enumerated uThing's will be ignored).

NOTE: Remember to restart the server after changing the configuration file (sudo systemctl restart ubridge-server.service).

Monitoring

Check running status of the service

 systemctl status ubridge-server.service

Log file

The log files for the uBridge and plugins are located in the /tmp directory:

tail /tmp/ubridge.log