NAME¶
arduino - Integrated development environment for Arduino
boards
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¶
The arduino integrated development environment allows
editing, compiling and uploading sketches (programs) for Arduino (and
compatible) microcontroller boards.
Normally, running the arduino command starts the IDE, optionally
loading any .ino files specified on the commandline.
Alternatively, if any of the following command line options is
given, no graphical interface will be shown and 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.
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.
Note that on MacOS X, the main executable is
Arduino.app/Contents/MacOS/Arduino instead of arduino.
Note that 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.
ACTIONS
--verify
Build the sketch.
--upload
Build and upload the sketch.
--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 (see EXIT STATUS below). If no preference is given as parameter,
it prints all preferences.
--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.
--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.
--version
Print the version information and exit.
OPTIONS¶
--board
package:arch:board[:parameters]
Select the board to compile for.
•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).
--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).
--verbose-build
Enable verbose mode during build. If this option is not
given, verbose mode during build is disabled regardless of the current
preferences.
--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.
--useprogrammer
Upload using a programmer. Set if you’re using an
external programmer, or using the Arduino as ISP.
--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.
-v, --verbose
Enable verbose mode during build and upload. This option
has the same effect of using both --verbose-build and
--verbose-upload.
This option is only valid together with --verify
or --upload.
--preferences-file filename
Read and store preferences from the specified
filename instead of the default one.
--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.
--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.
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.
sketchbook.path
The path where sketches are (usually) stored. This path
can also contain some special subdirectories (see FILES below).
update.check
When set to true, the IDE checks for a new version on
startup.
editor.external
When set to true, use an external editor (the IDE does
not allow editing and reloads each file before verifying).
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.
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.
EXIT STATUS¶
0
Success
1
Build failed or upload failed
2
Sketch not found
3
Invalid (argument for) commandline option
4
Preference passed to --get-pref does not
exist
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.
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¶
1.5.2
Added initial commandline support. This introduced
--verify, --upload, --board, --port,
--verbose and -v.
1.5.5
Added support for board-specific parameters to
--board.
Sketch filenames are now interpreted relative to the
current directory instead of the location of the arduino command itself.
1.5.6
Introduced --pref, --preferences-file,
--verbose-build and --verbose-upload.
Preferences set through --pref are remembered,
preferences set through --board, --port or the --verbose
options are not.
When running with --verify or --upload, the
full GUI is no longer shown. Error messages still use a graphical popup and on
Windows, the splash screen is still shown.
1.5.8
Introduced --save-prefs.
1.6.2
Main executable in MacOS X changed from
Arduino.app/Contents/MacOS/JavaApplicationStub to
Arduino.app/Contents/MacOS/Arduino.
1.6.4
Introduced --install-boards and
--install-library.
--pref options are now not saved to the
preferences file, just like --board and --port, unless
--save-prefs is specified.
A path passed to --preferences-file, or set in the
build.path, preferences.path or settings.path is now
interpreted relative to the current directory instead of the location of the
arduino command itself.
