LilyGo LoRa Series examples: one ping-pong sketch per board and radio combination

The utilities.h step that blocks every first compile

The News section at the top of the README carries the single most useful piece of information in the repository, and it is a step that is easy to miss.

Arduino IDE users need to configure the board to be used in the utilities.h file in the sketch directory before using the example. The utilities.h file contains the pin definitions of the board, and if you do not select it, an error will occur during compilation.

That is a real design constraint of the examples, not an oversight. The boards in this range differ in which pins carry the LoRa radio, the display and the power management unit, and rather than shipping one sketch per pinout, the examples share a common structure and read the board selection from a header you edit. The pin definitions then follow from your choice.

The Chinese version of the same note says the same thing, and the fact that the README is fully bilingual here is worth noting, because the rest of the documentation tree splits into per-language directories under docs/en and docs/zh.

The second warning in the News section is a hardware one. If using the PA version, carefully read the PA power setting limits on the corresponding page, because incorrect output power settings may damage the PA. A power amplifier in a 1W class radio is not forgiving of a badly chosen output setting, and the repository carries several PA variants including the T3-S3-LR1121 PA version and the T3-S3-SX1280PA.

Both notes are the kind of thing a documentation page should lead with, and this one does.

A ping-pong sketch for every board and radio pairing

The examples/LoRa directory is the core of the repository, and its shape is the shape of the problem.

The basic pattern is Receive_Interrupt and Transmit_Interrupt, described as common receive and transmit examples for all boards. Then, under each board family, there is a PingPong sketch per radio chip. T3_TCXO has SX1276_PingPong, T3_LoRa32 for the V1.6 board has SX1276 and SX1278, T3C6 has SX1262_PingPong, and T3S3, described as the S3 with multiple radio chip versions, has SX1262, SX1276, SX1278, SX1280, SX1280PA, LR1121 and LR1121PA variants, plus an SX1280_Ranging example. TBeam_AXP2101 for the T-Beam V1.2 with the AXP2101 power management unit has SX1262, SX1276 and SX1278. TBeam_S3_Supreme has SX1262 and LR1121, TBeam1W, the high power variant, has SX1262, LR1121 and LR2021, and TBeamBPF_SX1278 has SX1278_PingPong.

The design logic is clear. A LoRa link needs a matched pair of boards with a matched radio, and the radio chips are not interchangeable across the range: Rather than abstracting over that, the repository enumerates the combinations.

That is the right call for a hardware example set and the wrong one for a library. A user with a T3-S3 and an SX1280 gets an example that has been written and named for exactly their hardware, and a user with an unusual combination finds the nearest neighbour rather than a generic layer.

The ArduinoLoRa directory is the older, simpler pair, and the README notes it only supports the SX1276 and SX1278 radio modules.

The rest of the example tree, and what each group assumes

Beyond the LoRa examples, the tree is organised by function, and each group carries its own restriction in the comment.

GPS holds TinyGPS examples, a TinyGPS KitchenSink, and u-blox examples covering NMEA reading, NMEA parsing, output rate and recovery, all marked as only supporting the u-blox GNSS module. LoRaWAN holds LMIC_Library_OTTA, LoRaWAN_ABP and RadioLib_OTAA, covering both OTAA and ABP activation with two different stacks.

OLED holds SSD1306 and SH1106 demos, with font usage, a graphics test, an icon menu and a UTF-8 printing example. Display holds T-Beam TFT Shield examples including a free font demo and a character-times demo, marked as only supporting the T-Beam TFT Shield.

The Sensor group is the one with the tightest hardware assumption, marked as only supporting the t-beam-s3-supreme, and it is the largest directory. It covers a BME280 environmental sensor in three forms, advanced settings, a unified example and a test example, an I2CScanner, a PCF8563 real-time clock with alarm, time and time synchronisation examples, QMC6310 compass calibration and data reading, and a long set of QMI8658 accelerometer and gyroscope examples including a Madgwick AHRS filter, a pedometer, FIFO reading, interrupt and block handling, a wake-on-motion example and a locking mechanism example.

The rest of the tree is smaller. BLE has a BLE server, PMU has T-Beam and T-Beam S3 power management demos, SD has an SD card test, USBMSC has USB mass storage examples, and there are two factory test directories, Factory for the T-Beam, T-Beam S3 and BPF, and T3S3Factory for the T3 S3.

The pattern across all of them is the same: an example that assumes a particular peripheral, with the assumption written next to it, so a reader knows immediately whether it applies to their board.

A repository that also holds the hardware design files

The top level of the repository shows that this is much more than a code drop.

There are boards/, dimensions/, schematic/, variants/ and firmware/ directories alongside docs/, examples/, lib/, tools/, assets/ and images/. The tools/ directory is where the board definitions and variant handling live, and the platformio.ini file at the root is the PlatformIO project configuration, which is what makes the multi-board build matrix workable.

The dimensions/ and schematic/ directories are the important ones for anyone doing their own PCB work or enclosure design. A LoRa board is a two-layer RF design with a specific antenna keep-out, and having the outline and the schematic available means the antenna clearance can be respected rather than guessed.

The variants/ directory is the mechanism behind the utilities.h mechanism described earlier. Rather than one utilities.h per board family, the variants directory holds the per-board configuration, and the sketch header selects between them.

The docs/ tree is organised per board with quick start documents in English and Chinese, and the README links one for every product in the range: T-Beam, T-Beam Supreme, T-Beam Supreme in the 144 to 148 MHz band, T-Beam BPF, T-Beam 1W with the SX1262, T-Beam 1W with the LR1121, T-Beam 1W with the LR2021, LoRa32 V1.3, LoRa32 V1.6.1, LoRa32 TCXO, T3-C6, and the T3-S3 variants with the SX1262, LR1121, SX1280, SX1280PA, SX1276 and SX1278.

A separate section covers The Things Network, with a link to a separate LilyGo_LoRa_Series_Quick_Start document in the Chinese docs tree for accessing TTN, and a use reference table with YouTube walkthroughs for driving the T-Beam display, using it for positioning and for communication tests, and for entering boot mode to download the firmware.

The maintenance picture, and what the README does not cover

The last push was on 2026-10-12, so the tree is being worked on, and the primary language is C with the examples being Arduino sketches in C++.

The release history is thin. There is a single tag, v0.0.1, named Archive package, from 2024-05-12. A repository of example code that has not been tagged since 2024 is not unusual, since the artefacts being versioned are the board files rather than a library API, but it does mean there is no version marker to point at when asking which revision of a pinout you are using.

The licence situation is the one place to be careful. The overall licence is listed as unknown, and the README does not state one, so a company integrating any of this code has nothing to point at. For the sketches that may be fine, since they are configuration and driver glue, but the pin definitions and the variant handling are the kind of file that ends up in a product, and the absence of a stated licence is the gap to close before that happens.

What the README does not document is equally worth listing. There is no schema for the variant files, no description of the firmware/ directory beyond its name, no guidance on which example to use for a LoRaWAN deployment beyond the names, and no version compatibility matrix between the platformio configuration, the Arduino core version and the radio library versions. The per-board quick start documents are where that detail is expected to live, and they are the thing to read before your first compile rather than the README.

The TTN section points to a separate quick start document, so anyone joining a LoRaWAN network with these boards needs that document in hand from the start.

Editorial conclusion

LilyGo-LoRa-Series suits a developer who has just bought a T-Beam or T3 board and wants working Arduino code for it in an afternoon, because the ping-pong structure means the two-board link is already solved for your exact board and radio combination. It is the wrong tool if you need a library rather than sketches, since what is here is a set of worked examples and board documentation rather than a reusable API, and it is the wrong choice for anything requiring a current LoRaWAN stack or maintained firmware. Before you compile anything, edit the utilities.h file in your sketch directory to select your board, and if you are using a PA version, read the power setting limits first, because the README warns that incorrect output power settings may damage the PA.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. Xinyuan-LilyGO/LilyGo-LoRa-Series on GitHub