ARDUINO(1)

📦
version 1.8.19 · 5 versions
, in debian bookworm, ubuntu jammy

💖 ARDUINO 💖

okay bestie, welcome to the arduino(1) manual — this is the integrated development environment for Arduino boards, and yes she is THAT girl. sit down, get comfy, we're going through literally everything 🫶

🌸 SYNOPSIS 🌸

arduino [FILE.ino...]

arduino [--verify|--upload] [--board package:arch:board[:parameters]]
[--port portname] [--pref name=value] [-v|--verbose]
[--preserve-temp-files] [FILE.ino]

arduino [--get-pref [preference]]

arduino [--install-boards package name:platform architecture[:version]]

arduino [--install-library library name[:version][,library
name[:version],library name[:version]]

arduino [--version]

✨ DESCRIPTION ✨

so the arduino integrated development environment is the whole vibe for editing, compiling and uploading sketches (which is just a cute word for programs, iykyk) for Arduino and Arduino-compatible microcontroller boards. 💅

normally, running the arduino command just starts the IDE, optionally loading any .ino files you put on the commandline. classic.

but alternatively — and this is the part that eats — if any of the following command line options is given, no graphical interface will be shown. instead, a one-off verify (compile) or upload will be done. a single .ino file should be given. if the sketch contains multiple .ino files, any one can be specified on the commandline, but the entire sketch will be compiled. no half measures, periodt. 👑

when running in a one-off mode, it might be useful to set the build.path preference to allow keeping intermediate build results between multiple runs and only recompile the files that changed. lowkey a time-saver, fr fr.

note bestie: on MacOS X, the main executable is Arduino.app/Contents/MacOS/Arduino instead of arduino. she lives in a whole app bundle, iconic but also confusing.
also note: on Windows, due to the diffence between GUI and console apps, that the arduino_debug.exe is the appropriate executable to use if you want to use the majority of these command line options. the arduino.exe GUI version of the launcher may perform some of the functions described below, but will not output any messages to the console, meaning it is pretty useless if you want any feedback or to be able to keep log files for automated testing, etc. 💀 so use the debug one, trust.

🎀 ACTIONS 🎀

  • --verify — Build the sketch. just build. no upload, just vibes and compilation. 🛠️
  • --upload — Build and upload the sketch. build then yeet it onto the board. 🚀
  • --get-pref [preference] — Prints the value of the given preference to the standard output stream. when the value does not exist, nothing is printed and the exit status is set (go peek at EXIT STATUS below). if no preference is given as parameter, it prints all preferences. she's thorough. 💖
  • --install-boards package name:platform architecture[:version] — Fetches available board support (platform) list and install the specified one, along with its related tools. if version is omitted, the latest is installed. if a platform with the same version is already installed, nothing is installed and program exits with exit code 1. if a platform with a different version is already installed, it's replaced. out with the old. 💅
  • --install-library library name[:version] — Fetches available libraries list and install the specified one. if version is omitted, the latest is installed. if a library with the same version is already installed, nothing is installed and program exits with exit code 1. if a library with a different version is already installed, it's replaced. multiple libraries can be specified, separated by a comma. yes you can bring your friends. 🫶
  • --version — Print the version information and exit. short, sweet, slays.

👑 OPTIONS 👑

  • --board package:arch:board[:parameters] — Select the board to compile for. this one has lore, so buckle up:
    • package is the identifier of the vendor (the first level folders inside the hardware directory). default arduino boards use arduino.
    • architecture is the architecture of the board (second level folders inside the hardware directory). default arduino boards use either arduino:avr for all AVR-based boards (like Uno, Mega or Leonardo) or arduino:sam for 32bit SAM-based boards (like Arduino Due).
    • board is the actual board to use, as defined in boards.txt contained in the architecture folder selected. for example arduino:avr:uno for the Arduino Uno, arduino:avr:diecimila for the Arduino Duemilanove or Diecimila, or arduino:avr:mega for the Arduino Mega.
    • parameters is a comma-separated list of boards specific parameters that are normally shown under submenus of the "Tools" menu. for example arduino:avr:nano:cpu=atmega168 to Select the mega168 variant of the Arduino Nano board.

if this option is not passed, the value from the current preferences is used (e.g., the last board selected in the IDE). she remembers. 🧠

  • --port portname — Select the serial port to perform upload of the sketch. on linux and MacOS X, this should be the path to a device file (e.g., /dev/ttyACM0). on Windows, this should be the name of the serial port (e.g., COM3).

if this option is not passed, the value from the current preferences is used (e.g., the last port selected in the IDE). again, she remembers. 💖

  • --verbose-build — Enable verbose mode during build. if this option is not given, verbose mode during build is disabled regardless of the current preferences. no secrets here.
  • --preserve-temp-files — Keep temporary files (preprocessed sketch, object files...) after termination. if omitted, temporary files are deleted. 🗑️
this option is only valid together with --verify or --upload. don't try it solo, she won't answer.
  • --useprogrammer — Upload using a programmer. set if you're using an external programmer, or using the Arduino as ISP. main character external-tool energy. 🔌
  • --verbose-upload — Enable verbose mode during upload. if this option is not given, verbose mode during upload is disabled regardless of the current preferences.
this option is only valid together with --verify or --upload. bestie. read the room.
  • -v, --verbose — Enable verbose mode during build and upload. this option has the same effect of using both --verbose-build and --verbose-upload. two birds, one flag. 🦋
this option is only valid together with --verify or --upload. yes, again. it's a theme.
  • --preferences-file filename — Read and store preferences from the specified filename instead of the default one. pick your own file, be free. 🌈
  • --pref name=value — Sets the preference name to the given value.
⚠️ note that the preferences you set with this option are not validated: invalid names will be set but never used, invalid values might lead to an error later on. she's not checking your work, she's just writing it down. 💀
  • --save-prefs — Save any (changed) preferences to preferences.txt. in particular --board, --port, --pref, --verbose, --verbose-build and --verbose-upload may alter the current preferences. save your work bestie. 💾

🦋 PREFERENCES 🦋

Arduino keeps a list of preferences, as simple name and value pairs. below, a few of them are documented but a lot more are available. the lore goes deep, this is just the highlights.

  • sketchbook.path — The path where sketches are (usually) stored. this path can also contain some special subdirectories (go see FILES below).
  • update.check — When set to true, the IDE checks for a new version on startup. she's nosy about updates, honestly same.
  • editor.external — When set to true, use an external editor (the IDE does not allow editing and reloads each file before verifying). let her outsource the typing.
  • build.path — The path to use for building. this is where things like the preprocessed .cpp file, compiled .o files and the final .hex file go.

if set, this directory should already exist before running the arduino command. she will not create it for you. 🙈

if this preference is not set (which is normally the case), a new temporary build folder is created on every run and deleted again when the application is closed. ephemeral queen. ✨

💅 EXIT STATUS 💅

  • 0 — Success. ate and left no crumbs. 💖
  • 1 — Build failed or upload failed. it happens to the best of us. 😭
  • 2 — Sketch not found. she looked everywhere bestie.
  • 3 — Invalid (argument for) commandline option. that flag is not on the menu. 🚫
  • 4 — Preference passed to --get-pref does not exist. nothing to print, so she told you with a number instead.

🍓 FILES 🍓

  • %LOCALAPPDATA%/Arduino15/preferences.txt (Windows), ~/Library/Arduino15/preferences.txt (Max OS X), ~/.arduino15/preferences.txt (Linux)
    • This file stores the preferences used for the IDE, building and uploading sketches. her diary, basically. 📔
  • My Documents/Arduino/ (Windows), ~/Documents/Arduino/ (Mac OS X), ~/Arduino/ (Linux)
    • This directory is referred to as the "Sketchbook" and contains the user's sketches. the path can be changed through the sketchbook.path preference.

apart from sketches, three special directories can be inside the sketchbook:

  • libraries — Libraries can be put inside this directory, one library per subdirectory.
  • hardware — Support for third-party hardware can be added through this directory.
  • tools — External code-processing tools (that can be run through the Tools menu of the IDE) can be added here.

🌈 EXAMPLES 🌈

Start the Arduino IDE, with two files open:

arduino /path/to/sketch/sketch.ino /path/to/sketch/extra.ino

Compile and upload a sketch using the last selected board and serial port:

arduino --upload /path/to/sketch/sketch.ino

Compile and upload a sketch to an Arduino Nano, with an Atmega168 CPU, connected on port /dev/ttyACM0:

arduino --board arduino:avr:nano:cpu=atmega168 --port /dev/ttyACM0 --upload /path/to/sketch/sketch.ino

Compile a sketch, put the build results in the build directory an re-use any previous build results in that directory:

arduino --pref build.path=/path/to/sketch/build --verify /path/to/sketch/sketch.ino

Change the selected board and build path and do nothing else:

arduino --pref build.path=/path/to/sketch/build --board arduino:avr:uno --save-prefs

Install latest SAM board support:

arduino --install-boards "arduino:sam"

Install AVR board support, 1.6.2:

arduino --install-boards "arduino:avr:1.6.2"

Install Bridge library version 1.0.0:

arduino --install-library "Bridge:1.0.0"

Install Bridge and Servo libraries:

arduino --install-library "Bridge:1.0.0,Servo:1.2.0"

✨ HISTORY ✨

okay so let's take a lil trip down memory lane bestie, because this command line glow-up did not happen overnight 💅

1.5.2 🎀

this is when the command line first got its whole thing going ✨ it brought us --verify, --upload, --board, --port, --verbose and -v. iconic behavior tbh.

1.5.5 🦋

--board started accepting board-specific parameters, slay 💅 also, sketch filenames? they're now read relative to the current directory, not wherever the arduino command itself lives. no cap.

1.5.6 🌸

new besties arrived: --pref, --preferences-file, --verbose-build and --verbose-upload 🎀 here's the tea: prefs you set with --pref stick around, but prefs from --board, --port or the --verbose options? nope, not remembered. also when you run with --verify or --upload, the full GUI doesn't show up anymore. error messages still pop up graphically tho, and on Windows the splash screen is still there, so don't worry.

1.5.8 💖

--save-prefs said hi for the first time 🌈

1.6.2 👑

on MacOS X, the main executable moved from Arduino.app/Contents/MacOS/JavaApplicationStub to Arduino.app/Contents/MacOS/Arduino. glow up fr 💅

1.6.4 🔥

--install-boards and --install-library made their debut ✨ and big shift: --pref options are now not saved to the preferences file, just like --board and --port — unless you specifically say --save-prefs. also, a path you pass to --preferences-file, or set in build.path, preferences.path or settings.path, is now read relative to the current directory instead of where the arduino command itself is. periodt.

🌈 RESOURCES 🌈

need the links bestie? here you go 🫶

that's the whole page from ARDUINO(1), dated 12/27/2021 💖 stay slay, stay curious, and go make something cute with a microcontroller bestie ✨🦋

📦 where this page comes from