`lora` --- Driver modem LoRa¶

Modul lora menyediakan driver untuk modem LoRa Murata CMWX1ZZABZ pada Arduino Portenta Vision Shield. Modul ini mengekspos kelas Lora tingkat tinggi yang membungkus set perintah AT yang digunakan oleh firmware modem (termasuk firmware Arduino MKRWAN ARD-078) sehingga aplikasi dapat bergabung ke jaringan LoRaWAN dan mengirim/menerima paket.

Contoh:

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)

Konstanta¶

Mode aktivasi¶

lora.MODE_ABP: int¶: Mode Aktivasi Melalui Personalisasi.

lora.MODE_OTAA: int¶: Mode Aktivasi Over-The-Air.

Mode keluaran RF¶

lora.RF_MODE_RFO: int¶: Gunakan keluaran RF RFO (daya rendah) pada modem.

lora.RF_MODE_PABOOST: int¶: Gunakan keluaran RF PA_BOOST (daya tinggi) pada modem.

Pita frekuensi¶

lora.BAND_AS923: int¶: Pita regional AS923 (Asia 923 MHz).

lora.BAND_AU915: int¶: Pita regional AU915 (Australia 915 MHz).

lora.BAND_EU868: int¶: Pita regional EU868 (Eropa 868 MHz).

lora.BAND_KR920: int¶: Pita regional KR920 (Korea 920 MHz).

lora.BAND_IN865: int¶: Pita regional IN865 (India 865 MHz).

lora.BAND_US915: int¶: Pita regional US915 (Amerika Serikat 915 MHz).

lora.BAND_US915_HYBRID: int¶: Rencana regional hibrida US915 (sub-pita).

Kelas perangkat¶

lora.CLASS_A: str¶: Perangkat akhir LoRaWAN Kelas A.

lora.CLASS_B: str¶: Perangkat akhir LoRaWAN Kelas B.

lora.CLASS_C: str¶: Perangkat akhir LoRaWAN Kelas C.

Pengecualian¶

exception lora.LoraError¶: Pengecualian dasar yang dimunculkan untuk setiap kesalahan yang dikembalikan oleh modem atau driver.

exception lora.LoraErrorTimeout¶: Dimunculkan ketika modem tidak merespons dalam batas waktu yang dikonfigurasi (buffer penerimaan kosong).

exception lora.LoraErrorParam¶: Dimunculkan pada respons +ERR_PARAM ketika perintah AT diberikan dengan parameter yang tidak valid.

exception lora.LoraErrorBusy¶: Dimunculkan pada respons +ERR_BUSY ketika modem sibuk memproses perintah sebelumnya.

exception lora.LoraErrorOverflow¶: Dimunculkan pada respons +ERR_PARAM_OVERFLOW ketika sebuah parameter melebihi panjang maksimum yang diizinkan.

exception lora.LoraErrorNoNetwork¶: Dimunculkan pada respons +ERR_NO_NETWORK ketika modem belum bergabung ke jaringan.

exception lora.LoraErrorRX¶: Dimunculkan pada respons +ERR_RX ketika terjadi kesalahan saat menerima downlink.

exception lora.LoraErrorUnknown¶: Dimunculkan pada respons +ERR_UNKNOWN atau ketika modem melaporkan kesalahan yang tidak terdokumentasi.

Kelas¶

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)¶

Membuat driver modem baru. Konstruktor menginisialisasi (atau membuat secara otomatis) pin UART dan reset/boot, mereset modul secara hardware, melakukan sinkronisasi autobaud, me-reboot modul, menanyakan versi firmwarenya, dan mengonfigurasi band regional yang diminta.

Parameter:

uart -- Instance machine.UART yang sudah dikonfigurasi untuk berkomunikasi dengan modem. Jika None, driver membuka UART(8, 19200) dengan framing 8N2 (default Portenta Vision Shield).
rst_pin -- machine.Pin yang menggerakkan jalur reset modem. Jika None, "PC6" dikonfigurasi sebagai keluaran push-pull.
boot_pin -- machine.Pin yang menggerakkan jalur pilih boot modem. Jika None, "PG7" dikonfigurasi sebagai keluaran push-pull yang ditarik rendah.
band -- Pita regional yang akan dikonfigurasi. Salah satu dari konstanta BAND_*.
poll_ms -- Interval dalam milidetik antara uplink kosong otomatis yang dipicu oleh poll() untuk menjaga jendela downlink tetap terbuka.
debug -- Ketika True, semua lalu lintas UART dicetak melalui print().

LoraErrors: dict¶: Pemetaan dari string respons kesalahan modem (misalnya "+ERR_BUSY") ke kelas pengecualian yang sesuai. Digunakan secara internal oleh handle_error().

init_modem() → None¶: Inisialisasi malas self.uart, self.rst_pin dan self.boot_pin ke default Portenta Vision Shield jika belum disetel. Dipanggil dari konstruktor; biasanya tidak dipanggil oleh kode pengguna.

debug_print(data: str) → None¶: Cetak data jika debug diaktifkan saat konstruksi, jika tidak, tidak melakukan apa-apa.

is_arduino_firmware() → bool¶: Kembalikan True jika modem menjalankan firmware Arduino MKRWAN ARD-078 (dideteksi dari string fw_version yang tersimpan).

configure_class(_class: str) → None¶

Konfigurasikan kelas perangkat LoRaWAN.

Parameter:: _class -- Salah satu dari CLASS_A, CLASS_B, CLASS_C.

configure_band(band: int) → bool¶

Konfigurasikan pita regional dan, pada firmware Arduino dengan BAND_EU868, aktifkan pembatas duty-cycle ETSI. Mengembalikan True jika berhasil.

Parameter:: band -- Salah satu dari konstanta BAND_*.

set_baudrate(baudrate: int) → None¶

Ubah laju baud UART modem (AT+UART).

Parameter:: baudrate -- Laju baud baru, dalam bit per detik.

set_autobaud(timeout: int = 10000) → bool¶

Kirim perintah AT kosong hingga modem merespons dengan +OK atau hingga timeout milidetik berlalu. Mengembalikan True jika sinkronisasi berhasil.

Parameter:: timeout -- Waktu maksimum untuk mencoba, dalam milidetik.

get_fw_version() → str¶: Tanyakan string perangkat modem (AT+DEV?) dan versi firmware (AT+VER?) lalu kembalikan keduanya sebagai satu string yang dipisahkan spasi.

get_device_eui() → str¶: Kembalikan EUI Perangkat 64-bit modem sebagai string hex.

factory_default() → None¶: Pulihkan pengaturan pabrik melalui AT+FACNEW.

restart() → None¶: Sinkronisasi ulang laju baud, reboot modem, baca ulang versi firmware, dan terapkan kembali pita regional yang dikonfigurasi. Memunculkan LoraError jika gagal.

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

Konfigurasikan tahap keluaran RF modem (AT+RFPOWER).

Parameter:

mode -- Salah satu dari RF_MODE_RFO, RF_MODE_PABOOST.
power -- Indeks daya keluaran, dalam satuan spesifik firmware.

set_port(port: int) → None¶

Konfigurasikan port aplikasi LoRaWAN (1..223) yang digunakan oleh panggilan send_data() berikutnya.

Parameter:: port -- FPort LoRaWAN.

set_public_network(enable: bool) → None¶

Aktifkan atau nonaktifkan sync word jaringan publik.

Parameter:: enable -- True untuk sync word LoRaWAN publik, False untuk yang privat.

sleep(enable: bool) → None¶: Masukkan modem ke mode tidur daya rendah (True) atau bangunkan (False).

format(hexMode: bool) → None¶

Pilih format data yang digunakan melalui UART untuk byte payload.

Parameter:: hexMode -- True untuk format payload ASCII-hex, False untuk biner mentah.

set_datarate(dr: int) → None¶

Setel indeks laju data LoRaWAN (AT+DR).

Parameter:: dr -- Indeks laju data spesifik region.

get_datarate() → int¶: Kembalikan indeks laju data LoRaWAN saat ini.

set_adr(adr: bool) → None¶

Aktifkan atau nonaktifkan Adaptive Data Rate.

Parameter:: adr -- True untuk mengaktifkan ADR, False untuk menonaktifkannya.

get_adr() → int¶: Kembalikan pengaturan ADR saat ini (1 jika diaktifkan, 0 jika tidak).

get_devaddr() → str¶: Kembalikan DevAddr 32-bit saat ini sebagai string hex.

get_nwk_skey() → str¶: Kembalikan Network Session Key saat ini sebagai string hex.

get_appskey() → str¶: Kembalikan Application Session Key saat ini sebagai string hex.

get_rx2dr() → int¶: Kembalikan indeks laju data yang digunakan untuk jendela penerimaan RX2.

set_rx2dr(dr: int) → None¶

Setel indeks laju data yang digunakan untuk jendela penerimaan RX2.

Parameter:: dr -- Indeks laju data spesifik region.

get_ex2freq() → int¶: Kembalikan frekuensi, dalam Hz, yang digunakan untuk jendela penerimaan RX2.

set_rx2freq(freq: int) → None¶

Setel frekuensi yang digunakan untuk jendela penerimaan RX2.

Parameter:: freq -- Frekuensi dalam Hz.

set_fcu(fcu: int) → None¶

Setel penghitung bingkai uplink (AT+FCU).

Parameter:: fcu -- Nilai penghitung bingkai uplink baru.

get_fcu() → int¶: Kembalikan penghitung bingkai uplink saat ini.

set_fcd(fcd: int) → None¶

Setel penghitung bingkai downlink (AT+FCD).

Parameter:: fcd -- Nilai penghitung bingkai downlink baru.

get_fcd() → int¶: Kembalikan penghitung bingkai downlink saat ini.

change_mode(mode: int) → None¶

Ganti mode aktivasi.

Parameter:: mode -- Salah satu dari MODE_ABP, MODE_OTAA.

join(timeout_ms: int) → bool¶

Keluarkan AT+JOIN dan tunggu event join-accept. Mengembalikan True jika modem melaporkan +EVENT=1,1 (bergabung berhasil) dalam timeout_ms.

Parameter:: timeout_ms -- Waktu maksimum untuk menunggu +ACK dan event join berikutnya, dalam milidetik.

get_join_status() → bool¶: Kembalikan True jika modem saat ini tergabung ke jaringan.

get_max_size() → int¶: Kembalikan ukuran payload LoRaWAN maksimum, dalam byte, untuk laju data saat ini. Pada firmware Arduino ini tetap di 64.

poll() → None¶: Jika lebih dari poll_ms milidetik telah berlalu sejak panggilan terakhir, kirim uplink terkonfirmasi kosong untuk membuang downlink yang tertunda. Dimaksudkan untuk dipanggil secara sering dari loop utama aplikasi.

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

Kirim uplink LoRaWAN. Memunculkan LoraError jika buff lebih besar dari get_max_size().

Parameter:

buff -- Byte payload yang akan dikirim.
confirmed -- Ketika True, kirim uplink terkonfirmasi (+CTX) dan tunggu +ACK dari server jaringan. Ketika False, kirim uplink tidak terkonfirmasi (+UTX).

Kembali:

True jika modem menerima paket (dan, untuk uplink terkonfirmasi, jaringan mengakuinya), False jika tidak.

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

Tunggu downlink. Mengembalikan None jika tidak ada event +RECV yang diterima dalam timeout milidetik, jika tidak sebuah dict {"port": str, "data": str} yang berisi FPort dan byte payload.

Parameter:: timeout -- Waktu maksimum untuk menunggu, dalam milidetik.

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

Baca UART tingkat rendah. Membaca karakter dari modem hingga delimiter cocok, max_bytes karakter telah dibaca, atau timeout milidetik berlalu, kemudian mengembalikan string yang terkumpul dengan \r di akhir dihapus.

Parameter:

delimiter -- Satu karakter tunggal untuk dicocokkan di akhir buffer, string multi-karakter untuk dicocokkan terhadap buffer yang sudah dipangkas secara keseluruhan, atau daftar string semacam itu.
max_bytes -- Jika disetel, kembalikan segera setelah tepat sebanyak ini byte telah dibaca.
timeout -- Batas waktu baca keseluruhan, dalam milidetik.

available() → int¶: Kembalikan jumlah byte yang saat ini tersedia di buffer penerimaan UART modem.

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

Ganti modem ke mode OTAA, program kunci dan EUI yang diberikan, lalu coba bergabung ke jaringan. Mengembalikan True jika bergabung berhasil.

Parameter:

appEui -- Application/Join EUI 64-bit sebagai string hex.
appKey -- Application Key 128-bit sebagai string hex.
devEui -- Device EUI 64-bit opsional sebagai string hex. Jika None, Device EUI yang diprogram pabrik digunakan.
timeout -- Batas waktu bergabung, dalam milidetik.

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

Ganti modem ke mode ABP, program alamat dan kunci yang diberikan, lalu coba bergabung. Mengembalikan hasil dari get_join_status().

Parameter:

nwkId -- Pengidentifikasi jaringan (saat ini diabaikan oleh firmware).
devAddr -- Alamat Perangkat 32-bit sebagai string hex.
nwkSKey -- Network Session Key 128-bit sebagai string hex.
appSKey -- Application Session Key 128-bit sebagai string hex.
timeout -- Batas waktu bergabung, dalam milidetik.

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

Periksa respons modem dan munculkan subkelas LoraError yang cocok jika itu mewakili kesalahan. Tidak melakukan apa-apa untuk respons non-kesalahan.

Parameter:

command -- Perintah AT (tanpa awalan AT) yang menghasilkan data.
data -- String respons yang dikembalikan oleh modem.

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

Bangun perintah AT dari cmd dan args, opsional tambahkan payload data mentah, kirimkan, dan kembalikan respons modem. Untuk perintah kueri yang berakhiran ?, hanya bagian nilai (substring setelah =) yang dikembalikan.

Parameter:

cmd -- Sufiks perintah AT (misalnya "+JOIN", "+DR="); awalan "AT" dan \r di akhir ditambahkan secara otomatis.
args -- Argumen tambahan yang digabungkan ke cmd setelah konversi string.
delimiter -- Delimiter yang diteruskan ke receive().
data -- Byte mentah opsional yang ditulis langsung setelah perintah AT (digunakan untuk payload uplink biner).
timeout -- Batas waktu respons, dalam milidetik.
raise_error -- Ketika True, respons kesalahan dikonversi menjadi pengecualian LoraError; ketika False, respons mentah dikembalikan ke pemanggil.

lora --- Driver modem LoRa¶

Konstanta¶

Mode aktivasi¶

Mode keluaran RF¶

Pita frekuensi¶

Kelas perangkat¶

Pengecualian¶

Kelas¶

`lora` --- Driver modem LoRa¶