

SINUMERIK Edge MQTT Client¶

SINUMERIK Edge MQTT Client is an edge application that allows communication between an edge application and an external MQTT broker.

Configuration¶

SINUMERIK Edge MQTT Client can be configured in the following format:

{
  "specificConfig": {
    "brokers": [
      {
        "host": "<HOST>",
        "port": <PORT>,
        "label": "<BROKER-LABEL>",
        "clientId": "<CLIENT-ID>",
        "username": "<USERNAME>",
        "password": "<PASSWORD>",
        "quota": {
          "memory": {
            "threshold": <MEMORY-QUOTA-THRESHOLD>,
            "hysteresis": <MEMORY-QUOTA-HYSTERESIS>
          }
        }
      },
      ...
    ],
    "logLevel": "<LOG-LEVEL>"
  }
}

Explanation for the fields follow as:

HOST: Hostname or IP address of the external broker. This address must be reachable via factorylan0 interface.
PORT: Port of the external broker.
LABEL: Label to identify this broker by. This label is a handle to be used by the applications that make use of the SINUMERIK Edge MQTT Client. There may be more than one broker configured with the same label and the published data will be pushed to all of them.
CLIENT-ID: Client ID to use while connecting to brokers, if omitted, an auto generated value is used.
USERNAME: Username to be used in authentication, can be omitted if no authentication is required for broker.
PASSWORD: Password to be used in authentication, can be omitted if no authentication is required for broker.
LOG-LEVEL: Log level of the application. The valid options are "trace", "debug", "info", "warning", "error", "critical". The default is "info" when this option is not provided. Note that levels that are more verbose than "info" may severly degrade performance.
MEMORY-QUOTA-THRESHOLD: Threshold in bytes for total message memory consumption of this broker. The consumption includes the size of in-flight/buffered/queued messages plus a fixed overhead per message (mostly negligible). If this value is exceeded, messages to this broker are started to be discarded. Defaults to 0 which equally distributes the available memory (see below) between the brokers.
MEMORY-QUOTA-HYSTERESIS: The value in bytes which controls when to stop discarding messages. Once the MEMORY-QUOTA-THRESHOLD is reached, messages are discarded until the memory consumption of messages for this broker becomes less than or equal to the value of MEMORY-QUOTA-THRESHOLD - MEMORY-QUOTA-HYSTERESIS. Defaults to lowest integral value of 10% of MEMORY-QUOTA-THRESHOLD.

As an example to memory quota configuration, let a broker have a threshold of 1500 MBytes and hysteresis of 200 MBytes. Once the total memory consumption of this broker increases past 1500 MBytes, the message triggering this condition and the messages received after will be discarded until memory usage drops to 1300 MBytes.

Further explanations:

APP-MEMORY-LIMIT: Currently a fixed value of 2-gigabytes.
TOTAL-MEMORY-QUOTA: Currently a fixed value of APP-MEMORY-LIMIT - 200-megabytes.
AVAILABLE-MEMORY: Available memory calculated by substracting the quota configured for brokers from the TOTAL-MEMORY-QUOTA. I.e. if you have a broker-0 configured with a memory quota of 1.3-gigabytes and broker-1 with a memory quota of 100-megabytes, broker-3 & broker-4 does not have any configured quotas, broker-3 and broker-4 will be automatically assigned a memory quota of 200-megabytes each.

Currently, the publishing to brokers are done with QoS = 2 and it cannot be changed.

Authentication¶

Version 0.4.0 of SINUMERIK Edge MQTT Client introduces username/password authentication mechanism to connect external MQTT brokers. In order to use username/password authentication, users must have their external MQTT brokers configured with username/password authentication. Users can specify username/password fields for relevant brokers in the configuration of SINUMERIK Edge MQTT Client application. For brokers that dont use authentication, these fields can be omitted.

E.g

{
  "specificConfig": {
    "brokers": [
      {
        "host": "10.0.1.1",
        "port": 1883,
        "label": "auth-broker",
        "username": "mqtt-user",
        "password": "mqtt-password"
      },
      {
        "host": "10.0.1.2",
        "port": 1883,
        "label": "no-auth-broker",
      },
      ...
    ],
    "logLevel": "debug"
  }
}

Statistics¶

By default, the application will print the application status & internal state of the communication with brokers at 15 second intervals. The statics contain information such as in-flight message count, the size of the in-flight messages and so on.

There are two kinds of statistics messages. The first one is process statistics message and the other is broker statistics message. For each broker, a separate line containing the statistics of that boker will be printed. The following is an example to a statistics message of an application configured with one broker:

2021-11-01 10:14:20 operator(): mem-rss-kb=9004;mem-peak-rss-kb=9004;mem-max-kb=2097152
2021-11-01 10:14:20 operator(): broker=broker-1;host=127.0.0.1;port=2885;msgs-in-flight=0;bytes-in-flight=0;queue-size=0;peak-queue-size=0;total-msgs=0;total-bytes=0;failed-msgs=0;failed-bytes=0;memory-quota=1937768449;memory-quota-hysteresis=193776844;msg-bw=0;bw=0

If we look in detail what these fields mean:

First line is the process statistics message, where the meaning of the fields follow as:
- mem-rss-kb: Current memory usage of the application in kilobytes.
- mem-peak-rss-kb: Peak memory usage of the application in kilobytes since the launch of the application.
- mem-max-kb: Maximum allowed memory usage of the application in kilobytes. If the memory usage exceeds this, the application will be killed, all queued/buffered/in-flight messages will be lost and the application will be restarted automatically.
The second line is a broker statistics message, where:
- broker: The label of the broker.
- host: The hostname configured for the broker.
- port: The port number configured for the broker.
- msgs-in-flight: Messages that are being sent. These kind of messages:
  - May already be sent to the broker but not yet ackowledged (where QoS > 0),
  - buffered in the OS network layer or
  - queued in some lower layer of the application.
- bytes-in-flight: The total size of the messages in flight.
- queue-size: Messages that are currently queued and waiting to be sent (where QoS = 0).
- peak-queue-size: Peak size that the queue has reached since the launch of the application.
- total-msgs: Total number of messages that have been successfully sent so far.
- total-bytes: Total bytes that have been successfully sent so far. The message is considered sent depending on QoS:
  - If QoS is 0, the message has been passed down to the OS network layer.
  - If QoS is greater than 0, the external broker has acknowledged the message.
- failed-msgs: The number of messages that were not sent due to a failure. This can happen when messages are discarded due to being in a disconnected state for a long time or reaching the configured memory quota threshold.
- failed-bytes: Total bytes of the failed messages.
- memory-quota: The configured memory quota threshold for this broker.
- memory-quota-hysteresis: The configured memory quota hysteresis for this broker.
- msg-bw: Average of per-message bandwidth in bytes per second. Per-message bandwidth is calculated for each message depending on QoS:
  - If QoS is 0, it is the size of the message divided by the duration it takes to be passed down to the OS network layer.
  - If QoS is greater than 0, it is the size of the message divided by the duration it takes to receive acknowledge message from the external broker.
- bw: Average bandwidth (bytes per second) calculated towards the broker in the period since the last statistics message. It is calculated as the total size of the messages sent divided by the duration.

One can also explicitly trigger the stats message by sending SIGUSR1 to the application. This is only possible on a development image.

Limitations¶

The application is configured to use a maximum of 2GB of memory. If the communication with an external broker is slow (or lost, see below), the data being sent will end up being buffered in the application itself. If this happens continuously until the memory limit is reached (memory quota threshold of a broker), the application will start to discard messages until the memory usage is decreased by a certain amount (memory quota hysteresis of a broker).

Upon reaching the memory quota threshold of a broker, a warning level log will be printed to indicate the start of the messages being discarded:

discard: quota reached for '<broker-hostname>:<broker-port>', discard until hysteresis '<broker-memory-quota-hysteresis>' is sent, psize=<size of the first message being discarded>

After the memory consumption of the broker drops below the configured value, a warning level log memory quota hysteresis reached on '<broker-hostname>:<broker-port>', stop discarding is printed and the messages will not be discarded any more until the threshold is reached again.

The data sent towards a broker that was not connected at all is discarded.

If the connection to a broker is initially established and then it is lost, the data to be sent towards that broker will be buffered for 3 minutes. If the connection is not re-established in 3 minutes, all the buffered data will be discarded and no further buffering will be done until connection is re-established.

Any questions left?

Ask the community

Except where otherwise noted, content on this site is licensed under the The Siemens Inner Source License - 1.1.