Arduino Forum

Using Arduino => Programming Questions => Topic started by: nickgammon on Mar 19, 2012, 11:41 pm

Title: Read this before posting a programming question ...
Post by: nickgammon on Mar 19, 2012, 11:41 pm
1. Arduino programming language

The Arduino basically uses the industry-standard C++ language, implemented by the GNU g++ compiler.

For information on basic things like loops, strings, functions, data types, and so on try consulting one of the many online C++ references. Hint: Google "C++ tutorial".

The main sketch is C++, however the IDE does do a certain amount of pre-processing (in particular, generating function prototypes for you) before submitting the code to the main C++ compiler (see point 12 below).




2. Version 1.0 of the IDE*

A few things were changed in the 1.0 release version of the IDE. In particular some older examples and libraries may have this at the start:

Code: [Select]
#include "WProgram.h"

If you get errors try locating such places and changing that line to:

Code: [Select]
#include "Arduino.h"

* IDE = Integrated Development Environment




3. Libraries

Many useful features are implemented by libraries. These are basically xxx.cpp and xxx.h files collected together into a library folder. Some come with the IDE. See here for how to add additional libraries:

http://arduino.cc/it/Reference/Libraries (http://arduino.cc/it/Reference/Libraries)

(It is easy enough to write your own, they are basically just C++ source code).




4. Reference page

Many functions specific to the Arduino (like activating pins, reading analog input etc.) are documented on the reference page:

http://arduino.cc/en/Reference/HomePage (http://arduino.cc/en/Reference/HomePage)




5. Examples

Before rushing on to the forum saying you don't understand how to make something work, try working your way through the examples (File Menu -> Examples in the IDE). A few examples under the belt make everything else much easier.




6. Getting help on the forum

There are quite a few experienced people on the forum anxious to help you, and help you get as much as you can out of your Arduino. You can help them do that by making helpful posts:






7. Debugging

If you have puzzling behaviour, it is frequently helpful to put "debugging prints" inside your code. For example, initialize the serial port inside the setup function:

Code: [Select]
void setup ()
  {
  Serial.begin (115200);  // initialize serial comms at 115200 baud
  //  ... other setup here
  }  // end of setup


Later on you can print things of interest, eg.

Code: [Select]
Serial.println ("Button 5 pressed.");

(Check you have set your Serial Monitor to 115200 baud, or you may see gibberish characters).




8. Memory usage

Microcontrollers like the Arduino have much less memory than you would be used to on a Mac, Windows or Linux. For example the Atmega328 processor (used on the Uno, Fio, Nano, Duemilanove boards, and others) has 32 Kb of Program Memory (for your code), 2 Kb of SRAM* (for your variables), and 1 Kb of EEPROM (for saving data when powered off).

Typically programs that reset unexpectedly, or hang, have run out of SRAM. Note that the number reported by the compiler when you compile your program is program memory, not SRAM.

Even a simple array like the one below uses 2000 bytes of memory. This line alone would almost certainly make your program crash:

Code: [Select]
int myData [20] [50];

Hint: The String class tends to gobble up memory. Try to avoid using that, especially in larger programs.

* SRAM = Static Random Access Memory

Warning: In versions of the Arduino IDE up to 1.0.1 (at least) there is a bug in dynamic memory allocation. This affects both malloc/free and new/delete. In particular it also affects the String class, which uses dynamic memory allocation. This is discussed in this forum thread (http://arduino.cc/forum/index.php/topic,95914). A work-around is provided in this thread (http://arduino.cc/forum/index.php/topic,145765) (a replacement malloc.c file) until the inbuilt libraries are updated.

Hint: Static strings can quickly gobble up SRAM. A simple technique to avoid that is to use the F( ) macro, as shown here:

Instead of:

Code: [Select]

Serial.println ("Welcome to my program!");


Use:

Code: [Select]

Serial.println (F("Welcome to my program!"));





9. Reading serial data

Serial data arrives asynchronously, that is, a byte at a time at no particular rate between bytes. To read things longer than a byte it is helpful to collect incoming data into a suitable size buffer, and when all has arrived, process that. Typically you know it has all arrived when a special character, such a newline character, is received.




10. Try things!

Read this: 

http://mattgemmell.com/2008/12/08/what-have-you-tried/ (http://mattgemmell.com/2008/12/08/what-have-you-tried/)

You will get more help if you try something and describe what happened, rather than posting "I wonder if X will work".




11. Traps, tips, style guide and more reading.

On the page below are various frequently reported programming traps, some tips for enhancing your coding, a brief style guide, and links for further reading:

http://www.gammon.com.au/tips (http://www.gammon.com.au/tips)




12. Issues with the IDE pre-processor

Sometimes "valid C" (or "valid C++") will not compile properly due to the way that the IDE pre-processor converts your "sketch" file into a C++ file. This is explained in detail here:

http://www.gammon.com.au/forum/?id=12625 (http://www.gammon.com.au/forum/?id=12625)




13. Standard libraries (libc)

The Arduino IDE includes ("links") libc - a standard library of common building-blocks that C programs often need. This includes things such as type conversions and string manipulations.

The documentation is here: http://www.nongnu.org/avr-libc/user-manual/modules.html (http://www.nongnu.org/avr-libc/user-manual/modules.html)

C/C++ programmers should make themselves familiar with what kinds of things are already provided in this standard library. In particular, browse through the functions in stdlib.h and string.h and the types in stdint.h .




(edits)
1. Added a paragraph about memory usage.
2. Added a line about making forum subject headings descriptive.
3. Added a line about describing or posting your circuit.
4. Re-organized the sequence of paragraphs.
5. Added note to make sure you have your serial port set to 115200 baud.
6. Added note about not cross-posting.
7. Added note about posting a "minimal" sketch.
8. Numbered sections.
9. Added warning about bug in dynamic memory allocation.
10. Added note in point 1 about the compiler being "real" C++.
11. Added link to "traps and tips" page.
12. Added link to "How to avoid the quirks of the IDE sketch file pre-preprocessing"
13. Added mention of the "libc" standard libraries.
Title: Re: Proposed sticky: Before posting a programming question, read this!
Post by: PaulS on Mar 19, 2012, 11:45 pm
I like it, but there are only two stickies on the whole forum - both in the Website forum. I don't expect that this will make sticky status.
Title: Re: Proposed sticky: Before posting a programming question, read this!
Post by: nickgammon on Mar 19, 2012, 11:49 pm
Another one of mine got stickied (not by me):

http://arduino.cc/forum/index.php/topic,84190.0.html

I'm trying to save everyone some time by helping people out to help themselves here.
Title: Re: Proposed sticky: Before posting a programming question, read this!
Post by: fkeel on Mar 19, 2012, 11:54 pm
+1
think is useful.
Title: Re: Proposed sticky: Before posting a programming question, read this!
Post by: el_supremo on Mar 20, 2012, 03:35 am
In "Getting Help on the Forum" I would make something like this the first point:
- Use a descriptive Subject for your post. A Subject like "Noob needs help" or "Guidance needed" will not induce people to read your message.

I, for one, tend to ignore any post which doesn't have some useful info in the Subject or which is ALL IN CAPS or which has the word "urgent" in it.

Pete
Title: Re: Proposed sticky: Before posting a programming question, read this!
Post by: nickgammon on Mar 20, 2012, 03:45 am
Modified to follow your suggestion, thanks.
Title: Re: Proposed sticky: Before posting a programming question, read this!
Post by: mrdovey on Mar 20, 2012, 06:11 am
You could include a link to the venerable "How to Ask Questions the Smart Way" at http://www.catb.org/~esr/faqs/smart-questions.html#intro (http://www.catb.org/~esr/faqs/smart-questions.html#intro)
Title: Re: Proposed sticky: Before posting a programming question, read this!
Post by: WizenedEE on Mar 20, 2012, 06:12 am
My thought it that it may be helpful to organize it a little better, such that someone completely clueless to programming wouldn't have to wade through "Serial data arrives asynchronously" to get to "Post your code!" Put the important and easily understandable things at the top.
Title: Re: Proposed sticky: Before posting a programming question, read this!
Post by: macegr on Mar 20, 2012, 06:22 am
I don't think the problem is lack of available things to read. It's the fact that a lot of people don't want to read at all. Maybe we need an Arduino picture book...you know, bright colors, shapes, connect the dots....

(channeling a little Grumpy Mike today)
Title: Re: Proposed sticky: Before posting a programming question, read this!
Post by: Coding Badly on Mar 20, 2012, 07:10 am
(channeling a little Grumpy Mike today)


Indeed.

Quote
I don't think the problem is lack of available things to read.


I agree.

Quote
It's the fact that a lot of people don't want to read at all.


That is a problem but my impression is that most folks new to Arduino have a difficult time knowing how or where to get the information they need.  They come to the forum because they suffer from 3rd Order Ignorance.

For example, I can distinctly remember when I started that it was a few weeks before I realized there was a "Playground" and a few months before I realized what the "Playground" was.  I assumed, with the title "Playground", it was a place for advanced users to exchange project details so I simply didn't bother to visit.

Quote
Maybe we need an Arduino picture book...you know, bright colors, shapes, connect the dots....


XD
Title: Re: Proposed sticky: Before posting a programming question, read this!
Post by: nickgammon on Mar 20, 2012, 07:27 am

I don't think the problem is lack of available things to read. It's the fact that a lot of people don't want to read at all.


Yes, sure. But my experience with other forums is that if there is a sticky at the very top where I am about to post "der, how do I get X to work?" and it runs through a lot of the preliminaries, then there is a chance I will read it.

Quote
My thought it that it may be helpful to organize it a little better ...


I can work on that bit.
Title: Re: Proposed sticky: Before posting a programming question, read this!
Post by: dxw00d on Mar 20, 2012, 08:26 am
Thumbs up from me.

If you are going to suggest that people use 115200 baud for serial comms, it might be worth mentioning that they will need to set the serial monitor to match. It's not necessarily obvious for beginners, and could save on 'My serial output is just weird characters' problems.
Title: Re: Read this before posting a programming question ...
Post by: cjdelphi on Apr 04, 2012, 09:38 am
I think this was very useful, 2 questions answered (of mine)  - I was wondering about char arrays and sram, since most boards (the cheaper ones not the mega boards) only have 2k of sram, this post would save someone a LOT of time lol.... cheers - i hope it stays sticky.
Title: Re: Read this before posting a programming question ...
Post by: nickgammon on Apr 04, 2012, 09:42 am
Yeah I hope so too ... but I am just a Pawn in the Game of Life ...
Title: Re: Read this before posting a programming question ...
Post by: mromani on Apr 04, 2012, 09:58 am
Excellent!

The "what have you tried" link alone doubles the usefulness of the post. :-D
Title: Re: Read this before posting a programming question ...
Post by: PeterH on Apr 04, 2012, 12:27 pm
When posting code, rather than posting a complex sketch, aim to post the simplest sketch that shows the problem. As a courtesy to the people trying to help you, make sure the sketch actually compiles and demonstrates the problem before you post it, and format the code.
Title: Re: Read this before posting a programming question ...
Post by: liuzengqiang on Apr 04, 2012, 04:00 pm
Nice post Nick! My suggestion: Add number to each bold title so I can tell a noob to say read number 6 on the sticky thread about "getting help" and follow the "posting code" suggestion. Or simply issue a 6-5.
Title: Re: Read this before posting a programming question ...
Post by: nickgammon on Apr 05, 2012, 12:02 am

When posting code, rather than posting a complex sketch, aim to post the simplest sketch that shows the problem.


Added this suggestion to the "how to post" list.


My suggestion: Add number to each bold title so I can tell a noob to say read number 6 on the sticky thread about "getting help" and follow the "posting code" suggestion.


Now numbered each section.
Title: Re: Read this before posting a programming question ...
Post by: Sacman on Apr 16, 2012, 10:52 pm
Jeremy Blum's tutorial series on Youtube is the single most helpful resource for anyone just getting started using the Arduino.

I watched all 14 videos twice before I even received my Arduino in the mail. I think everyone should be required to watch those videos before they post a thing:

http://www.youtube.com/playlist?list=PLA567CE235D39FA84&feature=plcp (http://www.youtube.com/playlist?list=PLA567CE235D39FA84&feature=plcp)
Title: Re: Read this before posting a programming question ...
Post by: maniacbug on May 07, 2012, 08:52 pm
Here's my contribution, a collection of common beginner trouble spots: http://www.cprogramming.com/tutorial/common.html
Title: Re: Read this before posting a programming question ...
Post by: nickgammon on May 07, 2012, 11:28 pm
Thanks! And I'll add the C++ FAQ Lite:

http://www.parashift.com/c++-faq-lite/
Title: Re: Read this before posting a programming question ...
Post by: martin_80x on May 25, 2012, 07:55 pm
Nice.
Title: Re: Read this before posting a programming question ...
Post by: JChristensen on May 25, 2012, 08:42 pm

Thanks! And I'll add the C++ FAQ Lite:

http://www.parashift.com/c++-faq-lite/


I see there is also: http://www.parashift.com/c++-faq/

The few pages I checked appear identical between the two.  :~
Title: Re: Read this before posting a programming question ...
Post by: Tom Carpenter on Jun 27, 2012, 10:10 pm
Another thing, if the code being posted is not properly indented, it is a pain to follow. Press "tools->auto format" in the IDE first as it makes it far easier to understand :D
Title: Re: Read this before posting a programming question ...
Post by: dkl65 on Jul 04, 2012, 06:49 pm

Here's my contribution, a collection of common beginner trouble spots: http://www.cprogramming.com/tutorial/common.html

In section 5 of your link, it says that you have to declare the functions first. Why don't I have to do that in Arduino?
Title: Re: Read this before posting a programming question ...
Post by: AWOL on Jul 04, 2012, 06:51 pm
Because the Arduino pre-preprocessing does it for you, most of the time.
Sometimes, like functions with references as parameters, it doesn't work too well.
Title: Re: Read this before posting a programming question ...
Post by: dkl65 on Jul 04, 2012, 09:46 pm

Sometimes, like functions with references as parameters, it doesn't work too well.

I once did this:
Code: [Select]

void timer(unsigned long interval, void (*g)()){
  //...
}

and got compiler errors unless I write the function before it is used.
Title: Re: Read this before posting a programming question ...
Post by: pothos on Jul 26, 2012, 03:19 am
You may also point to this collection of libs: http://arduino.cc/playground/Main/LibraryList (http://arduino.cc/playground/Main/LibraryList)
Title: Re: Read this before posting a programming question ...
Post by: Coding Badly on Aug 06, 2012, 04:11 am
Quote
Post your code!


Please change that to "Post your complete sketch!"  Too many people post snippets of code that have nothing to do with the actual problem.
Title: Re: Read this before posting a programming question ...
Post by: nickgammon on Aug 06, 2012, 05:20 am
Done. I added a clarification that a sketch is a program/code.