Skip to content

Commit

Permalink
Updated README.
Browse files Browse the repository at this point in the history
  • Loading branch information
arobenko committed Aug 14, 2024
1 parent 2115248 commit 2df4b50
Showing 1 changed file with 33 additions and 36 deletions.
69 changes: 33 additions & 36 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
# Overview
The [MQTT-SN](https://www.oasis-open.org/committees/download.php/66091/MQTT-SN_spec_v1.2.pdf)
protocol is a sibling of [MQTT](http://mqtt.org). While **MQTT** is designed to be
used over a **reliable stream** transport protocol (such as TCP/IP), the **MQTT-SN**
Expand All @@ -14,15 +15,15 @@ and **without errors**.

This repository provides **single threaded**, **asynchronous**, **non-blocking**, easy to
use, suitable for **embedded** platforms, well documented libraries
of MQTT-SN client and gateway, which are
of MQTT-SN **client** and **gateway**, which are
completely generic and allow usage of MQTT-SN protocol over any I/O link. See
details below.

# Client Library
This repository provides the MQTT-SN **client** library. It is implemented
using C++(11) programming language, but provides **C** interface. The library's
using C++(17) programming language, but provides **C** interface. The library's
code doesn't use [RTTI](https://en.wikipedia.org/wiki/Run-time_type_information)
or exceptions, but by default
or exceptions. By default
the library's implementation uses C++ STL data types, such as
[std::string](http://en.cppreference.com/w/cpp/string/basic_string) and
[std::vector](http://en.cppreference.com/w/cpp/container/vector). However,
Expand All @@ -32,18 +33,23 @@ refer to [doc/custom_client_build.md](doc/custom_client_build.md) for instructio
how to do it.

The doxygen generated documentation of the library with its full tutorial can
be downloaded from the [release artefacts](releases).
be downloaded from the [release artefacts](releases) or browsed
[online](https://commschamp.github.io/cc_mqttsn_client_doc).

# Client Applications
The [Client Library](#client-library) described above is I/O link agnostic,
it allows to do any additional packatisation of the sent data to allow
correct delivery of the messages. This repository also provides a couple of
MQTT-SN **client** "publish"(**cc_mqttsn_pub_udp**) and "subscribe"
(**cc_mqttsn_sub_udp**) example applications, which use
UDP/IP as its datagram transport layer. These applications are also using
[Qt5](https://doc.qt.io/qt-5/) framework for their operation. It means that if
proper QT5 libraries are not installed or can not be found, these applications won't
be compiled.
This repository also provides extra utilities (example applications) which
use the [client library](#client-library) described above.

* **cc_mqttsn_gw_discover** - Discover available gateways client application
* **cc_mqttsn_client_pub** - Publish client application
* **cc_mqttsn_client_sub** - Subscribe client application

These applications use [Boost](https://www.boost.org) libraries,
([boost::program_options](https://www.boost.org/doc/libs/1_83_0/doc/html/program_options.html)
to parse the command line arguments and
[boost::asio](https://www.boost.org/doc/libs/1_83_0/doc/html/boost_asio.html) to run
the events loop and manage network connection(s)). Currently only UDP/IP network
connection type is supported.

# Gateway Library
Just like the [Client Library](#client-library) allows additional data
Expand All @@ -53,36 +59,27 @@ which provides the required core functionality and allows implementation of any
gateway application, suitable for the type
of I/O link to the client(s) being used.

This repository provides such a library. It is implemented using C++(11)
This repository provides such a library. It is implemented using C++(17)
programming language and provides both **C++** and **C** interfaces to use.
The gateway uses [v3.1.1](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.pdf)
of the MQTT protocol to connect to and communicate with the broker.

The doxygen generated documentation of the library with its full tutorial can
be downloaded from the [release artefacts](releases).
be downloaded from the [release artefacts](releases) or browsed
[online](https://commschamp.github.io/cc_mqttsn_gateway_doc).

# Gateway Applications
The [Gateway Library](#gateway-library) described above is I/O link agnostic,
it allows to do any additional packatisation of the sent data to allow
correct delivery of the messages. This repository also provides the
MQTT-SN gateway(**cc_mqttsn_gateway_udp**) example application, which uses
UDP/IP as its datagram transport layer. The application also using
[Qt5](https://doc.qt.io/qt-5/) framework for its operation. It means that if
proper QT5 libraries are not installed or can not be found, the gateway example
application won't be compiled.

# Spec Deviations
There are a couple of deviations from official MQTT-SN
[v1.2](https://www.oasis-open.org/committees/download.php/66091/MQTT-SN_spec_v1.2.pdf)
spec.

- The [client](#client-library) does NOT send **GWINFO** messages as a response
to **SEARCHGW** message from other clients, on behalf of the gateway.
- The [gateway](#gateway-library) sends **GWINFO** as a response to the
**SEARCHGW** message directly to the requesting client, not broadcasting it
like the protocol specifies.

All other behaviour is implemented as specified.
This repository also provides extra applications which
use the [gateway library](#gateway-library) described above.

* **cc_mqttsn_gateway_app** - Transparent gateway application.

These applications use [Boost](https://www.boost.org) libraries,
([boost::program_options](https://www.boost.org/doc/libs/1_83_0/doc/html/program_options.html)
to parse the command line arguments and
[boost::asio](https://www.boost.org/doc/libs/1_83_0/doc/html/boost_asio.html) to run
the events loop and manage network connection(s)). Currently only UDP/IP network
connection type is supported.

# How to Build
Detailed instructions on how to build and install all the components can be
Expand Down

0 comments on commit 2df4b50

Please sign in to comment.