Skip to content

Commit

Permalink
Add more doc, README and API
Browse files Browse the repository at this point in the history
  • Loading branch information
Ian Craggs committed Jul 14, 2017
1 parent 5d47e86 commit 1e7c337
Show file tree
Hide file tree
Showing 6 changed files with 7,324 additions and 10 deletions.
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -3,3 +3,6 @@
/build.paho/
*.swp
*.pyc
/doc/MQTTClient/
/doc/MQTTPacket/
/doc/MQTTClient-C/
41 changes: 31 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,24 +4,45 @@ This repository contains the source code for the [Eclipse Paho](http://eclipse.o

It is dual licensed under the EPL and EDL (see about.html and notice.html for more details). You can choose which of these licenses you want to use the code under. The EDL allows you to embed the code into your application, and distribute your application in binary or source form without contributing any of your code, or any changes you make back to Paho. See the EDL for the exact conditions.

The MQTTPacket directory contains the lowest level C library with the smallest requirements. This supplies simple serialization
and deserialization routines. It is mainly up to you to write and read to and from the network.
There are three sub-projects:

The MQTTClient directory contains the next level C++ library. This still avoids most networking code so that you can plugin the
network of your choice.
1. MQTTPacket - simple de/serialization of MQTT packets, plus helper functions
2. MQTTClient - high(er) level C++ client, plus
3. MQTTClient-C - high(er) level C client (pretty much a clone of the C++ client)

The *MQTTPacket* directory contains the lowest level C library with the smallest requirements. This supplies simple serialization
and deserialization routines. They serve as a base for the higher level libraries, but can also be used on their own
It is mainly up to you to write and read to and from the network.

The *MQTTClient* directory contains the next level C++ library. This networking code is contained in separate classes so that you can plugin the
network of your choice. Currently there are implementations for Linux, Arduino and mbed. ARM mbed was the first platform for which this was written,
where the conventional language choice is C++, which explains the language choice. I have written a starter [Porting Guide](http://modelbasedtesting.co.uk/2014/08/25/porting-a-paho-embedded-c-client/).

The *MQTTClient-C* directory contains a C equivalent of MQTTClient, for those platforms where C++ is not supported or the convention. As far
as possible it is a direct translation from *MQTTClient*.

## Build requirements / compilation

There are helper scripts (build...) in various directories. The client library is a set of building blocks which you pick and choose from, so that the smallest MQTT application can be built.
CMake builds for the various packages have been introduced, along with Travis-CI configuration for automated build & testing. The basic
method of building on Linux is:

## Usage and API
```
mkdir build.paho
cd build.paho
cmake ..
make
```

See the samples directory for examples of intended use.
The travis-build.sh file has the full build and test sequence for Linux.


## Usage and API

See the samples directories for examples of intended use. Doxygen config files for each package are available in the doc directory.

## Runtime tracing

As yet, there is no tracing. For the smallest client, should we have tracing?
The *MQTTClient* API has debug tracing for MQTT packets sent and received - turn this on by setting the MQTT_DEBUG preprocessor definition.


## Reporting bugs
Expand All @@ -30,8 +51,8 @@ This project uses GitHub Issues here: [github.com/eclipse/paho.mqtt.embedded-c/i

## More information

Discussion of the Paho clients takes place on the [Eclipse paho-dev mailing list](https://dev.eclipse.org/mailman/listinfo/paho-dev).
Discussion of the Paho clients takes place on the [Eclipse Mattermost Paho channel](https://mattermost.eclipse.org/eclipse/channels/paho) and the [Eclipse paho-dev mailing list](https://dev.eclipse.org/mailman/listinfo/paho-dev).

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 much more information available via the [MQTT community site](http://mqtt.org).
More information is available via the [MQTT community](http://mqtt.org).
Loading

0 comments on commit 1e7c337

Please sign in to comment.