commschamp / cc.mqttsn.libs

CommsChampion Ecosystem MQTT-SN client / gateway libraries and applications

The MQTT-SN protocol is a sibling of MQTT. While MQTT is designed to be used over a reliable stream transport protocol (such as TCP/IP), the MQTT-SN was designed to be used over a datagram transport protocol. It means, that if a message is received by the other end on the communication link, it is received in full and correctly.

There are multiple implementations of MQTT-SN client libraries and/or gateway applications. Most of them support only UDP/IP and/or ZigBee transport layers. However, it is possible to use MQTT-SN protocol with any other I/O link, such as RS-232 serial or CAN bus, as long as additional "packatisation" of the native MQTT-SN message is provided, to insure the message is delivered in full 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 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 code doesn't use RTTI or exceptions, but by default the library's implementation uses C++ STL data types, such as std::string and std::vector. However, it is possible to compile the library not to use any dynamic memory allocation, and make it suitable for bare-metal environment without any heap. Please refer to doc/custom_client_build.md for instructions on how to do it.

The doxygen generated documentation of the library with its full tutorial can be downloaded from the release artefacts.

Client Applications

The 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 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.

Gateway Library

Just like the Client Library allows additional data packatisation for correct delivery, the gateway application must implement the same functionality. As the result there is a need for a gateway library, 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) programming language and provides both C++ and C interfaces to use. The gateway uses v3.1.1 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.

Gateway Applications

The 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 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 spec.

• The client does NOT send GWINFO messages as a response to SEARCHGW message from other clients, on behalf of the gateway.
• The gateway 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.

How to Build

Detailed instructions on how to build and install all the components can be found in doc/BUILD.md file.

Branching Model

This repository will follow the Successful Git Branching Model.

The master branch will always point to the latest release, the development is performed on develop branch. As the result it is safe to just clone the sources of this repository and use it without any extra manipulations of looking for the latest stable version among the tags and checking it out.

Contact Information

For bug reports, feature requests, or any other question you may open an issue here in github or e-mail me directly to: [email protected]

cc.mqttsn.libs's Issues

Gateway sends data only slow in some cases

Hi,
I tried to use the gateway on my host and the client lib on my satellite. I noticed that the data is sent very slow to the client.

I reproduced this with the example programs:

What works:

1. start the gateway and connect it to Mosquitto as broker
2. start cc_mqttsn_sub_udp and subscribe with a # :

./client/src/app/sub/udp/cc_mqttsn_sub_udp -v -g localhost:1889 -t \#

What is very slow:

1. start the gateway and connect it to Mosquitto as broker
2. start cc_mqttsn_sub_udp and subscribe with a + :

./client/src/app/sub/udp/cc_mqttsn_sub_udp -v -g localhost:1889 -t foo/+/bar -k 5

I used -k5 because I noticed that some packages are sent on PINGRESP/PINGREQ. I get only one message per 5s (keepalive interval)

Any hint where I could start debugging?

Thanks

Can i use arduino here?

is this library compatible with arduino?

Topic names are not compared correctly

Hi,
I subscribe a topic test and get a confirmation SUBACK from the gateway. After that I try to publish to topic test/test but all my messages are send to test.
The problem is that the equality check in BasicClient.h is wrong.

A fix could be to check for equal length and for equal names.

 return elem.m_allocated && (elem.m_topic.size() == strlen(op->m_topic)) && (elem.m_topic == op->m_topic);

But at the end this seems to be a bug in COMMS. I did not check if this is fixed yet in a newer COMMS version and gets fixed here when we are compatible to new COMMS.
I can create a pull request on the weekend if you like.

Tests fail with Comms Champions 2.3.1

Hi,
To get rid of compiler warnings in cc (std::move local object into return) I tried cc version 2.3.1. All client tests but the ones that use msg.field_duration() fail (Test38, Test39). I debugged into doSleep() and saw that field_duration was set there. I don't understand where this field disappears Would be nice if you could have a look at it.
Thanks.

Regards
ailu

Encapsulation

Hi,
Do I see it correct, that encapsulation is not supported?

In the spec:
https://www.oasis-open.org/committees/download.php/66091/MQTT-SN_spec_v1.2.pdf

5.5 Forwarder Encapsulation

I have an forwarder and a connect from the client is responded with a "normal" CONNAK package

03 05 00

Ping is sometimes send twice

Hi,
I use the client on a MCU and notice strange disconnects to the MQTTSN gateway. The error was always that the gateway disconnected, though I see in the traffic that PINGREQ and PINGRESP are always on time. The disconnects happened often together with a valid ping in the logs:

<--- #4984
02 16                    | ..

---> #26
02 17                    | ..

I used retryPeriod = 5[s] and retryCount = 1.

I set retryCount = 3, m_keepAlivePeriod=10_000 and added some logs to the BasicClient.h and found the following:

The log format is:

internal clock in [ms], filename/function/line: some print

The "normal" operation looks like this:

I see a lot calls to updateTimestamp, and than about 30ms later tick() is called by my timer. tick() calls checkTimeouts().
It does not early exit because m_timestamp is not smaller than m_nextTimeoutTimestamp and finally calls checkPing().

bool needsToSendPing =
                ((m_lastSentMsgTimestamp + m_keepAlivePeriod) <= m_timestamp) ||
                ((m_lastRecvMsgTimestamp + m_keepAlivePeriod) <= m_timestamp);

evaluates to true because m_lastRecvMsgTimestamp (1322) + m_keepAlivePeriod(10_000) == m_timestamp(11322) and a ping is send.

15258 BasicClient.h/updateTimestamp:1948: 
15286 BasicClient.h/tick:591: 
15286 BasicClient.h/checkTimeouts:2188: m_timestamp: 11322 m_nextTimeoutTimestamp: 11322
15286 BasicClient.h/checkPing:2098: checkPing
15286 BasicClient.h/checkPing:2114: m_timestamp: 11322 m_lastSentMsgTimestamp: 11294 m_lastRecvMsgTimestamp 1322
15286 BasicClient.h/checkPing:2115: needsToSendPing 1
15286 BasicClient.h/sendPing:2640: count: 0 ts: 11322 lastping: 0

As expected this happens 10s later again:

25208 BasicClient.h/updateTimestamp:1948: 
25211 BasicClient.h/tick:591: 
25211 BasicClient.h/checkTimeouts:2188: m_timestamp: 21324 m_nextTimeoutTimestamp: 21324
25211 BasicClient.h/checkPing:2098: checkPing
25211 BasicClient.h/checkPing:2114: m_timestamp: 21324 m_lastSentMsgTimestamp: 21322 m_lastRecvMsgTimestamp 11324
25211 BasicClient.h/checkPing:2115: needsToSendPing 1
25211 BasicClient.h/sendPing:2640: count: 0 ts: 21324 lastping: 11322

But sometimes this happens:
updateTimstamp calls checkTimeouts and m_timestamp == m_nextTimeoutTimestamp so it does not exit and calls checkPing().
There again is needs to ping, because m_lastRecvMsgTimestamp is 10s old. But then tick is called and m_timestamp is magically increased by 5000ms in just 4ms, so m_timestamp == m_nextTimeoutTimestamp again and the call to sendPing() in the last line of checkPing() is executed. So basically there are two pings in just 4ms, though the retry period is 5s. This lead to my gateway disconnect errors.

35123 BasicClient.h/updateTimestamp:1948: 
35123 BasicClient.h/checkTimeouts:2188: m_timestamp: 31329 m_nextTimeoutTimestamp: 31329
35123 BasicClient.h/checkPing:2098: checkPing
35123 BasicClient.h/checkPing:2114: m_timestamp: 31329 m_lastSentMsgTimestamp: 31328 m_lastRecvMsgTimestamp 21329
35123 BasicClient.h/checkPing:2115: needsToSendPing 1
35123 BasicClient.h/sendPing:2640: count: 0 m_timestamp: 31329 lastping: 21324
35125 BasicClient.h/updateTimestamp:1948: 
35127 BasicClient.h/tick:591: 
35127 BasicClient.h/checkTimeouts:2188: m_timestamp: 36329 m_nextTimeoutTimestamp: 36329
35127 BasicClient.h/checkPing:2098: checkPing
35127 BasicClient.h/checkPing:2132: lastLine
35127 BasicClient.h/sendPing:2640: count: 1 m_timestamp: 36329 lastping: 31329
35129 BasicClient.h/updateTimestamp:1948: 

10s later "normal" operation:

45077 BasicClient.h/updateTimestamp:1948: 
45088 BasicClient.h/tick:591: 
45088 BasicClient.h/checkTimeouts:2188: m_timestamp: 46374 m_nextTimeoutTimestamp: 46374
45088 BasicClient.h/checkPing:2098: checkPing
45088 BasicClient.h/checkPing:2114: m_timestamp: 46374 m_lastSentMsgTimestamp: 46363 m_nextTimeoutTimestamp 36374
45088 BasicClient.h/checkPing:2115: needsToSendPing 1
45088 BasicClient.h/sendPing:2640: count: 0 m_timestamp: 46374 lastping: 36329
45090 BasicClient.h/updateTimestamp:1948: 

then some later again double ping.

74874 BasicClient.h/updateTimestamp:1948: 
74874 BasicClient.h/checkTimeouts:2188: m_timestamp: 76383 m_nextTimeoutTimestamp: 76380
74874 BasicClient.h/checkPing:2098: checkPing
74874 BasicClient.h/checkPing:2114: m_timestamp: 76383 m_lastSentMsgTimestamp: 76345 m_lastRecvMsgTimestamp 66380
74874 BasicClient.h/checkPing:2115: needsToSendPing 1
74874 BasicClient.h/sendPing:2640: count: 0 m_timestamp: 76383 lastping: 66378
74876 BasicClient.h/updateTimestamp:1948: 
74878 BasicClient.h/tick:591: 
74878 BasicClient.h/checkTimeouts:2188: m_timestamp: 81383 m_nextTimeoutTimestamp: 81383
74878 BasicClient.h/checkPing:2098: checkPing
74878 BasicClient.h/checkPing:2132: lastLine
74878 BasicClient.h/sendPing:2640: count: 1 m_timestamp:  <missing logs>

My workaround is to set retryCount to 3.

Since I am on a MCU with pretty limited debug functionality I cannot really step into the code. I hope the logs help.

Best regards

Add to existing CMake project

Hi,
I tried to add this library into my existing CMake project to compile it for my bare metal platform.
I had two issues doing this:

1. comms_champion cannot be compiled because
   arm-none-eabi-gcc.exe: error: unrecognized option '-rdynamic'
   I solved this by adding
   -DCMAKE_TRY_COMPILE_TARGET_TYPE=STATIC_LIBRARY to the external project CMAKE_ARGS (in https://github.com/arobenko/mqtt-sn/blob/ee28c7e06568758f227bbaf2f61c75379715f57f/CMakeLists.txt#L181-L182)

2. The option.h file could not be included because the include directory is set for a standalone project (https://github.com/arobenko/mqtt-sn/blob/ee28c7e06568758f227bbaf2f61c75379715f57f/client/CMakeLists.txt#L131)
   Changing this line to ${CMAKE_CURRENT_SOURCE_DIR}/../protocol/include solves this and the library compiles on my end.

I am not sure if the first one does not break other builds, since this forces the compiler to generate a static lib. I have no experience with ExternalProject. . Maybe it's a better way to use the BUILD_SHARED option (https://cmake.org/cmake/help/v3.0/variable/BUILD_SHARED_LIBS.html).

The second fix should work for standalone project.

If you like I can create a pull request with the second change, the first needs some discussion IMO.

kind regards

Client does not send PINGREQ if it receives packages

Hi,
I noticed that the client does not send PINGREQ packages if it receives packages in the keep alive period.

The MQTT spec states:

The client has a responsibility to send a message within each Keep Alive time period. In 
the absence of a data-related message during the time period, the client sends a
PINGREQ message, which the server acknowledges with a PINGRESP message.

The MQTTSN spec states:

As with MQTT, a PINGRESP message is the response to a PINGREQ message and means ”yes I
am alive”. Keep Alive messages flow in either direction, sent either by a connected 
client or the gateway

For me it seems that the client is responsible to send PINGREQ in MQTT, in MQTTSN the gateway can send PINGREQ too.

I am using the client in a setup with pahoo mqtt sn gateway and mosquitto mqtt broker. In this setup the gateway does not send PINGREQ to the client so I face a disconnect.

m_lastMsgTimestamp is used to calculate the delay for a PINGREQ and is set in BasicClient Line 526. So it is updated for each incoming message. To update m_lastMsgTimestamp only on sent messages we could move this into void sendMessage(const Message& msg, bool broadcast = false). Though I am not sure if this breaks something else, since I couldn't test it yet.

Regards

Protocol deviations around GWINFO/SEARCHGW

What are the reasons/pros/cons of the deviations? Does it affect interoperability with other implementation of MQTT-SN? Is there a way to revert to standard MQTT-SN 1.2 behavior so devices using this implementation mesh with others without any subtle surprise? Thanks!