Open topic with navigation

The C Broker

The C Broker is a small-footprint DSA broker that is intended for embedding in devices where economy of scale is important. This document tells you how to build, configure and launch the C Broker. This document assumes you are familiar with DSA and Atrius Solution Builder.

The C Broker receives data from devices by way of DSLinks. To use Solution Builder to manage DSLinks that connect to an instance of the C Broker, install and run the LifeCycle Manager as described below.

Differences between the DSA Server and the C Broker are as follows:

Feature Solution Builder + DART Broker C Broker
Built-in web server Yes No
Hosts Solution Builder Yes No
Manages users and filesystem access Yes No

Note: Because and the C Broker support a subset of the features of the DGLux Server, the JSON configuration files for the C Broker are not interchangeable with those of the DGLux Server.

Building the C Broker

To download the source code from GitHub, you must have git installed. To build the C Broker, you must have cmake 3.0.0 installed These instructions assume you are building on Ubuntu 14.04.

To download the C Broker source code from github, issue the following command: 

git clone https://github.com/IOT-DSA/sdk-dslink-c

To build the C Broker, issue the following commands in the directory where you cloned the source code: 

mkdir build
sh tools/build.sh

Configuring the C Broker

To configure settings for the C Broker, edit the broker.json file, which is created when you build the C Broker. This file must reside in same directory as the executable. The default broker.json file contains the following settings: 

{
  "http": {
    "enabled": true,
    "host": "0.0.0.0",
    "port": 8080
  },
  "log_level": "info",
  "allowAllLinks": true,
  "maxQueue": 1024,
  "defaultPermission": null,
  "storage": {
    "path": "."
  }
}

The following table lists valid C Broker settings.

HTTP settings
enabled To configure the broker to accept HTTP connections, set to true. Default: true
host Specify the host name of IP address where the broker runs. Default is 0.0.0.0, which means that if the host has multiple IP addresses, the C Broker accepts connections on all of them.
port Specify the port on which the broker accepts HTTP connections. Default is 8100.
HTTPS Settings
enabled To configure the broker to accept HTTPS connections, set to true. Default: true
host Specify the host name of IP address where the broker runs. Default is 0.0.0.0, which means that if the host has multiple IP addresses, the C Broker accepts connections on all of them.
port Specify the port on which the broker accepts HTTPS connections. Default is 8463.
certName Certificate file name (.pem file). Put certificate files in a subdirectory named "certs," under the directory where the C Broker is running.
certKeyName Key file name (.pem file). Put key files in a subdirectory named "certs," under the directory where the C Broker is running.
Other settings
log_level Specifies the logging verbosity. Valid values are fatal, error, warn, info and debug. Default is info.
allowAllLinks Specifies whether the C Broker accepts connections from all DSLinks or only previously-registered ones.
maxQueue The maximum number of messages from DSLinks that remain queued when the requestor has specified the qos 1 or qos 3 options. The qos (quality of service) settings control how the broker caches incoming data to handle disparities between the responsiveness of requestors and that of responders.)
defaultPermission Specifies the permissions to be assigned to DSLinks that do not have any permissions configured for their associated user. Valid permissions, from least to most restrictive, are config, write, read, list, and none. [More information]
path The directory that the C Broker uses for working storage for qos queue data, incoming data values, and other data that it must store locally.

Specify the defaultPermission setting using JSON notation; for example: 

  "defaultPermission": [
      [":config","config"],
      [":write","write"],
      [":read","read"],
      [":user","write"],
      ["default","read"]
   ]

If you are using tokens to authenticate connections from DSLinks, token files must reside in the "tokens" subdirectory under the directory where the C Broker is running. The name of the token file must be the first 16 characters of the full token string. Specify tokens in JSON format, as follows, one token per file, as follows: 

{"$$timeRange": null, "$$token": "47S7ybkxV6ka7Ha6zIHsFl16wiYwu4i8EGYlqdzK7NQw5Rus", "$$managed": false, "$$group": ":write"}
  • $$timeRange: A date and time range that specifies the start and end of the period when this token is valid. Example: 2017-03-10T00:00:00/2017-03-11T12:00:00
  • $$token: 48-character token
  • $$managed: To disconnect and remove all associated DSLinks when the token expires, set to true.
  • $$group: The permission group to be assigned to the DSLink that connects using this token.

Deploying the C Broker

To run the C Broker on a machine other than the machine where you built it, copy the broker executable and the broker.json file to the desired location.

To start the broker, invoke its executable on the command line. For example: 

./broker &

To verify that the broker is accepting connections, issue the following command (assuming you have configured the broker to listen on port 8080): 

telnet localhost 8080

Connecting to the C Broker

To use Solution Builder to get access to the data that the C Broker receives from its DSLinks, configure a connection as follows:

  1. In the Data panel, expand the sys node and right-click upstream.
  2. Choose Add Upstream Connection and specify settings,
  3. Click Invoke.

Settings:

  • Name: The name to be displayed in Solution Builder
  • Url: The URL required to connect to the DSA Server. For example: http://101.0.1.197:8080/conn
  • Broker Name: The name to be displayed by the upstream broker.
  • Token: If required, the name of the token file containing the token needed to authenticate.
  • Group: The group defining the permissions to be assigned to the connection.

When the C Broker accepts the connection, it displays a success message. To view the C Broker in Solution Builder, expand the sys > upstream node and verify that your broker instance is listed.

You can configure the C Broker connection to the DSA Server by manually editing configuration files that reside on the machine where the C Broker runs, as follows:

  1. In the directory where the C Broker runs, create a subdirectory named "upstream."
  2. In the "upstream" directory, create one JSON file for each upstream connection that you want to define, using whatever file naming convention is meaningful to you. In these files, specify the connection settings in JSON, formatted as follows: 
{"name": "rnd", "brokerName": "mybroker", "url": "http://rnd.iot-dsa.org", "token": "<token string>", "enabled": true, "group": ":config"}

Settings:

  • name: Name of the upstream broker, must be same as the file name in the upstream folder
  • brokerName: Name of the current broker to be displayed under the upstream broker
  • url: The URL required to connect to the C Broker. For example: http://101.0.1.197:8080/conn
  • token: (Optional) Token to be used when the C Broker connects.
  • group: The permission group for the C Broker.

The LifeCycle Manager

The C Broker lacks the DSLink-management features of the DGLux Server. The LifeCycle Manager enables you to use DGLux5 to manage the DSLinks that connect to the C Broker.

To build the LifeCycle Manager, your system must have the following software installed. The versions listed below are known to work. The build process and the software itself has not been tested with other versions of these packages.

  • g++-5 14.04
  • cmake 3.0.0
  • libssh2 1.4.3
  • zlib 1.2.8
  • boost 1.54
  • libcurl 7.35
  • http-parser 2.1

Building the LifeCycle Manager

Note: The github repository for the Lifecycle Manager is private. If you attempt to clone the source and are denied permission, contact DGLogik to request access to the repository.

To download the LifeCycle source code from github, issue the following command:

git clone https://github.com/dglogik/dslink-manager

To build the LifeCycle manager, issue the following commands in the directory where you cloned the source code:

	mkdir build
	cd build
	git submodule init
	git submodule update
	cmake -DCMAKE_CXX_COMPILER=g++-5 -DCMAKE_BUILD_TYPE=Release  ..
	make

To verify that the build succeeded, check that the build directory now contains an executable file named "dsmanager."

Deploying the LifeCycle Manager

To run the LifeCycle Manager on a machine other than the machine on which it was built, copy the following files from the build machine to the desired production directory:

  • dsmanager (executable)
  • libsdk_dslink_c.so
  • dslink.json (To configure the display name for LifeCycle Manager, edit this file.)

Before starting the LifeCycle Manager, verify that the C Broker is running. To start the LifeCycle manager, invoke its executable on the command line. For example, to run the LifeCycle Manager (assuming the broker is configured to listen on port 8080) in background mode, issue the following command:

./dsmanager --broker http://localhost:8080/conn

If the LifeCycle Manager started successfully, it displays "Successfully connected to the broker." To verify that the LifeCycle Manager is accessible using Atrius Solution Builder, expand the Data pane upstream node. Locate the C Broker, expand its downstream node, and verify that the LifeCycle Manager is listed and is not grayed out. To manage the DSLinks that are connected to the C Broker, right-click the LifeCycle Manager node.