From 85a687fc56162c9fe9a72e33247e0cb5e5def2e2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kuba=20Szczodrzy=C5=84ski?= Date: Mon, 24 Apr 2023 10:47:06 +0200 Subject: [PATCH] [docs] Add migration page --- SUMMARY.md | 4 +++- docs/dev/migration_v1.0.0.md | 44 ++++++++++++++++++++++++++++++++++ docs/getting-started/README.md | 8 +++---- docs/getting-started/gpio.md | 31 ++++++++++++++++++++++++ 4 files changed, 81 insertions(+), 6 deletions(-) create mode 100644 docs/dev/migration_v1.0.0.md create mode 100644 docs/getting-started/gpio.md diff --git a/SUMMARY.md b/SUMMARY.md index 740c997..ec94dd2 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -1,9 +1,10 @@ * [Home](README.md) * [](SUMMARY.md) * [😊 Getting started](docs/getting-started/README.md) + * [➡️ Info on accessing GPIOs](docs/getting-started/gpio.md) * [💡 ESPHome setup guide](docs/projects/esphome.md) * [📲 Flashing/dumping guide](docs/flashing/) -* [🔌 How to enter download mode?](docs/flashing/chip-connection/) +* [🔌 How to connect the chip in download mode?](docs/flashing/chip-connection/) * [💻 Supported chips](docs/status/supported.md) * [All boards](boards/) * [](SUMMARY.md) @@ -15,6 +16,7 @@ * [Exception decoder](docs/platform/realtek-ambz/exception-decoder.md) * [🔧 LT Configuration](docs/dev/config.md) * 🧑 Programmer's manual + * [⚠️ Migration guide](docs/dev/migration_v1.0.0.md) * [🔋 PlatformIO Examples](examples/) * [📖 LibreTuya API](docs/dev/lt-api.md) * [C API](ltapi/dir_c7e317b16142bccc961a83c0babf0065.md) diff --git a/docs/dev/migration_v1.0.0.md b/docs/dev/migration_v1.0.0.md new file mode 100644 index 0000000..b3a3063 --- /dev/null +++ b/docs/dev/migration_v1.0.0.md @@ -0,0 +1,44 @@ +# Migration to v1.0.0 + +1.0.0 is the first major release of LT. Compared to previous versions, few things have changed which can impact developers using LT in PlatformIO (but shouldn't affect ESPHome users at all). + +## GPIO numbering + +Pin numbers passed to `pinMode()`/`digitalWrite()`/etc. are now the raw GPIO numbers of the chip. Previously, one had to use `D#` numbering in these functions, so you have to migrate your code to use GPIO numbers instead. + +To make the migration easier, you can simply change: + +```cpp +digitalWrite(1, LOW); +``` + +to: + +```cpp +digitalWrite(PIN_D1, LOW); +// or +digitalWrite(D1, LOW); +``` + +For more information, refer to [GPIO instructions](../getting-started/gpio.md). + +## Environment stability + +All public headers exported by LT are now stable between all chip families - this means that they're not including any code from the vendor SDK. + +This change was made to prevent the SDK from introducing its own functions and macros, which often replace stdlib functions, or cause other compilation issues. + +If your code is using vendor SDK functions, you'll have to import the appropriate headers yourself. + +## OTA (.uf2 packages) + +The format of OTA packages has changed slightly, to reflect the OTA scheme naming change (described below). There's also a distinction between the `flasher` (PC flasher) and `device` (on-device OTA code) in the package. + +New OTA packages are backwards-compatible (i.e. can be installed on devices running LT v0.x.x), but **v1.0.0 will not accept older packages** - it's **not** possible to rollback a device from v1.0.0 to v0.x.x with an old .uf2 file. + +## OTA scheme naming change + +Previously, each chip family had a "has dual OTA" property, which was very confusing (even to me, the author of the code). A new scheme has been introduced: + +- single OTA - devices with a separate "download" partition, which is used by the bootloader to flash the main application +- dual OTA - devices with two separate application partitions, which can be updated directly by the application diff --git a/docs/getting-started/README.md b/docs/getting-started/README.md index 5f37d0d..31e11dc 100644 --- a/docs/getting-started/README.md +++ b/docs/getting-started/README.md @@ -30,14 +30,12 @@ Next, read one of the [flashing guides](../flashing/SUMMARY.md) to run your proj LibreTuya has a few configuration options that change its behavior or features. Refer to [LT configuration](../dev/config.md) for details. -### GPIO usage +### GPIO usage - important change !!! important - This can be confusing at first, so make sure to read this part carefully to understand it. + Since v1.0.0, GPIOs are no longer meant to be referenced by `D#` numbers. - Input/output pin numbers in Arduino code (i.e. `digitalWrite()`) use Arduino pin numbers - for example `D1`, `D3`. This is the same as simply `1` or `3`, but it cannot be confused with CPU GPIO numbers. - - On the board pinout page, the purple blocks represent Arduino pins, while the dark red blocks refer to GPIO numbers. + If your program is using Arduino I/O functions, refer to the [Migration guide](../dev/migration_v1.0.0.md) to modify your program accordingly. ### Examples diff --git a/docs/getting-started/gpio.md b/docs/getting-started/gpio.md new file mode 100644 index 0000000..6bf604e --- /dev/null +++ b/docs/getting-started/gpio.md @@ -0,0 +1,31 @@ +# GPIO usage instructions + +!!! note + This has changed since v1.0.0. Refer to the [migration guide](../dev/migration_v1.0.0.md) for more info. + +GPIO pins can be accessed in a few ways: + +- using the raw GPIO number of the chip +- using the "function macro" of the pin +- using Arduino digital pin numbers (`D#`, deprecated) + +This applies both to Arduino code and ESPHome YAML configs. + +## GPIO numbers - Arduino only + +The simplest form of GPIO access is by using raw pin numbers of the CPU (just like on ESP8266/ESP32). For example, to access GPIO6, write `digitalRead(6)`. + +## Function macros - Arduino & ESPHome + +If you go to a board documentation page (like [this one - CB2S](../../boards/cb2s/README.md)) you'll see a pinout drawing, containing various labels in small blocks. There's also a table below to make the pinout a bit more clear. + +**You can use any of these labels** to access a particular pin. For example, to access GPIO6, which is also the PWM0 pin on CB2S, one can use: + +- `digitalRead(PIN_P6)` (Arduino) or `pin: P6` (ESPHome) +- `digitalRead(PIN_PWM0)` (Arduino) or `pin: PWM0` (ESPHome) + +## Arduino `D#` numbers (deprecated) + +This method of accessing pins is deprecated since v1.0.0, and **will** (probably) **be removed** in the future. It's kept for legacy compatibility. + +To access the previously mentioned GPIO6, use `digitalRead(D2)` or `digitalRead(PIN_D2)` or `pin: D2`. Note that the `D#` pin numbers are not consistent between boards (for example, on WB3S, GPIO6 is already D4).