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).
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
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
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.
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:
#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.
result += value;
result -= value;
result *= value;
result /= value;
(Reading on, I see you mention them on page 29. Maybe a cross-reference?)
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.
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.
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.
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:
0b11010010001110
You aren't limited to 8 bits and it is more portable.
Page 38
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.
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.
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.
Page 85
Serial.print(78, BYTE);
That is old. That generates this error:
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.