Ошибка SoftwareSerial.h: No such file or directory появляется при компиляции скетча в Arduino IDE в тот момент, когда препроцессор встречает строку #include <SoftwareSerial.h>, но не находит сам заголовочный файл в путях поиска библиотек. Компиляция прерывается сразу, скетч не загружается в плату, а в консоли выводится сообщение об ошибке с указанием строки директивы #include.
Проблема встречается и у новичков, и у опытных разработчиков: причиной может быть как отсутствие библиотеки, так и неправильно выбранная плата, битая установка IDE или конфликт версий. Ниже разберём, почему возникает эта ошибка и как её устранить пошагово.
Что означает эта ошибка
SoftwareSerial — это стандартная библиотека Arduino, которая позволяет организовать последовательный порт (UART) программным способом на любых цифровых пинах платы. Она нужна, когда аппаратного UART не хватает: например, один занят отладкой через USB, а второй требуется для подключения GPS-модуля, Bluetooth HC-05 или GSM-модема SIM800.
Сообщение No such file or directory означает буквально следующее: компилятор искал файл SoftwareSerial.h во всех известных ему каталогах библиотек и не нашёл. Это не ошибка синтаксиса вашего кода — сам скетч может быть написан абсолютно корректно.
Важный нюанс: библиотека SoftwareSerial входит в состав платформы, а не устанавливается отдельно для большинства классических плат. Поэтому её «отсутствие» почти всегда указывает на проблему окружения, а не на необходимость что-то скачать вручную.
Основные причины появления ошибки
Прежде чем что-то переустанавливать, полезно понять, какая именно причина актуальна в вашем случае. Ниже перечислены наиболее типичные сценарии.
- 🔧 Выбрана несовместимая плата. Библиотека SoftwareSerial существует не для всех архитектур. Например, для некоторых плат на базе ESP32 или STM32 она либо отсутствует в ядре, либо реализована иначе.
- 📦 Повреждённое или неполное ядро платформы. Если установка пакета платы через Менеджер плат прервалась, часть файлов, включая SoftwareSerial, может отсутствовать.
- 🗂 Конфликт библиотек. Сторонняя библиотека с похожим именем в папке
librariesможет перекрывать стандартную или ломать пути поиска. - 💾 Некорректная установка Arduino IDE. Редкий, но возможный случай — повреждённые файлы самой среды разработки.
- ✏️ Опечатка в директиве. Написание
#include <softwareserial.h>со строчной буквы на системах с чувствительной к регистру файловой системой (Linux) приведёт к той же ошибке.
Проверка выбранной платы
Первое действие — убедиться, что в Arduino IDE выбрана именно та плата, для которой вы компилируете. Откройте меню Инструменты → Плата и проверьте текущий выбор. Если вы пишете скетч для Arduino Uno, а выбрана, к примеру, плата семейства ESP32, компилятор будет искать библиотеки в ядре ESP32 — и может их не найти.
Для классических плат AVR (Uno, Nano, Mega, Pro Mini) библиотека SoftwareSerial входит в состав ядра Arduino AVR Boards. Если плата выбрана верно, а ошибка остаётся, переходите к проверке самого ядра.
Вам также стоит проверить, что выбран правильный процессор и порт в тех же меню Инструменты — иногда после смены платы эти параметры сбрасываются, что приводит к неочевидным сбоям компиляции.
Переустановка ядра платформы
Если плата выбрана правильно, наиболее вероятная причина — повреждённое ядро. Переустановка занимает несколько минут и решает проблему в подавляющем большинстве случаев с платами AVR.
☑️ Переустановка ядра Arduino AVR
Порядок действий следующий. Откройте Инструменты → Плата → Менеджер плат, в строке поиска наберите Arduino AVR Boards. Удалите установленный пакет, затем установите его заново. После завершения установки полностью закройте и снова откройте Arduino IDE — это важно, потому что среда кеширует список библиотек при запуске.
⚠️ Внимание: во время установки пакета не закрывайте Менеджер плат и не обрывайте соединение с интернетом. Прерванная установка — одна из главных причин неполного ядра, из-за которого и пропадает SoftwareSerial.
После переустановки создайте пустой скетч с одной строкой #include <SoftwareSerial.h> и попробуйте скомпилировать его. Если компиляция проходит — проблема решена, и можно возвращаться к основному проекту.
Проверка директивы include и конфликтов библиотек
Следующий шаг — взглянуть на сам скетч. Убедитесь, что директива написана именно так:
#include <SoftwareSerial.h>Регистр букв имеет значение: softwareserial.h или SoftwareSerial.H на Linux-системах вызовут ту же ошибку, что и полное отсутствие файла. Используйте угловые скобки <>, а не кавычки — кавычки заставляют компилятор искать файл сначала в папке скетча.
Затем проверьте папку пользовательских библиотек. Обычно она находится в каталоге Документы/Arduino/libraries (на Windows) или ~/Arduino/libraries (на Linux и macOS). Если там лежит папка с именем SoftwareSerial, скачанная откуда-то вручную, она может конфликтовать со встроенной версией. Временно переименуйте или удалите её и перекомпилируйте скетч.
Особенности для ESP8266 и ESP32
Для плат ESP8266 библиотека SoftwareSerial существует, но поставляется вместе с ядром ESP8266 и имеет свои ограничения: она работает не на всех пинах и требовательна к таймингам. Если вы установили ядро ESP8266 корректно, include должен работать, но стоит убедиться, что версия ядра актуальна.
С ESP32 ситуация иная: стандартной SoftwareSerial в классическом виде там нет, поскольку у чипа несколько аппаратных UART. Для ESP32 вместо SoftwareSerial рекомендуется использовать аппаратные порты HardwareSerial (Serial1, Serial2) с переназначением пинов — это надёжнее и не нагружает процессор программной эмуляцией.
Если вы всё же хотите программный UART на ESP32, существуют сторонние библиотеки с аналогичной функциональностью, но их нужно устанавливать отдельно через Менеджер библиотек, и их API может отличаться от оригинальной SoftwareSerial.
Пример использования HardwareSerial на ESP32
Вместо SoftwareSerial объявите порт так: HardwareSerial mySerial(1); затем в setup() вызовите mySerial.begin(9600, SERIAL_8N1, 16, 17); где 16 и 17 — пины RX и TX. Точные номера пинов подбирайте под свою плату по её распиновке.
Сравнение способов решения
Сведём основные варианты устранения ошибки в таблицу, чтобы было проще выбрать подходящий под вашу ситуацию.
| Причина | Способ решения | Сложность |
|---|---|---|
| Неверно выбрана плата | Выбрать правильную плату в меню Инструменты | Минимальная |
| Повреждённое ядро AVR | Переустановить Arduino AVR Boards в Менеджере плат | Низкая |
| Опечатка в #include | Исправить регистр и угловые скобки | Минимальная |
| Конфликт со сторонней библиотекой | Удалить дубликат из папки libraries | Низкая |
| ESP32 без SoftwareSerial | Перейти на HardwareSerial | Средняя |
⚠️ Внимание: не скачивайте файл SoftwareSerial.h с сомнительных сайтов и не копируйте его вручную в папки IDE. Такой файл может не соответствовать версии вашего ядра, что приведёт к новым ошибкам компиляции или нестабильной работе порта.
Когда ничего не помогает
Если все перечисленные шаги выполнены, а ошибка сохраняется, остаётся вариант с чистой переустановкой среды. Удалите Arduino IDE, затем вручную проверьте и удалите остаточные папки ядра — на Windows это обычно каталог в AppData, связанный с Arduino. После этого установите свежую версию IDE с официального источника и заново установите нужные пакеты плат.
Полезно также проверить, не используется ли портативная (portable) версия IDE с собственным набором библиотек — в ней пути отличаются от стандартных, и библиотеки из обычной установки не будут видны.
Часто задаваемые вопросы
Нужно ли скачивать SoftwareSerial отдельно для Arduino Uno?
Нет. Для плат на базе AVR (Uno, Nano, Mega) библиотека входит в состав ядра Arduino AVR Boards и доступна сразу после установки IDE. Если include не работает — проблема в ядре или настройках, а не в отсутствии библиотеки.
Почему ошибка возникает только на одном компьютере?
Это указывает на различия в окружении: версии IDE, версии ядра платформы или содержимом папки libraries. Сравните версии пакетов в Менеджере плат на обоих компьютерах и приведите их к одному состоянию.
Работает ли SoftwareSerial на ESP32?
Стандартной библиотеки SoftwareSerial для ESP32 нет. Вместо неё используйте аппаратные порты HardwareSerial с переназначением пинов — у ESP32 несколько аппаратных UART, и это более надёжное решение.
Может ли ошибка появиться из-за старой версии Arduino IDE?
Возможная причина, да. В очень старых версиях IDE структура библиотек отличалась. Обновление до актуальной версии среды и ядра платформы — разумный шаг, если остальные методы не помогли.
Что делать, если после исправления ошибки порт не передаёт данные?
Это уже другая проблема: проверьте, что скорость порта в скетче совпадает со скоростью устройства, что пины RX и TX подключены перекрёстно (RX к TX), и что выбранные пины поддерживают программный UART на вашей плате.