Arduino IDE 2: установка, настройка и частые ошибки

Установка в Windows, macOS и Linux

Arduino IDE скачивают со страницы arduino.cc/en/software. Для версии 2.3.10 там выложены такие файлы:

Linux. AppImage — один исполняемый файл. Сделайте его исполняемым: в свойствах файла на вкладке «Права» отметьте «Разрешить выполнение файла как программы» или выполните chmod +x arduino-ide_2.3.10_Linux_64bit.AppImage. Если IDE не запускается с сообщением dlopen(): error loading libfuse.so.2 или AppImages require FUSE to run, не хватает библиотеки FUSE:

# Ubuntu 22.04
sudo add-apt-repository universe
sudo apt install libfuse2

# Ubuntu 24.04 and newer: the package was renamed
sudo apt install libfuse2t64

# Fedora
sudo dnf install fuse

Инструкция Arduino называет для Ubuntu только libfuse2, но в Ubuntu 24.04 пакет переименован в libfuse2t64 — так сказано в документации AppImage.

На некоторых композиторах Wayland (Hyprland, Sway, отдельные настройки KDE Plasma и GNOME) IDE падает при запуске с ошибками вида Failed to connect to Wayland display. Обходной путь из документации Arduino — запуск через X11 или XWayland: ключ --ozone-platform=x11 в командной строке или переменная окружения ELECTRON_OZONE_PLATFORM_HINT=x11. Права на последовательный порт в Linux разобраны ниже.

Русский язык. Откройте настройки — File → Preferences в Windows и Linux, Arduino IDE → Settings в macOS, сочетание Ctrl+, (в macOS ⌘+,), — выберите язык в списке Language и перезапустите IDE. Перевод делают участники сообщества, поэтому часть строк может остаться на английском. Сообщения сторонних программ в окне вывода, например avrdude, не переводятся. Дальше в статье названия пунктов меню даны по-английски, а в скобках — как они называются в русском интерфейсе IDE 2.3.10; меню Tools там называется «Инструменты», Sketch — «Скетч».

Как Arduino IDE собирает скетч

Скетч — это папка, в которой лежит файл .ino с тем же именем: скетч Blink — папка Blink с файлом Blink.ino. Имя начинается с латинской буквы, цифры или подчёркивания, дальше могут идти буквы, цифры, подчёркивание, точка и дефис; длина — до 63 символов, точка в конце не допускается. Если открыть .ino вне такой папки, IDE предложит создать папку и перенести в неё файл.

При сборке arduino-cli склеивает все .ino скетча в один файл C++, добавляет #include <Arduino.h> и прототипы функций, затем компилирует его вместе с ядром платы и подключёнными библиотеками и компонует в один файл. Для плат на AVR компилятор — avr-gcc, а результат — HEX-файл, который загружает avrdude. Ключи компилятора и программы загрузки берутся из файлов platform.txt и boards.txt ядра: для Uno это -mmcu=atmega328p, -DF_CPU=16000000L, протокол загрузки arduino на скорости 115 200 бит/с. Те же инструменты можно вызывать вручную — см. статьи «Тулчейн AVR GCC» и «AVRDUDE», а что ядро Arduino делает с микроконтроллером, разобрано в статье «Arduino и AVR».

Платы: менеджер плат и ссылки для ESP32

Ядро Arduino AVR Boards установлено вместе с IDE. Остальные пакеты ставятся из менеджера плат (Boards Manager, «Менеджер плат»): значок платы на левой боковой панели или Tools → Board → Boards Manager. Найдите пакет по названию платы, нажмите INSTALL («Установка») и дождитесь отметки INSTALLED с номером версии. В выпадающем списке рядом с кнопкой можно выбрать другую версию — так откатываются на предыдущую, если новая сломала сборку. Если подключить плату, для которой нет пакета, IDE сама предложит его установить.

Сторонние ядра. По умолчанию менеджер плат знает только официальный список пакетов Arduino. Ядро другого производителя добавляют ссылкой на его индекс — файл, имя которого оканчивается на _index.json. Откройте настройки и найдите внизу поле Additional Boards Manager URLs («Дополнительные ссылки для Менеджера плат»). Несколько ссылок можно вписать прямо в поле через запятую или нажать кнопку справа от него: откроется окно, где каждая ссылка пишется на отдельной строке. Для ESP32 Espressif даёт ссылку стабильных выпусков:

https://espressif.github.io/arduino-esp32/package_esp32_index.json

После этого в менеджере плат появится пакет esp32. Ссылка разработческих выпусков, package_esp32_dev_index.json, нужна, только если чип пока поддержан лишь в них. Пошагово — в ответе «Как подключить ESP32 к Arduino IDE?».

Установленные пакеты лежат в папке Arduino15: ядро — в packages/<производитель>/hardware/<архитектура>/<версия>, а компиляторы и программы загрузки — в packages/<производитель>/tools/<программа>/<версия>. Например, Arduino AVR Boards 1.8.8 подтягивает avr-gcc 7.3.0-atmel3.6.1-arduino7 и avrdude 8.0.0-arduino1.

Выбор платы и порта

Рядом с кнопками проверки и загрузки есть выпадающий список (board selector). В нём перечислены найденные порты, и если IDE узнала плату, рядом стоит её название. Выберите строку — плата и порт выберутся вместе, а имя платы станет жирным: связь есть. Если плата не опознана, она называется Unknown, и после выбора откроется окно Select Other Board and Port («Выберите другую плату и порт»): найдите плату в списке и нажмите OK. То же окно открывает пункт «Select other board and port…» в конце списка. То же можно сделать через меню Tools → Board и Tools → Port.

Важно различать две настройки:

• плата говорит IDE, как компилировать скетч и каким протоколом загружать — её можно выбрать и без подключённой платы, и проверка (Verify) будет работать;
• порт — это конкретное устройство, подключённое к компьютеру. Без него загрузка завершится ошибкой Failed uploading: no upload port provided (в русском интерфейсе — «Не удалась загрузка: порт загрузки не указан»).

Пункт Tools → Port в IDE 2 не показывается вовсе, если не найдено ни одного порта. Так называются порты плат Arduino в разных системах:

У классической Nano с микросхемой FTDI и у клонов с CH340 порт виден, но определить по нему плату IDE обычно не может и показывает Unknown — это нормально, плату выбирают вручную. Для клона Uno или Nano Arduino советует выбрать соответствующую плату из пакета Arduino AVR Boards. Если не понятно, какой порт ваш, отключите плату, откройте список, подключите снова — новый порт и есть нужный. Подробнее о подключении — в ответе «Как подключить Arduino к компьютеру?», расположение выводов — на страницах Arduino Uno и Arduino Nano.

Проверка и загрузка скетча

• Verify («Проверить», галочка, Ctrl+R) компилирует скетч и выводит ошибки в консоль, ничего не записывая в плату. Удобно запускать перед загрузкой.
• Upload («Загрузить на плату», стрелка, Ctrl+U) компилирует и загружает. По окончании IDE пишет «Done uploading.» («Загрузка завершена.»), ошибки — в консоли.
• Verify (Clean) — Shift+щелчок по галочке или Ctrl+Shift+R — пересобирает всё без кэша. Помогает, если после изменения кода кажется, что собралась старая версия.
• Upload Using Programmer («Загрузить на плату при помощи программатора», Ctrl+Shift+U) записывает скетч программатором, выбранным в Tools → Programmer («Программатор»: USBasp, Arduino as ISP и другие), через разъём ISP.

После компиляции IDE пишет, сколько флеш-памяти и ОЗУ займёт скетч, например «Скетч использует 2790 байт (8%) памяти устройства». Как считаются эти числа, разобрано в статье «Файлы прошивки», как проверить скетч до загрузки — в ответе «Как проверить скетч Arduino?».

Монитор порта и плоттер

Монитор порта (Serial Monitor) открывается кнопкой в правом верхнем углу окна или сочетанием Ctrl+Shift+M. В IDE 2 он не отдельное окно, а вкладка внизу, на месте консоли. Скорость в списке монитора должна совпадать с той, что задана в Serial.begin(), иначе принятые байты не сложатся в текст. Второй список задаёт, что добавлять к отправляемой строке: No Line Ending («Нет конца строки»), New Line («Новая строка»), Carriage Return («CR Возврат каретки») или Both NL & CR («NL & CR»). Кнопка Toggle Timestamp («Переключить отметку времени») добавляет к принятым строкам отметки времени.

Монитор привязан к окну скетча: если открыть два скетча и выбрать в каждом свою плату и порт, будут работать два монитора одновременно. Порт может держать только одна программа — пока он открыт в другом окне IDE, в терминале или в терминале COM-порта в браузере, загрузка через него не пройдёт.

Плоттер (Serial Plotter, «Построить графики из данных в мониторе порта», кнопка рядом) строит графики из чисел, которые плата присылает строками. Правила формата:

• строка заканчивается переводом строки \n или \r\n — Serial.println() добавляет \r\n сам;
• значения в строке разделяются запятой, пробелом или табуляцией;
• перед значением можно поставить подпись с двоеточием, имя:значение, — она станет названием линии; без подписей плоттер придумает свои.

Пример: сырые отсчёты АЦП и их сглаженное значение двумя линиями.

long acc = 0;                     // filter state, scaled by 8

void setup() {
  Serial.begin(115200);
}

void loop() {
  int raw = analogRead(A0);       // 0...1023
  acc += raw - acc / 8;           // moving average with weight 1/8
  int smooth = acc / 8;           // settles exactly on a constant raw
  Serial.print("raw:");
  Serial.print(raw);
  Serial.print(",smooth:");
  Serial.println(smooth);
  delay(20);
}

Состояние фильтра хранится в восемь раз большем масштабе: если делить на 8 сразу разность raw - smooth, целочисленное деление отбрасывает изменения меньше 8, и сглаженная линия застывает, не дойдя до сырой на несколько единиц. Открывайте плоттер после того, как загрузка закончилась. Флажки рядом с названиями линий скрывают и показывают отдельные графики.

Библиотеки: менеджер и ZIP

Менеджер библиотек (Library Manager, «Управление библиотеками») открывается значком библиотек на боковой панели или через Tools → Manage Libraries… Введите название в поиск, нажмите INSTALL («Установка») — по умолчанию ставится последняя версия, другую можно выбрать в списке. Если библиотеке нужны другие, IDE предложит поставить их вместе с ней (Install All, «Установить все») или без них (Install without dependencies, «Установка без зависимостей»). Примеры установленной библиотеки появятся в File → Examples («Примеры»), а строку #include в скетч вставит Sketch → Include Library («Скетч → Подключить библиотеку») → имя библиотеки.

Библиотека из ZIP-архива, скачанная, например, с GitHub, ставится командой Sketch → Include Library → Add .ZIP Library… («Скетч → Подключить библиотеку → Добавить .ZIP библиотеку...»): IDE попросит выбрать архив. Можно поставить и вручную: распакуйте архив, переложите главную папку библиотеки (обычно она названа по имени библиотеки) в подпапку libraries альбома и перезапустите IDE. Исходники библиотеки лежат в её подпапке src или, в старом формате, прямо в корне папки; примеры — в examples, описание — в файле library.properties.

Если две установленные библиотеки содержат файл с одним именем, сборщик выбирает по набору правил: подходит ли библиотека для архитектуры платы, совпадают ли имя библиотеки и имя папки с подключаемым файлом и где библиотека лежит. При прочих равных библиотека из папки libraries альбома важнее встроенных в ядро платы и в саму IDE — поэтому ручная установка «перекрывает» встроенную версию.

Где Arduino IDE хранит файлы

Расположение альбома показано в настройках, в поле Sketchbook location («Путь к альбому со скетчами»), — там же его можно сменить. Папки .arduinoIDE и .arduino15 скрытые. Удаление папки временных файлов arduino-ide иногда помогает, когда IDE ведёт себя странно, а удаление Arduino15 с повторной установкой пакета — когда плата видна, но загрузка падает из-за испорченных файлов ядра.

Настройки, которые стоит изменить

В окне настроек (File → Preferences, в macOS Arduino IDE → Settings):

Остальные параметры открываются через палитру команд: Ctrl+Shift+P → Preferences: Open Settings (UI). Там, например, настройка arduino.upload.autoVerify — пересобирать ли скетч перед каждой загрузкой (по умолчанию да; Arduino советует не выключать её без причины).

Если после включения More или All сборка завершается сообщением cc1plus: some warnings being treated as errors, значит ядро вашей платы на этих уровнях превращает предупреждения в ошибки. Arduino советует вернуть уровень Default — или исправить код, на который указывают предупреждения.

Как получить HEX-файл скетча

Команда Sketch → Export Compiled Binary («Скетч → Экспортировать скомпилированный бинарный файл», Ctrl+Alt+S) собирает скетч и копирует результаты сборки в папку build внутри папки скетча. Подпапка называется по полному имени платы (FQBN), в котором двоеточия заменены точками: для Uno с FQBN arduino:avr:uno это build/arduino.avr.uno/. Открыть её проще всего через Sketch → Show Sketch Folder («Показать папку скетча»).

Для скетча Blink на Uno в этой папке окажутся:

Записать HEX в Uno без IDE:

avrdude -p m328p -c arduino -P COM3 -b 115200 -U flash:w:Blink.ino.hex:i

Файл с загрузчиком пишут программатором, например USBasp: avrdude -c usbasp -p m328p -U flash:w:Blink.ino.with_bootloader.hex:i. Фьюзы при этом не меняются, и в новом кристалле их надо выставить отдельно — значения для Uno есть в статье «AVRDUDE», проверить каждый бит поможет калькулятор фьюзов AVR. Чем отличаются форматы HEX, ELF и BIN и что внутри каждого — в статье «Файлы прошивки».

Если экспорт не нужен, файлы можно взять и из кэша сборки: включите подробный вывод компиляции, и в командах avr-gcc и avr-objcopy будет виден полный путь к папке сборки.

Пример: поместится ли скетч в Uno

Пределы для Uno заданы в boards.txt ядра: 32 256 байт флеш-памяти (из 32 768 байт 512 занимает загрузчик) и 2048 байт ОЗУ. Пусть после проверки IDE насчитала 30 000 байт кода и 1600 байт глобальных переменных. Проценты IDE считает целочисленным делением:

Скетч поместится, но 78 % больше порога 75 %, поэтому IDE добавит предупреждение «Недостаточно памяти, программа может работать нестабильно»: на стек остаётся 448 байт. Если бы код превысил 32 256 байт, сборка завершилась бы ошибкой «Скетч слишком большой». Сократить расход памяти помогают макрос F() для строк в Serial.print(), PROGMEM для таблиц констант, типы поменьше (byte и int вместо long и float, где хватает) и отказ от тяжёлых библиотек. Загрузка программатором предел 32 256 байт не снимает: для платы «Arduino Uno» IDE проверяет размер одинаково при любом способе загрузки.

arduino-cli: то же из командной строки

Всё, что делает IDE, умеет arduino-cli — программа, на которой IDE построена. Её ставят отдельно: в macOS и Linux через Homebrew (brew install arduino-cli) или скриптом установки, а для Windows, macOS и Linux есть готовые архивы, для Windows ещё и установщик MSI. По умолчанию она работает с теми же папками Arduino15 и альбомом, что и IDE, поэтому видит установленные там ядра и библиотеки.

arduino-cli core update-index                    # refresh package indexes
arduino-cli core install arduino:avr             # install the AVR core
arduino-cli board list                           # list connected boards and ports
arduino-cli compile --fqbn arduino:avr:uno --export-binaries Blink
arduino-cli upload -p COM3 --fqbn arduino:avr:uno Blink

Ключ --export-binaries (-e) делает то же, что Export Compiled Binary, а --output-dir копирует результаты в указанную папку. Сторонние ядра подключаются ключом --additional-urls или параметром board_manager.additional_urls в файле настроек. arduino-cli удобна для сборки на сервере и в скриптах; если нужен полноценный редактор и проекты под много плат, посмотрите на PlatformIO.

Linux: права на порт и BRLTTY

Permission denied. Последовательные порты в Linux обычно принадлежат группе dialout, и без неё загрузка не открывает порт: avrdude 8.0 из Arduino AVR Boards 1.8.7 и 1.8.8 пишет OS error: cannot open port /dev/ttyACM0: Permission denied, avrdude 6.3 из более старых ядер — avrdude: ser_open(): can't open device "/dev/ttyACM0": Permission denied. Монитор порта в этом случае сообщает Error opening serial port. Проверьте группу и добавьте себя в неё:

ls -l /dev/ttyACM*        # crw-rw---- 1 root dialout ... /dev/ttyACM0
sudo usermod -a -G dialout $USER

Изменение вступит в силу после выхода из системы и повторного входа (Arduino советует перезагрузить компьютер). Если группа называется иначе, подставьте имя из вывода ls -l.

Правила udev нужны, чтобы система узнавала платы Arduino и давала права на загрузку и отладку. Если плата для загрузки перезапускается в режим загрузчика, а правил нет, загрузка начинается, но падает с ошибками вида usbdev_open(): cannot open device: Permission denied или dfu-util: No DFU capable USB device available. Arduino выпускает скрипт, который создаёт правила для всех своих плат:

wget https://content.arduino.cc/assets/arduino-udev-setup.sh
sudo bash arduino-udev-setup.sh

После этого переподключите плату. В руководстве по установке IDE приведено и короткое правило для файла /etc/udev/rules.d/99-arduino.rules — оно открывает доступ к USB-устройствам с кодом производителя 2341: SUBSYSTEMS=="usb", ATTRS{idVendor}=="2341", GROUP="plugdev", MODE="0666".

BRLTTY. В некоторых дистрибутивах установлена служба BRLTTY для брайлевских дисплеев. Она считает любой адаптер USB–UART дисплеем и забирает его порт, поэтому порт платы с CH340, FTDI или CP210x появляется и сразу пропадает. Признаки: ps -C brltty показывает процесс, а в dmesg после подключения видна строка о том, что интерфейс занял brltty. Если брайлевский дисплей не нужен, службу удаляют: sudo apt remove brltty. Если удалить нельзя (в некоторых дистрибутивах от BRLTTY зависит рабочий стол), останавливают и отключают обе её службы — запуск по udev и основную:

sudo systemctl stop brltty-udev.service
sudo systemctl mask brltty-udev.service
sudo systemctl stop brltty.service
sudo systemctl disable brltty.service

После этого переподключите плату.

Частые ошибки

В Windows avrdude 8.0 дописывает к cannot open port текст ошибки от самой системы, поэтому в русской Windows эта часть сообщения будет по-русски; Arduino тоже предупреждает, что текст ошибок зависит от языка системы. Строка exit status 1 сама по себе только сообщает, что загрузка или компиляция не удалась: причину ищите в строках выше неё, а лучше — включите подробный вывод.

«programmer is not responding»: что происходит

Загрузчик плат Uno, Nano и Pro Mini понимает протокол STK500 первой версии (в avrdude он выбирается ключом -c arduino). Перед записью avrdude отправляет плате команду синхронизации и ждёт ответа. Если байты не пришли, она пишет programmer is not responding; если пришёл не тот ответ — not in sync: resp=0x.., где 0x00 означает, что ничего полезного не получено. Всего делается 10 попыток.

Текст сообщений зависит от версии avrdude, которую ставит ядро. avrdude 6.3 (её ставят Arduino AVR Boards по версию 1.8.6 включительно) пишет avrdude: stk500_recv(): programmer is not responding и avrdude: stk500_getsync() attempt 1 of 10: not in sync: resp=0x00. avrdude 8.0 (Arduino AVR Boards 1.8.7 и 1.8.8) пишет то же короче — Error: programmer is not responding и Warning: attempt 1 of 10: not in sync: resp=0x00 — и перед каждой повторной попыткой сама сбрасывает плату коротким импульсом на линиях DTR и RTS, чтобы снова запустить загрузчик.

Что проверить, по порядку:

1. Плату и порт: выбрана именно ваша плата и тот порт, который появляется при её подключении.
2. У классической Nano — вариант загрузчика: попробуйте другой процессор в Tools → Processor, обычно ATmega328P (Old Bootloader). Старому загрузчику нужна скорость 57 600 бит/с вместо 115 200.
3. Выводы 0 (RX) и 1 (TX): всё, что к ним подключено, мешает обмену с загрузчиком — отключите на время загрузки.
4. Порт не занят другим окном IDE, монитором порта или терминалом.
5. Нажмите на плате кнопку RESET, переподключите кабель, попробуйте другой кабель и разъём.
6. Если ничего не помогло, загрузчик мог быть стёрт или повреждён. У Uno, Mega и классической Nano Arduino советует сначала проверить микросхему USB–UART петлевым тестом, а затем записать загрузчик заново другой платой Arduino в роли программатора — как это сделать через avrdude, рассказано в статье «AVRDUDE», а о самих загрузчиках и ISP — в статье «Программирование AVR».