Page History

Tip
Learn more about Receiver module functions.

Running module

Receiver can be started using the provided starting script, automatically when installed using the installer or manually, by executing following command:

Code Block

language	bash

java -Dapplication.name=receiver-1 -Dvertx.hazelcast.config=cluster.xml -Dfile.encoding=UTF8 -jar iot-collector-generic-receiver-x.y.z.jar -conf config.json

Runtime parameters explained

Parameter name	Description	Example
-Dapplication.name	Mandatory JVM parameter. Defines the name of the receiver.	-Dapplication.name=receiver-1
-Dvertx.hazelcast.config	Mandatory JVM parameter. Specifies the file containing the cluster configuration.	-Dvertx.hazelcast.config=cluster.xml
-Dfile.encoding	Optional JVM parameter. Specifies the encoding used when working with byte streams or reading messages and files.	-Dfile.encoding=UTF8
-jar	Specifies the collector JAR file to be started.	-jar iot-collector-generic-receiver-x.y.z.jar
-conf	Specifies the module configuration file	-conf config.json

Configuration

Configuration is provided in config.json, which is passed to the application as -conf parameter

Configuration options

Info
Options are listed in dot notation - dot is refering to nested enttiy (e.g. receivers[].license means { "receivers" : [ { "license" : "abcdefgh" } ] }

Tip
It is possible to run multiple receivers using single JAR - by defining multiple receivers in receivers array. See below.

Common options

Option/Entity	Type	Default	Description
receivers	Array of objects		Array of receivers configuration.
receivers[].license	String	empty	License provided by BellaDati
receivers[].name	String	empty	Name of the module
receivers[].host	String	localhost	HTTP host on which HTTP endpoints are running
receivers[].port	Integer	8001	HTTP port on which HTTP endpoints are running, eventually accepting HTTP POST requests if endpoint type is HTTP_POST_CONSUME
receivers[].endpointType	String	HTTP_POST_CONSUME	Specifies the mode in which receiver collects the data. Available options are: HTTP_POST_CONSUME - accepts HTTP POST payload MQTT_BROKER - module is running as MQTT broker, which allows devices to either subscribe or publish messages to it MQTT_SUBSCRIBE - subscribes to existing MQTT broker and receives messages from it UDP_SERVER - accepts UDP datagram payloads TELNET_SERVER - accepts TELNET connections and payload WEBSOCKET_SERVER - accepts Websockets requests and payload CUSTOM - module is using custom implementation
receivers[].bodyLimit	Integer	2097152	Maximum allowed request body size (in bytes)
receivers[].inputMode	String	SINGLE	Data input mode: SINGLE - message payload contains only single record BULK - message payload contains multiple records ("data" array element must be present in message content)
receivers[].jsonSensorId	String	sensorId	Field, which contains device identifier. Applicable for JSON and XML content types only. If device ID is nested element, dot notation can be used. E.g. data.device.id
receivers[].exposeEndpointsData	Boolean	true	Flag indicating if endpoints GET /data and DELETE /data should be exposed
receivers[].messageContentType	String	JSON	Message content type: JSON XML CSV
receivers[].csvMessageSeparator	String	,	Determines the CSV content separator. Applicable only for CSV messageContentType.
receivers[].csvMessageEncoding	String	UTF-8	Determines the CSV content encoding. Applicable only for CSV messageContentType.
receivers[].csvMessageSensorIdColumnIndex	String	0	Index of device identifier in CSV content array splitted by csvMessageSeparator. Applicable only for CSV messageContentType.
receivers[].messageRules	Object		Contains message rules configuration.
receivers[].messageRules.contentConstraints	Array of objects		Contains array of content constraint definition object
receivers[].messageRules.contentConstraints[].name	String		Name of the field
receivers[].messageRules.contentConstraints[].required	Boolean	false	Determines whether field value is required
receivers[].messageRules.contentConstraints[].type	String	STRING	Type of the field. Available values: STRING, BOOLEAN, INTEGER, FLOAT
receivers[].messageRules.contentConstraints[].validate	String		Validation REGEXP
receivers[].messageRules.sensorFilter	Array of strings		Array of strings defining whitelist of accepted device IDs.
receivers[].db	Object		Contains database configuration. You can keep the default values unless you use some specific database.
receivers[].db.url	String	jdbc:hsqldb:file:hsql/instance-db;shutdown=true	Database connection string
receivers[].db.user	String	SA	Database username
receivers[].db.password	String	empty	Database password
receivers[].db.driverclass	String	org.hsqldb.jdbcDriver	Database JDBC driver class
receivers[].db.max_pool_size	Integer	100	Database maximum pool size
receivers[].db.drop	Boolean	false	Flag indicating if database should be dropped during module startup
receivers[].auth	Object		Configuration of administrators common for all modules
receivers[].auth.enabled	Boolean	true	Flag indicating if administrator authentication is enabled
receivers[].auth.drop	Boolean	false	Flag indicating if administrators should be dropped during module startup
receivers[].auth.merge	Boolean	true	Flag indicating if administrators should be merged during module startup
receivers[].auth.users	Array		Array of administrators to merge (insert new or update existing)
receivers[].auth.users.username	String	admin	Unique username
receivers[].auth.users.password	String		Hashed password if 'salt' is defined, otherwise plain text password
receivers[].auth.users.salt	String		Salt used to hash password
receivers[].auth.users.roles	String array	[ "VIEWER", "EDITOR" ]	Array of user roles

MQTT server options

If receivers[].endpointType is set to MQTT_BROKER, following options are available:

Option/Entity	Type	Default	Description
receivers[].mqttBroker	Object		Provides configuration for MQTT_BROKER endpoint type.
receivers[].mqttBroker.host	String	localhost	Host on which MQTT broker will run.
receivers[].mqttBroker.port	Integer	1883	Port on which MQTT broker will run.
receivers[].mqttBroker.republish	Boolean	false	Determines whether the received messages should be republished to registered subscribers or not
receivers[].mqttBroker.options	Object		Contains MQTT server configuration options
receivers[].mqttBroker.options.receiveBufferSize	Integer		Set the TCP receive buffer size.
receivers[].mqttBroker.options.timeoutOnConnect	Integer	120	Set the timeout on CONNECT packet in seconds.
receivers[].mqttBroker.options.maxMessageSize	Integer	-1	Set max MQTT message size in bytes.
receivers[].mqttBroker.options.autoClientId	Boolean	false	Set if clientid should be auto-generated when it's "zero-bytes"
receivers[].mqttBroker.options.tcpNoDelay	Boolean	false	Set whether TCP no delay is enabled
receivers[].mqttBroker.options.tcpKeepAlive	Boolean	false	Set whether TCP keep alive is enabled
receivers[].mqttBroker.options.soLinger	Boolean	false	Set whether SO_linger keep alive is enabled
receivers[].mqttBroker.options.acceptBacklog	Integer	1024	Set the accept back log
receivers[].mqttBroker.options.useAlpn	Boolean	false	Set the ALPN usage.
receivers[].mqttBroker.options.logActivity	Boolean	false	Set to true to enabled network activity logging: Netty's pipeline is configured for logging on Netty's logger.
receivers[].mqttBroker.options.trafficClass	Integer	-1	Set the value of traffic class
receivers[].mqttBroker.options.idleTimeout	Integer	-1	Set the idle timeout, in seconds.
receivers[].mqttBroker.options.sendBufferSize	Integer	-1	Set the TCP send buffer size
receivers[].mqttBroker.options.usePooledBuffers	Boolean	false	Set whether Netty pooled buffers are enabled
receivers[].mqttBroker.options.clientAuth	String	NONE	NONE REQUEST - Accept authentication if presented by client. If this option is set and the client chooses not to provide authentication information about itself, the negotiations will continue. REQUIRED - Require client to present authentication, if not presented then negotiations will be declined.
receivers[].mqttBroker.options.ssl	Boolean	false	Set whether SSL/TLS is enabled

MQTT subscribe options

If receivers[].endpointType is set to MQTT_SUBSCRIBE, following options are available:

Option/Entity	Type	Default	Description
receivers[].mqttSubscribe	Object		Provides configuration for MQTT_SUBSCRIBE endpoint type.
receivers[].mqttSubscribe.host	String	localhost	Host on which MQTT broker is running.
receivers[].mqttSubscribe.port	Integer	1883	Port on which MQTT broker is running.
receivers[].mqttSubscribe.topic	String	#	MQTT topic to subscribe - wildcards (+ and #) are supported
receivers[].mqttSubscribe.qos	String	AT_MOST_ONCE	Quality of service. Available options: AT_LEAST_ONCE, AT_MOST_ONCE, EXACTLY_ONCE, FAILURE
receivers[].mqttSubscribe.options	Object		Contains MQTT subscriber configuration options
receivers[].mqttSubscribe.options.receiveBufferSize	Integer		Set the TCP receive buffer size.
receivers[].mqttSubscribe.options.timeoutOnConnect	Integer	120	Set the timeout on CONNECT packet in seconds.
receivers[].mqttSubscribe.options.maxMessageSize	Integer	-1	Set max MQTT message size in bytes.
receivers[].mqttSubscribe.options.autoClientId	Boolean	false	Set if clientid should be auto-generated when it's "zero-bytes"
receivers[].mqttSubscribe.options.tcpNoDelay	Boolean	false	Set whether TCP no delay is enabled
receivers[].mqttSubscribe.options.tcpKeepAlive	Boolean	false	Set whether TCP keep alive is enabled
receivers[].mqttSubscribe.options.soLinger	Boolean	false	Set whether SO_linger keep alive is enabled
receivers[].mqttSubscribe.options.acceptBacklog	Integer	1024	Set the accept back log
receivers[].mqttSubscribe.options.useAlpn	Boolean	false	Set the ALPN usage.
receivers[].mqttSubscribe.options.logActivity	Boolean	false	Set to true to enabled network activity logging: Netty's pipeline is configured for logging on Netty's logger.
receivers[].mqttSubscribe.options.trafficClass	Integer	-1	Set the value of traffic class
receivers[].mqttSubscribe.options.idleTimeout	Integer	-1	Set the idle timeout, in seconds.
receivers[].mqttSubscribe.options.sendBufferSize	Integer	-1	Set the TCP send buffer size
receivers[].mqttSubscribe.options.usePooledBuffers	Boolean	false	Set whether Netty pooled buffers are enabled
receivers[].mqttSubscribe.options.clientAuth	String	NONE	NONE REQUEST - Accept authentication if presented by client. If this option is set and the client chooses not to provide authentication information about itself, the negotiations will continue. REQUIRED - Require client to present authentication, if not presented then negotiations will be declined.
receivers[].mqttSubscribe.ssl	Boolean	false	Set whether SSL/TLS is enabled

UDP server options

If receivers[].endpointType is set to UDP_SERVER, following options are available:

Option/Entity	Type	Default	Description
receivers[].udpServer	Object		Provides configuration for UDP_SERVER endpoint type.
receivers[].udpServer.host	String	localhost	Host on which MQTT broker is running.
receivers[].udpServer.port	Integer	1234	Port on which MQTT broker is running.
receivers[].udpServer.otpions	Object		Contains UDP server configuration options
receivers[].udpServer.options.logActivity	Boolean	false	Set to true to enabled network activity logging: Netty's pipeline is configured for logging on Netty's logger.
receivers[].udpServer.options.trafficClass	Integer	-1	Set the value of traffic class
receivers[].udpServer.options.receiveBufferSize	Integer		Set the TCP receive buffer size.
receivers[].udpServer.options.sendBufferSize	Integer	-1	Set the TCP send buffer size
receivers[].udpServer.options.broadcast	Boolean	false	Set if the socket can send or receive broadcast packets
receivers[].udpServer.options.loopbackModeDisabled	Boolean	true	Set if loopback mode is disabled
receivers[].udpServer.options.multicastTimeToLive	Integer	-1	Set the multicast ttl value
receivers[].udpServer.options.multicastNetworkInterface	String		Set the multicast network interface address
receivers[].udpServer.options.ipV6	Boolean	false	Set if IP v6 should be used

Configuration sample

Code Block

linenumbers	true
collapse	true

{
  "receivers": [
    {
      "license": "n5NkzaEOALzvGs7LOExyAulYdqo8X+5==",
      "name": "Receiver 01",                         
      "host": "localhost",                           
      "port": 8001,                                  
      "bodyLimit": 2097152,                          
      "jsonSensorId": "sensorId",                    
      "inputMode": "SINGLE",                         
      "exposeEndpointsData": true,                   
      "endpointType" : "HTTP_POST_CONSUME",          
      "messageRules": {
        "contentConstraints" : [
          { 
            "name" : "field1",
            "required" : true,
            "type" : "INTEGER",
            "validate" : "regexp"
          },
          { 
            "name" : "field2",
            "required" : false,
            "type" : "BOOLEAN"
          },
        ],
        "structureConstraints" : {
          "field1" : { "innerField", "innerField2" },
          "field2"
        },
        "sensorFilter" : [ "123456", "78910132" ]
      },
      "mqttSubscribe" : {                            
        "host" : "hostname",
        "port" : 1883,
        "topic" : "topic/to/subscribe",              
        "qos" : "AT_MOST_ONCE",                      
        "options" : {
          "receiveBufferSize" : 123456,              
          "timeoutOnConnect" : 120,                  
          "maxMessageSize" : -1,                     
          "autoClientId" :  false,                   
          "tcpNoDelay" : false,                      
          "tcpKeepAlive" : false,                    
          "soLinger" : false,
          "tcpQuickAck" : false,
          "tcpFastOpen" : false,
          "tcpCork" : false,
          "acceptBacklog" : false,
          "useAlpn" : false,
          "clientAuth" : false,
          "logActivity" : false,
          "trafficClass" : -1,
          "idleTimeout" : -1,
          "sendBufferSize" :  -1,
          "usePooledBuffers" : false,
          "clientAuthRequired" :  false, 
          "enabledSecureTransportProtocols" :  false
        }
      },
      "mqttBroker" : {                               
        "host" : "localhost",//optional
        "port" : 1883,//optional
        "options" : {
          //same as mqtt_subscribe
        }
      },
      "db": {                                        
        "url": "jdbc:hsqldb:file:/path/to/my-receiver01-db;shutdown=true",  
        "user": "SA",                                                       
        "password": "",                                                     
        "driverclass": "org.hsqldb.jdbcDriver",                             
        "max_pool_size": 100,                                               
        "jsonVarcharLength": 2047,                                          
        "drop": true                                                        
      },
      "auth": {
        "enabled": true,                                                    
        "drop": false,                                                      
        "merge": true,                                                      
        "users": [                                                          
          {
            "username": "viewer",                                           
            "password": "DAAF8173380C604B392A1EF8D7559AA0",                 
            "salt": "BA1170DE9ADE8D29D2C18FD789EAB3BD",                     
            "roles": [ "VIEWER" ]                                           
          }
        ]
      },
      "ssl": {
        "enabled": true,                                                    
        "keystorePath": "/path/to/server-keystore.jks",                     
        "keystorePassword": "wibble"                                        
      }
    },
    {
      "name": "receiver02",
      ...
    }
  ]
}

On this page

Table of Contents

Page tree

Versions Compared

Old Version 19

New Version 20

Key