Library reference
The LorNode library handles the parts that are specific to this board: the LoRa pins, the switchable power rail, the RGB LED, battery readings and deep sleep. For the radio itself you use the regular Arduino LoRa library.
Install
- Install esp32 by Espressif Systems from the Boards Manager.
- Install LoRa (by Sandeep Mistry) and Adafruit NeoPixel from the Library Manager. The LorNode library needs both.
- Download the LorNode repo as a zip (Code > Download ZIP) and add it with Sketch > Include Library > Add .ZIP Library.
The library isn't in the Arduino Library Manager yet, so the zip is the way to install it for now. Step-by-step instructions are in Getting started.
Choose ESP32 Dev Module as the board.
The basics
#include <LorNode.h>
void setup() {
Serial.begin(115200);
LorNode.begin();
}
There is one global object, LorNode. Call LorNode.begin() at the top of setup() before anything else from the library.
Setup
begin()
void begin(const LorNodeConfig &config = LorNodeConfig());
Sets up the board. Call it once at the top of setup(). The board restarts from setup() after deep sleep, so it runs again on every wake-up, which is what you want.
With no argument it uses the defaults. To change something, fill in a LorNodeConfig first:
LorNodeConfig config;
config.ledBrightness = 20;
LorNode.begin(config);
LorNodeConfig
| Field | Default | What it does |
|---|---|---|
peripheralsOn |
true |
Switch the 3V3 SW rail on in begin(). Set to false to start with the LoRa module, LED and USB chip off. |
batteryTopOhms |
44200 |
Value of resistor R16 in ohms. Leave it alone on boards shipped so far. Set it to 100000 on a board with the revised resistor. See the R16 story. |
useBatteryCalibration |
true |
Apply the correction saved by calibrateBattery(), if there is one. |
ledBrightness |
48 |
Brightness of the RGB LED, 0 to 255. Every colour you pass to led() is scaled by this. The LED is very bright, so the default is low. |
Power
peripheralPower(on)
void peripheralPower(bool on);
Switches the 3V3 SW rail on or off. That rail powers the LoRa module, the RGB LED, the USB chip, and anything you connect to the 3V3 SW pin.
LorNode.peripheralPower(false); // off
LorNode.peripheralPower(true); // on again
While it is off, USB serial is silent and led() does nothing. After switching it back on, call loraBegin() again before using the radio.
peripheralPower()
bool peripheralPower() const;
Returns true if the 3V3 SW rail is on.
LoRa
loraBegin()
bool loraBegin(long frequency = 433E6);
Starts the radio. It switches the 3V3 SW rail on if needed, sets the board's LoRa pins and starts the LoRa library. Returns false if the module did not answer.
if (!LorNode.loraBegin()) {
Serial.println("LoRa did not start.");
}
After this, use the LoRa object as usual. See LoRa. Fit the antenna before you transmit.
loraReady()
bool loraReady() const;
Returns true once loraBegin() has succeeded. It goes back to false when the 3V3 SW rail is switched off.
RGB LED
led(r, g, b)
void led(uint8_t r, uint8_t g, uint8_t b);
Sets the colour of the RGB LED. Each value is 0 to 255, scaled by ledBrightness.
LorNode.led(255, 0, 0); // red
LorNode.led(255, 160, 0); // orange
Does nothing while the 3V3 SW rail is off, because the LED is powered from it.
ledOff()
void ledOff();
Turns the LED off. Same as led(0, 0, 0).
Battery and power input
batteryMillivolts()
uint16_t batteryMillivolts(uint8_t samples = 16);
Returns the battery voltage in millivolts. It takes samples readings and averages them. The default of 16 is a good balance.
Serial.printf("Battery: %u mV\n", LorNode.batteryMillivolts());
On boards shipped so far the reading stops at about 3950 mV. See batterySaturated().
batteryPercent()
uint8_t batteryPercent();
Returns a rough charge level from 0 to 100, worked out from the voltage with a typical Li-ion curve. It is a guide, not a fuel gauge. It is most accurate when the battery is resting.
batterySaturated()
bool batterySaturated();
Returns true when the battery reading has hit the top of what the board can measure. On boards with R16 = 44.2k that happens above roughly 3.95 V. When it is true, read batteryMillivolts() as "at least this much".
externalPower()
bool externalPower();
Returns true when 5 V is present on USB-C or the CHG IN pads. It can't tell you whether the battery is still charging or already full.
calibrateBattery(mV)
bool calibrateBattery(uint16_t measuredMillivolts);
Saves a correction for the battery reading. Measure the battery with a multimeter while it is between 3.4 V and 3.9 V, and pass the result in millivolts:
LorNode.calibrateBattery(3760);
The correction is stored in flash and used from then on, including after resets and new uploads. Returns false and saves nothing if the reading is capped, or if the correction would be more than 20% either way. The full steps are in Power and battery.
clearBatteryCalibration()
void clearBatteryCalibration();
Removes the saved correction.
batteryCalibration()
float batteryCalibration() const;
Returns the correction factor in use. 1.0 means no correction.
Deep sleep
sleepFor()
[[noreturn]] void sleepFor(uint32_t seconds, bool keepPeripherals = false);
Goes to deep sleep for seconds. First it puts the radio to sleep and switches the 3V3 SW rail off, and it holds the rail off for the whole sleep.
LorNode.sleepFor(60); // see you in a minute
This call never returns. When the time is up, the board restarts from setup().
Pass true as the second argument to leave the 3V3 SW rail on during sleep. The LED is switched off and the radio is put to sleep, but everything on the rail stays powered, so the board uses more power.
sleepUntilPin()
bool sleepUntilPin(uint8_t gpio, bool level, uint32_t timeoutSeconds = 0,
bool keepPeripherals = false);
Like sleepFor(), but the board wakes when a pin reaches a level. level is true for high and false for low.
// Wake when a button pulls GPIO33 low, or after an hour, whichever is first.
LorNode.sleepUntilPin(33, false, 3600);
Things to know:
- Only RTC-capable pins can wake the board. On the headers, the free ones are GPIO2, 12, 14, 25, 26, 32, 33, 36 and 39. GPIO32 and GPIO33 are the easy choices.
- Give the pin an external pull-up or pull-down resistor so it has a definite level while the board sleeps.
- If you pass a pin that can't wake the board,
sleepUntilPin()returnsfalsestraight away and the board stays awake. When it does sleep, it never returns.
wakeReason()
esp_sleep_wakeup_cause_t wakeReason() const;
Tells you why the board started. The useful values:
| Value | Meaning |
|---|---|
ESP_SLEEP_WAKEUP_TIMER |
The sleep time ran out |
ESP_SLEEP_WAKEUP_EXT0 |
The wake pin from sleepUntilPin() fired |
ESP_SLEEP_WAKEUP_UNDEFINED |
Not a wake-up. The board was powered on or reset. |
if (LorNode.wakeReason() == ESP_SLEEP_WAKEUP_EXT0) {
Serial.println("Woken by the button.");
}
bootCount()
uint32_t bootCount() const;
Returns how many times the board has started since it was powered up, counting every wake from deep sleep. The first boot is 1. It starts over when the board loses power or is reset.
Pin constants
LorNode.h also gives you a name for every pin, so you don't have to remember numbers.
Pins the board uses:
| Constant | GPIO | What it is |
|---|---|---|
LORNODE_LORA_NSS |
4 | LoRa chip select |
LORNODE_LORA_RESET |
16 | LoRa reset |
LORNODE_LORA_DIO0 |
13 | LoRa DIO0 interrupt |
LORNODE_SPI_SCK |
18 | SPI clock |
LORNODE_SPI_MISO |
19 | SPI MISO |
LORNODE_SPI_MOSI |
23 | SPI MOSI |
LORNODE_RGB_LED |
15 | RGB LED data |
LORNODE_PERIPH_EN |
27 | 3V3 SW rail enable |
LORNODE_BOOT_BUTTON |
0 | BOOT button |
LORNODE_VIN_SENSE |
34 | 5 V input sense |
LORNODE_BATTERY_SENSE |
35 | Battery sense |
Free header pins are named LORNODE_GPIO2, LORNODE_GPIO5, LORNODE_GPIO12, LORNODE_GPIO14, LORNODE_GPIO17, LORNODE_GPIO21, LORNODE_GPIO22, LORNODE_GPIO25, LORNODE_GPIO26, LORNODE_GPIO32, LORNODE_GPIO33, LORNODE_GPIO36 and LORNODE_GPIO39. Check the Pinout for the cautions on each one.
You can use the BOOT button as a plain button in your sketch once the board is running:
pinMode(LORNODE_BOOT_BUTTON, INPUT_PULLUP);
if (digitalRead(LORNODE_BOOT_BUTTON) == LOW) {
// pressed
}
Other constants
| Constant | Value | What it is |
|---|---|---|
LORNODE_LIBRARY_VERSION |
"0.1.0" |
Version of the library |
LORNODE_R16_OHMS |
44200 |
The R16 value the library assumes. Define it as 100000 in your build flags for a board with the revised resistor, or set batteryTopOhms instead. |
LORNODE_R16_SHIPPED_OHMS |
44200 |
R16 on boards shipped so far |
LORNODE_R16_REVISED_OHMS |
100000 |
R16 on future batches |
LORNODE_R10_OHMS |
160000 |
The bottom resistor of the battery divider |