mqtt 轻量级物联网消息传输协议

[](https://travis-ci.org/eclipse/paho.mqtt.c) [](https://lgtm.com/projects/g/eclipse/paho.mqtt.c/alerts/) [](https://scan.coverity.com/projects/paho-c) # Eclipse Paho C Client Library for the MQTT Protocol This repository contains the source code for the [Eclipse Paho](http://eclipse.org/paho) MQTT C client library. This code builds libraries which enable applications to connect to an [MQTT](http://mqtt.org) broker to publish messages, and to subscribe to topics and receive published messages. Synchronous and various asynchronous programming models are supported. ## Information About MQTT * [MQTT website](http://mqtt.org) * [The MQTT 3.1.1 standard](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html) * [The MQTT 5.0 standard](https://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html) * [HiveMQ introduction to MQTT](https://www.hivemq.com/mqtt/) * [OASIS Introduction to MQTT presentation](https://www.oasis-open.org/committees/download.php/49205/MQTT-OASIS-Webinar.pdf) ## Libraries The Paho C client comprises four variant libraries, shared or static: * paho-mqtt3a - asynchronous (MQTTAsync) * paho-mqtt3as - asynchronous with SSL/TLS (MQTTAsync) * paho-mqtt3c - "classic" / synchronous (MQTTClient) * paho-mqtt3cs - "classic" / synchronous with SSL/TLS (MQTTClient) [Which Paho C API to use, with some history, for context](https://modelbasedtesting.co.uk/2013/10/13/which-paho-mqtt-c-api-to-use-and-some-history/) ## Usage and API Detailed API documentation [is available online](https://eclipse.github.io/paho.mqtt.c/MQTTClient/html/). It is also available by building the Doxygen docs in the ``doc`` directory. Samples are available in the Doxygen docs and also in `src/samples` for reference. These are: - *paho_c_pub.c* and *paho_c_sub.c:* command line utilities to publish and subscribe, -h will give help - *paho_cs_pub.c* and *paho_cs_sub.c:* command line utilities using MQTTClient to publish and subscribe - *MQTTClient_publish.c, MQTTClient_subscribe.c* and *MQTTClient_publish_async.c:* MQTTClient simple code examples - *MQTTAsync_publish.c* and *MQTTAsync_subscribe.c:* MQTTAsync simple code examples Some potentially useful blog posts: - [Paho client MQTT 5.0 support and command line utilities](https://modelbasedtesting.co.uk/2018/08/08/paho-c-client-mqtt-5-0-and-command-line-utilities/) - [MQTT, QoS and persistence](https://modelbasedtesting.co.uk/2013/11/24/mqtt-qos-and-persistence/) - [A story of MQTT 5.0](https://modelbasedtesting.co.uk/2018/04/09/a-story-of-mqtt-5-0/) [Various MQTT and MQTT-SN talks I've given.](https://modelbasedtesting.co.uk/talks-ive-given/) ## Runtime tracing A number of environment variables control runtime tracing of the C library. Tracing is switched on using `MQTT_C_CLIENT_TRACE` (a value of ON traces to stdout, any other value should specify a file to trace to). The verbosity of the output is controlled using the `MQTT_C_CLIENT_TRACE_LEVEL` environment variable - valid values are ERROR, PROTOCOL, MINIMUM, MEDIUM and MAXIMUM (from least to most verbose). The variable `MQTT_C_CLIENT_TRACE_MAX_LINES` limits the number of lines of trace that are output. ``` export MQTT_C_CLIENT_TRACE=ON export MQTT_C_CLIENT_TRACE_LEVEL=PROTOCOL ``` ## Reporting bugs Please open issues in the Github project: https://github.com/eclipse/paho.mqtt.c/issues. ## More information Discussion of the Paho clients takes place on the [Eclipse paho-dev mailing list](https://dev.eclipse.org/mailman/listinfo/paho-dev). Follow Eclipse Paho on Twitter: [@eclipsepaho](https://twitter.com/eclipsepaho) General questions about the MQTT protocol are discussed in the [MQTT Google Group](https://groups.google.com/forum/?hl=en-US&fromgroups#!forum/mqtt). There is more information available via the [MQTT community site](http://mqtt.org). ## Building with CMake The build process currently supports a number of Linux "flavors" including ARM and s390, OS X, AIX and Solaris as well as the Windows operating system. The build process requires the following tools: * [CMake](http://cmake.org) * [GNU Make](https://www.gnu.org/software/make/) or [Ninja](https://martine.github.io/ninja/) * A conforming C compiler, such as [gcc](https://gcc.gnu.org/), [Clang](https://clang.llvm.org/), etc On Debian based systems this would mean that the following packages have to be installed: ``` $ apt-get install build-essential gcc make cmake cmake-gui cmake-curses-gui ``` Also, in order to build a debian package from the source code, the following packages have to be installed ``` $ apt-get install fakeroot devscripts dh-make lsb-release ``` Ninja can be downloaded from its github project page in the "releases" section. Optionally it is possible to build binaries with SSL/TLS support. This requires the OpenSSL libraries and includes to be available. E. g. on Debian: ``` $ apt-get install libssl-dev ``` The documentation requires doxygen and optionally graphviz: ``` $ apt-get install doxygen graphviz ``` ### Building your application with CMake If the Paho C library was built with CMake and is already installed on the system, it is relatively easy to set up a CMake build for your application. (If it's not already built and installed read the next section). The library can be built with several options which create variations of the library for asynchronous or synchronous use; encryption (SSL/TLS) support or not; and whether the library is shared or static. CMake exports all of the libraries that were built as targets, and the user can chose which is best suited for an application. The package is named: **eclipse-paho-mqtt-c** The namespace for all the targets is also: **eclipse-paho-mqtt-c** The target names are the same as the library names. The static libraries append *-static* to the target name even for platforms that use the same base name for shared and static libraries. So: Target|Description ------|----------- paho-mqtt3a | asynchronous, no encryption paho-mqtt3as | asynchronous with SSL/TLS support paho-mqtt3c | synchronous, no encryption paho-mqtt3cs | synchronous with SSL/TLS support paho-mqtt3a-static | asynchronous, no encryption, static linkage paho-mqtt3as-static | asynchronous with SSL/TLS support, static linkage paho-mqtt3c-static | synchronous, no encryption, static linkage paho-mqtt3cs-static | synchronous with SSL/TLS support, static linkage Remember, though, that not all of these targets may be available. It depends on how the library was built. A sample *CMakeLists.txt* for an application that uses the asynchronous library with encryption support *(paho-mqtt3as)* might look like this: ``` cmake_minimum_required(VERSION 3.5) project(MyMQTTApp VERSION 1.0.0 LANGUAGES C) find_package(eclipse-paho-mqtt-c REQUIRED) add_executable(MyMQTTApp MyMQTTApp.c) target_link_libraries(MQTTVersion eclipse-paho-mqtt-c::paho-mqtt3as) ``` If the library was installed to a non-traditional location, you may need to tell CMake where to find it using `CMAKE_PREFIX_PATH`. For example, if you installed it in */opt/mqtt/paho.mqtt.c* ``` $ cmake -DCMAKE_PREFIX_PATH=/opt/mqtt/paho.mqtt.c .. ``` ### Building the Paho C library with CMake Before compiling, determine the value of some variables in order to configure features, library locations, and other options: Variable | Default Value | Description ------------ | ------------- | ------------- PAHO_BUILD_SHARED | TRUE | Build a shared version of the libraries PAHO_BUILD_STATIC | FALSE | Build a static version of the libraries PAHO_HIGH_PERFORMANCE | FALSE | When set to true, the debugging aids internal tracing and heap tracking are not included. PAHO_WITH_SSL | FALSE | Flag that defines whether to build ssl-enabled bi