Перейти к содержанию
USB Radio: подключение и первый обмен

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
Linuxls /dev/ttyACM* до и после подключения/dev/ttyACM0
macOSls /dev/tty.usbmodem*/dev/tty.usbmodem1101

Отдельный драйвер не нужен. Для Windows 7 и 8 установите CDC-драйвер.

В Linux пользователь должен входить в группу dialout:

sudo usermod -aG dialout "$USER"   # затем выйдите из системы и войдите снова

Порт может открыть только одна программа. Перед запуском клиента закройте терминал или другую программу, которая работает с этим портом.

Первый пакет между двумя адаптерами

Адаптеры можно подключить к одному компьютеру или к двум. Для первой проверки разнесите их на 2–5 м: вплотную приёмник перегружается сильным сигналом.

  1. Установите pyserial:

    python3 -m pip install pyserial
    
  2. Сохраните клиент unitx_radio.py в рабочую папку.

  3. Проверьте, что каждый адаптер отвечает. Подставьте имя своего порта:

    python3 unitx_radio.py COM5 status
    

    В ответе должен быть словарь со строкой 'protocol': 4. Если появилось TimeoutError, проверьте имя порта и закройте другие программы.

  4. Запустите приём на первом адаптере:

    python3 unitx_radio.py COM5 listen
    
  5. Передайте сообщение со второго адаптера — во втором окне терминала или на втором компьютере:

    python3 unitx_radio.py COM6 send "Привет"
    

    Клиент ответит передано.

  6. На первом адаптере появится строка вида:

    -52.5 dBm, LQI 12: Привет
    

    Уровень сигнала у вас будет другим. Чем ближе RSSI к −110 dBm, тем меньше запас связи.

Клиент перед обменом выбирает пресет 0 — 1,2 кбит/с с проверкой занятости канала. Чтобы выбрать другой профиль, добавьте --preset N на обеих сторонах.

Как выбрать радиопрофиль

ПресетСкоростьКогда выбирать
01,2 кбит/сПо умолчанию: наибольший запас на расстояние, стены и перекрытия
1, 22,4 и 4,8 кбит/сСообщения чаще, запас ещё большой
3, 410 и 38 кбит/сЧастые сообщения на небольшом расстоянии
5, 6100 и 250 кбит/сСтенд и ближняя связь
7500 кбит/сТолько стенд, на канале 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 МГц собраны на странице «Дальность и размещение», а проверка на месте описана в статье «Как проверить радиоканал на объекте».

Связанные материалы