Skip to content

Commit 286d4b6

Browse files
mastrolinuxmastrolinux
authored
Merge pull request arduino#143 from bcmi-labs/docs
[WIP] Docs
2 parents 346c7c9 + 06c162e commit 286d4b6

File tree

1 file changed

+184
-3
lines changed

1 file changed

+184
-3
lines changed

‎README.md

+184-3
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,190 @@ You may want to copy the executable into a directory which is in your `PATH` env
2525

2626
## Usage
2727

28+
The goal of the Arduino CLI is to be used by either including it in Makefile or in any kind of script for the Command Line.
29+
The Arduino CLI aims to replace the majority of features the Arduino IDE has without the graphical UI.
30+
31+
## Getting Started
32+
33+
### Step 1. Create a new sketch
34+
The command will create a new empty sketch named MyFirstSketch in the default directory under $HOME/Arduino/
35+
36+
$ arduino-cli sketch new MyFirstSketch
37+
Sketch created in: /home/luca/Arduino/MyFirstSketch
38+
39+
$ cat /home/luca/Arduino/MyFirstSketch/MyFirstSketch.ino
40+
void setup() {
41+
}
42+
43+
void loop() {
44+
}
45+
46+
### Step 2. Modify your sketch
47+
Use your favourite file editor or IDE to modify the .ino file under: `$HOME/Arduino/MyFirstSketch/MyFirstSketch.ino`
48+
and change the file to look like this one:
49+
50+
void setup() {
51+
pinMode(LED_BUILTIN, OUTPUT);
52+
}
53+
54+
void loop() {
55+
digitalWrite(LED_BUILTIN, HIGH);
56+
delay(1000);
57+
digitalWrite(LED_BUILTIN, LOW);
58+
delay(1000);
59+
}
60+
61+
### Step 3. Connect the board to your PC
62+
If you are running a fresh install of the arduino-cli you probably need to update the platform indexes by running:
63+
64+
$ arduino-cli core update-index
65+
Updating index: package_index.json downloaded
66+
67+
Now, just connect the board to your PCs by using the USB cable. In this example we will use the MKR1000 board.
68+
69+
$ arduino-cli board list
70+
FQBN Port ID Board Name
71+
/dev/ttyACM0 2341:804E unknown
72+
73+
the board has been discovered but we do not have the correct core to program it yet. Let's install it!
74+
75+
### Step 4. Find and install the right core
76+
77+
We have to look at the core available with the `core search` command. It will provide a list of available cores matching the name arduino
78+
79+
$ arduino-cli core search arduino
80+
Searching for platforms matching 'arduino'
81+
82+
ID Version Installed Name
83+
Intel:arc32 2.0.2 No Intel Curie Boards
84+
arduino:avr 1.6.21 No Arduino AVR Boards
85+
arduino:nrf52 1.0.2 No Arduino nRF52 Boards
86+
arduino:sam 1.6.11 No Arduino SAM Boards (32-bits ARM Cortex-M3)
87+
arduino:samd 1.6.18 No Arduino SAMD Boards (32-bits ARM Cortex-M0+)
88+
arduino:stm32f4 1.0.1 No Arduino STM32F4 Boards
89+
littleBits:avr 1.0.0 No littleBits Arduino AVR Modules
90+
91+
If you're unsure you can try to refine the search with the board name
92+
93+
$ arduino-cli core search mkr1000
94+
Searching for platforms matching 'mkr1000'
95+
96+
ID Version Installed Name
97+
arduino:samd 1.6.19 No Arduino SAMD Boards (32-bits ARM Cortex-M0+)
98+
99+
So, the right platform for the Arduino MKR1000 is arduino:samd, now we can install it
100+
101+
$ arduino-cli core install arduino:samd
102+
Downloading tools...
103+
arduino:[email protected] downloaded
104+
arduino:[email protected] downloaded
105+
arduino:[email protected] downloaded
106+
arduino:[email protected] downloaded
107+
arduino:[email protected] downloaded
108+
arduino:[email protected] downloaded
109+
Downloading cores...
110+
arduino:[email protected] downloaded
111+
Installing tools...
112+
Installing platforms...
113+
Results:
114+
arduino:[email protected] - Installed
115+
arduino:[email protected] - Installed
116+
arduino:[email protected] - Installed
117+
arduino:[email protected] - Installed
118+
arduino:[email protected] - Installed
119+
arduino:[email protected] - Installed
120+
arduino:[email protected] - Installed
121+
122+
Now verify we have installed the core properly by running
123+
124+
$ arduino-cli core list
125+
ID Installed Latest Name
126+
arduino:samd 1.6.19 1.6.19 Arduino SAMD Boards (32-bits ARM Cortex-M0+)
127+
128+
129+
We can finally chek if the board is now recognized as a MKR1000
130+
131+
$ arduino-cli board list
132+
FQBN Port ID Board Name
133+
arduino:samd:mkr1000 /dev/ttyACM0 2341:804E Arduino/Genuino MKR1000
134+
135+
Great! Now the Board FQBN (Fully Qualified Board Name) and the Board Name look good, we are ready to compile and upload the sketch
136+
137+
### Step 5. Compile the sketch
138+
To compile the sketch we have to run the `compile` command with the proper FQBN we just got in the previous command.
139+
140+
$ arduino-cli compile --fqbn arduino:samd:mkr1000 Arduino/MyFirstSketch
141+
Sketch uses 9600 bytes (3%) of program storage space. Maximum is 262144 bytes.
142+
143+
### Step 6. Upload your sketch
144+
We can finally upload the sketch and see our board blinking, we now have to specify the serial port used by our board other than the FQBN:
145+
146+
$ arduino-cli upload -p /dev/ttyACM0 --fqbn arduino:samd:mkr1000 Arduino/MyFirstSketch
147+
No new serial port detected.
148+
Atmel SMART device 0x10010005 found
149+
Device : ATSAMD21G18A
150+
Chip ID : 10010005
151+
Version : v2.0 [Arduino:XYZ] Dec 20 2016 15:36:43
152+
Address : 8192
153+
Pages : 3968
154+
Page Size : 64 bytes
155+
Total Size : 248KB
156+
Planes : 1
157+
Lock Regions : 16
158+
Locked : none
159+
Security : false
160+
Boot Flash : true
161+
BOD : true
162+
BOR : true
163+
Arduino : FAST_CHIP_ERASE
164+
Arduino : FAST_MULTI_PAGE_WRITE
165+
Arduino : CAN_CHECKSUM_MEMORY_BUFFER
166+
Erase flash
167+
done in 0.784 seconds
168+
169+
Write 9856 bytes to flash (154 pages)
170+
[==============================] 100% (154/154 pages)
171+
done in 0.069 seconds
172+
173+
Verify 9856 bytes of flash with checksum.
174+
Verify successful
175+
done in 0.009 seconds
176+
CPU reset.
177+
178+
### Step 7. Add libraries
179+
Now we can try to add a useful library to our sketch. We can at first look at the name of a library, our favourite one is the wifi101, here the command to get more info
180+
181+
$ arduino-cli lib search wifi101
182+
Name: "WiFi101OTA"
183+
Author: Arduino
184+
Maintainer: Arduino <[email protected]>
185+
Sentence: Update sketches to your board over WiFi
186+
Paragraph: Requires an SD card and SAMD board
187+
Website: http://www.arduino.cc/en/Reference/WiFi101OTA
188+
Category: Other
189+
Architecture: samd
190+
Types: Arduino
191+
Versions: [1.0.2, 1.0.0, 1.0.1]
192+
Name: "WiFi101"
193+
Author: Arduino
194+
Maintainer: Arduino <[email protected]>
195+
Sentence: Network driver for ATMEL WINC1500 module (used on Arduino/Genuino Wifi Shield 101 and MKR1000 boards)
196+
Paragraph: This library implements a network driver for devices based on the ATMEL WINC1500 wifi module
197+
Website: http://www.arduino.cc/en/Reference/WiFi101
198+
Category: Communication
199+
Architecture: *
200+
Types: Arduino
201+
Versions: [0.5.0, 0.6.0, 0.10.0, 0.11.0, 0.11.1, 0.11.2, 0.12.0, 0.15.2, 0.8.0, 0.9.0, 0.12.1, 0.14.1, 0.14.4, 0.14.5, 0.15.1, 0.7.0, 0.14.0, 0.14.2, 0.14.3, 0.9.1, 0.13.0, 0.15.0, 0.5.1]
202+
203+
We are now ready to install it! Please be sure to use the full name of the lib as specified in the "Name:" section previously seen
204+
205+
$ arduino-cli lib install "WiFi101"
206+
Downloading libraries...
207+
[email protected] downloaded
208+
Installed [email protected]
209+
210+
## Inline Help
211+
28212
`arduino-cli` is a container of commands, to see the full list just run:
29213
```bash
30214
$ arduino-cli
@@ -43,11 +227,8 @@ Available Commands:
43227
core Arduino Core operations.
44228
help Help about any command
45229
lib Arduino commands about libraries.
46-
login Creates default credentials for an Arduino Create Session.
47-
logout Clears credentials for the Arduino Create Session.
48230
sketch Arduino CLI Sketch Commands.
49231
upload Upload Arduino sketches.
50-
validate Validates Arduino installation.
51232
version Shows version number of arduino CLI.
52233
....
53234
```

0 commit comments

Comments
 (0)