
USB Radio: подключение и первый обмен
Как подключить USB-радиоадаптер UnitX USB Radio, найти COM-порт, передать первый пакет между двумя адаптерами и найти причину, если приёма нет.
USB Radio подключает программу на компьютере к радиоканалу 868 МГц. Программа передаёт до 61 байта данных в каждом пакете и получает принятые пакеты с уровнем сигнала. Адаптер работает как виртуальный COM-порт, обмен идёт по протоколу UnitX Radio.
Для обмена нужна вторая радиоточка: ещё один USB Radio или встраиваемый радиомодуль в вашем устройстве. В программе модуля задают ту же скорость и тот же канал, что у адаптера. По умолчанию оба работают на канале 10 — 868,9 МГц.
Что понадобится
- два USB Radio или USB Radio и встраиваемый радиомодуль с программой на uLua;
- один или два компьютера со свободными USB-портами;
- Python 3.8 или новее и библиотека pyserial;
- файл
unitx_radio.py— эталонный клиент со страницы протокола.
Адаптер питается от USB.
Исполнения
| Исполнение | С кем работает |
|---|---|
| CC1101 | С любым USB Radio и встраиваемым радиомодулем |
| Si4463 | С любым USB Radio и встраиваемым радиомодулем |
Исполнения CC1101 и Si4463 передают один и тот же радиопакет и работают друг
с другом. Встраиваемый радиомодуль передаёт пакет того же формата. Адаптер связывается с
ним на всех восьми скоростях, если у адаптера пресет той же скорости, что в
radio.init модуля, и тот же канал. Подробнее — в статье
«Совместимость устройств UnitX Radio».
Подключение
Вставьте адаптер в USB-порт и найдите имя порта.
| Система | Где искать | Пример имени |
|---|---|---|
| Windows 10/11 | «Диспетчер устройств» → «Порты (COM и LPT)» | COM5 |
| Linux | ls /dev/ttyACM* до и после подключения | /dev/ttyACM0 |
| macOS | ls /dev/tty.usbmodem* | /dev/tty.usbmodem1101 |
Отдельный драйвер не нужен. Для Windows 7 и 8 установите CDC-драйвер.
В Linux пользователь должен входить в группу dialout:
sudo usermod -aG dialout "$USER" # затем выйдите из системы и войдите снова
Порт может открыть только одна программа. Перед запуском клиента закройте терминал или другую программу, которая работает с этим портом.
Первый пакет между двумя адаптерами
Адаптеры можно подключить к одному компьютеру или к двум. Для первой проверки разнесите их на 2–5 м: вплотную приёмник перегружается сильным сигналом.
Установите pyserial:
python3 -m pip install pyserialСохраните клиент
unitx_radio.pyв рабочую папку.Проверьте, что каждый адаптер отвечает. Подставьте имя своего порта:
python3 unitx_radio.py COM5 statusВ ответе должен быть словарь со строкой
'protocol': 4. Если появилосьTimeoutError, проверьте имя порта и закройте другие программы.Запустите приём на первом адаптере:
python3 unitx_radio.py COM5 listenПередайте сообщение со второго адаптера — во втором окне терминала или на втором компьютере:
python3 unitx_radio.py COM6 send "Привет"Клиент ответит
передано.На первом адаптере появится строка вида:
-52.5 dBm, LQI 12: ПриветУровень сигнала у вас будет другим. Чем ближе RSSI к −110 dBm, тем меньше запас связи.
Клиент перед обменом выбирает пресет 0 — 1,2 кбит/с с проверкой занятости
канала. Чтобы выбрать другой профиль, добавьте --preset N на обеих
сторонах.
Как выбрать радиопрофиль
| Пресет | Скорость | Когда выбирать |
|---|---|---|
| 0 | 1,2 кбит/с | По умолчанию: наибольший запас на расстояние, стены и перекрытия |
| 1, 2 | 2,4 и 4,8 кбит/с | Сообщения чаще, запас ещё большой |
| 3, 4 | 10 и 38 кбит/с | Частые сообщения на небольшом расстоянии |
| 5, 6 | 100 и 250 кбит/с | Стенд и ближняя связь |
| 7 | 500 кбит/с | Только стенд, на канале 0–3 |
Пресеты 8–15 — те же скорости без проверки занятости канала. Они нужны для испытаний, в рабочей системе используйте 0–7. Все пресеты работают на канале 10. Сигнал на 500 кбит/с шире полосы 868,7–869,2 МГц, поэтому для пресета 7 переключите адаптер на канал 0–3. Полная таблица с полосой фильтра и каналами и порядок смены канала — в описании протокола.
Обмен со встраиваемым радиомодулем
Модуль и адаптер обмениваются пакетами, если совпадают скорость и канал.
Например, клиент выбирает пресет 3 — 10 кбит/с, а программа модуля вызывает
radio.init(10000): канал по умолчанию у обоих 10.
python3 unitx_radio.py COM5 listen --preset 3
Если модуль передаёт, в окне клиента появятся его пакеты. Программы для модуля — в руководстве «uLua на радиомодуле».
Клиент в своей программе
Клиент подключается к вашей программе как модуль:
from unitx_radio import UnitXRadio, TX_OK
radio = UnitXRadio("COM5")
radio.set_preset(0) # задавайте пресет при каждом подключении
if radio.send(b"\x12\x01\x20\x07\x01") != TX_OK:
print("не передано: канал занят или ошибка радиочасти")
packet = radio.receive(timeout=5) # (RSSI, LQI, данные) или None
if packet:
rssi, lqi, data = packet
print(rssi, data.hex())
Читайте порт постоянно, например вызывайте receive() в цикле или в
отдельном потоке. Если программа надолго перестаёт читать порт, входящие
пакеты теряются.
Ответ передано значит, что пакет ушёл в эфир. Получил ли его кто-то,
адаптер не знает. Как построить подтверждение и повторы, описано в статье
«Отправлено, принято, выполнено».
Если не работает
| Признак | Причина | Что сделать |
|---|---|---|
| Порт не появляется | Кабель или USB-порт, старая Windows | Подключите напрямую к компьютеру без хаба; для Windows 7/8 установите CDC-драйвер; в Linux проверьте dmesg |
Permission denied в Linux | Нет прав на порт | Добавьте пользователя в группу dialout и войдите заново |
TimeoutError: нет ответа | Неверный порт или порт занят | Проверьте имя порта, закройте терминалы и другие программы |
канал занят, повторите | Эфир занят по CCA, адаптер принимает пакет или принятые данные ещё не прочитаны | Прочитайте входящие пакеты и повторите через 50–200 мс. Если ответ повторяется постоянно, ищите источник помех рядом |
передано, но приёма нет | Разные пресеты или каналы | Задайте одинаковый --preset на обеих сторонах. Для модуля задайте в radio.init ту же скорость и тот же канал |
| Модуль и адаптер связываются на 100 кбит/с, но не на 1,2–10 кбит/с | У одной из сторон нет заводской поправки кварца, и частоты разошлись шире фильтра медленных пресетов | Напишите инженеру: поправку кварца адаптера или модуля записывают заново |
передано, но приёма нет | Адаптеры вплотную, слишком далеко или за металлом | Разнесите на 2–5 м и проверьте; затем увеличивайте расстояние |
Часть пакетов не доходит, растёт счётчик radio_crc_errors в статусе | Слабый сигнал или помеха: адаптер отбрасывает пакеты с ошибкой CRC | Выберите более медленный пресет, переставьте адаптер или антенну |
Адаптер не принимает пакеты устройства, которое раньше работало, и radio_crc_errors не растёт | У одной из сторон прошивка до ноября 2026 года, без перемешивания пакетов | Напишите инженеру, чтобы обновить прошивку |
| Пропадают пакеты при частом обмене | Программа не успевает читать порт, или передачи двух сторон совпадают по времени | Читайте порт без пауз; проверьте счётчик переполнений в статусе; разнесите передачи сторон во времени |
Ограничения
- До 61 байта в каждом пакете. Длинные данные делите на части в своём протоколе.
- Нет подтверждения доставки.
переданоподтверждает только отправку в эфир. Получение подтверждает ответ принимающего приложения. - Нет адресации и шифрования. Адаптер принимает все пакеты своего пресета и канала; адрес и защиту данных задаёт приложение.
- Не пересылает чужие сообщения. Адаптер связывается с радиоточками в зоне приёма. Сеть с промежуточными узлами UnitX Mesh строится из радиомодулей с uLua. Компьютер с USB Radio подключается к ней оконечным узлом: адаптер сам подтверждает кадры для своего адреса, а программа на ПК ищет маршруты и повторяет передачу. Состав сети подбирают по заявке на пилот.
Дальность зависит от профиля, препятствий, высоты установки и помех. Ориентиры для 868 МГц собраны на странице «Дальность и размещение», а проверка на месте описана в статье «Как проверить радиоканал на объекте».