Эхо-протокол для отладки: ok и bad на каждую команду

Плата молчит после команды. Это может значить четыре вещи: строка не доехала, доехала кривой, парсер её не понял, или понял, исполнил — а эффект не там, где ждали. Без второй платы, осциллографа и логического анализатора эти четыре случая не различить на глаз — и именно здесь их различает один приём, который не стоит ни копейки: заставить плату отвечать на каждую входящую строку вслух. Две строки на команду: что услышала и что решила. Называю это эхо-протоколом и ставлю в скетч раньше любой бизнес-логики.

Механику приёма и базовую разборку строки вы уже видели в двух прошлых уроках; здесь фокус на второй половине разговора — на ответах. Отладка через порт вообще начинается с дисциплины вывода, это разобрано в уроке про отладку логики; эхо-протокол — следующая ступень той же мысли: не просто печатать значения, а вести диалог, где у каждой реплики есть класс и причина. Уже после первой недели с таким протоколом исчезают вопросы в духе «почему не работает»: ответ лежит в мониторе с указанием ступени, на которой всё встало.

Префиксы ok, bad и st — контракт: первый токен ответа всегда называет класс события. ok — команда принята и исполнена, bad — отвергнута с причиной, st — снимок состояния без команды. Такой лог читается глазами даже через неделю после записи, а сортировкой по префиксам превращается в таблицу отказов за минуту. Полную иерархию сообщений — когда что печатать, сколько слов тратить и куда писать подробности — я разворачиваю в уроке про уровни логов; для командного протокола хватает трёх классов, и три держатся годами.

Почему не слова вроде «принято» и «отвергнуто»? Длина и различимость: префиксы в два-три символа видны в логе с одного взгляда, не сливаются с аргументами и фильтруются поиском без конфигурации. Короткий префикс экономит и буфер печати: ответ с эхом и причиной укладывается в 40-50 байтов, очередь не растягивается на проходы loop. Протокол вообще любит такие мелкие числа: они не старятся и не требуют комментариев.

Эхо строки я беру в квадратные скобки: >> eho: [GET]. Скобки рисуют границу строки, и невидимые символы перестают быть невидимыми: [GET ] с хвостом после скобки честно показывает, что монитор досылает что-то лишнее, и trim в парсере только что оправдал своё место в коде. Без скобок тот же хвост выглядел бы как загадочная разница между поведением двух плат — ищи её потом глазом по экрану.

Ответ зеркалит команду: SET возвращает присвоенное число, ON — фактический пин и его состояние. Мелочь, которая экономит вечера: увидели ok: relay on, а реле молчит — виновата электрика, а не протокол, и проверять надо пин и питание, а не парсер. Границу между программой и железом протокол должен показывать, а не смазывать: ровно для этого ok печатает то, что сделал, а не то, что собирался.

Разберём сценарий «команда не сработала» по протоколу. Ни эха, ни ответа — строка не доехала: скорость, кабель, не тот порт, монитор не открыт. Эхо есть, ответа нет — парсер принял строку и замолчал: где-то ранний return без печати, смотрите ветки if. bad с причиной — парсер здоров, виновато значение: причина называет поле и границу. ok есть, а эффекта нет — протокол отработал, ищите в железе: пин, питание, проводка. Четыре случая, четыре разных лекарства, и все различаются по двум строкам в мониторе — без пайки и без второго комплекта платы.

Когда подозрение всё же падает на сам провод — дрожи линии, помехи, пропадающие байты — дальше порта не уйдёшь без приборов, и тут есть отдельная методика: урок про диагностику глюков линии. Эхо-протокол не заменяет её, а отрезает: если эхо доходит байт в байт, линия чистая, и искать надо в коде, а не в кабеле. А когда к плате подключится второй собеседник — скрипт или другая плата — формат уже готов: машина читает префикс, человек читает остальное. Провод для пары плат показан в уроке про связь двух Arduino, а формат разговора у вас уже есть.

Живой пример. Насос в теплице включался командой ON, ok приходил, насос молчал. Эхо-протокол отрезал половину поисков за минуту: в логе красовалось ok: relay on — значит, пин D7 получил высокий уровень, код дошёл до конца ветки. Осталась физика, и физика не заставила себя ждать: реле-модуль оказался с активным низом, где включение — это LOW. Три строки в мониторе сэкономили вечер, который иначе ушёл бы на перепроверку исправного скетча.

Ещё два качества скетча стоит проговорить вслух. Состояние relayOn живёт в переменной, а не в чтении выходного пина: digitalRead на выходе и правда работает, но переменная показывает замысел, и GET опирается именно на неё. Ветка else с replyBad — единственная точка, куда падают неизвестные глаголы: новая команда означает новую ветку до неё, и точка отказа остаётся одна. Протокол растёт, не теряя гарантий, — это главное отличие архитектуры от кучи if.

Обратная сторона — ответы, которые хуже молчания. bad без причины: вы узнаёте про отказ ровно столько же, сколько без него, только экран замусорен. Ответ в две-три строки с рамками из равно: в живом логе рамки слипаются, и искать начало события — работа для археолога. Самое коварное — печать телеметрии внутри быстрого цикла: показание раз в 100 мс выдаёт шестьсот строк в минуту, и ваша команда тонет в потоке раньше, чем вы допечатаете. Телеметрию — реже или на запрос GET, команды — всегда и сразу. Большой словарь с вложенными подкомандами и правила оформления ответов для него собраны отдельно в уроке про командный парсер.

Отдельная прививка — молчание при пустой строке. Соблазн отбросить пустой ввод без ответа велик, но тогда на линии появится случай без реплики, неотличимый от обрыва связи. Мой скетч отвечает и на пустоту: bad: pustaya stroka. Пустых строк в живом вводе мало, лог не страдает, а полнота восстанавливается: каждое событие на входе получает реплику на выходе, и диагностическая лестница остаётся без дыр.

Таблица выше — рабочий чек-лист, который я первое время держал напечатанным над столом. Порядок обхода всегда один: транспорт, парсер, значения, железо. Навигация в обратную сторону сжирает вечера, потому что на каждом этаже версия выглядит правдоподобно, и перебирать их без направления — удовольствие так себе.

Заметьте, как мало стоит сам механизм: одна печать эха в начале runCommand и одна функция replyBad на четыре строки. Всё остальное — привычка печатать вердикт в каждой ветке, включая отказные. Привычка ставится за один вечер с симулятором ниже: десять вводов, десять вердиктов, и рука сама тянется печатать причину, а не только вердикт.