Introduction to Arduino IDE: Your First Programming Environment

Arduino IDE 2.x interface layout:

┌──────────────────────────────────────────────────────────────────┐
│  [File] [Edit] [Sketch] [Tools] [Help]          Menubar          │
├──────────────────────────────────────────────────────────────────┤
│  [✓ Verify] [→ Upload] [Debug] [Serial Monitor]   Toolbar       │
│                                                                  │
│  Board: Arduino Uno   Port: /dev/ttyACM0          Status bar    │
├──────┬───────────────────────────────────────────────────────────┤
│      │                                                           │
│ File │  void setup() {                    ←── Code editor       │
│  Ex. │    pinMode(13, OUTPUT);                                   │
│  Lib │  }                                                        │
│      │                                                           │
│      │  void loop() {                                            │
│      │    digitalWrite(13, HIGH);                                │
│      │    delay(1000);                                           │
│      │    digitalWrite(13, LOW);                                 │
│      │    delay(1000);                                           │
│      │  }                                                        │
│      │                                                           │
├──────┴───────────────────────────────────────────────────────────┤
│  Output / Error panel                                            │
│  Sketch uses 924 bytes (2%) of program storage space.           │
│  Global variables use 9 bytes (0%) of dynamic memory.           │
└──────────────────────────────────────────────────────────────────┘

void setup() {
  // Runs ONCE when the board is powered on or reset
  // Use for: pin mode configuration, Serial.begin(), library initialization,
  //           moving servos to starting positions, calibration routines
}

void loop() {
  // Runs CONTINUOUSLY after setup() completes
  // Repeats from top to bottom, then immediately restarts from top
  // Use for: reading sensors, making decisions, controlling actuators,
  //           sending data over Serial, updating display
}

Power on / Reset
      ↓
  [C runtime initialization — global variables set to zero/initial values]
      ↓
  [Arduino framework init — timer setup, interrupt configuration, USB serial]
      ↓
  setup()  ← runs once
      ↓
  ┌── loop()  ← runs
  │     ↓
  │   [return from loop()]
  └─── loop()  ← immediately called again
  ↑         (no delay between loop() calls unless you add one)
  └── forever

// GLOBAL variable — declared outside any function
// Lives for entire program duration (allocated in SRAM at startup)
int globalCounter = 0;     // Accessible from all functions
float lastSensorReading;   // Be careful: 6 floats × 4 bytes = 24 bytes of permanent SRAM

void setup() {
  // LOCAL variable — declared inside a function
  // Created when function is entered, destroyed when it exits
  int setupVar = 42;  // Only visible inside setup()
  // setupVar ceases to exist when setup() returns
}

void loop() {
  // Local variable in loop — re-created every loop iteration
  int loopTemp = analogRead(A0);  // Fresh every iteration — previous value lost

  // STATIC local variable — persists between calls but scoped to function
  static int callCount = 0;  // Initialized once, retains value between loop() calls
  callCount++;
}

Compilation pipeline:

1. PREPROCESSING
   Source: your_sketch.ino
   Tool: avr-gcc preprocessor
   Process: - Expands #include directives (inserts header files)
            - Expands #define macros
            - Removes comments
            - Adds Arduino-specific header: #include <Arduino.h>
            - Generates function prototypes automatically (so you can
              define functions below where they're called)
   Output: preprocessed_source.cpp

2. COMPILATION
   Source: preprocessed_source.cpp + all included .cpp files
   Tool: avr-g++ (C++ compiler for AVR architecture)
   Process: - Parses C++ syntax
            - Checks types, function signatures, scope
            - Optimizes code (removes dead code, inlines small functions)
            - Generates AVR assembly instructions
   Output: object files (.o) for each .cpp file

3. LINKING
   Source: all .o files + Arduino core library .o files
   Tool: avr-ld (linker)
   Process: - Resolves cross-file function references
            - Places code sections in correct memory regions
              (Flash for program code, SRAM for variables)
            - Generates the final executable with exact memory layout
   Output: your_sketch.elf (executable with debug symbols)

4. CONVERSION
   Tool: avr-objcopy
   Process: Strips debug symbols, converts to uploadable format
   Output: your_sketch.hex (Intel HEX format — human-readable hex)

5. UPLOAD
   Tool: avrdude (for classic Arduino boards)
   Process: - Resets the board (via DTR pin toggle on USB)
            - Bootloader on board receives hex over Serial/USB
            - Bootloader writes hex to Flash memory
            - Board resets, new program begins running
   Output: "Done uploading." in IDE status bar

// WRONG: optimizer may keep ledState in a register, never re-reading from SRAM
bool ledState = false;
void myISR() { ledState = !ledState; }

// CORRECT: volatile tells compiler "this variable can change outside normal flow"
volatile bool ledState = false;
void myISR() { ledState = !ledState; }

Serial Monitor flow:

Arduino sketch         USB cable         Serial Monitor
     │                                        │
     │  Serial.println("Sensor: 423")  →      │  displays: "Sensor: 423"
     │                                        │
     │         ← "r\n" (you typed 'r')        │  you type 'r', press Send
     │                                        │
     │  if (Serial.available()) {             │
     │    char c = Serial.read();  // = 'r'   │
     │    // handle 'r' command               │
     │  }                                     │

void setup() {
  Serial.begin(9600);   // 9600 baud — visible in Serial Monitor at 9600 baud
  // OR
  Serial.begin(115200); // 115200 baud — faster, better for high-frequency data
  // The two are NOT interchangeable — match them or you'll see garbage characters
}

// Serial.print() — print without newline
Serial.print("Distance: ");    // Text
Serial.print(42);              // Integer
Serial.print(3.14159, 4);      // Float with 4 decimal places: "3.1416"
Serial.print(0b11010101, BIN); // Binary representation: "11010101"
Serial.print(255, HEX);        // Hexadecimal: "FF"

// Serial.println() — print with newline (carriage return + line feed)
Serial.println("Hello!");      // "Hello!\r\n" — starts new line in monitor

// Serial.print() + Serial.println() pattern for labeled values:
Serial.print("Left: ");        // "Left: "
Serial.print(brightLeft);      // "Left: 423"
Serial.print("  Right: ");     // "Left: 423  Right: "
Serial.println(brightRight);   // "Left: 423  Right: 371\r\n" (new line)

// Efficient pattern for multiple variables on one line:
// CSV format — can be pasted into spreadsheet or plotted
Serial.print(millis());  Serial.print(",");
Serial.print(sensorA);  Serial.print(",");
Serial.print(sensorB);  Serial.print(",");
Serial.println(motorSpeed);
// Output: "1523,423,371,180"

// Reading a single character command
void loop() {
  if (Serial.available() > 0) {
    char cmd = Serial.read();   // Read one byte
    Serial.print(F("Received: "));
    Serial.println(cmd);

    switch (cmd) {
      case 'f': driveForward(150);  break;
      case 's': stopMotors();       break;
      case '1': Serial.println(analogRead(A0)); break;
    }
  }
}

// Reading a complete line (newline-terminated string)
void loop() {
  if (Serial.available() > 0) {
    String line = Serial.readStringUntil('\n');
    line.trim();  // Remove trailing whitespace/CR
    Serial.print(F("Command: "));
    Serial.println(line);
    processCommand(line);
  }
}

// Serial Plotter format: comma-separated values, one set per line
// Labels in the format "Label:Value" are supported in IDE 2.x

void loop() {
  int sensorLeft  = analogRead(A0);
  int sensorRight = analogRead(A1);
  float battVolt  = analogRead(A2) * (5.0 / 1023.0) / 0.319;

  // IDE 2.x labeled format:
  Serial.print("Left:");    Serial.print(sensorLeft);
  Serial.print(",Right:");  Serial.print(sensorRight);
  Serial.print(",Battery:"); Serial.println(battVolt * 10);  // Scale for visibility

  delay(50);  // 20 Hz update rate — faster than display refresh is unnecessary
}

A library installed in ~/Arduino/libraries/ServoLibrary/:

ServoLibrary/
├── src/
│   ├── Servo.h      ← Header: declares classes, functions, constants
│   └── Servo.cpp    ← Implementation: defines the actual code
├── examples/
│   ├── Sweep/
│   │   └── Sweep.ino ← Example sketches showing how to use the library
│   └── Knob/
│       └── Knob.ino
├── library.properties  ← Name, version, author, dependencies
└── keywords.txt        ← Words to highlight in the IDE editor

// Include a library by its header file name
#include <Servo.h>      // Servo library (built into Arduino)
#include <Wire.h>       // I2C communication (built into Arduino)
#include <EEPROM.h>     // EEPROM read/write (built into Arduino)
#include <AccelStepper.h>  // Third-party: install via Library Manager first

// After including: all classes and functions from the library are available
Servo myServo;            // Create a Servo object (defined in Servo.h)
myServo.attach(9);        // Use a method from the Servo class
myServo.write(90);

Built-in Arduino libraries:
  Servo          — Hobby servo PWM control
  Wire           — I2C (two-wire interface) communication
  SPI            — SPI (four-wire interface) communication
  EEPROM         — Read/write microcontroller EEPROM
  SD             — SD card file read/write (requires SD module)
  LiquidCrystal  — HD44780-compatible LCD displays
  Ethernet       — Ethernet shield networking
  WiFi           — WiFi shields (classic; use WiFi libraries for ESP32)
  Stepper        — Basic stepper motor control (AccelStepper is better)
  HardwareSerial — Accessed as Serial, Serial1, etc. (Mega boards)

Error message:
  sketch_name:14:3: error: expected ';' before 'digitalWrite'

Translation:
  In your sketch file, at line 14, column 3:
  The compiler expected a semicolon but found 'digitalWrite'.
  Look at line 13 — the previous statement is missing its semicolon.

Example:
  Line 13: digitalWrite(13, HIGH)   ← missing semicolon here
  Line 14: delay(1000);             ← error reported here (compiler lost context)

Error message:
  sketch_name:23:5: error: 'motorSpeed' was not declared in this scope

Translation:
  At line 23, 'motorSpeed' is used but was never declared with a type.
  Either: you misspelled it (check case: 'motorSpeed' ≠ 'MotorSpeed'),
  or you forgot to declare it (add: int motorSpeed = 0; before use),
  or it's declared inside a different function than where it's used.

Error message:
  sketch_name:31:20: error: invalid conversion from 'float' to 'int'

Translation:
  At line 31, you're trying to assign a float to an int variable (or
  pass a float to a function that expects int) without explicit casting.

Fix:
  int pinNumber = 3.5;          // Error: float → int implicit
  int pinNumber = (int)3.5;     // OK: explicit cast → pinNumber = 3
  int pinNumber = round(3.5);   // OK: round → pinNumber = 4

Error message:
  sketch_name:1:10: fatal error: AccelStepper.h: No such file or directory

Translation:
  The included library header doesn't exist on this computer.
  The library is not installed.

Fix: Open Library Manager, search "AccelStepper", install it.

Error message:
  sketch_name:12:5: error: 'driveForward' was not declared in this scope

Translation:
  The function 'driveForward' is used at line 12 but isn't declared yet.
  In standard C++, functions must be declared before use.
  Arduino's preprocessor auto-generates prototypes for .ino files,
  but sometimes fails for complex function signatures.

Fix: Add a function prototype before setup():
  void driveForward(int speed);  // Prototype

Or: Move the function definition above setup() in the file.

Strategy for compiler error lists:
  1. Read the first error only
  2. Note: filename, line number, column, error text
  3. Go to that line in the editor
  4. Fix the issue
  5. Recompile — many subsequent errors will disappear
  6. Repeat with the new first error

Common board packages to install:

Board                     Package name in Board Manager
─────────────────────────────────────────────────────────────────
Arduino Mega, Nano, Uno   Arduino AVR Boards (included by default)
Arduino Due               Arduino SAM Boards
Arduino Zero, MKR series  Arduino SAMD Boards
ESP32 boards              esp32 by Espressif Systems
ESP8266 boards            esp8266 by ESP8266 Community
RP2040 / Raspberry Pi Pico  Raspberry Pi Pico/RP2040 by Earle Philhower
Teensy                    Teensyduino (separate installer at pjrc.com)

Installing a board package:
  Tools → Board → Boards Manager
  Search for the package name above
  Install (may require adding additional URLs in Preferences first)
  
  Example: ESP32 requires adding this URL to Additional Boards Manager URLs:
  https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json

Port naming conventions:

Windows:
  COM1–COM256 (e.g., COM3, COM7)
  Arduino Uno typically appears as COM3–COM10
  Check Device Manager → Ports (COM & LPT) if unsure which port

macOS:
  /dev/cu.usbmodem... (e.g., /dev/cu.usbmodem14201)
  /dev/cu.SLAB_USBtoUART (for CP2102-based boards like some ESP32)
  Multiple ports may appear — choose the one with "usbmodem" or the board name

Linux:
  /dev/ttyACM0 (Arduino Uno, Mega — CDC ACM USB serial)
  /dev/ttyUSB0 (ESP32, NodeMCU, boards with CH340 USB-serial chip)
  If port not visible: add user to 'dialout' group:
    sudo usermod -aG dialout $USER  (then log out and back in)

General rule: unplug the board, check available ports, plug it back in,
  see which new port appears — that's your board's port.

Feature comparison:

Feature                    IDE 1.8.x          IDE 2.x
────────────────────────────────────────────────────────────────────────
Interface framework        Java/Processing    Electron (web-based)
Startup time               ~3–5 sec           ~5–10 sec (heavier)
Autocompletion             None               Yes — function/method suggestions
Error highlighting         After compile      Real-time (underlines errors as you type)
Compilation cache          Limited            Full incremental caching (much faster)
Hardware debugger          No                 Yes (supported boards only)
Serial Monitor style       Separate window    Integrated panel at bottom
Serial Plotter             Separate window    Integrated panel
Board/Library managers     Separate windows   Integrated sidebar panels
Dark mode                  Limited            Full dark mode support
Multiple sketches          Multiple windows   Tabbed interface
Offline library docs       No                 Limited
Resource usage             Low (~200MB RAM)   Higher (~400–600MB RAM)

Recommendation:
  IDE 2.x for all new users — better experience, same hardware compatibility
  IDE 1.8.x if running on a very old computer (< 4GB RAM)

Essential Arduino IDE keyboard shortcuts:

Action                     Windows/Linux        macOS
─────────────────────────────────────────────────────────────────
Verify (compile)           Ctrl+R              Cmd+R
Upload                     Ctrl+U              Cmd+U
Open Serial Monitor        Ctrl+Shift+M        Cmd+Shift+M
Auto-format code           Ctrl+T              Cmd+T
Find and Replace           Ctrl+H              Cmd+H
Comment/uncomment line     Ctrl+/              Cmd+/
New sketch                 Ctrl+N              Cmd+N
Open sketch                Ctrl+O              Cmd+O
Save                       Ctrl+S              Cmd+S
Increase font size         Ctrl++              Cmd++
Go to line                 Ctrl+G              Cmd+G

Sketch folder structure with multiple files:

my_robot_sketch/
├── my_robot_sketch.ino   ← Main file: setup(), loop()
├── motor_control.ino     ← Motor functions: driveForward(), turnLeft(), etc.
├── sensor_reading.ino    ← Sensor functions: measureDistance(), readBrightness()
└── pid_control.ino       ← PID controller: computeCorrection(), resetPID()

// PIDController.h — header file: declares the class interface

#ifndef PID_CONTROLLER_H   // Include guard: prevents double inclusion
#define PID_CONTROLLER_H

class PIDController {
public:
  PIDController(float kp, float ki, float kd);
  void reset();
  float compute(float error, float dt);

private:
  float _kp, _ki, _kd;
  float _integral;
  float _lastError;
};

#endif

// PIDController.cpp — source file: implements the class

#include "PIDController.h"

PIDController::PIDController(float kp, float ki, float kd)
  : _kp(kp), _ki(ki), _kd(kd), _integral(0), _lastError(0) {}

void PIDController::reset() {
  _integral = 0;
  _lastError = 0;
}

float PIDController::compute(float error, float dt) {
  _integral += error * dt;
  _integral = constrain(_integral, -500, 500);
  float derivative = (error - _lastError) / dt;
  _lastError = error;
  return _kp * error + _ki * _integral + _kd * derivative;
}

// In your main .ino file:
#include "PIDController.h"

PIDController linePID(0.25, 0.001, 0.8);

void loop() {
  float error = computePosition();
  float correction = linePID.compute(error, dt);
  // apply correction to motors...
}

Key example categories to explore:

01. Basics
  └── Blink        — The simplest possible sketch (LED on/off)
  └── AnalogRead   — Reading a potentiometer (the ADC in practice)
  └── DigitalRead  — Reading a button
  └── Fade         — PWM LED dimming with analogWrite()

02. Digital
  └── Debounce     — Button debouncing with millis() (covered in article 66)
  └── StateChange  — Detecting button press events (not just state)

03. Analog
  └── Smoothing    — Running average for noisy sensor readings

04. Communication
  └── SerialEvent  — Event-driven serial reading (not blocking)
  └── Graph        — Serial Plotter usage

05. Sensors
  └── Various ultrasonic, light, temperature examples

Library examples (appear under Examples → Library Name):
  Servo → Sweep    — Basic servo position control
  Servo → Knob     — Potentiometer-controlled servo (article 78 basis)
  Wire  → master_reader — I2C communication between two Arduinos
  EEPROM → eeprom_read   — Reading/writing EEPROM (article 72 basis)

void loop() {
  float distance = measureDistance();
  Serial.print(F("Distance: ")); Serial.println(distance, 1);

  if (distance < 20.0) {
    Serial.println(F("Would avoid obstacle"));
    // driveBackward(150);  ← commented out during testing
    // delay(500);
  } else {
    Serial.println(F("Would drive forward"));
    // driveForward(150);   ← commented out during testing
  }
  delay(200);
}

// Read three samples and average to reduce HC-SR04 noise
// Each measureDistance() call takes ~30ms (limited by 60ms sensor cycle / 2)
float getSmoothedDistance() {
  long sum = 0;
  for (int i = 0; i < 3; i++) {
    sum += measureDistance();
    delay(30);  // 30ms between reads — prevents echo interference
  }
  return sum / 3.0;
}

my_rover_v1.ino          ← working basic version
my_rover_v2_pid.ino      ← PID control added (may break things)
my_rover_v3_sensors.ino  ← three sensors added