Connecting LMQTT_client to Local Mosquitto Broker on S7-1500 CPUs

1. Overview of the LMQTT_client Communication Architecture

The LMQTT_Client function block is part of the Siemens Library for MQTT (LMQTT), distributed through the Siemens Industry Online Support portal. The library implements a lightweight MQTT v3.1.1 client directly on the CPU's user program, eliminating the need for a dedicated CP 1545-1 or CloudConnect gateway. The client exchanges publish/subscribe messages with any standards-compliant broker, including the open-source Eclipse Mosquitto broker.

The typical deployment topology is illustrated below. The S7-1500/ET 200SP CPU acts as an MQTT client; the workstation running mosquitto.exe (or the Linux mosquitto daemon) acts as the broker. Both endpoints must share an IP-reachable subnet and must agree on TCP port (default 1883, or 8883 for TLS).

The PLC initiates a TCP connection to the broker. Authentication, topic filtering, keep-alive, and QoS handling are managed inside the FB. The programmer does not have to write any low-level socket or TLS code.

2. Prerequisites

Before instantiating LMQTT_Client in your project, verify the following hardware, firmware, and software requirements.

3. Installing the LMQTT Library in TIA Portal

1. Open the Siemens Support search page and search for entry ID 109771836 ("Library for MQTT (LMQTT) – for S7-1500 and ET 200SP"). Download the .zip matching your TIA Portal major version.
2. Extract the archive. You will find global library files such as LMQTT_V2_0_x.zal16 and accompanying PDFs describing the FB interfaces.
3. In TIA Portal, choose Options → Global libraries → Open library and select the .zal16 file.
4. Drag the LMQTT_Client type from the Master copies pane into your project tree under Program blocks → Types.
5. Open Devices & networks, select the CPU, and confirm that the LMQTT library is shown under PLC supervision & diagnostics → Information → Library versions after compilation.

If you do not see the library version, the project still references a previous type FB version of LMQTT. Re-compile all blocks with Project → Compile all → Software (rebuild all blocks).

4. LMQTT_Client Function Block Interface

The block exposes a fixed input/output interface. The following table lists the inputs you must populate to establish a connection. All string parameters are of type WString on the S7-1500 (UTF-16 LE encoding).

Outputs of interest: connected (BOOL, true while the session is established), busy (BOOL), error (BOOL), and status (WORD). When error = TRUE, status holds the diagnostic code described in Section 8.

5. Mosquitto Broker Installation and Configuration

Eclipse Mosquitto is the reference broker for this library. Install it on the same workstation that will run long-term, or on a dedicated IPC in the control cabinet.

5.1 Installation on Windows

1. Download the official installer (64-bit) from the Mosquitto download page on the Eclipse Foundation site. The Windows build is shipped by the Mosquitto project itself and is signed.
2. Run the installer with administrator rights. The default install path is C:\Program Files\mosquitto\.
3. Open a Command Prompt in the install directory and confirm the version:

   cd "C:\Program Files\mosquitto"
   mosquitto -h | findstr "version"
   mosquitto -v
   # 1719287873: mosquitto version 2.0.18 starting

4. Add the install directory to the system PATH environment variable for convenience.

5.2 Minimal mosquitto.conf for Local Development

Create a configuration file at C:\mosquitto\config\mosquitto_plc.conf with the following content. This configuration is suitable for a closed lab network where the PLC and the broker are the only participants.

# mosquitto_plc.conf - minimal config for LMQTT_Client testing
listener 1883 0.0.0.0
allow_anonymous true
persistence true
persistence_location C:/mosquitto/data/
log_dest file C:/mosquitto/log/mosquitto.log
log_type error
log_type warning
log_type notice
log_type information
connection_messages true
log_timestamp true
max_inflight_messages 200
max_queued_messages 1000

5.3 Generate a Password File (Optional but Recommended)

cd "C:\Program Files\mosquitto"
mosquitto_passwd -c C:\mosquitto\config\plc_pw.txt plc_user
# type password twice

Add the following lines to the configuration file and restart the broker service:

allow_anonymous false
password_file C:/mosquitto/config/plc_pw.txt
acl_file C:/mosquitto/config/plc_acl.txt

Sample plc_acl.txt granting the PLC read/write access to a single topic subtree:

user plc_user
topic readwrite siemens/#

5.4 Verifying the Broker

Use the bundled mosquitto_sub and mosquitto_pub command-line tools to confirm the broker accepts and routes messages.

# Terminal A - subscribe
mosquitto_sub -h 127.0.0.1 -p 1883 -t "siemens/#" -v

# Terminal B - publish (from any reachable host)
mosquitto_pub -h 127.0.0.1 -p 1883 -t "siemens/line1/temp" -m "23.5"

If Terminal A prints siemens/line1/temp 23.5, the broker is healthy and ready to accept the S7 client.

6. Network and Firewall Configuration

On a Windows host, the default firewall rule created by the Mosquitto installer opens only loopback traffic in some builds. Add an explicit inbound rule:

netsh advfirewall firewall add rule name="Mosquitto 1883" dir=in action=allow protocol=TCP localport=1883
netsh advfirewall firewall add rule name="Mosquitto 8883" dir=in action=allow protocol=TCP localport=8883

On the PLC side there is no firewall, but confirm the following in Devices & networks:

• The PROFINET interface of the CPU is in the same IP subnet as the broker host (e.g. 192.168.0.10/24 for the CPU, 192.168.0.20/24 for the broker).
• The CPU's Security → Firewall settings (only on CPU firmware V2.9 and higher with security enabled) are not blocking outbound TCP.
• Any managed switch between CPU and broker is not filtering by MAC ACL.

A quick reachability test from a Windows command shell on the same subnet:

ping 192.168.0.10
Test-NetConnection 192.168.0.10 -Port 1883

The Test-NetConnection cmdlet should return TcpTestSucceeded: True. If it returns False, the TCP path is blocked; do not proceed with the LMQTT configuration until this is resolved.

7. Step-by-Step Commissioning Procedure

1. Create a new cyclic OB (e.g. OB1 or a dedicated OB35 at 100 ms). Declare a single instance DB of LMQTT_Client and assign all input parameters in the call interface as shown below.
2. Wire the input parameters with constants, tags, or HMI fields. Begin with unencrypted settings: brokerPort := 1883, useTLS := FALSE, userName := "", userPassword := "" (matches allow_anonymous true).
3. Start the broker using the custom config file:

   cd "C:\Program Files\mosquitto"
   mosquitto -c C:\mosquitto\config\mosquitto_plc.conf -v

   The -v flag enables verbose logging in the console window; useful during commissioning.
4. Compile and download the TIA Portal project to the CPU. Perform a warm restart to ensure the OB is executed.
5. Trigger the connection by setting connect := TRUE. The FB requires a rising edge; if the input stays TRUE the FB handles reconnection automatically on error.
6. Observe the FB outputs in the watch table or HMI:
   • connected should toggle to TRUE within 1–3 seconds.
   • error should remain FALSE.
   • status should read 16#0000.
7. Verify from the broker side in the Mosquitto console window. You should see a line similar to:

   1719287923: New connection from 192.168.0.10:49152 on port 1883.
   1719287923: New client connected from 192.168.0.10:49152 as S7_1512SPF_01 (p2, c1, k30).

   The token c1 means clean session = 1, k30 means keep-alive = 30 s.
8. Publish a test message by pulsing publish for one OB cycle. The publishDone output acknowledges a successful QoS-1 acknowledgement from the broker.
9. Subscribe and receive by setting subscribeTopic := "siemens/cmd/#" and pulsing subscribe. Any matching message published by mosquitto_pub appears at receivedTopic and receivedMessage.

8. Diagnostic Status Codes (status WORD)

The status output reports the library-internal or TCP-layer error. The most common values you will encounter are listed below. The codes conform to the LMQTT library reference manual shipped with the download.

9. Diagnosing the "Difference in Low-Level Component" Error

The message "difference in low-level component" displayed in the TIA Portal online watch table is a generic notification that the user program references a type FB (here LMQTT_Client) whose version on the CPU does not match the version in the project. The library uses several subordinate FBs (LMQTT_TLS_Client, the OpenSSL-derived security component, and the TCP socket wrappers); any version skew between them triggers this message.

9.1 Root Causes

• Library and TIA Portal mismatch: LMQTT V2.1 was compiled for TIA V17; opening it in TIA V16 produces a "type cannot be resolved" warning and the 16#80B1 error on download.
• Firmware older than the library expects: LMQTT V2.0 requires the security patches shipped in CPU firmware V2.6+. Older firmware lacks the OPC-UA security update that LMQTT depends on.
• Partial download: Only the program blocks were downloaded, but the type/version metadata of the FB was not refreshed.
• Online/offline drift: A colleague changed the library on a different engineering station, but the current station still has the old .zal16 open.

9.2 Resolution Procedure

1. In TIA Portal open Project tree → PLC → Type FB versions and compare the online and offline versions of LMQTT_Client and all referenced types.
2. Right-click → Update type / Replace with current version to align online and offline.
3. Right-click the CPU → Compile → Software (rebuild all blocks). This regenerates every instance DB and resets the version stamps.
4. Perform a full download (program blocks and PLC data types). Watch the Info → Compile window for warnings.
5. Go online, open the watch table, and confirm the difference in low-level component message is gone. LMQTT_Client.status should now return 16#0000 after the next rising edge on connect.

10. TLS/SSL Configuration in Detail

When useTLS := TRUE, the LMQTT library requires a separate configuration block (commonly named LMQTT_TLS_Config_DB) that holds certificates, trust chains, and cipher lists. The configuration steps are:

1. Generate a CA and broker certificate on the Mosquitto host with openssl:

   openssl req -new -x509 -days 3650 -extensions v3_ca \
     -keyout ca.key -out ca.crt -subj "/CN=Mosquitto-CA"
   openssl genrsa -out broker.key 2048
   openssl req -new -key broker.key -out broker.csr \
     -subj "/CN=192.168.0.20"
   openssl x509 -req -in broker.csr -CA ca.crt -CAkey ca.key \
     -CAcreateserial -out broker.crt -days 3650

2. Enable TLS in mosquitto.conf:

   listener 8883 0.0.0.0
   cafile C:/mosquitto/certs/ca.crt
   certfile C:/mosquitto/certs/broker.crt
   keyfile C:/mosquitto/certs/broker.key
   require_certificate false
   tls_version tlsv1.2

3. Import the CA certificate into the CPU. Use the TIA Portal certificate manager (Project tree → Security → Certificates). The file format is .crt or .pem (DER or Base64). The certificate is downloaded with the project and stored in the CPU's security memory.
4. Fill the TLS config DB with the subject name, fingerprint, and time-to-live values as described in the LMQTT reference manual. Use the certificate SHA-256 fingerprint printed by openssl x509 -fingerprint -sha256 -in broker.crt -noout.
5. Set LMQTT_Client.useTLS := TRUE and brokerPort := 8883. Recompile and download.

11. Sample Structured-Text Implementation

The following example shows a complete OB35 call with publish-on-change and a simple ack monitoring. Adapt the fbMqtt instance DB to your project naming.

// OB35 - Cyclic 100 ms
// Trigger publish on rising edge of bTrigger
IF i_bPublishTrigger AND NOT i_bPublishTriggerOld THEN
    fbMqtt.publish := TRUE;
ELSE
    fbMqtt.publish := FALSE;
END_IF;
i_bPublishTriggerOld := i_bPublishTrigger;

fbMqtt.connect         := TRUE;
fbMqtt.brokerAddress   := '192.168.0.20';
fbMqtt.brokerPort      := 1883;
fbMqtt.clientID        := 'S7_1512SPF_01';
fbMqtt.userName        := '';
fbMqtt.userPassword    := '';
fbMqtt.keepAlive       := T#30s;
fbMqtt.cleanSession    := TRUE;
fbMqtt.useTLS          := FALSE;
fbMqtt.publishTopic    := 'siemens/line1/temp';
fbMqtt.publishMessage  := REAL_TO_STRING(fTemperature);
fbMqtt.publishQoS      := 1;
fbMqtt.publishRetain   := FALSE;
fbMqtt.subscribeTopic  := 'siemens/cmd/#';
fbMqtt.subscribeQoS    := 0;

fbMqtt();

// Mirror outputs to flags for HMI
o_bConnected := fbMqtt.connected;
o_bError     := fbMqtt.error;
o_wStatus    := fbMqtt.status;
o_bPublishOk := fbMqtt.publishDone;
o_sLastRx    := fbMqtt.receivedMessage;
IF fbMqtt.error THEN
    // optional: increase counter for diagnostics
    i_dwErrorCount := i_dwErrorCount + 1;
END_IF;

12. Verification Checklist

Walk through this list before declaring the integration complete:

13. Troubleshooting Matrix

14. Operational Notes and Field-Proven Caveats

• Single connection per instance. A single LMQTT_Client instance opens exactly one MQTT session. To use multiple topics, rely on the wildcard subscriptions (+, #) and route messages inside the PLC using receivedTopic string comparison.
• Topic length limit. The WString[128] input for publishTopic and subscribeTopic limits topic length to 127 UTF-16 characters (plus the implicit terminator). Design your topic tree to stay under 80 characters for headroom.
• Payload encoding. publishMessage is a UTF-16 string. To send binary or numeric payloads, use the byte-array variant of the FB or convert the value to a hex string in SCL before assigning.
• Performance. The library runs in the user program and consumes OB runtime proportional to the message rate. With QoS 0 and messages under 256 bytes, the cycle impact is below 1 ms on a CPU 1512SPF-1. Higher QoS or larger payloads increase the time per message.
• Firewall on CPU firmware V2.9+. If the security functions are activated, an outbound rule for TCP 1883 (or 8883) must be added under Security → Firewall in TIA Portal. Otherwise the connection is silently dropped at the CPU.
• Broker redundancy. Mosquitto V2.x has no built-in high availability. For redundant brokers, use a third-party bridge such as HAProxy in front of two Mosquitto instances and set brokerAddress to the virtual IP.
• Library update path. When upgrading from LMQTT V1.x to V2.x, the instance DB layout changes. Always re-create the instance after a major library upgrade, and review the new FB interface in the supplied PDF.

15. Frequently Asked Questions