Переслать роботу на Ардуине несколько байт через вайфай, блютус, последовательный порт или любой другой канал связи в виде команды, а потом принять несколько байт в качестве ответа труда не составляет: достаточно скачать скетч с примером обмена данными «здравствуй мир» и вставить в него несколько строк своего кода, который будет выполнять желаемые действия.
Однако с развитием проекта область вспомогательного кода, который отвечает за связь с внешним миром, раздувается: появляется логика, отделяющая один пакет данных от другого, разрастается лес проверок, что за команда пришла, какие у нее параметры, как её правильно выполнить, что делать, если пакет данных не корректен, если данные пришли не полностью, если они не умещаются в отведенных для них буфер памяти и так далее. Код, обслуживающий вспомогательную логику, переплетается с главным кодом, выполняющим интересную и полезную работу. Заменить один канал связи на другой (например, добавить к последовательному порту вайфай) без переработки накопившейся кодовой базы становится весьма проблематично.
Долгое время я таскал такой код из одного проекта в другой, новые улучшения и исправления приходилось обновлять во всех проектах параллельно. Это утомительно, чревато появлением новых ошибок и не всегда возможно. Наконец пришло время вынести всю эту логику в отдельную библиотеку.
Исходная задача: упростить процесс создания прошивки для роботов, которые будут работать в режиме «вопрос-ответ». Главный скетч должен содержать полезный код (что, собственно, должен делать робот) и минимальное количество вспомогательных конструкций. Все вспомогательные транспортно-протокольные блоки окуклить в библиотеку и вынести за пределы внимания инженера.
В качестве побочного эффекта получилась своеобразная командная строка, работающая внутри Ардуины, если подключиться к ней через монитор последовательного порта и отправлять команды вручную:
Особенности библиотеки
— Работа в режиме вопрос-ответ
— Максимальные размеры входящей команды и ответа ограничены размером буферов (задаются в настройках в скетче)
— Каналы связи (последовательный порт, вайфай, блютус) взаимозаменяемы, реализованы в виде отдельных подмодулей
— Нет жестких требований к деталям протокола (строится поверх модулей связи)
— Новые команды добавляются в виде отдельных функций (подпрограмм) и регистрируются в системе по уникальному имени
— Механизмы передачи информации об исключительных ситуациях на сторону клиента
Архитектурно библиотека разбита на 3 уровня:
— Модули каналов связи (реализована работа через последовательный порт, вайфай и блютус в среднесрочный планах): установка и обслуживание соединения, вычленение пакетов из потока входных данных, отправка ответа.
— Модуль регистрации и исполнения команд: регистрация функции (подпрограммы) в виде команды, поиск команды по имени, выполнение команды.
— Вспомогательные контейнерные протоколы: для получения команд и упаковки ответов в пакеты в формате JSON.
Канал связи через последовательный порт: babbler_serial
Модуль работы с командами: babbler_h
Модуль JSON: babbler_json
Модули относительно независимы друг от друга: можно использовать только модуль канала связи для обмена сырыми данными и выстроить с его помощью собственный протокол, к модулю работы с командами можно подключать другие реализации каналов связи, модуль JSON можно вообще не использовать или поставить на его место реализацию модуля работы с пакетами XML и так далее.
Далее примеры.
Установка библиотеки
Проект на гитхабе: babbler_h
git clone https://github.com/1i7/babbler_h.gitИли скачать очередной релиз в архиве
далее поместить подкаталоги babbler_h, babbler_serial, babbler_json в каталог к библиотекам Arduino $HOME/Arduino/libraries, должно получиться:
$HOME/Arduino/libraries/babbler_h
$HOME/Arduino/libraries/babbler_serial
$HOME/Arduino/libraries_babbler_json
Всё.
Запустить среду разработки Ардуино, в меню Файл/Примеры/babbler_h появятся примеры:
_1_babbler_hello: простая прошивка: настройка канала связи, регистрация команд (встроенные команды: ping и help)
_2_babbler_custom_cmd: добавление собственных команд (включить/выключить лампочку)
_3_babbler_cmd_params: команды с параметрами (транспорт для pin_mode/digital_write)
_4_babbler_cmd_devino: набор команд для получения информации об устройстве
_5_babbler_custom_handler: собственный обработчик входных данных (то же, что и _1_babbler_hello, только внутренности снаружи)
_6_babbler_reply_json: ввод/вывод упакован JSON
_7_babbler_reply_xml: ввод строкой, ответ в XML
babbler_basic_io: сырой вопрос-ответ через последовательный порт без инфраструктуры модуля команд
Простой пример: эхо через последовательный порт
Без использования инфраструктуры работы с командами.
Файл/Примеры/babbler_h/babbler_basic_io.ino
Нам нужен только модуль babbler_serial:
#include "babbler_serial.h"
Буферы для получения входящих данных и отправки ответа. Входящий пакет (команда и параметры) должен полностью умещаться в буфер serial_read_buffer (плюс один байт резервируем на один завершающий ноль). Ответ должен полностью умещаться в буфер serial_write_buffer.
// Размеры буферов для чтения команд и записи ответов
#define SERIAL_READ_BUFFER_SIZE 128
#define SERIAL_WRITE_BUFFER_SIZE 512
// Буферы для обмена данными с компьютером через последовательный порт.
// +1 байт в конце для завершающего нуля
char serial_read_buffer[SERIAL_READ_BUFFER_SIZE+1];
char serial_write_buffer[SERIAL_WRITE_BUFFER_SIZE];
Функция-обработчик входящих данных: принимает данные в буфере input_buffer, решает, что с ними делать, записывает ответ в буфер reply_buffer, возвращает количество байт, записанных в буфер ответа. Здесь весь пользовательский код.
int handle_input(char* input_buffer, int input_len, char* reply_buffer, int reply_buf_size) {
// добавим к входным данным завершающий ноль,
// чтобы рассматривать их как корректную строку
input_buffer[input_len] = 0;
// как-нибудь отреагируем на запрос - пусть будет простое эхо
if(reply_buf_size > input_len + 10)
sprintf(reply_buffer, "you say: %sn", input_buffer);
else
sprintf(reply_buffer, "you are too verbose, dearn");
return strlen(reply_buffer);
}
Предварительные настройки модуля связи через последовательный порт:
— babbler_serial_setup: передаём буферы для входящих команд и исходящих ответов,
— packet_filter_newline: фильтр новых пакетов — пакеты отделены переводом строки
— babbler_serial_set_input_handler: указатель на функцию-обработчик входных данных в коде пользователя (наш handle_input)
void setup() {
Serial.begin(9600);
Serial.println("Starting babbler-powered device, type something to have a talk");
babbler_serial_set_packet_filter(packet_filter_newline);
babbler_serial_set_input_handler(handle_input);
//babbler_serial_setup(
// serial_read_buffer, SERIAL_READ_BUFFER_SIZE,
// serial_write_buffer, SERIAL_WRITE_BUFFER_SIZE,
// 9600);
babbler_serial_setup(
serial_read_buffer, SERIAL_READ_BUFFER_SIZE,
serial_write_buffer, SERIAL_WRITE_BUFFER_SIZE,
BABBLER_SERIAL_SKIP_PORT_INIT);
}
В главный цикл помещаем babbler_serial_tasks: постоянно следим за последовательным портом, ждем входные данные. Вызов babbler_serial_tasks не блокирующий, после него можно размещать любую другую логику.
void loop() {
// постоянно следим за последовательным портом, ждем входные данные
babbler_serial_tasks();
}Прошиваем, открываем Инструменты>Монитор порта, вводим сообщения, получаем ответы:
Простой пример: работа с командами
Следующий простой пример — работа с командами. Регистрируем в прошивке две встроенные команды (определены в модуле babbler_cmd_core.h):
— help (получить список команд, посмотреть справку по выбранной команде) и
— ping (проверить, живо ли устройство).
Команда ping:
pingВозвращает «ok»
Команда help:
helpВывести список команд:
help --listВывести список команд с кратким описанием
help имя_командыВывести подробную справку по команде.
Файл/Примеры/babbler_h/_1_babbler_hello.ino
Здесь инфраструктура для регистрации, поиска и выполнения команд по имени:
#include "babbler.h"
Здесь разбор входящей командной строки: строка разбивается на элементы по пробелам, первый элемент — имя команды, все остальные — параметры.
#include "babbler_simple.h"
Здесь определения команд: help и ping
#include "babbler_cmd_core.h"
Модуль общения через последовательный порт:
#include "babbler_serial.h"
Буферы для ввода и для вывода, здесь всё без изменений.
// Размеры буферов для чтения команд и записи ответов
#define SERIAL_READ_BUFFER_SIZE 128
#define SERIAL_WRITE_BUFFER_SIZE 512
// Буферы для обмена данными с компьютером через последовательный порт.
// +1 байт в конце для завершающего нуля
char serial_read_buffer[SERIAL_READ_BUFFER_SIZE+1];
char serial_write_buffer[SERIAL_WRITE_BUFFER_SIZE];
Регистрируем команды — добавляем структуры CMD_HELP и CMD_PING (они определены в babbler_cmd_core.h) в глобальный массив BABBLER_COMMANDS. Попутно фиксируем количество зарегистрированных команд BABBLER_COMMANDS_COUNT — количество элементов в массиве BABBLER_COMMANDS (в Си нельзя узнать размер массива, определенного таким образом, динамически в том месте, где это нам потребуется).
/** Зарегистрированные команды */
extern const babbler_cmd_t BABBLER_COMMANDS[] = {
// команды из babbler_cmd_core.h
CMD_HELP,
CMD_PING
};
/** Количество зарегистрированных команд */
extern const int BABBLER_COMMANDS_COUNT = sizeof(BABBLER_COMMANDS)/sizeof(babbler_cmd_t);
По этой же схеме регистрируем человекочитаемые руководства для зарегистрированных команд в массиве BABBLER_MANUALS — их выводит команда help (можете определить пустой массив без элементов, если хотите поэкономить память, но тогда не будет работать команда help).
/** Руководства для зарегистрированных команд */
extern const babbler_man_t BABBLER_MANUALS[] = {
// команды из babbler_cmd_core.h
MAN_HELP,
MAN_PING
};
/** Количество руководств для зарегистрированных команд */
extern const int BABBLER_MANUALS_COUNT = sizeof(BABBLER_MANUALS)/sizeof(babbler_man_t);
Настраиваем модуль:
— babbler_serial_set_packet_filter и babbler_serial_setup — всё, как и раньше
— в babbler_serial_set_input_handler отправляем указатель на функцию handle_input_simple (из babbler_simple.h, вместо собственного handle_input) — она делает всю необходимую работу: разбирает входную строку по пробелам, отделяет имя команды от параметров, выполняет команду, записывает ответ.
void setup() {
Serial.begin(9600);
Serial.println("Starting babbler-powered device, type help for list of commands");
babbler_serial_set_packet_filter(packet_filter_newline);
babbler_serial_set_input_handler(handle_input_simple);
//babbler_serial_setup(
// serial_read_buffer, SERIAL_READ_BUFFER_SIZE,
// serial_write_buffer, SERIAL_WRITE_BUFFER_SIZE,
// 9600);
babbler_serial_setup(
serial_read_buffer, SERIAL_READ_BUFFER_SIZE,
serial_write_buffer, SERIAL_WRITE_BUFFER_SIZE,
BABBLER_SERIAL_SKIP_PORT_INIT);
}
Главный цикл без изменений:
void loop() {
// постоянно следим за последовательным портом, ждем входные данные
babbler_serial_tasks();
}
Прошиваем, открываем Инструменты>Монитор порта, вводим команды, получаем ответы:
<b>]help --list</b>
help ping
<b>]ping</b>
ok
<b>]help</b>
Commands:
help
list available commands or show detailed help on selected command
ping
check if device is available
<b>]help ping</b>
ping - manual
NAME
ping - check if device is available
SYNOPSIS
ping
DESCRIPTION
Check if device is available, returns "ok" if device is ok
<b>]help help</b>
help - manual
NAME
help - list available commands or show detailed help on selected command
SYNOPSIS
help
help [cmd_name]
help --list
DESCRIPTION
List available commands or show detailed help on selected command. Running help with no options would list commands with short description.
OPTIONS
cmd_name - command name to show detailed help for
--list - list all available commands separated by spaceДобавление собственных команд
И, наконец, добавление собственной команды так, чтобы её можно легко вызывать по имени. Для примера добавим две команды:
— ledon (включить лампочку) и
— ledoff (выключить лампочку)
для включения и выключения светодиода, подключенного к выбранной ножке микроконтроллера.
Здесь всё без изменений:
#include "babbler.h"
#include "babbler_simple.h"
#include "babbler_cmd_core.h"
#include "babbler_serial.h"
// Размеры буферов для чтения команд и записи ответов
#define SERIAL_READ_BUFFER_SIZE 128
#define SERIAL_WRITE_BUFFER_SIZE 512
// Буферы для обмена данными с компьютером через последовательный порт.
// +1 байт в конце для завершающего нуля
char serial_read_buffer[SERIAL_READ_BUFFER_SIZE+1];
char serial_write_buffer[SERIAL_WRITE_BUFFER_SIZE];Номер ножки светодиода:
#define LED_PIN 13А вот и сразу полезный код — для каждой команды должна быть определена функция с параметрами:
— reply_buffer — буфер для записи ответа
— reply_buf_size — размер буфера reply_buffer (ответ должен в него уместиться, иначе сообщить об ошибке)
— argc — количество аргументов (параметров) команды
— argv — значения аргументов команды (первый аргумент всегда имя команды, всё по аналогии с обычной main)
Вариант для ledon:
/** Реализация команды ledon (включить лампочку) */
int cmd_ledon(char* reply_buffer, int reply_buf_size, int argc=0, char *argv[]=NULL) {
digitalWrite(LED_PIN, HIGH);
// команда выполнена
strcpy(reply_buffer, REPLY_OK);
return strlen(reply_buffer);
}Структура babbler_cmd_t для регистрации команды: имя команды и указатель на её функцию:
babbler_cmd_t CMD_LEDON = {
/* имя команды */
"ledon",
/* указатель на функцию с реализацией команды */
&cmd_ledon
};Руководство для команды — структура babbler_man_t: имя команды, краткое описание, подробное описание.
babbler_man_t MAN_LEDON = {
/* имя команды */
/* command name */
"ledon",
/* краткое описание */
/* short description */
"turn led ON",
/* руководство */
/* manual */
"SYNOPSISn"
" ledonn"
"DESCRIPTIONn"
"Turn led ON."
};Всё то же самое для ledoff:
/** Реализация команды ledoff (включить лампочку) */
int cmd_ledoff(char* reply_buffer, int reply_buf_size, int argc=0, char *argv[]=NULL) {
digitalWrite(LED_PIN, LOW);
// команда выполнена
strcpy(reply_buffer, REPLY_OK);
return strlen(reply_buffer);
}
babbler_cmd_t CMD_LEDOFF = {
/* имя команды */
/* command name */
"ledoff",
/* указатель на функцию с реализацией команды */
/* pointer to function with command implementation*/
&cmd_ledoff
};
babbler_man_t MAN_LEDOFF = {
/* имя команды */
/* command name */
"ledoff",
/* краткое описание */
/* short description */
"turn led OFF",
/* руководство */
/* manual */
"SYNOPSISn"
" ledoffn"
"DESCRIPTIONn"
"Turn led OFF."
};
Регистрируем новые CMD_LEDON и CMD_LEDOFF вместе с уже знакомым CMD_HELP и CMD_PING, аналогично руководства.
/** Зарегистрированные команды */
extern const babbler_cmd_t BABBLER_COMMANDS[] = {
// команды из babbler_cmd_core.h
CMD_HELP,
CMD_PING,
// пользовательские команды
CMD_LEDON,
CMD_LEDOFF
};
/** Количество зарегистрированных команд */
extern const int BABBLER_COMMANDS_COUNT = sizeof(BABBLER_COMMANDS)/sizeof(babbler_cmd_t);
/** Руководства для зарегистрированных команд */
extern const babbler_man_t BABBLER_MANUALS[] = {
// команды из babbler_cmd_core.h
MAN_HELP,
MAN_PING,
// пользовательские команды
MAN_LEDON,
MAN_LEDOFF
};
/** Количество руководств для зарегистрированных команд */
extern const int BABBLER_MANUALS_COUNT = sizeof(BABBLER_MANUALS)/sizeof(babbler_man_t);Сетап и главный цикл без изменений.
void setup() {
Serial.begin(9600);
Serial.println("Starting babbler-powered device, type help for list of commands");
babbler_serial_set_packet_filter(packet_filter_newline);
babbler_serial_set_input_handler(handle_input_simple);
//babbler_serial_setup(
// serial_read_buffer, SERIAL_READ_BUFFER_SIZE,
// serial_write_buffer, SERIAL_WRITE_BUFFER_SIZE,
// 9600);
babbler_serial_setup(
serial_read_buffer, SERIAL_READ_BUFFER_SIZE,
serial_write_buffer, SERIAL_WRITE_BUFFER_SIZE,
BABBLER_SERIAL_SKIP_PORT_INIT);
pinMode(LED_PIN, OUTPUT);
}
void loop() {
// постоянно следим за последовательным портом, ждем входные данные
babbler_serial_tasks();
}Прошиваем, открываем Инструменты → Монитор порта, вводим команды, наблюдаем за лампочкой:
Вживую с железкой:
→ Пример команды с параметрами на самостоятельную работу.
Автор: sadr0b0t
