[docs] Add migration page

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)

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

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
 

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).