Sketch specification

This is the specification for Arduino sketches.

The programs that run on Arduino boards are called "sketches". This term was inherited from Processing, upon which the Arduino IDE and the core API were based.

Sketch folders and files

The sketch root folder name and code file names must start with a basic letter (

A

Z

a

z

0

9

_

.

-

.

Sketch root folder

Because many Arduino sketches only contain a single .ino file, it's easy to think of that file as the sketch. However, it is the folder that is the sketch. The reason is that sketches may consist of multiple code files and the folder is what groups those files into a single program.

Primary sketch file

Every sketch must contain a

.ino

.pde

.ino

Additional code files

Sketches may consist of multiple code files.

The following extensions are supported:

• .ino - Arduino language files.
• .pde - Alternate extension for Arduino language files. This file extension is also used by Processing sketches. .ino is recommended to avoid confusion.

  .pde

  extension is deprecated and will be removed in the future.
• .cpp - C++ files.
• .c - C Files.
• .S - Assembly language files.
• .h, .hpp, .hh ¹ - Header files.
• .tpp, .ipp ² - Header files.

For information about how each of these files and other parts of the sketch are used during compilation, see the Sketch build process documentation.

src

subfolder

The contents of the

src

This is useful for files you don't want to expose to the sketch user via the IDE's interface. It can be used to bundle libraries with the sketch in order to make it a self-contained project.

Arduino language files under the

src

• In Arduino IDE 1.6.5-r5 and older, no recursive compilation was done.
• In Arduino IDE 1.6.6 - 1.6.9, recursive compilation was done of all subfolders of the sketch folder.
• In Arduino IDE 1.6.10 and newer, recursive compilation is limited to the

  src

  subfolder of the sketch folder.

data

subfolder

The

data

Files added to the sketch via the Arduino IDE's Sketch > Add File... are placed in the

data

The Arduino IDE's File > Save As... only copies the code files in the sketch root folder and the full contents of the

data

data

Metadata

sketch.json

Arduino Web Editor uses a file named

sketch.json

The

cpu

The

included_libs

Sketch project file

This is an optional file named

sketch.yaml

Inside the sketch project file the user can define one or more "profiles": each profile is a description of all the resources needed to build the sketch (platform and libraries each pinned to a specific version).

The sketch project file is also used in the

arduino-cli board attach

For more information see the sketch project file documentation.

Secrets

Arduino Web Editor has a "Secret tab" feature that makes it easy to share sketches without accidentally exposing sensitive data (e.g., passwords or tokens). The Arduino Web Editor automatically generates macros for any identifier in the sketch which starts with

SECRET_

When you download a sketch from Arduino Web Editor that contains a Secret tab, the empty

#define

#include

Documentation

Image and text files in common formats which are present in the sketch root folder are displayed in tabs in the Arduino Web Editor.

Sketch file structure example

1Foo
2|_ arduino_secrets.h
3|_ Abc.ino
4|_ Def.cpp
5|_ Def.h
6|_ Foo.ino
7|_ Ghi.c
8|_ Ghi.h
9|_ Jkl.h
10|_ Jkl.S
11|_ sketch.yaml
12|_ data
13|  |_ Schematic.pdf
14|_ src
15   |_ SomeLib
16      |_ library.properties
17      |_ src
18         |_ SomeLib.h
19         |_ SomeLib.cpp

Sketchbook

The Arduino IDE provides a "sketchbook" folder (analogous to Arduino CLI's "user directory"). In addition to being the place where user libraries and manually installed platforms are installed, the sketchbook is a convenient place to store sketches. Sketches in the sketchbook folder appear under the Arduino IDE's File > Sketchbook menu. However, there is no requirement to store sketches in the sketchbook folder.

Library/Boards Manager links

(available in Arduino IDE >=1.6.9 <2.x || >=2.0.1)

A URI in a comment in the form:

1http://librarymanager[/TYPE_FILTER[/TOPIC_FILTER]][#SEARCH_KEYWORDS]

will open a search in Library Manager when clicked in the Arduino IDE.

A URI in a comment in the form:

1http://boardsmanager[/TYPE_FILTER][#SEARCH_KEYWORDS]

will open a search in Boards Manager when clicked in the Arduino IDE.

These links can be used to offer the user an easy way to install dependencies of the sketch.

The search field will be populated with the

SEARCH_KEYWORDS

A

Z

a

z

0

9

:

(available in Arduino IDE >=2.0.1)

The "Type" filter will be set to the optional

TYPE_FILTER

The Library Manager "Topic" filter will be set to the optional

TOPIC_FILTER

Unlike the

SEARCH_KEYWORDS

Signal%20Input%2FOutput

Although the filter setting is not supported by previous IDE versions, URIs containing these path components still function in all other respects.

This feature is only available when using the Arduino IDE, so be sure to provide supplementary documentation to help the users of other development software install the sketch dependencies.

Example

1// install the Arduino SAMD Boards platform to add support for your MKR WiFi 1010 board
2// if using the Arduino IDE, click here: http://boardsmanager/Arduino#SAMD
3
4// install the WiFiNINA library via Library Manager
5// if using the Arduino IDE, click here: http://librarymanager/Arduino/Communication#WiFiNINA
6#include <WiFiNINA.h>

See also

• Sketch build process documentation
• Style guide for example sketches