日本語

SINETStream User Guide

Configuration file for Android

Overview

The Android version of SINETStream library, unlike the Java or Python versions, currently uses only Paho MQTT Android as the underlying messaging system.

Some of the configuration parameters, to be shown in this document, are used to populate the MqttConnectOptions at the initialization of the Paho MQTT Android library. For omitted optional items, corresponding default values are used in the Paho MQTT Android library.

Description blocks per service

   sinetstream_config.yml
   +------------------------+
   |  +------------------+  |
   |  | service #1       |  |
   |  |   ...            |  |
   |  +------------------+  |
   |      ...               |
   |  +------------------+  |
   |  | service #n       | <---- target service
   |  |   ...            |  |
   |  +------------------+  |
   +------------------------+

Cooperation with the configuration server

From the release of SINETStream v1.6, we introduced the configuration server which manages the SINETStream settings at one place.

In the previous SINETStream versions, we took an operation model that a SINETStream configuration file is being placed somewhere on the Android device. Adding to that, we take the new model that a system manager sets up SINETStream configurations on the configuration server, while each Android devices dynamically download it via REST-API.

In the former operation model, the Android SINETStream library simply reads the local file in YAML format. In the latter operation model, the Android SINETStream library accesses to the configuration server to download a JSON data and handle it only on memory.

The JSON data structure received from the configuration server roughly looks like the figure shown below. The right part of the figure corresponds to the conventional SINETStream configuration file contents (expressed in JSON format). The configuration server can handle multiple information blocks (basic SINETStream configurations, attachments like SSL/TLS certificates and secrets like public key) in centralized manner. If there are additional information other than basic ones, optional elements (attachments and secrets respectively) will be added to the JSON data. Basic configuration also has some extra items in this case. To distinguish the SINETStream configuration versions from previous releases, control header will be added as shown in the center of the figure. If the JSON data does not contain neither attachments nor secrets, and the SINETStream configurations is described within the SINETStream v1.6 conventions, the header will be omitted.

    JSON data                 config part        sinetstream_config
   +---------------+     - - +----------+        part
   | name          |    /    | (header) |
   +---------------+ - -     +----------+ - - - +----------------+
   | config        |         | config   |       | +------------+ |
   +---------------+ - - - - +----------+ - -   | | service #1 | |
   | (attachments) |                         \  | |   ...      | |
   +---------------+                          \ | +------------+ |
   | (secrets)     |                            +----------------+
   +---------------+

List of setting items

Basic parameters

Major classification Middle classification Subcategory Type Range Mandatory Remarks
service     String Any √ Service Identifier
  type   String {“mqtt”} √ Currently "mqtt" only
  brokers   String hostport1[,hostport2[, …]] √ Concatenate with commas for multiple elements

API parameters

Major classification Middle classification Subcategory Type Range Mandatory Remarks
  topics   String topic1[,topic2[, …]] √ Concatenate with commas for multiple elements
  client_id   String Any   Default: automatically generated
  consistency   String {“AT_MOST_ONCE”,”AT_LEAST_ONCE”,”EXACTLY_ONCE”}   Default: “AT_LEAST_ONCE”

SSL/TLS parameters

Format 1: Limited SSL/TLS certificates usage

Major classification Middle classification Subcategory Type Range Mandatory Remarks
  tls   Boolean {true,false}   Default: false

Format 2: Use SSL/TLS certificates stored in the Android KeyChain

Major classification Middle classification Subcategory Type Range Mandatory Remarks
  tls protocol String {TLSv1.2,TLSv1.3}   Default: “TLSv1.2”
  tls client_certs Boolean {true,false}   Default: false
  tls server_certs Boolean {true,false}   Default: false
  tls check_hostname Boolean {true,false}   Default: false

Format 3: Use SSL/TLS certificates downloaded from the configuration server

Major classification Middle classification Subcategory Type Range Mandatory Remarks
  tls protocol String {TLSv1.2,TLSv1.3}   Default: “TLSv1.2”
  tls keyfilePassword String Any   Password of the client certificate (xxx.pfx)
  tls check_hostname Boolean {true,false}   Default: false

MQTT specific parameters

Basic

Major classification Middle classification Subcategory Type Range Mandatory Remarks
  clean_session   Boolean {true,false}   Default: true
  protocol [1]   String {“MQTTv31”,”MQTTv311”,”DEFAULT”}   Default: “DEFAULT”
  transport   String {“tcp”,”websocket”}   Default: “tcp”
  qos   Integer {0,1,2}   Default: 1
  retain   Boolean {true,false}   Default: true
  max_inflight_messages_set inflight Integer Positive integer   Default: 10
  reconnect_delay_set max_delay Integer Positive integer   Default: 128000
  connect keepalive Integer Positive integer   Default: 60
  connect automatic_reconnect Boolean {true,false}   Default: false
  connect connection_timeout Integer Positive integer   Default: 30
  mqtt_debug [2]   Boolean {true,false}   Default: false

[1]: mqtt_version can be used as an alias of the item protocol. If both are specified, protocol is taken.

[2]: Option for developers; Turn on/off debug trace in MqttAndroidClient.

MQTT user authentication parameters

Major classification Middle classification Subcategory Type Range Mandatory Remarks
  username_pw_set username String Any    
  username_pw_set password String Any    

MQTT LWT (Last Will and Testament) parameters

Major classification Middle classification Subcategory Type Range Mandatory Remarks
  will_set topic String Any √  
  will_set payload String Any √  
  will_set qos Integer Positive integer √  
  will_set retain Boolean {true,false} √  

MQTT SSL/TLS parameters