Go Down

Topic: Arduino Language Reference (Read 5172 times) previous topic - next topic

PaulieT

Hi,

I am new to Arduino, however, I am not new to software and hardware development.

My customer needed a quick timing circuit and I used an Arduino. Since I was using a Arduino for the first time, I needed to learn the language details or differences. All the information is on-line which may be nice for some, but was a problem for me. I needed a printed manual but could not find one. So, I made one from the on-line information.

It is attached as a PDF, if anyone else needs it printed. It is formatted for US Letter (8.5 x 11) size.

Feel free to post it on the Arduino web if you like.

Regards,
Paul

Robin2

Thanks for sharing.

I have only skimmed through the first 10 pages or so (after the index) and it looks to be clearly written and very useful.

I will bookmark it so I can refer it to others.

...R
Two or three hours spent thinking and reading documentation solves most programming problems.

nickgammon

#2
Apr 08, 2016, 01:03 am Last Edit: Apr 09, 2016, 12:53 am by Nick Gammon
It looks very good. Excellent presentation. I hope I may be allowed to pick a few small issues with it? I have been asked to link to it from our "useful material" page, and thus want to make sure there aren't any major errors (so far I haven't found any).

Quote
Page 7

The C understood by the Arduino compiler is not standard C; rather, it is a robust subset of standard C. A few standard C features are missing, but, the absence of those features is not crippling by any means.
The default language used by the IDE is C++. You can include C modules, but it is actually C++ in the main "xxx.ino" file. C and C++ are not totally interchangeable. I think it is a bit misleading to call it a subset. Some things are disabled by compiler command-line options (such as exceptions) but you can disable those on your PC as well.

I prefer to get away from the notion that there is an "Arduino language" because then beginners post code that couldn't possibly work in ordinary C++ and ask "how do you do this in Arduino?". The answer usually is "same as in C++".





Page 8

Code: [Select]

if (x > 120){ digitalWrite(LEDpin, HIGH); }


As a style issue you shouldn't encourage code on the same line after the "{" symbol. This usually sets a number of people in this forum off, and they suggest that you use the auto-formatter to fix it.




Page 15

Quote
goto
Personally I wouldn't even mention goto. Very few examples have them, and if someone is keen enough they can look up how to use it themselves. Similar to my point above, if you start encouraging people to use goto they are likely to produce code which (when it doesn't work) no-one will look at until the gotos are removed. I used to work for a company which, when I submitted my first piece of coding for code review was told to rewrite without using goto before they would look at it any further.

Your example of "goto bailout" for example could be simply replaced by "return". You may need to move those loops into a function on its own, but its a small price to pay.





Quote
Page 18
In general, the const keyword is preferred for defining constants and should be used instead of #define.
Where you mention that const is preferred to define, it would be helpful to have an example. The text almost suggests you can replace #define literally by const which you can't.

For example:

Code: [Select]

#define ledPin 3

or

const byte ledPin = 3;


The syntax is different enough that an example is helpful.




Page 20

Suggest mentioning the shorthand arithmetic operators. They can be confusing if you seem them in code and haven't had them explained, eg.

Code: [Select]

result += value;
result -= value;
result *= value;
result /= value;


(Reading on, I see you mention them on page 29. Maybe a cross-reference?)




Quote
Page 25
PORTD is a built-in constant that refers to the output states of digital pins 0,1,2,3,4,5,6,7.
This is rather specific to one processor. It might help to clarify that you are talking about the Atmega328P here, rather than all Arduinos.

Plus, it isn't a constant. It resolves to a dereferenced volatile pointer to a processor register. You can write to PORTD so it is hardly a constant. Maybe you mean "variable name" or "processor reference" - I'm not sure of the best word to describe it.





Quote
Page 32
When a pin is configured as an INPUT with pinMode, and read with digitalRead, the microcontroller will report HIGH if a voltage of 3 volts or more is present at the pin.
Hmm. It depends a bit on the processor and the voltage you are running at. An Atmega328P running at 2.4V or more Vcc will consider 0.6 * Vcc to be HIGH. Thus you are right about 3 volts being HIGH if it is running at 5 volts. However some Arduinos run at 3.3V so therefore a HIGH will be 0.6 * 3.3 which is 1.98 volts.

Quote
When a pin is configured as an INPUT with pinMode, and read with digitalRead, the microcontroller will report LOW if a voltage of 2 volts or less is present at the pin.
For the Atmega328P it is 0.3 * Vcc so actually it would be 1.5 volts or less if you are running Vcc at 5 volts.

Sorry if this seems pedantic, but an excellent document like yours is likely to get shared around and quoted as a reference.




Quote
Page 33
Integer Constants
Binary: Leading "B"
This is one of the silly things the IDE implements with a whole slew of defines. As you note "only works with 8 bit values (0 to 255)". Far more portable and robust is to use the C++ language feature of leading "0b", for example:

Code: [Select]

0b11010010001110


You aren't limited to 8 bits and it is more portable.




Page 38

Code: [Select]

int x
x = -32,768;
x = x - 1;     // x now contains 32,767 - rolls over in neg. direction
x = 32,767;  
x = x + 1;    // x now contains -32,768 - rolls over


Get rid of the commas in the numeric constants. :) They would compile but give you totally different results than what you claim.




Quote
Page 82

Get the number of bytes (characters) available for reading from the serial port. This is data that's already arrived and stored in the serial receive buffer (which holds 128 bytes).
64 bytes, I think.




Quote
Page 84

Flushes the buffer of incoming serial data. That is, any call to Serial.read() or Serial.available() will return only data received after all the most recent call to Serial.flush().
No. It might have once. It flushes the output buffer of any stored (pending) output. It does not affect the input buffer.




Quote
Page 85

Code: [Select]
Serial.print(78, BYTE);

That is old. That generates this error:

Code: [Select]
sketch_apr08a:2: error: The 'BYTE' keyword is no longer supported.
As of Arduino 1.0, the 'BYTE' keyword is no longer supported.
Please use Serial.write() instead.


 Serial.print(78, BYTE);
                  ^
exit status 1
The 'BYTE' keyword is no longer supported.


(Also see page 87).




I skimmed a bit. Others may pick up other things. Excellent document, don't be discouraged by the comments. The more accurate it is, the more likely people are to recommend it to others.
Please post technical questions on the forum, not by personal message. Thanks!

More info: http://www.gammon.com.au/electronics

westfw

1) A more complete reference manual is something that a lot of people ask about, so thank you for putting one together.

2) It really is a full C / C++ compiler, syntax-wise.  It's gcc.  The only place that it's a subset is in library and runtime support.

3) in view of (2), it might be nice to either separate or explicitly tag those features that are "just standard C", rather than forcing someone to read through the descriptions of various language features looking for "gotchas."

----

You don't mention structures, classes, or the standard libc functions that are available.  Especially notable in absence are the standard string function (strlen/etc.)

The F() macro isn't mentioned, and can be relatively important (and is easy to use.)

The .pdf file doesn't have a PDF table of contents, which would be nice to have.

No mention of ternary operator?  Beginners are unlikely to use it, but it appears often enough in the libraries and core functions that it might be nice to include it.

Quote
you are talking about the Atmega328P
The size of various data types described is also AVR specific.  The ARM-based Arduinos (Due, Zero, Teensy, etc) have 32bit "int" and 64bit "double" variables, for instance.

Somewhere in the "Constants" section, you might want to explain the "Pin number" abstraction used by the Arduino functions.  This is pretty fundamental and somewhat unique to the Arduino environment, and I know it initially confuses some people have "some" microcontroller background.  I'm not sure exactly how to explain it so that people with the right background go "ah hah!  THAT'S what they're doing" without confusing people who don't have any background at all, but ... give it a shot - you've done well with the rest of things...


nickgammon

#4
Apr 09, 2016, 12:54 am Last Edit: Apr 09, 2016, 12:55 am by Nick Gammon
(oops - it's correct in the actual document.  Must be something weird about cut&paste from pdf.)
That was my fault. The copy and paste from the PDF totally re-organized the code, and I put it back wrongly. I fixed my post above.
Please post technical questions on the forum, not by personal message. Thanks!

More info: http://www.gammon.com.au/electronics

Robin2

I appreciate all the time that Nick has taken to study the document. I did not do that {A} because I am lazy and {B} because I am not very proficient with C/C++.

It is disappointing that there has been no response from the OP / Author.

I reckon this document fills a large gap and would be useful for newcomers - hence my suggestion that it be added to the Useful Links page.

Even if the document has some style / subject shortcomings it would be better to provide a link to a "good" doument rather than wait forever for a "perfect" document.

...R
Two or three hours spent thinking and reading documentation solves most programming problems.

nickgammon

Give him a few more days. Maybe he is fixing it as we speak. :)
Please post technical questions on the forum, not by personal message. Thanks!

More info: http://www.gammon.com.au/electronics

weedpharma

It is handy to have a language reference when offline (yes, some of us do actually travel around without continuous connection to the interweb).

Thanks for sharing.

Looking forward to an updated edition.

Weedpharma

Bruce_Emsworth

Well done PaulieT! This is a much needed document for people like us who can program in other languages but are now coming to terms with C++.
This was a HUGE investment of your time and I REALLY appreciate it.

Now a general question to the rest of the posters.
What other similar documents exist?
Could we get a group of subscribers together to write a few extensions to PaulieT's document?

One I would like is something on Object Oriented stuff - I am using a standard textbook right now - but am struggling to find what specific classes are capable of.
Right now I am trying to figure out the Ethernet class and the PubSubClient class.
Any suggestions?

Thanks
Bruce

ChrisTenone

Wow! Your booklet really rocks Paul! Thank you soo much for the contribution to the community!

I hope you don't mind if I further disseminate your url cos that's what I'm gonna do.

If you are indeed incorporating the changes suggested - great! Nick is generally recognized as one of the most authoritative Arduino teachers here. You can make his suggested corrections without fear, Nick's got the goods.
What, I need to say something else too?

pert

Apparently none of you have realized that PDF is pretty much just an outdated copy of the Arduino language reference(http://www.arduino.cc/en/Reference/HomePage). I remember noticing it was even significantly out of date at the time of the original post. Having a PDF version of the reference is great but there have been quite a few changes since that scrape. If it's not going to be actively maintained it's not something I'd recommend people to use unless you absolutely need a PDF.

If anyone has suggestions for improvements to the reference then please post them to the GitHub issue tracker, after first checking that an issue doesn't already exist for that topic. agdl, the Arduino employee responsible for updating the reference is very easy to work with. I find that if I provide a well thought out and complete suggested edit the change will usually be made very quickly, as in a few business days.

smellai

Hi everybody,
we're almost ready to replace the Arduino Language Reference pages with an updated version hosted on GitHub, making it easier for anyone in the community to suggest changes and improvements.
(Before the switch on October 30th, we'd love you to take a look to ensure we got it right!)
Here the complete tutorial: https://create.arduino.cc/projecthub/Arduino_Genuino/contribute-to-the-arduino-reference-af7c37

Robin2

#12
Oct 19, 2017, 11:20 am Last Edit: Oct 19, 2017, 11:23 am by Robin2
, we'd love you to take a look to ensure we got it right!
I tried both of your links and I could not see any Arduino Language Reference Pages


I am not in favour of users having to go to Github to read Arduino reference material. IMHO it should remain part of this website. Make things easy for your users.

...R
Two or three hours spent thinking and reading documentation solves most programming problems.

smellai

Hi @Robin2, the tutorial links to https://reference.arduino.cc/reference/en/

Robin2

Hi @Robin2, the tutorial links to https://reference.arduino.cc/reference/en/
Sorry - my brain seems to be slow today. When I click that link it seems like I am no longer logged in.

...R
Two or three hours spent thinking and reading documentation solves most programming problems.

Go Up