module-api

Цель этого руководства — написание новых основных модулей, которые могут запускаться на устройстве. В большинстве случаев лучше начать с использования последовательного модуля, а не создания нового. Однако, если вы заинтересованы в создании новой основной функциональности с нуля, то создание модуля будет подходящим.

Ключевые концепции

Все модули должны быть подклассами MeshModule. Наследуя от этого класса и создавая экземпляр вашего нового модуля — ваш модуль будет автоматически зарегистрирован для получения пакетов.

Сообщения отправляются на конкретные номера портов (аналогично UDP-сетям). Ваш новый модуль в конечном итоге должен выбрать свой собственный номер порта (см. ниже). Для разработки вы можете просто использовать PRIVATE_APP (который является значением по умолчанию).

Пакеты могут отправляться и получаться как:

Сырые бинарные структуры
Protobufs.

Иерархия классов

Обычно вы захотите наследовать от SinglePortModule (если вы просто отправляете/получаете сырые байты) или ProtobufModule (если вы отправляете/получаете protobufs). Вы реализуете свой собственный handleReceived/handleReceivedProtobuf — вероятно, на основе примера кода.

Релевантные части иерархии классов следующие:

Первый уровень: MeshModule

src/mesh/MeshModule.h — вы, вероятно, не захотите использовать этот базовый класс напрямую.

Второй уровень: SinglePortModule

src/mesh/SinglePortModule.h — для модулей, которые отправляют/получают с одного номера порта (нормальный случай).

Третий уровень: ProtobufModule

src/mesh/ProtobufModule.h — для модулей, которые отправляют/получают один конкретный тип Protobuf. Наследуйте от этого, если вы используете протокол буферы в вашем модуле.

Операции запуска

Если вашему модулю нужно выполнить какие-либо операции при запуске, вы можете переопределить и реализовать метод setup(), чтобы запустить ваш код.

Если вам нужно отправить пакет, вы можете вызвать service.sendToMesh с кодом вроде этого (из примеров):

MeshPacket *p = allocReply();
p->to = dest;

service.sendToMesh(p);

Примерные модули

Несколько ключевых сервисов реализованы с использованием API модулей. Эти модули следующие:

TextMessageModule — Получает текстовые сообщения и отображает их на экране LCD/хранит их в локальной БД.
NodeInfoModule — Получает/отправляет информацию о пользователе другим узлам, чтобы имена пользователей были доступны в базах данных.
GenericThreadModule — Пример модуля, который периодически выполняется, например, для отправки сообщения в mesh.
RemoteHardwareModule — Модуль, который предоставляет простой удалённый доступ к аппаратному обеспечению устройства (для таких вещей, как включение или выключение GPIO). Предназначен для более подробного примера и предоставления полезной собственной функции. См. remote-hardware для деталей.
ReplyModule — Простой модуль, который просто отвечает на любой полученный пакет (предоставляет сервис 'ping').

Начало работы

Самый простой способ начать:

Собрать кодовую базу прошивки.
Скопировать ReplyModule как шаблон в src/modules/. shell cp src/modules/ReplyModule.* src/modules/YourModule.*
Изменить номер порта с meshtastic_PortNum_REPLY_APP на номер порта, который вы хотите использовать для ваших данных. Чтобы протестировать с текстовыми сообщениями, используйте meshtastic_PortNum_TEXT_MESSAGE_APP.
Отредактировать функцию setupModules(), расположенную в modules/Modules.cpp, чтобы добавить вызов для создания экземпляра вашего модуля (см. комментарий в начале этой функции).
Пересобрать с вашим новым модулем и установить на устройство.
Отправить пакет с вашим номером порта на узел, чтобы проверить, вызывается ли ваш модуль. Если вы использовали номер порта текстовых сообщений, вы можете использовать любое из клиентских приложений для отправки текстового сообщения.

Получение ответа

allocReply() из ReplyModule вызывается только когда входящий пакет устанавливает want_response = true. Внутренне MeshModule::sendResponse() вызывает ваш allocReply(). Большинство чатовых UI (Android/iOS/Web) не устанавливают этот флаг, поэтому копирование ReplyModule и отправка обычного текста не вызовет ответа от вашего модуля.

Для начального тестирования реализуйте handleReceived(), чтобы ваш код запускался на каждом пакете на ваш порт. Для минимальных изменений от кода шаблона протестируйте allocReply() с клиентом, который может установить want_response = true.

Потоки

Очень часто вы хотите, чтобы ваш модуль вызывался периодически. Мы используем простую/базовую кооперативную систему потоков, чтобы позволить это на любой из поддерживаемых платформ. Простой пример модуля, который использует это, — GenericThreadModule (обратите внимание, что его нужно включить, удалив макрос MESHTASTIC_EXCLUDE_GENERIC_THREAD_MODULE). В противном случае просто наследуйте ваш модуль от OSThread и реализуйте runOnce(). См. документацию OSThread для получения дополнительных деталей.

Отправка сообщений

Если вы хотите проактивно отправлять сообщения (а не просто отвечать на них), просто вызовите service.sendToMesh(). Для примера см. NodeInfoModule::sendOurNodeInfo(...).

Выбор номера порта

См. Номера портов Meshtastic

Как добавить пользовательские протокол буферы

Если вы хотите использовать протокол буферы для определения структур, которые вы отправляете по mesh (рекомендуется), вот как это сделать.

Создать новый файл .proto в директории protos.
Запустить ./bin/regen-protos.sh, чтобы перегенерировать C-код для доступа к протокол буферам. Если у вас нет требуемого инструмента nanopb, следуйте инструкциям, выводимым скриптом, чтобы его получить.
Готово! Теперь вы можете использовать ваш новый protobuf так же, как любой из существующих protobuf в Meshtastic.