The 4 basic sections of an Arduino sketch

When using the Arduino IDE to program Arduino or Arduino-like microcontrollers, there are 4 basic sections that each sketch should have.

Table of contents

Introduction to the sections of an Arduino sketch

In order to get a better understanding of coding ‘sketches’ for the Arduino development boards, a good starting point is to know the basic sections of sketches. These sections are the comment section, the variables section, the setup section and the loop section.

For explanatory purposes, Arduino Blink.iso and a basic Wi-Fi connection sketch for the ESP8288 will be used:

/*
  Blink

  Turns an LED on for one second, then off for one second, repeatedly.

  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.
  If you want to know what pin the on-board LED is connected to on your Arduino
  model, check the Technical Specs of your board at:
  https://www.arduino.cc/en/Main/Products

  modified 8 May 2014 by Scott Fitzgerald
  modified 2 Sep 2016 by Arturo Guadalupi
  modified 8 Sep 2016 by Colby Newman

  This example code is in the public domain.

  https://www.arduino.cc/en/Tutorial/BuiltInExamples/Blink
*/

// the setup function runs once when you press reset or power the board
void setup() {
  // initialize digital pin LED_BUILTIN as an output.
  pinMode(LED_BUILTIN, OUTPUT);
}

// the loop function runs over and over again forever
void loop() {
  digitalWrite(LED_BUILTIN, HIGH);  // turn the LED on (HIGH is the voltage level)
  delay(1000);                      // wait for a second
  digitalWrite(LED_BUILTIN, LOW);   // turn the LED off by making the voltage LOW
  delay(1000);                      // wait for a second
}

Blink.ino is probably the most often used Arduino sketch today.

#include <ESP8266WiFi.h>

void setup()
{
  Serial.begin(115200);
  Serial.println();

  WiFi.begin("network-name", "pass-to-network");

  Serial.print("Connecting");
  while (WiFi.status() != WL_CONNECTED)
  {
    delay(500);
    Serial.print(".");
  }
  Serial.println();

  Serial.print("Connected, IP address: ");
  Serial.println(WiFi.localIP());
}

void loop() {}

A basic version of the ESP8266 Wi-Fi connection sketch. This sketch uses third-party libraries to be able to program ESP8266 and other microcontrollers with Wi-Fi functionality.

The comment section

After opening almost any sketch file, the first thing you’ll see is the comment section. This is also a good place where coders can start to plan and keep track of their sketches.

This section is basically a text area, enclosed in /* and */. The information in the code comment section can contain any non-code lines and usually include things such as the description and/or function of the sketch, the version, details, how to configure the sketch and author attribution. Comment sections are not encoded into the uploaded version of sketches.

Looking at Blink.ino, it has a very comprehensive comment section. This makes it easy to identify the features and track changes.

/*
  Blink

  Turns an LED on for one second, then off for one second, repeatedly.

  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.
  If you want to know what pin the on-board LED is connected to on your Arduino
  model, check the Technical Specs of your board at:
  https://www.arduino.cc/en/Main/Products

  modified 8 May 2014 by Scott Fitzgerald
  modified 2 Sep 2016 by Arturo Guadalupi
  modified 8 Sep 2016 by Colby Newman

  This example code is in the public domain.

  https://www.arduino.cc/en/Tutorial/BuiltInExamples/Blink
*/

Because the ESP8266 Wi-Fi connection sketch was copied as an example code, it does not contain a comment section, but this doesn’t mean you cannot add your own comments.

For me, apart from a comprehensive date and description, important details include URL information from where the sketch/code was obtained from.

The variables section

The variables section comes before the setup section (see later) and can either be used to declare variables (i.e. #define) and/or to import libraries (e.g. #include).

Blink.ino has LED to the value of 13:

#define LED 13 // define connection of LED, in this case GPIO13

This means that LED will have a value of 13 and until it is changed later in the code. This makes it easy to use ‘LED’ each time 13 needs to be used.

Libraries are a collection of code that contain additional functions to be used in sketches. The Arduino IDE has all its related functions built into its own libraries, but additional (third-party) libraries can also be installed. To be able to use an installed library, it needs to be imported into the sketch.

Blink.ino needs no additional libraries, but the ESP8266 Wi-Fi connection sketch makes use of the Wi-Fi library for ESP8266. After its installation, a library is imported using its name and #include.

#include <ESP8266WiFi.h>

The best place to add the variables section is the uppermost code section of the sketch, i.e. just before or just after the comment section. If needs be, and memory allows, multiple variables and libraries can be declared/imported per sketch — where they are simply listed sequentially, each in its own line.

The setup section

The setup section of a sketch comes after the variables section and/or after the comment section. Whereas the previous two sections were optional, the setup section (and the loop section) is mandatory, even if it doesn’t contain any code.

This is where the sketch starts and is used to place all the startup tasks and define variables. As suppose to the loop section (see later), the setup section is only called once.

In the Arduino IDE, the setup section is defined using a special function called void setup(). Its content is encapsulated by { and }. Both Blink.ino and the ESP8266 Wi-Fi connection sketch have a setup section defined:

// the setup function runs once when you press reset or power the board
void setup() {
  // initialize digital pin LED_BUILTIN as an output.
  pinMode(LED_BUILTIN, OUTPUT);
}

void setup()
{
  Serial.begin(115200);
  Serial.println();

  WiFi.begin("network-name", "pass-to-network");

  Serial.print("Connecting");
  while (WiFi.status() != WL_CONNECTED)
  {
    delay(500);
    Serial.print(".");
  }
  Serial.println();

  Serial.print("Connected, IP address: ");
  Serial.println(WiFi.localIP());
}

The loop section

The last section of an Arduino sketch is the loop section. This is where all the actual task(s) of the microcontroller is defined and executed. As long as the microcontroller has sufficient power, the loop section will run over and over.

As with the setup section, the loop section is also defined by a special function (void setup()) with { and } encapsulating the code.

As this section is also mandatory, both Blink.ino and the ESP8266 Wi-Fi connection sketch have a loop setup section defined – even though it is not always used.

// the loop function runs over and over again forever
void loop() {
  digitalWrite(LED_BUILTIN, HIGH);   // turn the LED on (HIGH is the voltage level)
  delay(1000);                       // wait for a second
  digitalWrite(LED_BUILTIN, LOW);    // turn the LED off by making the voltage LOW
  delay(1000);                       // wait for a second
}
void loop() {}

Conclusion

Arduino sketches are divided into 4 important sections. By knowing these sections one can get a better understanding of how sketches work. These sections are the comment section, the variables section, the setup section and the loop section.