lora — LoRa modem sürücüsü#

lora modülü, Arduino Portenta Vision Shield üzerindeki Murata CMWX1ZZABZ LoRa modemi için bir sürücü sağlar. Modem aygıt yazılımının (firmware) kullandığı AT komut kümesini (Arduino MKRWAN ARD-078 aygıt yazılımı dahil) saran üst düzey bir Lora sınıfı sunar; böylece bir uygulama bir LoRaWAN ağına katılabilir ve paket gönderip alabilir.

Örnek:

import lora

modem = lora.Lora(band=lora.BAND_EU868, debug=True)
print("Device EUI:", modem.get_device_eui())
if modem.join_OTAA("0000000000000000", "00000000000000000000000000000000"):
    modem.send_data(b"hello", confirmed=True)

Sabitler#

Etkinleştirme modları#

lora.MODE_ABP: int#

Kişiselleştirme ile Etkinleştirme (Activation By Personalization) modu.

lora.MODE_OTAA: int#

Havadan Etkinleştirme (Over-The-Air Activation) modu.

RF çıkış modları#

lora.RF_MODE_RFO: int#

Modemin RFO (düşük güç) RF çıkışını kullan.

lora.RF_MODE_PABOOST: int#

Modemin PA_BOOST (yüksek güç) RF çıkışını kullan.

Bantlar#

lora.BAND_AS923: int#

AS923 (Asya 923 MHz) bölgesel bandı.

lora.BAND_AU915: int#

AU915 (Avustralya 915 MHz) bölgesel bandı.

lora.BAND_EU868: int#

EU868 (Avrupa 868 MHz) bölgesel bandı.

lora.BAND_KR920: int#

KR920 (Kore 920 MHz) bölgesel bandı.

lora.BAND_IN865: int#

IN865 (Hindistan 865 MHz) bölgesel bandı.

lora.BAND_US915: int#

US915 (Amerika Birleşik Devletleri 915 MHz) bölgesel bandı.

lora.BAND_US915_HYBRID: int#

US915 hibrit (alt bant) bölgesel planı.

Cihaz sınıfları#

lora.CLASS_A: str#

LoRaWAN uç cihazı Sınıf A.

lora.CLASS_B: str#

LoRaWAN uç cihazı Sınıf B.

lora.CLASS_C: str#

LoRaWAN uç cihazı Sınıf C.

İstisnalar#

exception lora.LoraError#

Modem veya sürücü tarafından döndürülen herhangi bir hata için ortaya çıkarılan temel istisna.

exception lora.LoraErrorTimeout#

Modem yapılandırılmış zaman aşımı içinde yanıt vermediğinde (alma arabelleği boştur) ortaya çıkarılır.

exception lora.LoraErrorParam#

Bir AT komutu geçersiz bir parametreyle gönderildiğinde gelen +ERR_PARAM yanıtında ortaya çıkarılır.

exception lora.LoraErrorBusy#

Modem önceki bir komutu işlemekle meşgulken gelen +ERR_BUSY yanıtında ortaya çıkarılır.

exception lora.LoraErrorOverflow#

Bir parametre izin verilen maksimum uzunluğu aştığında gelen +ERR_PARAM_OVERFLOW yanıtında ortaya çıkarılır.

exception lora.LoraErrorNoNetwork#

Modem bir ağa katılmamışken gelen +ERR_NO_NETWORK yanıtında ortaya çıkarılır.

exception lora.LoraErrorRX#

Bir downlink alınırken hata oluştuğunda gelen +ERR_RX yanıtında ortaya çıkarılır.

exception lora.LoraErrorUnknown#

+ERR_UNKNOWN yanıtında veya modem belgelenmemiş bir hata bildirdiğinde ortaya çıkarılır.

Sınıflar#

class lora.Lora(uart: machine.UART | None = None, rst_pin: machine.Pin | None = None, boot_pin: machine.Pin | None = None, band: int = BAND_EU868, poll_ms: int = 300000, debug: bool = False)#

Yeni bir modem sürücüsü oluşturur. Yapıcı (constructor), UART ile reset/boot pinlerini başlatır (veya otomatik oluşturur), modülü donanım olarak sıfırlar, otomatik baud senkronizasyonu yapar, modülü yeniden başlatır, aygıt yazılımı sürümünü sorgular ve istenen bölgesel band değerini yapılandırır.

Parametreler:

  • uart – Modemle iletişim kurmak için kullanılan önceden yapılandırılmış machine.UART örneği. None ise sürücü, UART(8, 19200) bağlantısını 8N2 çerçevelemeyle (Portenta Vision Shield varsayılanı) açar.

  • rst_pin – Modemin reset hattını süren machine.Pin. None ise "PC6" push-pull çıkış olarak yapılandırılır.

  • boot_pin – Modemin boot-select hattını süren machine.Pin. None ise "PG7" düşük seviyeye çekilmiş push-pull çıkış olarak yapılandırılır.

  • band – Yapılandırılacak bölgesel bant. BAND_* sabitlerinden biri.

  • poll_ms – Downlink penceresini açık tutmak için poll() tarafından tetiklenen otomatik boş uplink’ler arasındaki milisaniye cinsinden aralık.

  • debug – True olduğunda tüm UART trafiği print() aracılığıyla yazdırılır.

LoraErrors: dict#

Modem hata yanıtı dizelerinden (ör. "+ERR_BUSY") ilgili istisna sınıfına eşleme. handle_error() tarafından dahili olarak kullanılır.

init_modem() → None#

self.uart, self.rst_pin ve self.boot_pin henüz ayarlanmamışsa bunları Portenta Vision Shield varsayılanlarına tembel olarak başlatır. Yapıcıdan çağrılır; normalde kullanıcı kodu tarafından çağrılmaz.

debug_print(data: str) → None#

Yapım sırasında debug etkinleştirilmişse data değerini yazdırır, aksi takdirde hiçbir şey yapmaz.

is_arduino_firmware() → bool#

Modem Arduino MKRWAN ARD-078 aygıt yazılımını çalıştırıyorsa (önbelleğe alınmış fw_version dizesinden tespit edilir) True döndürür.

configure_class(_class: str) → None#

LoRaWAN cihaz sınıfını yapılandırır.

Parametreler:

_class – CLASS_A, CLASS_B, CLASS_C değerlerinden biri.

configure_band(band: int) → bool#

Bölgesel bandı yapılandırır ve BAND_EU868 ile Arduino aygıt yazılımında ETSI çalışma oranı sınırlayıcısını etkinleştirir. Başarılı olduğunda True döndürür.

Parametreler:

band – BAND_* sabitlerinden biri.

set_baudrate(baudrate: int) → None#

Modemin UART baud hızını değiştirir (AT+UART).

Parametreler:

baudrate – Saniyede bit cinsinden yeni baud hızı.

set_autobaud(timeout: int = 10000) → bool#

Modem +OK ile yanıt verene veya timeout milisaniye geçene kadar boş AT komutları gönderir. Senkronizasyon başarılı olursa True döndürür.

Parametreler:

timeout – Denemeye harcanacak milisaniye cinsinden maksimum süre.

get_fw_version() → str#

Modem cihaz dizesini (AT+DEV?) ve aygıt yazılımı sürümünü (AT+VER?) sorgular ve bunları tek bir boşlukla ayrılmış dize olarak döndürür.

get_device_eui() → str#

Modemin 64-bit Device EUI değerini bir onaltılık dize olarak döndürür.

factory_default() → None#

AT+FACNEW aracılığıyla fabrika varsayılanlarını geri yükler.

restart() → None#

Baud hızını yeniden senkronize eder, modemi yeniden başlatır, aygıt yazılımı sürümünü yeniden okur ve yapılandırılmış bölgesel bandı yeniden uygular. Başarısızlıkta LoraError ortaya çıkarır.

set_rf_power(mode: int, power: int) → None#

Modem RF çıkış katını yapılandırır (AT+RFPOWER).

Parametreler:

  • mode – RF_MODE_RFO, RF_MODE_PABOOST değerlerinden biri.

  • power – Aygıt yazılımına özgü birimlerde çıkış gücü indeksi.

set_port(port: int) → None#

Sonraki send_data() çağrıları tarafından kullanılan LoRaWAN uygulama portunu (1..223) yapılandırır.

Parametreler:

port – LoRaWAN FPort.

set_public_network(enable: bool) → None#

Genel ağ senkronizasyon sözcüğünü etkinleştirir veya devre dışı bırakır.

Parametreler:

enable – Genel LoRaWAN senkronizasyon sözcüğü için True, özel olanı için False.

sleep(enable: bool) → None#

Modemi düşük güçlü uyku moduna alır (True) veya uyandırır (False).

format(hexMode: bool) → None#

Yük baytları için UART üzerinden kullanılan veri biçimini seçer.

Parametreler:

hexMode – ASCII-onaltılık yük biçimi için True, ham ikili için False.

set_datarate(dr: int) → None#

LoRaWAN veri hızı indeksini ayarlar (AT+DR).

Parametreler:

dr – Bölgeye özgü veri hızı indeksi.

get_datarate() → int#

Geçerli LoRaWAN veri hızı indeksini döndürür.

set_adr(adr: bool) → None#

Adaptif Veri Hızı’nı (Adaptive Data Rate) etkinleştirir veya devre dışı bırakır.

Parametreler:

adr – ADR’yi etkinleştirmek için True, devre dışı bırakmak için False.

get_adr() → int#

Geçerli ADR ayarını döndürür (etkinse 1, aksi halde 0).

get_devaddr() → str#

Geçerli 32-bit DevAddr değerini bir onaltılık dize olarak döndürür.

get_nwk_skey() → str#

Geçerli Network Session Key değerini bir onaltılık dize olarak döndürür.

get_appskey() → str#

Geçerli Application Session Key değerini bir onaltılık dize olarak döndürür.

get_rx2dr() → int#

RX2 alma penceresi için kullanılan veri hızı indeksini döndürür.

set_rx2dr(dr: int) → None#

RX2 alma penceresi için kullanılan veri hızı indeksini ayarlar.

Parametreler:

dr – Bölgeye özgü veri hızı indeksi.

get_ex2freq() → int#

RX2 alma penceresi için kullanılan frekansı Hz cinsinden döndürür.

set_rx2freq(freq: int) → None#

RX2 alma penceresi için kullanılan frekansı ayarlar.

Parametreler:

freq – Hz cinsinden frekans.

set_fcu(fcu: int) → None#

Uplink çerçeve sayacını ayarlar (AT+FCU).

Parametreler:

fcu – Yeni uplink çerçeve sayacı değeri.

get_fcu() → int#

Geçerli uplink çerçeve sayacını döndürür.

set_fcd(fcd: int) → None#

Downlink çerçeve sayacını ayarlar (AT+FCD).

Parametreler:

fcd – Yeni downlink çerçeve sayacı değeri.

get_fcd() → int#

Geçerli downlink çerçeve sayacını döndürür.

change_mode(mode: int) → None#

Etkinleştirme modunu değiştirir.

Parametreler:

mode – MODE_ABP, MODE_OTAA değerlerinden biri.

join(timeout_ms: int) → bool#

Bir AT+JOIN komutu verir ve katılma-kabul (join-accept) olayını bekler. Modem timeout_ms içinde +EVENT=1,1 bildirirse (katılma başarılı) True döndürür.

Parametreler:

timeout_ms – Hem +ACK hem de sonraki katılma olayı için beklenecek milisaniye cinsinden maksimum süre.

get_join_status() → bool#

Modem şu anda bir ağa katılmışsa True döndürür.

get_max_size() → int#

Geçerli veri hızı için bayt cinsinden maksimum LoRaWAN yük boyutunu döndürür. Arduino aygıt yazılımında bu değer 64 olarak sabittir.

poll() → None#

Son çağrıdan bu yana poll_ms milisaniyeden fazla geçtiyse, bekleyen downlink’leri boşaltmak için boş bir onaylı uplink gönderir. Uygulamanın ana döngüsünden sık sık çağrılmak üzere tasarlanmıştır.

send_data(buff: bytes, confirmed: bool = True) → bool#

Bir LoRaWAN uplink iletir. buff, get_max_size() değerinden büyükse LoraError ortaya çıkarır.

Parametreler:

  • buff – İletilecek yük baytları.

  • confirmed – True olduğunda onaylı bir uplink (+CTX) gönderir ve bir ağ sunucusu +ACK bekler. False olduğunda onaysız bir uplink (+UTX) gönderir.

Dönüşler:

Modem paketi kabul ettiyse (ve onaylı uplink’ler için ağ onayladıysa) True, aksi halde False.

receive_data(timeout: int = 1000) → dict | None#

Bir downlink bekler. timeout milisaniye içinde herhangi bir +RECV olayı alınmadıysa None, aksi halde FPort ile yük baytlarını içeren {"port": str, "data": str} sözlüğünü döndürür.

Parametreler:

timeout – Milisaniye cinsinden beklenecek maksimum süre.

receive(delimiter: str | list | None = None, max_bytes: int | None = None, timeout: int = 1000) → str#

Düşük seviyeli UART okuması. Bir sınırlayıcı eşleşene, max_bytes karakter okunana veya timeout milisaniye geçene kadar modemden karakter okur, ardından sondaki \r kırpılmış biriktirilen dizeyi döndürür.

Parametreler:

  • delimiter – Arabelleğin sonunda eşleştirilecek tek bir karakter, tam kırpılmış arabellekle eşleştirilecek çok karakterli bir dize veya bu tür dizelerden oluşan bir liste.

  • max_bytes – Ayarlanmışsa, tam olarak bu kadar bayt okunur okunmaz döner.

  • timeout – Milisaniye cinsinden genel okuma zaman aşımı.

available() → int#

Modemin UART alma arabelleğinde şu anda mevcut olan bayt sayısını döndürür.

join_OTAA(appEui: str, appKey: str, devEui: str = None, timeout: int = 60000) → bool#

Modemi OTAA moduna geçirir, verilen anahtarları ve EUI’leri programlar, ardından ağa katılmayı dener. Katılma başarılı olursa True döndürür.

Parametreler:

  • appEui – Onaltılık dize olarak 64-bit Application/Join EUI.

  • appKey – Onaltılık dize olarak 128-bit Application Key.

  • devEui – Onaltılık dize olarak isteğe bağlı 64-bit Device EUI. None ise fabrikada programlanmış Device EUI kullanılır.

  • timeout – Milisaniye cinsinden katılma zaman aşımı.

join_ABP(nwkId: int, devAddr: str, nwkSKey: str, appSKey: str, timeout: int = 60000) → bool#

Modemi ABP moduna geçirir, verilen adresleri ve anahtarları programlar, ardından katılmayı dener. get_join_status() sonucunu döndürür.

Parametreler:

  • nwkId – Ağ tanımlayıcısı (şu anda aygıt yazılımı tarafından yok sayılır).

  • devAddr – Onaltılık dize olarak 32-bit Device Address.

  • nwkSKey – Onaltılık dize olarak 128-bit Network Session Key.

  • appSKey – Onaltılık dize olarak 128-bit Application Session Key.

  • timeout – Milisaniye cinsinden katılma zaman aşımı.

handle_error(command: str, data: str) → None#

Bir modem yanıtını inceler ve bir hatayı temsil ediyorsa eşleşen LoraError alt sınıfını ortaya çıkarır. Hata olmayan yanıtlar için hiçbir şey yapmaz.

Parametreler:

  • command – data üreten AT komutu (AT öneki olmadan).

  • data – Modem tarafından döndürülen yanıt dizesi.

send_command(cmd: str, *args, delimiter: str = '\\r', data: bytes = None, timeout: int = 1000, raise_error: bool = True) → str#

cmd ve args değerlerinden bir AT komutu oluşturur, isteğe bağlı olarak ham bir data yükü ekler, iletir ve modemin yanıtını döndürür. ? ile biten sorgu komutları için yalnızca değer kısmı (= işaretinden sonraki alt dize) döndürülür.

Parametreler:

  • cmd – AT komut soneki (ör. "+JOIN", "+DR="); "AT" öneki ve sondaki \r otomatik olarak eklenir.

  • args – Dize dönüşümünden sonra cmd değerine eklenen ek argümanlar.

  • delimiter – receive() öğesine iletilen sınırlayıcı.

  • data – AT komutundan hemen sonra yazılan isteğe bağlı ham baytlar (ikili uplink yükleri için kullanılır).

  • timeout – Milisaniye cinsinden yanıt zaman aşımı.

  • raise_error – True olduğunda hata yanıtları LoraError istisnalarına dönüştürülür; False olduğunda ham yanıt çağırana döndürülür.