Arduino i Visual Studio Code: veći projekti s PlatformIO-om

Kako programirati Arduino u Visual Studio Codeu s PlatformIO-om: instalacija, projekt i platformio.ini, main.cpp, biblioteke i program u više datoteka.

Što su Visual Studio Code i PlatformIO?

Visual Studio Code, kraće VS Code, besplatan je uređivač programa tvrtke Microsoft. PlatformIO je dodatak (extension) za VS Code koji od njega napravi razvojno okruženje za mikrokontrolere: prevodi program, učitava ga na pločicu, ima serijski monitor i brine o pločicama i bibliotekama.

Ova stranica je za Arduino radionicu i nastavlja se na stranicu Arduino IDE, pa pretpostavlja da već znaš učitati program na pločicu i koristiti serijski monitor. VS Code s PlatformIO-om koristimo kad program naraste i na njemu radi više ljudi, kao na radionicama o fliperu.

Arduino IDE ili VS Code?

Arduino IDE i VS Code nisu suparnici: za brzo isprobavanje i dalje je zgodniji Arduino IDE, a za veći projekt VS Code.

Instalacija

1. Preuzmi VS Code sa službene stranice, code.visualstudio.com. Za Windows postoji i inačica koja ne treba administratorska prava (User Installer).
2. U VS Codeu otvori Extensions (ikona s četiri kvadratića na traci lijevo, Ctrl+Shift+X), potraži PlatformIO IDE i klikni Install.
3. Pričekaj: PlatformIO sam instalira svoju jezgru (PlatformIO Core). To traje nekoliko minuta i treba internet. Kad završi, zatraži da ponovno pokreneš VS Code.
4. Kad prvi put prevodiš projekt za Uno, PlatformIO preuzme još prevoditelj i podršku za pločicu. I to traje nekoliko minuta.

Upravljački program za USB čip na pločici isti je kao za Arduino IDE, pa pogledaj Spajanje pločice ako se port ne pojavi.

Pazi na hrvatska slova u putanji. PlatformIO ne podržava putanje sa slovima kao što su č, ć, đ, š i ž. Projekte zato spremaj u mapu bez njih, na primjer C:\projekti\fliper, a ne u C:\Users\Ivančić\Documents.

Novi projekt

1. Klikni ikonu PlatformIO na traci lijevo (glava s dvije antene), pa PIO Home → Open. Isto otvara i kućica na statusnoj traci dolje.
   
   
   Na početnoj stranici, pod Quick Access, su tipke za novi projekt, za uvoz programa iz Arduino IDE-a i za otvaranje projekta. Lijevo su Projects (tvoji projekti), Libraries (biblioteke), Boards (pločice) i Devices, popis spojenih pločica s njihovim portovima.
2. Klikni New Project. Upiši ime, bez razmaka i hrvatskih slova, u polju Board potraži Arduino Uno, kao Framework ostavi Arduino, odaberi mapu i klikni Finish.
3. PlatformIO napravi mapu projekta:

1. platformio.ini: postavke projekta, na primjer pločica, brzina serijskog monitora i biblioteke.
2. src/main.cpp: program, s funkcijama setup() i loop().
3. include: datoteke .h koje koristi više dijelova programa.
4. lib: vlastite biblioteke projekta.
5. test: za automatske testove. Na radionici ga ne koristimo.
6. .pio: ono što PlatformIO napravi pri prevođenju. Ne mijenjaj je i ne šalji je drugima. Ako je izbrišeš, PlatformIO je napravi ponovno.

Datoteka platformio.ini

Novi projekt za Uno ima ovakve postavke. Redak monitor_speed dodaj sam:

[env:uno]
platform = atmelavr
board = uno
framework = arduino
monitor_speed = 9600

• [env:uno] je okruženje (environment) s imenom uno: skup postavki za jednu pločicu.
• platform = atmelavr je obitelj mikrokontrolera, AVR, kojoj pripada ATmega328P na Unu.
• board = uno je pločica.
• framework = arduino znači da programiramo Arduino naredbama, kao u Arduino IDE-u.
• monitor_speed = 9600 je brzina serijskog monitora. Mora biti ista kao u Serial.begin().

Kasnije ovdje dodajemo biblioteke (lib_deps) i port (upload_port). Redak koji počinje s ; je komentar.

main.cpp umjesto .ino

U PlatformIO-u program je obična datoteka C++. Arduino IDE datoteci .ino prije prevođenja sam doda dvije stvari, a ovdje ih pišemo sami:

1. #include <Arduino.h> na vrhu. Bez njega prevoditelj ne poznaje pinMode(), digitalWrite() i ostale Arduino naredbe.
2. Deklaraciju funkcije koju koristiš prije nego što je napisana: prvi redak funkcije, sa ; na kraju.

#include <Arduino.h>

void trepni(unsigned int trajanje);  // deklaracija: funkcija je napisana niže

void setup() {
  pinMode(LED_BUILTIN, OUTPUT);
}

void loop() {
  trepni(500);
}

void trepni(unsigned int trajanje) {
  digitalWrite(LED_BUILTIN, HIGH);
  delay(trajanje);
  digitalWrite(LED_BUILTIN, LOW);
  delay(trajanje);
}

Bez deklaracije prevoditelj javi error: 'trepni' was not declared in this scope, jer funkciju vidi tek ispod loop(). Uz grešku predloži i suggested alternative: ‘strspn’, funkciju koja s našim programom nema veze: prijedlozi prevoditelja nisu uvijek točni. Umjesto deklaracije funkciju možeš i napisati iznad mjesta na kojem je koristiš.

Prevođenje, učitavanje i serijski monitor

1. Explorer (Ctrl+Shift+E): mape i datoteke projekta.
2. Extensions: dodaci za VS Code. Ovdje instaliraš PlatformIO.
3. PlatformIO: PIO Home i Project Tasks, popis svih naredbi projekta (Build, Upload, Monitor, Clean…).
4. Uređivač: ovdje pišeš program.
5. Terminal: poruke prevođenja i učitavanja, i serijski monitor.
6. Build (kvačica, Ctrl+Alt+B): prevede program.
7. Upload (strelica, Ctrl+Alt+U): prevede program i učita ga na pločicu.
8. Serial Monitor (utikač, Ctrl+Alt+S): otvori serijski monitor u terminalu.

Na statusnoj traci su i kućica (PIO Home), kanta (Clean, obriše prevedeno, pa sljedeće prevođenje krene ispočetka) i terminal PlatformIO-a. U novijim inačicama tipke Build i Upload su i gore desno, iznad uređivača. Ako u novijoj inačici tipke izgledaju drukčije, svaku naredbu nađeš i u paleti naredbi: Ctrl+Shift+P, pa upiši na primjer PlatformIO: Upload.

• Port PlatformIO obično pronađe sam. Kad je spojeno više pločica, kao četiri Una na fliperu, upiši port u platformio.ini: upload_port = COM5 i monitor_port = COM5.
• Serijski monitor radi u terminalu. Zatvara se s Ctrl+C. Ako učitavanje ne uspije jer je port zauzet, zatvori monitor i pokušaj ponovno.

• Serial Plottera nema. Za grafove koristi Serial Plotter u Arduino IDE-u.

Biblioteke

1. Otvori PIO Home → Libraries i potraži biblioteku, na primjer RTClib za modul sata.
2. Klikni na nju, pa Add to Project, odaberi svoj projekt i klikni Add.

PlatformIO biblioteku upiše u platformio.ini:

lib_deps =
    adafruit/RTClib @ ^2.1.4

To znači: biblioteka RTClib autora adafruit, verzija 2.1.4 ili novija, ali ne 3.0 i dalje, jer bi ona mogla raditi drukčije. PlatformIO je preuzme u mapu .pio kad spremiš platformio.ini, ili najkasnije pri prvom prevođenju. Budući da je biblioteka zapisana u projektu, svi u timu dobiju istu verziju, a na novom računalu ne treba ništa instalirati ručno. Vlastite biblioteke projekta spremaš u mapu lib, svaku u svoju mapu.

Program u više datoteka

Kad program naraste, podijelimo ga na dijelove: na fliperu, na primjer, lampice, zavojnice i rezultat. Svaki dio ima dvije datoteke:

• .h (header) kaže što dio nudi: popis funkcija.
• .cpp kaže kako to radi: same funkcije.

src/lampice.h:

#pragma once
#include <Arduino.h>

// Lampice na pinovima 5, 6 i 7
void lampicePocetak();
void lampiceTrepni(byte pin, unsigned int trajanje);

src/lampice.cpp:

#include "lampice.h"

const byte LAMPICE[] = {5, 6, 7};

void lampicePocetak() {
  for (byte pin : LAMPICE) {
    pinMode(pin, OUTPUT);
  }
}

void lampiceTrepni(byte pin, unsigned int trajanje) {
  digitalWrite(pin, HIGH);
  delay(trajanje);
  digitalWrite(pin, LOW);
}

src/main.cpp:

#include <Arduino.h>
#include "lampice.h"

void setup() {
  lampicePocetak();
}

void loop() {
  lampiceTrepni(5, 200);
  lampiceTrepni(6, 200);
  lampiceTrepni(7, 200);
}

• #pragma once na vrhu datoteke .h pazi da se ona uključi samo jednom, i kad je uključuje više datoteka.
• Vlastitu datoteku uključujemo s navodnicima, #include "lampice.h", a biblioteku sa šiljastim zagradama, #include <Arduino.h>.
• Popis pinova LAMPICE je samo u lampice.cpp, pa ga ostali dijelovi programa ne vide i ne mogu ga slučajno promijeniti.

Kad svatko u timu radi na svojem paru datoteka, manje si smetaju, a program je pregledniji.

Više pločica u jednom projektu

Fliper ima četiri Una, a svaki ima svoj program. Svi mogu biti u jednom projektu: zajedničke postavke pišemo u odjeljak [env], a za svaku pločicu dodamo njezino okruženje, koje prevodi samo njezinu mapu u src:

; zajedničke postavke za sve pločice
[env]
platform = atmelavr
board = uno
framework = arduino
monitor_speed = 9600

; Uno s pravilima igre: prevodi samo src/igra
[env:igra]
build_src_filter = +<igra/>

; Uno koji upravlja zavojnicama: prevodi samo src/zavojnice
[env:zavojnice]
build_src_filter = +<zavojnice/>

U Project Tasks svako okruženje ima svoje naredbe Build i Upload. Svakom okruženju dodaj i upload_port njegove pločice, da program ode na pravi Uno.

Pomoć uređivača

• Dovršavanje riječi: dok pišeš, VS Code nudi imena funkcija i varijabli. Tab ili Enter prihvati prijedlog.
• Greške dok pišeš: crvena valovita crta pod greškom, a popis svih grešaka u panelu Problems (Ctrl+Shift+M).
• F12 (Go to Definition) skoči na mjesto gdje je funkcija ili varijabla napisana, i kad je u drugoj datoteci.
• F2 (Rename Symbol) promijeni ime funkcije ili varijable svugdje u projektu odjednom.
• Shift+Alt+F (Format Document) uredno poravna uvlake.
• Ctrl+Shift+F traži riječ u svim datotekama projekta.

Ponekad VS Code podcrta nešto što se ipak uredno prevede, na primjer odmah nakon što napraviš projekt. Pravi ispit je Build. Ako crte ne nestanu ni nakon uspješnog prevođenja, u paleti naredbi pokreni PlatformIO: Rebuild IntelliSense Index.

Kad nešto ne radi

• Greške pri prevođenju iste su kao u Arduino IDE-u, jer je i prevoditelj isti. Pogledaj savjete za traženje grešaka.
• was not declared in this scope nakon prebacivanja programa iz Arduino IDE-a: nedostaje #include <Arduino.h> ili deklaracija funkcije.
• Port je zauzet: zatvori serijski monitor (Ctrl+C u terminalu) i učitaj ponovno.
• Program je otišao na pogrešnu pločicu: provjeri okruženje i upload_port.
• Instalacija ili prevođenje javlja čudne greške o putanjama: provjeri ima li u putanji projekta hrvatskih slova.

Prebacivanje programa iz Arduino IDE-a

• U PIO Home → Projects klikni Import Arduino Project i odaberi mapu programa .ino. PlatformIO od njega napravi projekt.
• Ili ručno: napravi novi projekt, kopiraj program u src/main.cpp, na vrh dodaj #include <Arduino.h> i deklaracije funkcija, a biblioteke dodaj u lib_deps.

Što smo naučili?

• PlatformIO je dodatak za VS Code koji prevodi i učitava programe za mikrokontrolere i brine o pločicama i bibliotekama.
• Postavke projekta, pločica, brzina i biblioteke s verzijama, zapisane su u platformio.ini, pa svi u timu rade s istima.
• U main.cpp sami pišemo #include <Arduino.h> i deklaracije funkcija, što Arduino IDE radi sam.
• Veći program dijelimo na dijelove, svaki s datotekom .h i .cpp.
• Projekte spremamo u mapu bez hrvatskih slova u putanji.

Mali kviz

Razgovaraj na Discord-u. (pridruži se)