[lightning-ln882h] Add support for Lightning LN882H family (#312)

* fix mbedtls bad pointer in function call (prototype mismatch) * fix issue with weak families functions implemented in static library, it will never be linked. fixed by redefining prototypes inside families * [ln882x] add support for lightning ln882x & ln882h families * add i2c (wire) support * add analog (adc) support * add watchdog support * [ln882x] changed default uart 0/1 pins; added board wl2s * [ln882x] fix IRQ & ADC pins * [ln882x] boards cosmetic * [ln882x] wifi sta use otp mac addr by default; re-enabled wifi powersave mode * [ln882x] clang-format clean code * [ln882x] clang-format clean code * Update families.json * Apply suggestions from code review * [ln882x] reformat json board files * [ln882x] os_queue cleanup * [ln882x] removed Beken auto-download command * [ln882x] removed personal script file * [ln882x] removed unusefull pi section in debugging.md * [ln882x] removed Arduino.h and changed private I2C definition * [ln882x] updated README.md * [ln882x] changed pin naming scheme to PA/PB * [ln882x] clean code * [ln882x] clean code * [ln882x] add ota image verification * Update push-dev.yml * [ln882x] fix boards ADC missing inputs] * [ln882x] removed reg_xxx fixup files and use include guards instead * [ln882x] cleanup code * [ln882x] cleanup code * [ln882x] fix lt_init weak functions linking * [ln882x] revert lt_api.h modification, fixed with previous commit * [ln882x] setup UF2 firmware for flasher with partitions * [ln882x] update README.md * [ln882x] include ln_wifi.h and ln_serial.h to avoid including bad headers on case insensitive systems * [ln882x] Replace RingBuffer by SerialRingBuffer * [ln882x] clang-format * [ln882x] update README.md * Apply suggestions from code review * Reformat board JSON files * Add mkdocs link redirect * Update ltchiptool to v4.12.0 --------- Co-authored-by: Kuba Szczodrzyński <kuba@szczodrzynski.pl>
2025-03-25 17:26:53 +01:00
parent 6083cca72e
commit 69e7e2debe
73 changed files with 4856 additions and 28 deletions
--- a/docs/platform/SUMMARY.md
+++ b/docs/platform/SUMMARY.md
@@ -2,3 +2,4 @@

 * [Beken BK72xx](beken-72xx/README.md)
 * [Realtek RTL8710Bx](realtek-ambz/README.md)
+* [Lightning LN882x](lightning-ln882x/README.md)
--- a/docs/platform/lightning-ln882x/README.md
+++ b/docs/platform/lightning-ln882x/README.md
@@ -0,0 +1,101 @@
+# Lightning LN882x
+
+## Introduction
+
+Lightning LN882x is a family of Wi-Fi and BLE microcontrollers designed for indoor short-range IoT.
+
+Features:
+
+- 32-bit Cortex M4F CPU (160 MHz)
+- 296 KiB SRAM
+- built-in 512 KiB to 2 MiB flash with XiP
+- 802.11b/g/n Wi-Fi
+- Bluetooth 5.1 (LN882H only)
+
+Resources:
+
+- [LN882H](http://www.lightningsemi.com/ln882h)  : MCU Combo Wi-Fi/BLE IoT
+- [LN882H Datasheet](https://gitee.com/lightningsemi/ln882h-document-collection/blob/master/1.%E8%8A%AF%E7%89%87%E8%A7%84%E6%A0%BC%E4%B9%A6/LN882H_Datasheet.pdf)  : LN882H Datasheet
+- [LN882H DOC](https://gitee.com/lightningsemi/ln882h-document-collection)  : Official LN882H Document Collection
+- [LN882H SDK](https://gitee.com/lightningsemi/ln882h)  : Official LN882H SDK
+- [LN882X SDK](https://gitee.com/lightningsemi/ln882x-sdk)  : Official LN882X SDK
+- [LN8825A/B](http://www.lightningsemi.com/LN8825AB) : Wi-Fi SOC
+- [LN8825A/B SDK](https://gitee.com/lightningsemi/ln882x-mcu) : Official LN8825A/B SDK
+- [Flashing tool (GUI)](https://gitee.com/lightningsemi/ln882h-document-collection/blob/master/4.%E7%83%A7%E5%BD%95%E5%B7%A5%E5%85%B7/%E4%B8%B2%E5%8F%A3%E7%83%A7%E5%BD%95/%E4%BA%AE%E7%89%9B%E4%B8%B2%E5%8F%A3%E7%83%A7%E5%BD%95%E5%B7%A5%E5%85%B7V3.0.5.zip) : Flashing tool with GUI (chinese)
+- [Flashing tool (CMD)](https://gitee.com/lightningsemi/ln882h-document-collection/blob/master/4.%E7%83%A7%E5%BD%95%E5%B7%A5%E5%85%B7/%E4%B8%B2%E5%8F%A3%E7%83%A7%E5%BD%95/LN882H%E5%91%BD%E4%BB%A4%E8%A1%8C%E5%B7%A5%E5%85%B7_V1.0.16.zip) : Command-line Flashing tool
+
+## Finding your board
+
+{%
+	include-markdown "../../inc/find-board.md"
+%}
+
+---
+
+## Flashing
+
+{%
+	include-markdown "../../inc/flashing-note.md"
+%}
+
+LN882x has two UART ports - The UART0 port is used for flashing and text output.
+
+You need to find which pins correspond to UART0 TX and RX. If your board is supported, you'll find the pinout on its documentation page. Otherwise (and for generic boards), you'll have to find the pinout online.
+
+### Wiring
+
+Connect UART0 of the LN882H to the USB-TTL adapter:
+
+PC  | LN882H
+----|-----------------------
+RX  | TX0 (GPIOA2 / P2)
+TX  | RX0 (GPIOA3 / P3)
+GND | GND
+
+{%
+	include-markdown "../../inc/uart-power.md"
+%}
+
+{%
+	include-markdown "../../inc/uart-cen.md"
+%}
+
+The download mode is entered when the chip communicates with the flasher program. Hence, the first step is running the flasher program (described below). While the program is trying to establish communication, **the chip has to be rebooted**. In order to do that, you need to bridge BOOT1 pin to GND with a wire **before** powering the chip.
+
+After linking with the chip, the flasher program will begin writing (or reading) the firmware automatically. If that doesn't happen, try resetting the chip again until it works.
+
+If you're getting a `No response received` (or similar) error, this means that:
+
+- the power supply is too weak (read above)
+- you're resetting the chip too quickly, i.e. you resetted it *after* the program started communicating with it
+
+### Flashing
+
+The recommended tool to flash (or dump firmware) is `ltchiptool`.
+
+**Read [Using ltchiptool](../../flashing/tools/ltchiptool.md) to learn the flashing procedure**
+
+!!! tip
+	Because the UART uploading code is programmed in the ROM of the chip, it can't be software-bricked, even if you damage the bootloader.
+
+## Firmware output files
+
+These files are present in the build directory after successful compilation:
+
+File                            | Description
+--------------------------------|----------------------------------------
+**firmware.uf2**                | **UF2 package for UART and OTA upload**
+**image_firmware.0x000000.bin** | **Full flash binary image** - flashable at 0x0
+image_boot.0x000000.bin         | Boot partition binary image - flashable at 0x0
+image_part_tab.0x006000.bin     | Partition table binary image - flashable at 0x6000
+image_app.0x007000.bin          | Application partition binary image - flashable at 0x7000
+image_ota.0x133000.bin          | OTA partition binary image - flashable at 0x133000
+
+
+## Other tools/guides
+
+- Official command-line [flashing tool](https://gitee.com/lightningsemi/ln882h-document-collection/blob/master/4.%E7%83%A7%E5%BD%95%E5%B7%A5%E5%85%B7/%E4%B8%B2%E5%8F%A3%E7%83%A7%E5%BD%95/LN882H%E5%91%BD%E4%BB%A4%E8%A1%8C%E5%B7%A5%E5%85%B7_V1.0.16.zip)
+
+	 Usage Examples:<br/>
+	 `LN882H_CMD_Tool.exe COM1 download flash 921600 0x0 image_firmware.0x000000.bin`<br/>
+	 `LN882H_CMD_Tool.exe COM1 download flash 921600 0x7000 image_app.0x007000.bin`
--- a/docs/platform/lightning-ln882x/debugging.md
+++ b/docs/platform/lightning-ln882x/debugging.md
@@ -0,0 +1,59 @@
+# Debugging
+
+Debugging of Lightning LN882x chips is possible and was tested with a JLink probe on OpenOCD and JLinkGDBServer.
+
+*(the following is applicable to Arduino framework, and was not tested with SDK framework)*
+
+LibreTiny has ready-to-use OpenOCD config files:
+
+- [platform/lightning-ln882x/openocd/ln882x.cfg](../../../cores/lightning-ln882x/misc/ln882x.cfg)
+
+## Local debugger
+
+It should be possible to use PlatformIO's built-in debugging capabilities directly, when plugging an OpenOCD-compatible debugger into your PC. As there are no debugger interfaces built into these IoT boards, you need to specify your interface of choice in `platformio.ini`:
+
+```ini
+[env:my_board]
+openocd_interface = <interface name>
+```
+where `<interface name>` is for example `raspberrypi2-native`, `stlink`, etc.
+
+## JLink configuration
+
+```ini
+[env:my_board]
+board = ln-02
+debug_tool = custom
+debug_server =
+    ../JLink_Linux_V698e_x86_64/JLinkGDBServerExe
+    -singlerun
+    -if
+    SWD
+    -select
+    USB
+    -port
+    3333
+    -device
+    Cortex-M4
+debug_init_cmds =
+    define pio_reset_halt_target
+        monitor reset
+    end
+    target extended-remote $DEBUG_PORT
+    ;monitor speed auto
+    monitor reset
+    $LOAD_CMDS
+    $INIT_BREAK
+upload_protocol = custom
+upload_flags =
+    -auto
+    -startapp
+    -exit
+upload_command = ../JLink_Linux_V698e_x86_64/JFlashExe -openprj"../JLink_Linux_V698e_x86_64/ln882h.jflash" -open"${BUILD_DIR}/image_firmware.bin",0 $UPLOAD_FLAGS
+debug_init_break = tbreak Reset_Handler
+```
+
+## Technical details
+
+GDB is first configured with `mem 0x0000000 0x1000000 ro` in order to mark flash memory as read-only. This makes GDB use hardware breakpoints, as software BPs don't work on these boards.
+
--- a/docs/status/supported.md
+++ b/docs/status/supported.md
@@ -36,30 +36,30 @@ The following list corresponds to UF2 OTA format family names, and is also [avai

 If you notice a feature that you've tested, which works (or not) and doesn't match this table, feel free to submit an issue on GitHub.

-&nbsp;                   | `BK7231T` | `BK7231N` | `RTL8710B` | `RTL8720C` | `BK7231Q`
-------------------------|-----------|-----------|------------|------------|----------
-Stability                | 5/5       | 5/5       | 4/5        | 2/5        | 1/5
-LibreTiny Core           | ✔️        | ✔️        | ✔️         | ✔️         | ✔️
-Wiring Core              | ✔️        | ✔️        | ✔️         | ✔️         | ✔️
-**PERIPHERALS** (Core)   |           |           |            |            |
-UART I/O                 | ✔️        | ✔️        | ✔️         | ✔️         | ✔️
-Flash I/O                | ✔️        | ✔️        | ✔️         | ❓          | ❓
-Deep sleep               | ❓         | ✔️        | ❌          | ❌          | ❓
-Watchdog timer           | ✔️        | ✔️        | ✔️         | ❓          | ❓
-**PERIPHERALS** (Wiring) |           |           |            |            |
-Digital I/O              | ✔️        | ✔️        | ✔️         | ❓          | ❓
-PWM                      | ✔️        | ✔️        | ✔️         | ❓          | ❓
-Interrupts               | ✔️        | ✔️        | ✔️         | ❓          | ❓
-Analog input (ADC)       | ✔️        | ✔️        | ✔️         | ❓          | ❓
-`Wire` (I²C)             | ❌         | ❌         | ❗          | ❌          | ❌
-`SPI`                    | ❌         | ❌         | ❌          | ❌          | ❌
-`Serial`                 | ✔️        | ✔️        | ✔️         | ✔️         | ❓
-`SoftwareSerial`         | ❌         | ❌         | ✔️         | ❌          | ❌
-**NETWORKING**           |           |           |            |            |
-Wi-Fi STA/AP/Mixed       | ✔️        | ✔️        | ✔️         | ❓          | ❌
-Wi-Fi Events             | ✔️        | ✔️        | ✔️         | ❓          | ❌
-OTA updates              | ✔️        | ✔️        | ✔️         | ❌          | ❌
-MDNS                     | ✔️        | ✔️        | ✔️         | ❓          | ❓
+&nbsp;                   | `BK7231T` | `BK7231N` | `RTL8710B` | `RTL8720C` | `BK7231Q`  |  `LN882H` 
+-------------------------|-----------|-----------|------------|------------|------------|------------
+Stability                | 5/5       | 5/5       | 4/5        | 2/5        | 1/5        | 3/5
+LibreTiny Core           | ✔️        | ✔️        | ✔️         | ✔️         | ✔️         | ✔️
+Wiring Core              | ✔️        | ✔️        | ✔️         | ✔️         | ✔️         | ✔️
+**PERIPHERALS** (Core)   |           |           |            |            |            |
+UART I/O                 | ✔️        | ✔️        | ✔️         | ✔️         | ✔️         | ✔️
+Flash I/O                | ✔️        | ✔️        | ✔️         | ❓          | ❓         | ✔️
+Deep sleep               | ❓         | ✔️        | ❌          | ❌          | ❓         | ❌
+Watchdog timer           | ✔️        | ✔️        | ✔️         | ❓          | ❓         | ✔️
+**PERIPHERALS** (Wiring) |           |           |            |            |            |
+Digital I/O              | ✔️        | ✔️        | ✔️         | ❓          | ❓         | ✔️
+PWM                      | ✔️        | ✔️        | ✔️         | ❓          | ❓         | ❌
+Interrupts               | ✔️        | ✔️        | ✔️         | ❓          | ❓         | ❓
+Analog input (ADC)       | ✔️        | ✔️        | ✔️         | ❓          | ❓         | ✔️
+`Wire` (I²C)             | ❌         | ❌         | ❗          | ❌          | ❌         | ❓
+`SPI`                    | ❌         | ❌         | ❌          | ❌          | ❌         | ❌
+`Serial`                 | ✔️        | ✔️        | ✔️         | ✔️         | ❓         | ✔️
+`SoftwareSerial`         | ❌         | ❌         | ✔️         | ❌          | ❌         | ❌
+**NETWORKING**           |           |           |            |            |            |
+Wi-Fi STA/AP/Mixed       | ✔️        | ✔️        | ✔️         | ❓          | ❌         | ✔️
+Wi-Fi Events             | ✔️        | ✔️        | ✔️         | ❓          | ❌         | ✔️
+OTA updates              | ✔️        | ✔️        | ✔️         | ❌          | ❌         | ✔️
+MDNS                     | ✔️        | ✔️        | ✔️         | ❓          | ❓         | ✔️

 Symbols: