0

documentation MQTT lib ??
Moderators: adafruit_support_bill, adafruit

Please be positive and constructive with your questions and comments.

documentation MQTT lib ??

by Lo on Mon Mar 11, 2019 2:42 pm

When switching over from the Adafruit Arduino IOT lib to the Adafruit MQTT lib, I unfortunately experience the same thing when I devellop my application within the Arduino IDE: WHERE is the documentation ?? I mean, there are some example sketches but we can't find al the ins and outs of the MQTT library... There is no documentation, so we have to browse all the source code of the MQTT library to find things out. This is not very comfortable. When documentation was online, it could save a lot of time. Also note that not everybody is capable of examining library sourcecodes !.
Example:
I develloped an application with a ESP8266 module and the Adafruit MQTT library. I liked the mqtt_esp8266_callback example, so I used it as a base for my application.
But I ran into problems because I did not know certain things like:

1. a callback like 'somethingcallback(int x)' gives me compiler errors, so a int x is apperantly not allowed. Why? we don't know, we have to examine source code and find out that int x is not allowed, apperantly only a (double x) is possible.
If there was any documentation I would have known this directy.

2. In the same example we wait for incomming subscription packets by calling mqtt.processPackets(10000); Apperantly these are milliseconds, but this is not documented. My application can spend much time there, so I used mqtt.processPackets(60000) to wait for 60 seconds in this function. Strange things happen now: the function will never be left and I get a watchdog error. ( I also did not know there was a watchdog timer active )
Why does this happen? Again we have to examine the code of the MQTT library. And with my moderate knowledge level of the C language I think that the maximum time here is 32767 milliseconds because the time parameter must probably be an integer and not an unsigned integer.
So again: if there was any documentation I would have known this directy...

I don't want to be negative. I really like Adafruit and their products, but the lack of this kind of documentation is annoying.
The examples are good but not enough to know all the possibilities of the libraries. I think some good documentation will be a very nice addition !

Kind regards, Lo

Lo
 
Posts: 11
Joined: Fri Oct 26, 2018 11:32 am

Re: documentation MQTT lib ??

by brubell on Mon Mar 11, 2019 3:13 pm

We're in the process of redoing the MQTT API documentation for Adafruit IO and working on giving it a proper home. Latest documentation is currently hosted on this learn page: https://learn.adafruit.com/welcome-to-a ... entation-2

Most of the issues you ran into are issues with the Adafruit MQTT library, not the API itself:

1. a callback like 'somethingcallback(int x)' gives me compiler errors, so a int x is apperantly not allowed. Why? we don't know, we have to examine source code and find out that int x is not allowed, apperantly only a (double x) is possible.

Can you provide an example of code where this compiler error occurs? Or where you found the `(double x)` in the library?

In the same example we wait for incomming subscription packets by calling mqtt.processPackets(10000); Apperantly these are milliseconds, but this is not documented. My application can spend much time there, so I used mqtt.processPackets(60000) to wait for 60 seconds in this function. Strange things happen now: the function will never be left and I get a watchdog error. ( I also did not know there was a watchdog timer active )
Why does this happen? Again we have to examine the code of the MQTT library. And with my moderate knowledge level of the C language I think that the maximum time here is 32767 milliseconds because the time parameter must probably be an integer and not an unsigned integer.

Could you provide an example where the watchdog error occurs? This will help me, or another community member, to reproduce the error on their end.

brubell
 
Posts: 282
Joined: Fri Jul 17, 2015 10:33 pm

Re: documentation MQTT lib ??

by Lo on Tue Mar 12, 2019 1:25 pm

It is not at all about the API documentation indeed.
It is all about the Adafruit MQTT library when writing a sketch.
We learn to do things by the given Arduino sketch examples and build further on that.

So I built my sketch based on the mqtt_esp8266_callback example.
I am not at home this week and have no access to my own computer with Arduino installed, so I cannot give you the exact code of my application. But it is really very similar to the mqtt_esp8266_callback example.
So you can try the things mentioned yourself :
1.
Code: Select all | TOGGLE FULL SIZE
void slidercallback(double x) {
  Serial.print("Hey we're in a slider callback, the slider value is: ");
  Serial.println(x);

} here I tried changing to slidercallback(int x) but it gives me a compiler error probably because int is not allowed, but we don't know why it has to be double float....(not documented) ( double float is much to big for my purpose )
2.
Code: Select all | TOGGLE FULL SIZE
mqtt.processPackets(10000);

here I assumed milliseconds (not documented) and tried 60 seconds by :
Code: Select all | TOGGLE FULL SIZE
mqtt.processPackets(60000)

Now this function will never be left and in my case a watchdog time out will come after a while.
Why? Probably because mqtt.processPackets(time) expects an integer. But we dont know that because.... it is not documented.
We have dive into library code like Adafruit_MQTT.cpp to find out..... not very comfortable !

We expect documentation something like :
mqtt.processPackets(time) :
- Purpose : to process subscriptions......... points to watch out for ....etc.
- Parameter : time in milliseconds, integer
- Returns : -

Hope you see my point. If this all was documented it would be much much easier !
When I used the Arduino IOT library I had similar isues : See post DOCUMENTATION OF DATA FUNCTIONS ?

Kind regards, Lo

Lo
 
Posts: 11
Joined: Fri Oct 26, 2018 11:32 am

Re: documentation MQTT lib ??

by abachman on Tue Mar 12, 2019 1:54 pm

Hello Lo,


You're welcome to send a pull request to the MQTT project with documentation for the methods you're describing. The software is open source under the MIT license and includes contributions from 19 individuals already, your additions sound like they would be very welcome for other people using the library in their projects.

As a side note, I'm sure the 19 people who've written code or otherwise contributed in the history of that library were not setting out with the intention of causing you problems. Please consider your tone when you're asking for help with your project.


- adam b.

abachman
 
Posts: 276
Joined: Mon Feb 01, 2010 12:48 pm

Re: documentation MQTT lib ??

by Lo on Wed Mar 13, 2019 7:15 pm

Ok, thanks for your answer.
I am not familiair with github and their pull requests but I will study this and maybe try this later.
And ofcourse I will stay positive with my questions and comments to all you people that did great work!

Lo
 
Posts: 11
Joined: Fri Oct 26, 2018 11:32 am

Please be positive and constructive with your questions and comments.