Purpose:
This is a section by section discussion/explanation of what the MyBlink sketch/code is doing.
Big Picture:
A helpful perspective to have is that the sketch (program) has to be translated into a more basic set of commands that the microprocessor on the UNO can understand. This translation process is called compiling. The machine code that the microprocessor actually understands in not easy to read and understand (except by wizards) so we write code in 'higher level' languages that look more like everyday language. The language used by the Arduino IDE is a version of the programming language called C.
Comments:
An important feature of all science is the need to communicate clearly what we are doing. What we hear all the time is that we will change jobs multiple times over our work careers which means that someone else will very likely be trying to make sense of any documentation we create for our current employer. Computer code is just another product but the same could be said of an Excel spreadsheet that you use and modify as part of your work. In all cases writing clear comments in your document that explain what is going on are very helpful to the next person looking at the document.
In sketches that we create for our Arduino there are two ways to indicate that you are making a comment that should be ignored by the Arduino. Both are evident near the begining of the MyBlink code.
/* */ : Any text which is in between these two symbols is considered a comment and is ignored by the compiler (translator). I, and most who work with the IDE use these symbols to create a robust description of what the sketch is intended to do as well as any references or core concepts that may be of interest to some future user. This method of indicating a comment is more commonly used for large blocks of writing.
// : For single lines or shorter comments the '//' notation is typically used. Any text that follows a '//' on a single line is also ignored by the compiler. Be careful -- as soon as a new line is started the compiler is paying attention again. See if you can find examples of the commenting process in the code below.
/*
MyBlinkTurns an LED on for one second, then off for one second, repeatedly.
This version of Blink allows the user to make an arbitrary pin to 'blink'
Most Arduinos have an on-board LED you can control. On the UNO, MEGA and ZERO
it is attached to digital pin 13, on MKR1000 on pin 6. LED_BUILTIN is set to
the correct LED pin independent of which board is used.For the purpose of this version of Blink you can choose which pin you wish to
use to 'blink' and LED. To chose a new pin merely change the pin number after
int testPin = 13;
to whatever pin you would like to use. You can change the timing of the blinks
just as you did with the original Blink sketch.
modified 8 May 2014
by Scott Fitzgerald
modified 2 Sep 2016
by Arturo Guadalupi
modified 8 Sep 2016
by Colby Newman
modified 6/15/20
by Bruce Emerson*/
//Define the pin I'm testing with this sketch
int testPin = 13;
// the setup function runs once when you press reset or power the board
void setup() {
Before we move on to the next section I would point out that the tradition is to add your name to the bottom of the list of those who have modified this code. I am not going to insist but recognize that this is both a way of knowing who to ask if you have questions and a way of showing respect for those who have come before and from whose work you are benefitting.
Definitions: After the comments there is section of the sketch before the void setup(); section that can be used to define useful variables. The Arduino world has a gentle convention that variable names use camelCase (never heard of it before now) which does help our eye see the two words without using other forms of spacing. The polite thing to do with your variable names is to make them clearly descriptive. This makes your code more readable to others. There is only one such variable in this sketch but there will be many more in future sketches
The line below has this form
int [variable name] = [value];
The 'int' tells the IDE that the value you are assigning to that variable is an integer. If you set the variable equal to some decimal value the IDE will cut off the decimals (mathematicians call this truncating the value) and just save the whole number. Another choice which we will meet later is called 'float' for floating point (decimal numbers)
NOTE: Every line (statement) terminates with a ';'. This is an important detail that tells the IDE when you are done with that statement. Try leaving this off and see what the IDE spits up at you for an error. This is one of the more irritating mistakes we all make while writing sketches for the Arduino.
//Define the pin I'm testing with this sketch
int testPin = 13;
Getting things started: As we develop our experience with the Arduino/Qbot we will find that there are some particular steps that need to be taken only once when we start the program/sketch running. These commands are best placed in the setup() { } section.
void setup() {
}
Notice a couple of things. There is no ';' at the end of the first line. That's because the setup() function tells the IDE to do everything between the { } before it is done with this command. If we put an ';' after the first '{' it tells the IDE that thats the end of the actions it should take. For readability the left bracket '{' is usually right after the command and the right bracket '}' is on it's own line after the last statement within the brackets.
void: What is this 'void' thing up above? We're going to keep it simple at the moment merely note that setup() is a function. A function is a single name for a collection of actions that you wish to do. I have no idea what those actions are (haven't found a good reference yet). Many times the function will give us back some information. In the case of the setup() function nothing is returned and the void statement lets the compiler know that nothing is coming back from the function.
pinMode();: pinMode is a function (a special command) that tells the IDE whether a pin is going to be used as an OUTPUT pin to control some external object or as an INPUT that brings information in from the outside world. For our LEDs we want to control their behavior through the pin. The on board LED's for most Arduino varieties are connected to pin 13. This is the general format of the pinMode function (note the ; at the end). The link at the beginning of this paragraph takes you to the Arduino manual description of the pinMode() function. When you have a moment take the time to read and see how much of it you understand.
pinMode([which pin], [OUTPUT or INPUT]);
// the setup function runs once when you press reset or power the board
void setup() {
// initialize the testPin as an output.pinMode(testPin, OUTPUT);
}
Arduino Pins: If you look at your Arduino there are many numbered pins on each side of the board. On an UNO there are 14 (0-13) pins on one side and 6 (A0 - A5) on the other side. This is why we have to let the Arduino know what we want it to do. Some of the pins have different possible behaviors which is why they have different symbols and names. We will explore these in time as we need to. For now just be aware that there are many choices.
The Main Feature (the loop): The loop(){ } is the part of the sketch that runs over and over until you turn the power off. The structure of the loop() function is essentially the same as the setup() function.
void loop() {
}
Again, there is not ';' at the end of the line because the IDE needs to consider everything from the '{' to the '}' as part of what the loop is asking it to do.
digitalWrite(); In this part of the sketch there are really only two functions we need to talk about. digitalWrite() and delay(). We'll start with digitalWrite().
digitalWrite([which pin], [HIGH or LOW]);
We use digitalWrite() when we want the pin to switch on and off very much like a basic light switch. As we get deeper into this we will learn that on (HIGH) holds the pin at 5V and off (LOW) holds it at close to 0V. Notice that when you type HIGH or LOW into the IDE it recognizes that these are special words and makes them a particular color. Notice that the IDE also recognized digitalWrite() as an function that it already knows. [which pin] tells the IDE which pin I'm switching and [HIGH or LOW] tells the IDE I want it On (HIGH) or Off (LOW). When you look below in the code I'm using off/on switches to tell the LED whether to turn on or turn off and these are the only choices I need at this time.
delay();: delay is a function which tells the Arduino to wait for a certain number of milliseconds before moving on to the next operation. It is NOT a very efficient way to do timing in more complex settings but is conceptually clear and simple for us. I chose to delay for 1 s (1000 ms) after I turn the LED on and a further delay of 1 s (1000 ms) after I turn the LED off. A common first Arduino exercise for engineering students is to turn the light on and off to send an SOS signal.
// the loop function runs over and over again forever
void loop() {digitalWrite(testPin, HIGH); // turn the LED on (HIGH is the voltage level)
delay(100); // wait for some time in ms
digitalWrite(testPin, LOW); // turn the LED off by making the voltage LOW
delay(1000); // wait for some time in ms// You can turn the pin off and on in more complex patterns to mimic Morse code
// or other patterns of interest by adding more lines after the ones above.
}
Note the clear closure of the loop(){ function with the '}' at the very end on it's own line. Tracking whether you have closed a parenthesis or a bracket is a common aggravation and putting them on their own line helps enormously with visibility.
