Syntax for Libraries?

[stephe]

I'm new to Arduino, but have written code for other projects and most of this Arduino code makes sense. Where I have gotten lost is I can't seem to find the documentation showing the syntax for some of the libraries, like this rfm69 one and the lowpower one.

For example, this page clearly shows the syntax for the pin mode command https://www.arduino.cc/en/Reference/PinMode.

I understand that contributed code might not be this clearly explained but for example I have no idea what the total syntax options for radio.sendWithRetry was. I was using this (RECEIVER, radiopacket, strlen(radiopacket)); and stumbled upon some code with added syntax radio.sendWithRetry(RECEIVER, radiopacket, strlen(radiopacket),6); which retries 6 times and fixed a small glitch I had. I have no idea what the default number of retries is or of there is some other syntax I'm not aware of.

I saw that using this library with breakout boards I might need to use for example  RFM69 radio = RFM69(RFM69_CS, RFM69_IRQ, IS_RFM69HCW, RFM69_IRQN); to define which pins are used for CS and IRQ but with a moteino it just uses RFM69 radio; so there must be some default pins this library assumes for moteino use or?

And which pins on the moteino are connected to which pins on the radio module? I couldn't find this specific, just that XYZ pins are used by the transmitter and assumed 13 is CLK, 12 is MISO, 11 is MOSI, 10 is CS, 9 is RST and 2 is IRQ with IRQN of 0. 8 seems to be used for the option ram module.

I hope I'm just not finding some documentation that does exist, as it feels like I'm reverse engineering this from sample code I'm finding from various sources. I'm pretty sure I'm missing something that is obvious to everyone else I have got this library working and the moteino boards working and talking to each other using my code but I want to play with the lowpower library and am sure I don't know all the syntax for it to use it effectively. Thanks for any help you can give me!

Steph

[Felix]

Everything is here: moteino.com
The RFM69 Examples will teach you the syntax and how to use the libs.

[stephe]

So there isn't any documentation of the syntax other than the examples?

I looked at the moteino site and unless I'm missing it I don't see any documentation for the syntax to, for example, set other pins for  IRQ or CS or reset. I figured that out from looking at some adafruit code using this library. And is readTemperature usable? I saw this in the library .h code but not in examples. I've been playing with trying to send data back in the ACK, which I also haven't see in the examples but seems to work?

I'm not complaining and this may just seem simple to many people, I just assumed there must be some documentation of syntax other than the examples I was overlooking, but if I need to study the library code and experiment, I can do that too. I'm just trying to learn, thanks for any tips you may have.

[TomWS]

Other than the Arduino reference documentation on the built-in libraries, I think you will find that virtually all Arduino libraries are 'documented' by example.

Tom

[stephe]

OK, thanks. Just making sure I wasn't overlooking something obvious.

[syrinxtech]

@stephe,

Don't forget you can always read the source code itself and learn a lot about the function.  Particularly the function header.  For example, you mentioned the sendWithRetry() example.  If you look in RFM69.CPP under that function you will see the additional parameters you mentioned.  In this case you can specify the number of retries and the wait time for each retry.

[DonpK]

As I mentioned elsewhere, I agree with stephe about the usefulness of function documentation. But as TomWS points out, "virtually all Arduino libraries are 'documented' by example". His use of quotes around "documented" is appropriate, since having to study the thousands of lines of code in the examples and .h and .cpp files is not particularly efficient.

In the example stephe gives, radio.sendWithRetry, how do I change the number of retries in this function: (radio.sendWithRetry(GATEWAYID, (const void*)(&theData), sizeof(theData))) ? The RFM69.cpp files show number of retries as the fourth parameter.

[syrinxtech]

DonpK,

If you look at the function declaration for sendWithRetry, we see the following:

bool RFM69::sendWithRetry(uint8_t toAddress, const void* buffer, uint8_t bufferSize, uint8_t retries, uint8_t retryWaitTime)

This function returns a "boolean" with a total of 5 parameters.  To answer your question, you would enter something like this:

radio.sendWithRetry(GATEWAYID, (const void *)(&buffer), sizeof(buffer), 5, 50);

This implies you are sending up to 5 retries.

[TomWS]

DonpK,

If you look at the function declaration for sendWithRetry, we see the following:

bool RFM69::sendWithRetry(uint8_t toAddress, const void* buffer, uint8_t bufferSize, uint8_t retries, uint8_t retryWaitTime)

This function returns a "boolean" with a total of 5 parameters.  To answer your question, you would enter something like this:

radio.sendWithRetry(GATEWAYID, (const void *)(&buffer), sizeof(buffer), 5, 50);

This implies you are sending up to 5 retries.

Actually, the key is to look at the .h file as, with C++, the optional argument defaults are specified as in:

Code Select Expand

virtual bool sendWithRetry(uint8_t toAddress, const void* buffer, uint8_t bufferSize, uint8_t retries=2, uint8_t retryWaitTime=40);

So you only NEED to specify the first three arguments with the fourth and fifth optionally defaulted to 2 and 40 respectively.  However, you can alway override these by specifying a different value.  If you want to learn about an Arduino library, ALWAYS read the .h file first.  Then look at the examples.

Tom.

[Felix]

Thanks Tom & syrinxtech,
Indeed I think the .h file is the "map" of a library, written in C++ code rather than descriptive narrative.
IMO I think people tend to get confused and bewildered when looking at all those pointers and variable types, though learning some computer types is hugely useful in stepping from the copy-paste-i-hope-it-works user to an entry coder who understands what they are typing. I really don't blame anyone as coding is still an art to me as well, and I truly respect those who can code much better than I.

[syrinxtech]

I'm learning Python now and wow....what a difference from everything else I've known.

I thought learning Lisp, Pascal, Fortran, Basic, COBOL, C, C++, a little Java and several web languages would help.....but those guys really pack a lot of capability into a few commands!

I learn something new everyday.....not only syntax but data structures, logic, program structure, architecture.....that's what keeps this hobby fun.

[Felix]

Talking languages, don't forget there is a big difference between an interpreted language like python, javascript, php, and a compiled language like C++.
In fact most interpreted languages ride on C++ interpreters.
Yes python is great and powerful, but IMO interpreted languages are not best suited for hardware development.
There is a lot of value in knowing something like C++, it teaches you the innards of the processor and memory.
I use python for instance to generate my production PCB panels, it shines at that, I would really not want to to that in C++.

[syrinxtech]

Agreed.  Of course I really got to appreciate things at the hardware level when I took an IBM 360 Assembler class back in '84.  Now that was programming.

I'm still getting used to the fact that since Python is interpreted you can have errors hiding in code that hasn't been executed yet.  All of a sudden, wham...your code blows chunks.

I spent almost 15 years coding in C on early Pyramid Unix systems in the late 80's and early 90's and loved it.  That easily translated to writing network code for Novell and Banyan Vines in C.  I actually wrote my Master's Thesis on an HP/UX box in C...a DHCP server before Microsoft actually offered one.  I got to work with Ralph Droms from Bucknell who authored the original DHCP RFC's.

[powernode]

Yeah, reading the source isn't that bad.  You learn a lot of cool implementation details.

I'm still getting used to the fact that since Python is interpreted you can have errors hiding in code that hasn't been executed yet.  All of a sudden, wham...your code blows chunks.

Hehe, just wait till you start coding in Javascript.

[DonpK]

Thanks for the followup responses to my question about the sendWithRetry function, (radio.sendWithRetry(GATEWAYID, (const void*)(&theData), sizeof(theData))) . One part of the syntax that did confuse me, although perhaps not bewilder, was the single closing parenthesis without a matching opening parenthesis. Does that indicate the availability of optional, default parameters? In this case that would be number of retries and wait time.