lapki-flasher

Модуль загрузчика в составе Lapki IDE. Предоставляет WebSockets-интерфейс для опроса и прошивки совместимых аппаратных платформ.

Поддерживаемые устройства

• Arduino Uno (ATmega328P)
• Arduino Micro (ATmega32U4)
• Arduino Mega (ATmega2560)

Добавление нового устройства

Для того, чтобы добавить шаблон (описание) нового типа устройств, нужно открыть файл device_list.JSON и дополнить его описанием нового устройства.

Описание должно содержать следующие поля:

• ID: уникальный идентификатор шаблона (это именно идентификатор описания, а не самого устройства, он назначается самим разработчиком)
• name: имя устройство (можно написать что угодно, оно не обязтельно должно совпадать с реальным названием устройства)
• productIDs: возможные значения productID, требуется для обнаружения устройства (можно найти через базу данных: https://devicehunt.com/)
• vendorIDs: возможные значения vendorID, требуется для обнаружения устройства (можно найти через базу данных: https://devicehunt.com/)
• controller: контроллер устройства, требуется для avrdude
• programmer: программатор устройства, требуется для avrdude
• bootloaderID: уникальный идентификатор шаблона bootloader (см. раздел "Добавление bootloader") версии устройства, если отсутствует, то значение должно быть равным -1.

Добавление bootloader

Если устройство прошивается через bootloader (как Arduino Micro), то это значит, что оно состоит из двух устройств, каждому из которых необходимо предоставить своё описание, при этом основное устройство должно ссылаться на ID bootloader, а сам bootloader, не должен ссылаться на что-либо (см. описания Arduino Micro и Arduino Micro (bootloader) в файле со списком устройств).

Зависимости

Поддерживаемые ОС:

• Windows 7 и новее
  • Могут понадобиться драйвера для прошиваемых устройств (например, нестандартных Arduino или в Windows 7).
• Linux-дистрибутивы с менеджером Systemd.
  • Для компиляции нужен libusb.
  • Для опроса устройств используется udevadm. Возможна работа с eudev, но это не тестировалось.
• macOS (тестировалось на macOS 13 Ventura).
  • Для опроса устройств используется ioreg.

Также для прошивки потребуется avrdude. В Linux достаточно установить утилиту встроенным пакетным менеджером, под Windows предлагается установить форк от maurisgreuel, положить в рабочую директорию или PATH.

Сборка и разработка

Для сборки требуется компилятор Go версии 1.20 и новее. Перейдите в директорию src и выполните:

go build -mod=mod .

Репозиторий содержит описание пакета для NixOS. Для сборки этого пакета выполните nix-build, для входа в окружение разработки – nix-shell.

Настраиваемые параметры

Некоторые параметры загрузчика можно настроить перед запуском программы, указав их в коммандной строке при запуске модуля:

• -address (string): адресс для подключения (по-умолчанию "localhost:8080").
• -fileSize (int): максимальный размер файла, загружаемого на сервер (в байтах) (по-умолчанию 2097152).
• -listCooldown (int): минимальное время (в секундах), через которое клиент может снова запросить список устройств, игнорируется, если количество клиентов меньше чем 2 (по-умолчанию 2 секунды).
• -msgSize (int): максмальный размер одного сообщения, передаваемого через веб-сокеты (в байтах) (по-умолчанию 1024).
• -thread (int): максимальное количество потоков (горутин) на обработку запросов на одного клиента (по-умолчанию 3).
• -updateList (int): количество секунд между автоматическими обновлениями, не может быть меньше единицы, если получено значение меньше единицы, то оно заменяется на 1 (по-умолчанию 15)
• -verbose: если указан, то программа будет выводить подробное описание того, что она делает.
• -help: вывести описание настраиваемых параметров.
• -alwaysUpdate: всегда искать устройства и обновлять их список, даже когда ни один клиент не подключён (используется для тестирования)
• -stub: количество ненастоящих, симулируемых устройств, которые будут восприниматься как настоящие, применяется для тестирования, при значении 0 или меньше фальшивые устройства не добавляются (по-умолчанию 0)
• -avrdudePath: путь к avrdude (по-умолчанию avrdude, то есть будет использоваться системный путь)
• -configPath: путь к файлу конфигурации avrdude (по-умолчанию '', то есть пустая строка)
• -deviceListPath: путь к JSON-файлу со списком устройств. Если прописан, то заменяет стандартный список устройств, при условии, что не возникнет ошибок, связанных с чтением и открытием JSON-файла, иначе используется стандартный список устройств (по-умолчанию пустая строка, означающая, что будет используется, встроенный в загрузчик список)

Пример: ./lapki-flasher.exe -address localhost:3939 -verbose -updateList 10.

Запуск в качестве сервера

Для размещения загрузчика как сетевого сервиса рекомендуется использовать сервер под управлением Linux-дистрибутива с менеджером Systemd.

На текущий момент репозиторий не предоставляет инструментов для развёртывания, но эта задача решается тривиально.

Самая важная деталь – по умолчанию загрузчик запускается по адресу localhost:8080, что делает его недоступным извне, так как основная задача модуля – работа в фоне Lapki IDE. Поэтому при запуске модуля необходимо указать ключ --address :8080, и открыть соответствующий порт в файрволле.

Пример Systemd-сервиса для запуска загрузчика (путь к загрузчику может быть иной):

[Unit]
Description=Starts lapki-flasher
After=network-online.target

[Service]
ExecStart=/bin/lapki-flasher --address :8080
User=root
Type=simple
Restart=always
RestartSec=3
TimeoutStopSec=5

Альтернативно, можно разместить загрузчик за HTTP-сервером по типу nginx, но при этом следует настроить проксирование WebSocket-канала.

Протокол для общения с клиентом

Клиент и сервер обмениваются сообщениями через веб-сокеты.

Общий вид сообщений

Все сообщения от сервера кодируется через JSON, для обратной коммуникации клиент тоже должен кодировать свои сообщения через JSON, за исключением бинарных данных (см. таблицу "Взаимодействие с загрузчиком").

// Общий вид сообщения на сервер (язык - Golang)
type Event struct {
    // Тип сообщения (flash-start, get-list и т.д.)
    Type string `json:"type"`
    // Параметры сообщения, не все сообщения обязаны иметь параметры
    Payload json.RawMessage `json:"payload"`
}

// аналогичная струтура для TS
class Event {
    constructor(type, payload) {
        this.type = type;
        this.payload = payload;
    }
}

Ниже представлены таблицы с сообщениями, все параметры имеют тип string, если не указано обратное в скобках. Столбец источник указывает на того, кто может отправить данный тип сообщения (клиент или сервер).

Взаимодействие со списком устройств

Взаимодействие с загрузчиком

Сообщения об ошибках от сервера

Serial monitor

МС-ТЮК