Module lora_radio

Expand description

The C ABI for a LoRa radio on a Linux board, or on a simulated chip anywhere.

These functions open an SX126x or SX127x module through the kernel’s spidev and GPIO character devices, as [pamoja_radios::linux] does, and drive either family with the same calls: configure, transmit, receive, listen, standby, sleep, and a register read and write. A radio holds its device files open between calls, so it crosses the boundary as a handle the caller releases with pamoja_lora_radio_free.

Only Linux has those devices. On every other platform the header and the functions are the same, and opening a radio returns PamojaStatus::Unsupported with a message saying why.

A simulated chip, PamojaLoraSimChip, stands in for a module on any platform. The radio pamoja_lora_sim_chip_radio gives drives it with the same calls, while the caller says what arrives on the air and reads back what the chip was tuned to and what it sent.

Each call blocks until the chip answers: a transmission for its airtime, a reception for its timeout. A caller with an event loop makes these calls from a worker thread, and a handle is used by one thread at a time.

Structs§

PamojaLoraRadio: A LoRa radio opened on a Linux board or wired to a simulated chip, released with pamoja_lora_radio_free.
PamojaLoraRadioConfig: What a radio of either family sends and listens with.
PamojaLoraRadioReception: How a reception ended, with the frame’s signal levels when one arrived.
PamojaLoraSimChip: A simulated SX126x or SX127x, released with pamoja_lora_sim_chip_free.
PamojaLoraTuning: What a simulated chip is tuned to.
PamojaSx126xBoard: How a module wires its SX126x.

Constants§

PAMOJA_LORA_RADIO_CORRUPT: A reception outcome: a frame arrived whose header or CRC failed its check, and was dropped.
PAMOJA_LORA_RADIO_DEFAULT_SPI_HZ: The SPI clock a radio opens at when the call passes 0, in hertz.
PAMOJA_LORA_RADIO_FRAME: A reception outcome: a frame arrived and checked.
PAMOJA_LORA_RADIO_NOTHING: A reception outcome: nothing has arrived since the last frame was taken.
PAMOJA_LORA_RADIO_SX126X: The family of an SX1261, SX1262, SX1268, or LLCC68.
PAMOJA_LORA_RADIO_SX127X: The family of an SX1276, SX1277, SX1278, or SX1279.
PAMOJA_LORA_RADIO_SYNC_WORD_PRIVATE: The sync word of a private network, and both families’ reset value.
PAMOJA_LORA_RADIO_SYNC_WORD_PUBLIC: The sync word of a public network such as LoRaWAN.
PAMOJA_LORA_RADIO_TIMEOUT: A reception outcome: no frame arrived before the timeout.

Functions§

pamoja_lora_radio_config_default: Returns a configuration with a private sync word, standard IQ both ways, and an SX126x calibrating for the carrier alone.
pamoja_lora_radio_configure^⚠: Tunes a radio to a configuration.
pamoja_lora_radio_detect^⚠: Listens a few symbols for a LoRa preamble and reports whether one is there, as a relay’s scan does, leaving the chip in standby.
pamoja_lora_radio_family^⚠: Returns the family of a radio’s chip.
pamoja_lora_radio_free^⚠: Closes a radio’s device files and releases it.
pamoja_lora_radio_listen^⚠: Starts listening, frame after frame, until another call changes the mode.
pamoja_lora_radio_open_sx126x^⚠: Opens an SX1261, SX1262, SX1268, or LLCC68 module on a Linux board and resets it.
pamoja_lora_radio_open_sx127x^⚠: Opens an SX1276, SX1277, SX1278, or SX1279 module on a Linux board, such as an RFM95W, and resets it into LoRa mode.
pamoja_lora_radio_random^⚠: Draws a random number from the noise a radio’s receiver hears, leaving the chip in standby.
pamoja_lora_radio_read_register^⚠: Reads one register of a radio’s chip.
pamoja_lora_radio_receive^⚠: Listens for one frame.
pamoja_lora_radio_sleep^⚠: Puts a radio to sleep until the next call wakes it. An SX126x is configured again before its next frame; an SX127x keeps its registers.
pamoja_lora_radio_standby^⚠: Puts a radio in standby, which stops a transmission or a reception.
pamoja_lora_radio_take_frame^⚠: Takes the frame a listening radio has received, if one has arrived.
pamoja_lora_radio_transmit^⚠: Sends one frame and waits for it to leave.
pamoja_lora_radio_write_register^⚠: Writes one register of a radio’s chip.
pamoja_lora_sim_chip_family^⚠: Returns the family of a simulated chip.
pamoja_lora_sim_chip_free^⚠: Releases a simulated chip. A radio wired to it keeps working until it is released too.
pamoja_lora_sim_chip_hear^⚠: Puts a frame on the air for a simulated chip to receive the next time it listens.
pamoja_lora_sim_chip_hear_corrupt^⚠: Puts a frame on the air whose CRC fails, which the chip reports and drops.
pamoja_lora_sim_chip_radio^⚠: Wires a radio to a simulated chip and resets it, as opening a module does.
pamoja_lora_sim_chip_sent_count^⚠: Returns how many frames a simulated chip has put on the air.
pamoja_lora_sim_chip_sent_payload^⚠: Copies the payload of a frame a simulated chip sent.
pamoja_lora_sim_chip_sent_tuning^⚠: Reads what a simulated chip was tuned to when it sent a frame.
pamoja_lora_sim_chip_sx126x^⚠: Creates a simulated SX1261, SX1262, SX1268, or LLCC68, out of reset.
pamoja_lora_sim_chip_sx127x^⚠: Creates a simulated SX1276, SX1277, SX1278, or SX1279, out of reset.
pamoja_lora_sim_chip_tuning^⚠: Reads what a simulated chip is tuned to now.
pamoja_lora_sim_chip_waiting^⚠: Returns how many frames wait on the air for a simulated chip to receive.