Eclipse Paho C Client Library for the MQTT Protocol

This repository contains the source code for the Eclipse Paho MQTT C client library.

This code builds libraries which enable applications to connect to an MQTT 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
• The MQTT 3.1.1 standard
• The MQTT 5.0 standard
• HiveMQ introduction to MQTT
• OASIS Introduction to MQTT presentation

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

Usage and API

Detailed API documentation is available online. 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
• MQTT, QoS and persistence
• A story of MQTT 5.0

Various MQTT and MQTT-SN talks I’ve given.

Supported Network Protocols

The library supports connecting to an MQTT server using TCP, SSL/TLS, Unix-domain sockets, and websockets (secure and insecure). This is chosen by the client using the URI supplied in the connect options. It can be specified as:

"mqtt://<host>:<port>"         - TCP, unsecure
 "tcp://<host>:<port>"           (same)

"mqtts://<host>:<port>"        - SSL/TLS
 "ssl://<host>:<port>"           (same)

"unix:///path/to/socket        - UNIX-domain socket (*nix systems only)

"ws://<host>:<port>[/path]"    - Websockets, unsecure
"wss://<host>:<port>[/path]"   - Websockets, secure

The “mqtt://” and “tcp://” schemas are identical. They indicate an insecure connection over TCP. The “mqtt://” variation is new for the library, but becoming more common across different MQTT libraries.

Similarly, the “mqtts://” and “ssl://” schemas are identical. They specify a secure connection over SSL/TLS sockets. The use any of the secure connect options requires that you compile the library with the PAHO_WITH_SSL=TRUE CMake option to include OpenSSL. In addition, you must specify ssl_options when you connect to the broker - i.e. you must add an instance of ssl_options to the connect_options when calling connect().

The use of Unix-domain sockets requires the build option of PAHO_WITH_UNIX_SOCKETS=TRUE is required. This is only available on *nix-style systems like Linux and macOS. It is not vailable on Windows.

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/paho.mqtt.c/issues.

More information

Discussion of the Paho clients takes place on the Eclipse paho-dev mailing list.

Follow Eclipse Paho on Twitter: @eclipsepaho

General questions about the MQTT protocol are discussed in the MQTT Google Group.

There is more information available via the MQTT community site.

File truncated at 100 lines see the full file

Contributing to Paho

Thanks for your interest in this project!

You can contribute bugfixes and new features by sending pull requests through GitHub.

Legal

In order for your contribution to be accepted, it must comply with the Eclipse Foundation IP policy.

Please read the Eclipse Foundation policy on accepting contributions via Git.

1. Sign the Eclipse ECA
2. Register for an Eclipse Foundation User ID. You can register here.
3. Log into the Eclipse projects forge, and click on ‘Eclipse Contributor Agreement’.
4. Go to your account settings and add your GitHub username to your account.
5. Make sure that you sign-off your Git commits in the following format:

Signed-off-by: Alex Smith <alexsmith@nowhere.com> This is usually at the bottom of the commit message. You can automate this by adding the ‘-s’ flag when you make the commits. e.g.
```git commit -s -m “Adding a cool feature”

4. Ensure that the email address that you make your commits with is the same one you used to sign up to the Eclipse Foundation website with.

## Contributing a change

1. [Fork the repository on GitHub](https://github.com/eclipse/paho.mqtt.c/fork)
2. Clone the forked repository onto your computer: 
``` git clone https://github.com/<your username>/paho.mqtt.c.git 

1. Create a new branch from the latest

   ``` branch with 
   ```git checkout -b YOUR_BRANCH_NAME origin/develop
   

2. Make your changes
3. If developing a new feature, make sure to include JUnit tests.
4. Ensure that all new and existing tests pass.
5. Commit the changes into the branch: git commit -s Make sure that your commit message is meaningful and describes your changes correctly.
6. If you have a lot of commits for the change, squash them into a single / few commits.
7. Push the changes in your branch to your forked repository.
8. Finally, go to https://github.com/eclipse/paho.mqtt.c and create a pull request from your “YOUR_BRANCH_NAME” branch to the develop one to request review and merge of the commits in your pushed branch.

What happens next depends on the content of the patch. If it is 100% authored by the contributor with less than 1000 lines of new product code that meets the needs of the project (refactored, test code and sample code is excluded from the count), then it can be pulled into the main repository. When there are more than 1000 lines of new product code, more steps are required. More details are provided in the handbook.

Developer resources:

Information regarding source code management, builds, coding standards, and more.

• https://projects.eclipse.org/projects/iot.paho/developer

Contact:

Contact the project developers via the project’s development mailing list.

Search for bugs:

This project uses GitHub Issues here: github.com/eclipse/paho.mqtt.c/issues to track ongoing development and issues.

Create a new bug:

Be sure to search for existing bugs before you create another one. Remember that contributions are always welcome!

• Create new Paho bug