Skip to content

Latest commit

 

History

History
327 lines (199 loc) · 6.4 KB

API.md

File metadata and controls

327 lines (199 loc) · 6.4 KB
Raw

Heltec LoRa basic library API

Include Library

#include <LoRa.h>

Setup

Begin

Initialize the library with the specified frequency.

LoRa.begin(frequency);
  • frequency - frequency in Hz (433E6, 866E6, 915E6)

Returns 1 on success, 0 on failure.

Set pins

Override the default NSS, NRESET, and DIO0 pins used by the library. Must be called before LoRa.begin().

LoRa.setPins(ss, reset, dio0);
  • ss - new slave select pin to use, defaults to 18
  • reset - new reset pin to use, defaults to 14
  • dio0 - new DIO0 pin to use, defaults to 26

This call is optional and only needs to be used if you need to change the default pins used.

Set SPI Frequency

Override the default SPI frequency of 10 MHz used by the library. Must be called before LoRa.begin().

LoRa.setSPIFrequency(frequency);
  • frequency - new SPI frequency to use, defaults to 10E6

This call is optional and only needs to be used if you need to change the default SPI frequency used. Some logic level converters cannot support high speeds such as 10 MHz, so a lower SPI frequency can be selected with LoRa.setSPIFrequency(frequency).

End

Stop the library

LoRa.end()

Sending data

Begin packet

Start the sequence of sending a packet.

LoRa.beginPacket();

LoRa.beginPacket(implicitHeader);
  • implicitHeader - (optional) true enables implicit header mode, false enables explicit header mode (default)

Returns 1 on success, 0 on failure.

Writing

Write data to the packet. Each packet can contain up to 255 bytes.

LoRa.write(byte);

LoRa.write(buffer, length);
  • byte - single byte to write to packet

or

  • buffer - data to write to packet
  • length - size of data to write

Returns the number of bytes written.

Note: Other Arduino Print API's can also be used to write data into the packet

End packet

End the sequence of sending a packet.

LoRa.endPacket()

Returns 1 on success, 0 on failure.

Receiving data

Parsing packet

Check if a packet has been received.

int packetSize = LoRa.parsePacket();

int packetSize = LoRa.parsePacket(size);
  • size - (optional) if > 0 implicit header mode is enabled with the expected a packet of size bytes, default mode is explicit header mode

Returns the packet size in bytes or 0 if no packet was received.

Continuous receive mode

Register callback

Register a callback function for when a packet is received.

LoRa.onReceive(onReceive);

void onReceive(int packetSize) {
 // ...
}
  • onReceive - function to call when a packet is received.

Receive mode

Puts the radio in continuous receive mode.

LoRa.receive();

LoRa.receive(int size);
  • size - (optional) if > 0 implicit header mode is enabled with the expected a packet of size bytes, default mode is explicit header mode

The onReceive callback will be called when a packet is received.

Packet RSSI

int rssi = LoRa.packetRssi();

Returns the RSSI of the received packet.

Packet SNR

float snr = LoRa.packetSnr();

Returns the estimated SNR of the received packet in dB.

Available

int availableBytes = LoRa.available()

Returns number of bytes available for reading.

Peeking

Peek at the next byte in the packet.

byte b = LoRa.peek();

Returns the next byte in the packet or -1 if no bytes are available.

Reading

Read the next byte from the packet.

byte b = LoRa.read();

Returns the next byte in the packet or -1 if no bytes are available.

Note: Other Arduino Stream API's can also be used to read data from the packet

Other radio modes

Idle mode

Put the radio in idle (standby) mode.

LoRa.idle();

Sleep mode

Put the radio in sleep mode.

LoRa.sleep();

Radio parameters

TX Power

Change the TX power of the radio.

LoRa.setTxPower(txPower);

LoRa.setTxPower(txPower, outputPin);
  • txPower - TX power in dB, defaults to 14
  • outputPin - (optional) PA output pin, supported values are PA_OUTPUT_RFO_PIN and PA_OUTPUT_PA_BOOST_PIN, defaults to PA_OUTPUT_PA_BOOST_PIN.

Supported values are between 2 and 17 for PA_OUTPUT_PA_BOOST_PIN, 0 and 14 for PA_OUTPUT_RFO_PIN.

Most modules have the PA output pin connected to PA BOOST,

Frequency

Change the frequency of the radio.

LoRa.setFrequency(frequency);
  • frequency - frequency in Hz (433E6, 866E6, 915E6)

Spreading Factor

Change the spreading factor of the radio.

LoRa.setSpreadingFactor(spreadingFactor);
  • spreadingFactor - spreading factor, defaults to 11

Supported values are between 6 and 12. If a spreading factor of 6 is set, implicit header mode must be used to transmit and receive packets.

Signal Bandwidth

Change the signal bandwidth of the radio.

LoRa.setSignalBandwidth(signalBandwidth);
  • signalBandwidth - signal bandwidth in Hz, defaults to 125E3.

Supported values are 7.8E3, 10.4E3, 15.6E3, 20.8E3, 31.25E3, 41.7E3, 62.5E3, 125E3, and 250E3.

Coding Rate

Change the coding rate of the radio.

LoRa.setCodingRate4(codingRateDenominator);
  • codingRateDenominator - denominator of the coding rate, defaults to 5

Supported values are between 5 and 8, these correspond to coding rates of 4/5 and 4/8. The coding rate numerator is fixed at 4.

Preamble Length

Change the preamble length of the radio.

LoRa.setPreambleLength(preambleLength);
  • preambleLength - preamble length in symbols, defaults to 8

Supported values are between 6 and 65535.

Sync Word

Change the sync word of the radio.

LoRa.setSyncWord(syncWord);
  • syncWord - byte value to use as the sync word, defaults to 0x34

CRC

Enable or disable CRC usage, by default a CRC is not used.

LoRa.enableCrc();

LoRa.disableCrc();

iqInverted

Enable or disable iqInverted for TX/RX

LoRa.disableInvertIQ();
LoRa.enableInvertIQ();
LoRa.enableTxInvertIQ();
LoRa.enableRxInvertIQ();

Other functions

Random

Generate a random byte, based on the Wideband RSSI measurement.

byte b = LoRa.random();

Returns random byte.