Alex
192 lines
10 KiB
Markdown
192 lines
10 KiB
Markdown
|
||
|
||
# Gyver433
|
||
Библиотека для радиомодулей 433 МГц и Arduino
|
||
- Поддержка кривых китайских модулей
|
||
- Встроенный CRC контроль целостности
|
||
- Ускоренный алгоритм IO для AVR Arduino
|
||
- Асинхронный приём в прерывании
|
||
- Супер лёгкая либа, заведётся даже на тини13
|
||
|
||
### Совместимость
|
||
Совместима со всеми Arduino платформами (используются Arduino-функции)
|
||
- При подключении прерывания на esp8266 не забудь аттрибут `IRAM_ATTR`
|
||
|
||
## Содержание
|
||
- [Установка](#install)
|
||
- [Интерфейс](#interface)
|
||
- [Подключение](#wiring)
|
||
- [Инициализация](#init)
|
||
- [Использование](#usage)
|
||
- [Пример](#example)
|
||
- [Версии](#versions)
|
||
- [Баги и обратная связь](#feedback)
|
||
|
||
<a id="install"></a>
|
||
## Установка
|
||
- Библиотеку можно найти по названию **Gyver433** и установить через менеджер библиотек в:
|
||
- Arduino IDE
|
||
- Arduino IDE v2
|
||
- PlatformIO
|
||
- [Скачать библиотеку](https://github.com/GyverLibs/Gyver433/archive/refs/heads/main.zip) .zip архивом для ручной установки:
|
||
- Распаковать и положить в *C:\Program Files (x86)\Arduino\libraries* (Windows x64)
|
||
- Распаковать и положить в *C:\Program Files\Arduino\libraries* (Windows x32)
|
||
- Распаковать и положить в *Документы/Arduino/libraries/*
|
||
- (Arduino IDE) автоматическая установка из .zip: *Скетч/Подключить библиотеку/Добавить .ZIP библиотеку…* и указать скачанный архив
|
||
- Читай более подробную инструкцию по установке библиотек [здесь](https://alexgyver.ru/arduino-first/#%D0%A3%D1%81%D1%82%D0%B0%D0%BD%D0%BE%D0%B2%D0%BA%D0%B0_%D0%B1%D0%B8%D0%B1%D0%BB%D0%B8%D0%BE%D1%82%D0%B5%D0%BA)
|
||
|
||
<a id="interface"></a>
|
||
## Интерфейс
|
||
- Перед отправкой данных идёт синхронизирующий импульс, *TRAIN* мс
|
||
- Далее старт импульс, *START* мс, LOW
|
||
- Данные кодируются длиной импульса
|
||
- Завершает отправку стоп импульс, *TRAIN* мс
|
||
|
||
|
||
|
||
<a id="wiring"></a>
|
||
## Подключение
|
||
|
||
Передатчики:
|
||
- SYN115, маленький чип: 1.8-3.6V, макс. скорость 8000
|
||
- FS1000A: 3-12V, макс. скорость 10000
|
||
- WL102-341: 2.0-3.6V, макс. скорость 6000
|
||
|
||
Приёмники:
|
||
- SYN480R, крупный чип: 3.3-5.5V
|
||
- MX-RM-5V (RF-5V): 5V
|
||
- RX470 (WL101-341): 3-5V
|
||
|
||
|
||
|
||
|
||
<a id="init"></a>
|
||
## Инициализация
|
||
```cpp
|
||
// === ПЕРЕДАТЧИК ===
|
||
Gyver433_TX<пин> tx;
|
||
Gyver433_TX<пин, CRC> tx;
|
||
|
||
// === ПРИЁМНИК ===
|
||
Gyver433_RX<пин> rx;
|
||
Gyver433_RX<пин, буфер> rx;
|
||
Gyver433_RX<пин, буфер, CRC> rx;
|
||
|
||
// пин: цифровой пин
|
||
// буфер: размер буфера в байтах, по умолч. 64
|
||
// CRC: проверка целостности данных: G433_CRC8 (надёжный), G433_XOR (лёгкий), G433_NOCRC (отключено). По умолч. G433_CRC8
|
||
```
|
||
|
||
<a id="usage"></a>
|
||
## Использование
|
||
```cpp
|
||
// ========= Gyver433_TX =========
|
||
void sendData(T &data); // отправить данные любого типа (CRC добавляется автоматически)
|
||
void write(uint8_t* buf, uint8_t size); // отправить массив байт указанного размера (CRC не добавляется)
|
||
|
||
// ========= Gyver433_RX =========
|
||
// приём в прерывании
|
||
void tickISR(); // тикер приёма для вызова в прерывании по CHANGE
|
||
uint8_t tickISRraw(); // ручной приём в прерывании по CHANGE. Вернёт 1 (начало приёма), 2 (принят байт), 3 (конец пакета)
|
||
|
||
// приём в loop
|
||
uint16_t tick(); // неблокирующий приём. Вернёт количество успешно принятых байт
|
||
uint16_t tickWait(); // блокирующий приём. Вернёт количество успешно принятых байт
|
||
|
||
bool readData(T &data); // прочитает буфер в любой тип данных (в указанную переменную)
|
||
uint16_t getSize(); // получить размер принятых данных
|
||
uint16_t gotData(); // вернёт количество успешно принятых в tickISR() байт (см. пример isr_rx)
|
||
uint8_t getRSSI(); // получить качество приёма (процент успешных передач 0.. 100)
|
||
|
||
uint8_t buffer[]; // доступ к буферу приёма
|
||
uint8_t byteBuf; // доступ к буферу принятого байта
|
||
|
||
// ============= CRC =============
|
||
// можно использовать встроенные функции для генерации байта CRC для ручной упаковки пакетов
|
||
uint8_t G433_crc8(uint8_t *buffer, uint8_t size); // ручной CRC8
|
||
uint8_t G433_crc_xor(uint8_t *buffer, uint8_t size); // ручной CRC XOR
|
||
|
||
// ====== ДЕФАЙНЫ-НАСТРОЙКИ ======
|
||
// вызывать перед подключением библиотеки
|
||
#define G433_FAST // [TX] короткая синхронизация для зелёных модулей
|
||
#define G433_MEDIUM // [TX] средняя синхронизация при отправке на SYN480R ЧАЩЕ 400мс (активно по умолчанию)
|
||
#define G433_SLOW // [TX] длинная синхронизация при отправке на SYN480R РЕЖЕ 400мс
|
||
#define G433_SPEED 1000 // [RX/TX] скорость, должна быть одинакова на RX и TX, 100-10000 бит/с, по умолч. 2000 бит/с
|
||
#define G433_RSSI_COUNT 8 // [RX] количество успешно принятых пакетов для расчёта RSSI (по умолч. 8)
|
||
#define G433_CUT_RSSI // [RX] убрать расчёт RSSI из кода (сэкономит чуть памяти)
|
||
```
|
||
|
||
### Работа приёмника без прерываний
|
||
Для приёма данных достаточно вызывать в основном цикле метод `tick()`, он сам опрашивает пин радио.
|
||
- Если в программе есть блокирующие места и loop() выполняется с задержками - будет потеря данных
|
||
- Для более надёжного приёма рекомендуется вызывать `tickWait()`, она блокирует выполнение кода на время приёма.
|
||
|
||
### Работа приёмника с прерываниями
|
||
Рекомендуется использовать приём в прерывании по CHANGE, для этого нужно вызывать в нём `tickISR()`.
|
||
Тогда приём будет асинхронный и будет работать даже в загруженной программе.
|
||
- Если стандартных пинов прерываний не хватает, можно задействовать PCINT. Вручную или с помощью библиотеки https://github.com/NicoHood/PinChangeInterrupt
|
||
|
||
<a id="example"></a>
|
||
## Примеры
|
||
Остальные примеры смотри в **examples**!
|
||
### Отправка
|
||
```cpp
|
||
#include <Gyver433.h>
|
||
Gyver433_TX<2> tx; // указали пин
|
||
|
||
void setup() {
|
||
}
|
||
|
||
char data[] = "Hello from #xx"; // строка для отправки
|
||
byte count = 0; // счётчик для отправки
|
||
|
||
void loop() {
|
||
// добавляем счётчик в строку
|
||
data[12] = (count / 10) + '0';
|
||
data[13] = (count % 10) + '0';
|
||
if (++count >= 100) count = 0;
|
||
tx.sendData(data);
|
||
delay(100);
|
||
}
|
||
```
|
||
|
||
### Приём в прерывании
|
||
```cpp
|
||
#include <Gyver433.h>
|
||
Gyver433_RX<2, 20> rx; // указали пин и размер буфера
|
||
|
||
void setup() {
|
||
Serial.begin(9600);
|
||
attachInterrupt(0, isr, CHANGE); // прерывание пина радио по CHANGE
|
||
}
|
||
|
||
// спец. тикер вызывается в прерывании
|
||
void isr() {
|
||
rx.tickISR();
|
||
}
|
||
|
||
void loop() {
|
||
if (rx.gotData()) { // если успешно принято больше 0
|
||
Serial.write(rx.buffer, rx.size); // выводим
|
||
Serial.println();
|
||
}
|
||
delay(50); // имитация загруженного кода
|
||
}
|
||
```
|
||
|
||
<a id="versions"></a>
|
||
## Версии
|
||
- v1.0
|
||
- v1.1 - оптимизация, новый интерфейс, поддержка дешёвых синих модулей, работа в прерывании
|
||
- v1.2 - улучшение качества связи, оптимизация работы в прерывании
|
||
- v1.3 - добавлен вывод RSSI
|
||
- v1.4 - переделан FastIO
|
||
- v1.4.1 - убран FastIO, CRC вынесен отдельно
|
||
- v2.0 - убран буфер на отправку, убран манчестер, полностью переделан и оптимизирован интерфейс связи
|
||
- v2.0.1 - fix compiler warnings
|
||
|
||
<a id="feedback"></a>
|
||
## Баги и обратная связь
|
||
При нахождении багов создавайте **Issue**, а лучше сразу пишите на почту [alex@alexgyver.ru](mailto:alex@alexgyver.ru)
|
||
Библиотека открыта для доработки и ваших **Pull Request**'ов!
|