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:

Error rendering macro 'code': Invalid value specified for parameter 'com.atlassian.confluence.ext.code.render.InvalidValueException'
java -Dapplication.name=receiver-1 -Dfile.encoding=UTF8 -jar iot-collector-generic-receiver-x.y.z.jar

This command will start the receiver with the default configuration of the cluster and audit. If necessary, it is also possible to manually specify these files:

Error rendering macro 'code': Invalid value specified for parameter 'com.atlassian.confluence.ext.code.render.InvalidValueException'
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
 Optional 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 Controller 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

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

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
  • KEYENCE_MC_TCP - can connect to a PLC device as MC TCP Client
  • KEYENCE_MC_SERIAL - can connect to a PLC device as MC serial Client
  • JMS_SUBSCRIBE
  • 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[].dataElement
 String data Specifies "data" element path in BULK mode 
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[].forceSensorId
 String
When enabled, a device ID will be assigned to all data sent to this receiver. 
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
  • BINARY_Q15_LE
 
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

UDP server options

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

Option/Entity Type Default Description 
receivers[].modbus.connectionString
 String
Modbus connection string, e.g. tcp://localhost:502 
receivers[].modbus.requestInterval
 Int
How often poll Modbus (in ms) 
receivers[].modbus.address
 String

Modbus data address, e.g. to read 4 values into fields first, second, rest and coil, this is the configuration:

first=holding-register:0
second=holding-register:1
rest=holding-register:2[8]
coil=coil:0[6]

Configuration sample

Error rendering macro 'code': Invalid value specified for parameter 'com.atlassian.confluence.ext.code.render.InvalidValueException'
{
  "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

  • No labels