ez.radio

audio bus crypto display ez global gps keyboard mesh net radio sprite storage synth system wifi

Low-level LoRa radio configuration and status

Direct control of the SX1262 LoRa radio hardware. Configure frequency, bandwidth, spreading factor, and transmit power. Most applications should use ez.mesh instead, which provides higher-level mesh networking on top of the radio. The radio status indicator shows "!RF" if initialization fails.

Functions

available() → boolean Check if data is available
ez.radio.available() -> boolean
Checks if a packet has been received and is waiting to be read. Call this after start_receive() to poll for incoming data. Non-blocking.
Returns: true if packet waiting
if ez.radio.available() then
local data = ez.radio.receive()
print("Got packet:", data)
end
get_config() → table Get current radio configuration
ez.radio.get_config() -> table
Returns a table with all current radio settings. Useful for debugging or displaying radio status. Returns nil if radio not initialized.
Returns: Table with frequency, bandwidth, spreading_factor, coding_rate, sync_word,
local cfg = ez.radio.get_config()
if cfg then
print(string.format("Freq: %.1f MHz, SF%d, BW %.0f kHz",
cfg.frequency, cfg.spreading_factor, cfg.bandwidth))
end
get_last_rssi() → number Get last received signal strength
ez.radio.get_last_rssi() -> number
Returns the RSSI of the most recently received packet. RSSI is typically negative: -30dBm is strong, -90dBm is weak, -120dBm is near the noise floor. Useful for signal strength displays and link quality assessment.
Returns: RSSI in dBm
local rssi = ez.radio.get_last_rssi()
if rssi > -80 then
print("Good signal")
elseif rssi > -100 then
print("Weak signal")
else
print("Very weak signal")
end
get_last_snr() → number Get last signal-to-noise ratio
ez.radio.get_last_snr() -> number
Returns the SNR of the most recently received packet. SNR indicates how much the signal stands above noise: positive values are good, negative values mean signal is below noise floor (LoRa can decode signals down to -20dB SNR). Higher spreading factors work better with lower SNR.
Returns: SNR in dB
local snr = ez.radio.get_last_snr()
if snr > 5 then
print("Excellent signal quality")
elseif snr > 0 then
print("Good signal quality")
else
print("Signal below noise floor, SNR:", snr)
end
is_busy() → boolean Check if radio is busy
ez.radio.is_busy() -> boolean
Returns true if the radio is currently transmitting or receiving a packet. Use this to check if the radio can accept a new command. Combines the checks of is_transmitting() and is_receiving().
Returns: true if transmitting or receiving
-- Wait for radio to be idle
while ez.radio.is_busy() do
ez.system.delay(10)
end
ez.radio.send("data")
is_initialized() → boolean Check if radio is initialized
ez.radio.is_initialized() -> boolean
Checks if the LoRa radio hardware was successfully initialized at boot. If false, the radio module failed to start - check hardware connections. The status bar shows "!RF" when radio initialization fails.
Returns: true if radio is ready
if ez.radio.is_initialized() then
print("Radio ready")
else
print("Radio failed - check LoRa module")
end
is_receiving() → boolean Check if in receive mode
ez.radio.is_receiving() -> boolean
Checks if the radio is currently in receive mode and listening for packets. Returns true after calling start_receive() until a packet is received or another operation changes the radio state.
Returns: true if listening
if not ez.radio.is_receiving() then
ez.radio.start_receive()
end
is_transmitting() → boolean Check if currently transmitting
ez.radio.is_transmitting() -> boolean
Checks if the radio is currently transmitting a packet. Do not start another transmission while this returns true. Useful for implementing TX indicators or managing channel access.
Returns: true if transmission in progress
if ez.radio.is_transmitting() then
display:draw_text(10, 10, "TX", 0xFF0000)
end
receive() → string, number, number Receive a packet
ez.radio.receive() -> string, number, number
Reads a received packet from the radio buffer. Returns the packet data along with signal quality metrics: RSSI (Received Signal Strength Indicator) in dBm and SNR (Signal-to-Noise Ratio) in dB. Higher SNR means cleaner signal. Returns nil if no packet is available.
Returns: Data string, RSSI in dBm, SNR in dB, or nil if no data
local data, rssi, snr = ez.radio.receive()
if data then
print("Data:", data)
print(string.format("Signal: %d dBm, SNR: %.1f dB", rssi, snr))
end
send() → string Transmit data
ez.radio.send(data) -> string
Transmits a raw LoRa packet. For mesh networking, use ez.mesh functions instead which handle routing and encryption. This is for low-level radio access. Maximum packet size is 255 bytes. Blocks until transmission complete.
ParameterDescription
dataString or table of bytes to send (max 255 bytes)
Returns: Result string (ok, error_init, error_tx, error_busy)
local result = ez.radio.send("Hello LoRa")
if result == "ok" then
print("Packet sent")
else
print("Send failed:", result)
end
set_bandwidth() → string Set radio bandwidth
ez.radio.set_bandwidth(khz) -> string
Sets the LoRa channel bandwidth. Wider bandwidth allows faster data rates but reduces sensitivity. Common values: 125kHz (standard), 250kHz (faster), 500kHz (fastest). Narrower bandwidths (62.5, 41.7, 31.25, 20.8, 15.6, 10.4, 7.8) increase range but slow transmission.
ParameterDescription
khzBandwidth in kHz (7.8 to 500)
Returns: Result string (ok, error_init, error_param)
ez.radio.set_bandwidth(125)  -- Standard bandwidth
set_coding_rate() → string Set LoRa coding rate
ez.radio.set_coding_rate(cr) -> string
Sets the forward error correction (FEC) coding rate. Higher values add more redundancy for error recovery but reduce throughput. Value represents the denominator of 4/x ratio: 5=4/5, 6=4/6, 7=4/7, 8=4/8. CR5 is fastest, CR8 is most robust against interference.
ParameterDescription
crCoding rate (5-8)
Returns: Result string (ok, error_init, error_param)
ez.radio.set_coding_rate(5)  -- Minimal FEC, highest throughput
ez.radio.set_coding_rate(8)  -- Maximum FEC, best error recovery
set_frequency() → string Set radio frequency
ez.radio.set_frequency(mhz) -> string
Sets the LoRa carrier frequency. Common ISM bands: 433MHz (Asia), 868MHz (Europe), 915MHz (Americas). Ensure you use a frequency legal in your region. All nodes in a mesh must use the same frequency to communicate.
ParameterDescription
mhzFrequency in MHz (e.g., 915.0 for US)
Returns: Result string (ok, error_init, error_param)
local result = ez.radio.set_frequency(915.0)
if result == "ok" then
print("Frequency set to 915 MHz")
end
set_spreading_factor() → string Set LoRa spreading factor
ez.radio.set_spreading_factor(sf) -> string
Sets the spreading factor (SF) which controls the chirp rate. Higher SF increases range and noise immunity but reduces data rate. SF7 is fastest (~5.5kbps), SF12 has longest range (~300bps). Each SF increase roughly doubles range but halves speed. MeshCore typically uses SF9-SF11.
ParameterDescription
sfSpreading factor (6-12)
Returns: Result string (ok, error_init, error_param)
ez.radio.set_spreading_factor(10)  -- Good balance of range and speed
set_sync_word() → string Set sync word
ez.radio.set_sync_word(sw) -> string
Sets the sync word for packet detection. Only packets with matching sync word are received. Different networks can coexist on same frequency by using different sync words. Public LoRa uses 0x12, LoRaWAN uses 0x34. MeshCore uses 0x12.
ParameterDescription
swSync word value (0-255)
Returns: Result string (ok, error_init, error_param)
ez.radio.set_sync_word(0x12)  -- Standard LoRa sync word
set_tx_power() → string Set transmit power
ez.radio.set_tx_power(dbm) -> string
Sets the RF transmit power level. Higher power increases range but uses more battery and may cause interference. The SX1262 on T-Deck supports up to +22dBm. Use the minimum power needed for your application. Power is limited by regional regulations (e.g., +20dBm for US ISM band).
ParameterDescription
dbmPower in dBm (0-22)
Returns: Result string (ok, error_init, error_param)
ez.radio.set_tx_power(17)  -- Moderate power, good battery life
ez.radio.set_tx_power(22)  -- Maximum power, maximum range
sleep() → string Put radio into sleep mode
ez.radio.sleep() -> string
Puts the LoRa radio into low-power sleep mode. In sleep mode, the radio cannot transmit or receive but consumes minimal power. Use for battery saving when mesh communication is not needed. Call wake() to resume operation.
Returns: Result string (ok, error_init)
-- Save power when idle
ez.radio.sleep()
ez.system.delay(60000)  -- Sleep for 1 minute
ez.radio.wake()
ez.radio.start_receive()
start_receive() → string Start listening for packets
ez.radio.start_receive() -> string
Puts the radio in continuous receive mode. The radio will listen for packets until a packet is received or another operation is started. Use available() to check for received packets and receive() to read them.
Returns: Result string (ok, error_init)
ez.radio.start_receive()
while true do
if ez.radio.available() then
local data, rssi, snr = ez.radio.receive()
print("Received:", data, "RSSI:", rssi)
end
ez.system.delay(10)
end
wake() → string Wake radio from sleep
ez.radio.wake() -> string
Wakes the LoRa radio from sleep mode. After waking, the radio is in standby mode and ready for commands. Call start_receive() to resume listening for packets.
Returns: Result string (ok, error_init)
ez.radio.wake()
ez.radio.start_receive()  -- Resume listening