mirror of
https://github.com/arduino/Arduino.git
synced 2024-12-10 21:24:12 +01:00
285 lines
9.3 KiB
Plaintext
285 lines
9.3 KiB
Plaintext
// Generate a manpage with: a2x -f manpage manpage.adoc
|
|
// or HTML with: a2x -f xhtml manpage.adoc
|
|
//
|
|
// This file uses {empty}:: in some places, to allow putting multiple
|
|
// paragraphs inside a single label list item. This is a bit ugly and
|
|
// non-semantic, but it seems this is the best way to do this. Asciidoc
|
|
// also supports putting a plus sign on a line by itself to join two
|
|
// paragraphs into a single list item. However, the indentation on the
|
|
// second paragraph makes that formatted with a fixed-size font.
|
|
// Removing the indentation completely makes the asciidoc source very
|
|
// unreadable. Also, for the --board option, there is a a paragraph,
|
|
// followed by a list, followed by another paragraph. The + approach can
|
|
// only put the latter paragraph into the inner list, not the outer
|
|
// one...
|
|
|
|
ARDUINO(1)
|
|
==========
|
|
:doctype: manpage
|
|
|
|
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*] [__FILE.ino__]
|
|
|
|
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/JavaApplicationStub' instead of 'arduino'.
|
|
|
|
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.
|
|
|
|
{empty}::
|
|
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*).
|
|
|
|
{empty}::
|
|
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.
|
|
|
|
{empty}::
|
|
This option is only valid together with *--verify* or
|
|
*--upload*.
|
|
|
|
*--verbose-upload*::
|
|
Enable verbose mode during upload. If this option is not given,
|
|
verbose mode during upload is *disabled* regardless of the current
|
|
preferences.
|
|
|
|
{empty}::
|
|
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*.
|
|
|
|
{empty}::
|
|
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__.
|
|
|
|
{empty}::
|
|
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.
|
|
|
|
*--upload*::
|
|
Build and upload the sketch.
|
|
|
|
*--verify*::
|
|
Build 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).
|
|
|
|
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.
|
|
|
|
{empty}::
|
|
If set, this directory should already exist before running the
|
|
arduino command.
|
|
|
|
{empty}::
|
|
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
|
|
-----
|
|
*~/.arduino15/preferences.txt*::
|
|
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.
|
|
|
|
{empty}::
|
|
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
|
|
|
|
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*.
|
|
|
|
{empty}::
|
|
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*.
|
|
|
|
{empty}::
|
|
Preferences set through --pref are remembered, preferences set
|
|
through *--board*, *--port* or the *--verbose* options are not.
|
|
|
|
{empty}::
|
|
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*.
|
|
|
|
{empty}::
|
|
*--pref* options are now not saved to the preferences file, just
|
|
like *--board* and *--port*, unless *--save-prefs* is specified.
|
|
|
|
{empty}::
|
|
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.
|
|
|
|
|
|
RESOURCES
|
|
---------
|
|
Web site: <http://arduino.cc/>
|
|
|
|
Help on projects and programming: <http://forum.arduino.cc/>
|
|
|
|
Report bugs: <http://github.com/arduino/Arduino/issues>
|
|
|
|
IDE and framework development mailing list: <https://groups.google.com/a/arduino.cc/forum/#!forum/developers>
|