SkillAgentSearch skills...

Paho.mqtt.cpp

No description available

GenerateConvertImprove

Install / Use

/learn @eclipse-paho/Paho.mqtt.cpp
About this skill

Quality Score

0/100

Supported Platforms

Universal

README

Eclipse Paho MQTT C++ Client Library

This repository contains the source code for the Eclipse Paho MQTT C++ client library for memory-managed operating systems such as Linux, MacOS, and Windows.

This code builds a library which enables Modern C++ applications (C++17 and beyond) to connect to an MQTT broker, publish messages, subscribe to topics, and receive messages from the broker.

The library has the following features:

  • Support for MQTT v3.1, v3.1.1, and v5.
  • Network Transports:
    • Standard TCP
    • UNIX-domain sockets
    • Secure sockets with SSL/TLS
    • WebSockets
      • Secure and insecure
      • Proxy support
  • Message persistence
    • User configurable
    • Built-in File persistence
    • User-defined key/value persistence easy to implement
  • Automatic Reconnect
  • Offline Buffering
  • High Availability
  • Blocking and non-blocking APIs
  • Modern C++ interface (C++17)

This code requires the Paho C library by Ian Craggs, et al., specifically version 1.3.16 or possibly later.

Latest News

To keep up with the latest announcements for this project, or to ask questions:

Mastodon: @fpagliughi@fosstodon.org

Email: Eclipse Paho Mailing List

What's New in v1.6.x

The v1.6.x is tested and builds around the latest Paho C v1.3.16, which has a number of performance enhancements and reduces a number of latency issues in connecting and publishing. Some additional updates:

  • Bumped Paho C submodule to v1.3.16 and updated directory name to externals/paho.mqtt.c
    • Some significant performance increases (lower latency) for connect and publish
  • Fixes to topic matching:
    • Fixed topic_matcher and topic_filter to properly match parent with multi-level ('#') wildcard.
    • Slight optimization of topic_filter to do simple string comparison if the filter does not contain wildcards.
    • Prevent undefined behaviour on empty topic matching
  • Set a minimum version for Paho C in the CMake file.
  • Debian .deb file properly versioned, and adds the architecture to the .deb file name.
  • Fixed post-reconnect crash in the sync client

For the full list of updates in each release, see the CHANGELOG.

Contributing

Contributions to this project are gladly welcomed and appreciated. Before submitting a Pull Request, please keep three things in mind:

  • This is an official Eclipse project, so it is required that all contributors sign an Eclipse Contributor Agreement (ECA)
  • Please submit all Pull Requests against the develop branch (not master).
  • Please sign all commits.

For full details, see CONTRIBUTING.md.

Building from source

As of v1.5, the Paho C++ library uses C++17 features, thus requiring a fully compliant C++17 compiler. Some of the more common compilers that can be used, depending on the target platform, are:

  • GCC v8 or later
  • clang v5 or later
  • Visual Studio 2017 15.8 (MSVC 19.15) or later

CMake is a cross-platform build system suitable for Unix and non-Unix platforms such as Microsoft Windows. It is the only supported build system. The current supported minimum version is:

  • cmake v3.13

The Paho C++ library requires the Paho C library, v1.3.16 or greater to be built and installed. That can be done before building this library, or it can be done here using the CMake PAHO_WITH_MQTT_C build option to build both libraries at the same time. This also guarantees that a proper version of the C library is used, and that it is build with compatible options.

Build Options

CMake allows for options to direct the build. The following are specific to Paho C++:

Variable | Default Value | Description ------------ | ------------- | ------------- PAHO_BUILD_SHARED | TRUE (*nix), FALSE (Win32) | Whether to build the shared library PAHO_BUILD_STATIC | FALSE (*nix), TRUE (Win32) | Whether to build the static library PAHO_WITH_SSL | TRUE (*nix), FALSE (Win32) | Whether to build SSL/TLS support into the library PAHO_BUILD_DOCUMENTATION | FALSE | Create the HTML API documentation (requires Doxygen) PAHO_BUILD_EXAMPLES | FALSE | Whether to build the example programs PAHO_BUILD_TESTS | FALSE | Build the unit tests. (Requires Catch2) PAHO_BUILD_DEB_PACKAGE | FALSE | Flag that configures cpack to build a Debian/Ubuntu package PAHO_WITH_MQTT_C | FALSE | Whether to build the bundled Paho C library

Enabling PAHO_WITH_MQTT_C builds and links in the Paho C library using compatible build options. If this is enabled, it passes the PAHO_WITH_SSL option to the C library, and also sets the options PAHO_HIGH_PERFORMANCE and PAHO_WITH_UNIX_SOCKETS for the C lib. These can be disabled in the cache before building if desired.

In addition, the C++ build might commonly use CMAKE_PREFIX_PATH to help the build system find the location of the Paho C library if it was built separately.

Build the Paho C++ and Paho C libraries together

The quickest and easiest way to build Paho C++ is to build it together with Paho C in a single step using the included Git submodule. This requires the CMake option PAHO_WITH_MQTT_C set.

$ git clone https://github.com/eclipse/paho.mqtt.cpp
$ cd paho.mqtt.cpp
$ git co v1.6.0

$ git submodule update --init

$ cmake -Bbuild -H. -DPAHO_WITH_MQTT_C=ON -DPAHO_BUILD_EXAMPLES=ON
$ sudo cmake --build build/ --target install

This assumes the build tools and dependencies, such as OpenSSL, have already been installed. For more details and platform-specific requirements, see below.

Unix-style Systems (Linux, macOS, etc)

On *nix systems CMake creates Makefiles.

The build process currently supports a number of Unix and Linux flavors. The build process requires the following tools:

  • CMake v3.13 or newer
  • A fully-compatible C++17 compiler. Common options are:
    • GCC v8 or later
    • clang v5 or later

On Debian based systems this would mean that the following packages have to be installed:

$ sudo apt-get install build-essential gcc make cmake

If you will be using secure sockets (and you probably should if you're sending messages across a public network):

$ sudo apt-get install libssl-dev

Building the documentation requires doxygen and optionally graphviz to be installed:

$ sudo apt-get install doxygen graphviz

Unit tests are built using Catch2.

Catch2 can be found here: Catch2. You must download and install Catch2 to build and run the unit tests locally. Currently Catch2 versions v2.x and v3.x are supported.

Building the Paho C library

The Paho C library can be built automatically when building this library by enabling the CMake build option, PAHO_WITH_MQTT_C. That will build and install the Paho C library from a Git submodule, using a known-good version, and the proper build configuration for the C++ library. But iIf you want to manually specify the build configuration of the Paho C library or use a different version, then it must be built and installed before building the C++ library. Note, this version of the C++ library requires Paho C v1.3.16 or greater.

To download and build the Paho C library:

$ git clone https://github.com/eclipse/paho.mqtt.c.git
$ cd paho.mqtt.c
$ git checkout v1.3.16

$ cmake -Bbuild -H. -DPAHO_ENABLE_TESTING=OFF -DPAHO_WITH_SSL=ON -DPAHO_HIGH_PERFORMANCE=ON
$ sudo cmake --build build/ --target install

This builds the C library with SSL/TLS enabled. If that is not desired, omit the -DPAHO_WITH_SSL=ON.

It also uses the "high performance" option of the C library to disable more extensive internal memory checks. Remove the PAHO_HIGH_PERFORMANCE option (i.e. turn it off) to debug memory issues, but for most production systems, leave it on for better performance.

The above will install the library to the default location on the host, which for Linux is normally /usr/local. To install the library to a non-standard location, use the CMAKE_INSTALL_PREFIX to specify a location. For example, to install into a directory under the user's home directory, perhaps for local testing, do this:

$ cmake -Bbuild -H. -DPAHO_ENABLE_TESTING=OFF \
    -DPAHO_WITH_SSL=ON -DPAHO_HIGH_PERFORMANCE=ON \
    -DCMAKE_INSTALL_PREFIX=$HOME/install

Building the Paho C++ library

If the Paho C library is not already installed, the recommended version can be built along with the C++ library in a single step using the CMake option PAHO_WITH_MQTT_C set on.

$ git clone https://github.com/eclipse/paho.mqtt.cpp
$ cd paho.mqtt.cpp
$ git co v1.6.0
$ git submodule update --init

$ cmake -Bbuild -H. -DPAHO_WITH_MQTT_C=ON -DPAHO_BUILD_EXAMPLES=ON
$ sudo cmake --build build/ --target install

If a recent version of the Paho C library is available on the build host, and it's installed to a default location, it does not need to be built again. Omit the PAHO_WITH_MQTT_C option:

$ cmake -Bbuild -H. -DPAHO_BUILD_SAMPLES=ON

If the Paho C library is installed to a non-default location, or you want to build against a different version, use the CMAKE_PREFIX_PATH to specify its install location. Perhaps something like this:

$ cmake -Bbuild -H. -DPAHO_BUILD_SAMPLES=ON -DCMAKE_PREFIX_PATH=$HOME/install

Building a Debian/Ubuntu package

A Debian/Ubuntu install .deb file can be created as follows:

$ cmake -Bbuild -H. -DPAHO_WITH_SSL=ON -DPAHO_ENABLE_TESTING=OFF -DPAHO_BUILD_DEB_PACKAGE=ON
$ cmake --build build
$ (cd build && cpack)

Windows

On Windows, CMake creates Visual Studio project files for use with MSVC. Currently, other compilers like clang or MinGW are not directly supported.

eclipse-paho

View profile

View on GitHub
GitHub Stars1.3k
CategoryDevelopment
Updated4d ago
Forks468
eclipse-paho/paho.mqtt.cpp

Languages

C++

Security Score

75/100

Audited on Mar 25, 2026

No findings