diff --git a/README.md b/README.md index 61561db..32135b8 100644 --- a/README.md +++ b/README.md @@ -92,79 +92,6 @@ A (mostly) complete* list of Tuya wireless module boards. ** I/O count includes GPIOs, ADCs, PWM outputs and UART, but doesn't count CEN/RST and power pins. -## Project structure - -``` -arduino/ -├─ / Arduino Core for specific SoC -│ ├─ cores/ Wiring core files -│ ├─ libraries/ Supported built-in platform libraries -├─ libretuya/ -│ ├─ api/ Library interfaces -│ ├─ common/ Units common to all platforms -│ ├─ compat/ Fixes for compatibility with ESP32 framework -│ ├─ core/ LibreTuya API for Arduino cores -│ ├─ libraries/ Built-in platform-independent libraries -boards/ -├─ / Board-specific code -│ ├─ variant.cpp Arduino variant initialization -│ ├─ variant.h Arduino variant pin configs -├─ .json PlatformIO board description -builder/ -├─ frameworks/ Framework builders for PlatformIO -│ ├─ -sdk.py Vanilla SDK build system -│ ├─ -arduino.py Arduino Core build system -├─ arduino-common.py Builder to provide ArduinoCore-API and LibreTuya APIs -├─ main.py Main PlatformIO builder -├─ utils.py SCons utils used during the build -docs/ Project documentation, guides, tips, etc. -platform/ -├─ / Platform-specific configurations -│ ├─ bin/ Binary blobs (bootloaders, etc.) -│ ├─ fixups/ Code fix-ups to replace SDK parts -│ ├─ ld/ Linker scripts -│ ├─ openocd/ OpenOCD configuration files -tools/ -├─ / Tools used during the build -platform.json PlatformIO manifest -platform.py Custom PlatformIO script -``` - -## Platforms - -A list of platforms currently available in this project. - -Platform name | Supported MCU(s) | Arduino Core | Source SDK (PIO framework) ----------------|------------------------------------------------------------------------|--------------|-------------------------------------------------------------------------- -`realtek-ambz` | Realtek [AmebaZ](https://www.amebaiot.com/en/amebaz/) SoC (`RTL87xxB`) | ✔️ | `framework-realtek-amb1` ([amb1_sdk](https://github.com/ambiot/amb1_sdk)) - -### Realtek Ameba - -The logic behind naming of Realtek chips and their series took me some time to figure out: - -- RTL8xxxA - Ameba1/Ameba Series -- RTL8xxxB - AmebaZ Series -- RTL8xxxC - AmebaZ2/ZII Series -- RTL8xxxD - AmebaD Series - -As such, there are numerous CPUs with the same numbers but different series, which makes them require different code and SDKs. - -- [RTL8195AM](https://www.realtek.com/en/products/communications-network-ics/item/rtl8195am) -- RTL8710AF (found in amb1_arduino) -- [RTL8711AM](https://www.realtek.com/en/products/communications-network-ics/item/rtl8711am) -- [RTL8710BN](https://www.realtek.com/en/products/communications-network-ics/item/rtl8710bn) -- RTL8710BX (found in Tuya product pages) -- RTL8710B? (found in amb1_sdk) -- RTL8711B? (found in amb1_sdk) -- [RTL8710CM](https://www.realtek.com/en/products/communications-network-ics/item/rtl8710cm) -- RTL8722CSM (found in ambd_arduino) -- RTL8720DN (found in ambd_arduino) -- [RTL8721DM](https://www.realtek.com/en/products/communications-network-ics/item/rtl8721dm) -- RTL8722DM (found in ambd_arduino) -- and probably many more - -Different Ameba series are not compatible with each other. Apparently, there isn't an official public SDK for AmebaZ that can support C++ properly. - ## Arduino Core support status Note: this list will probably change with each functionality update. @@ -188,13 +115,12 @@ Wi-Fi Events | ✔️ IPv6 | ❌ HTTP Client (SSL) | ✔️ (✔️) HTTP Server | ✔️ -NVS / Preferences | ❌ +NVS / Preferences | ✔️ SPIFFS | ❌ BLE | - -HTTP | ❌ NTP | ❌ -OTA | ❌ -MDNS | ❌ +OTA | ❓ +MDNS | ✔️ MQTT | ✅ SD | ❌ diff --git a/SUMMARY.md b/SUMMARY.md index 7eb7c6e..2b19e2b 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -1,6 +1,9 @@ * [Home](README.md) -* [Configuration](docs/config.md) -* Reference +* [💻 Platform list](docs/platforms.md) +* [✔️ Implementation status](docs/implementation-status.md) +* [🔧 Configuration](docs/config.md) +* [📁 Project structure](docs/project-structure.md) +* 🔖 Code reference * [LibreTuya API](docs/reference/lt-api.md) * [Class reference](ltapi/class_libre_tuya.md) * [Static functions](ltapi/_libre_tuya_a_p_i_8cpp.md) @@ -26,7 +29,7 @@ * [ssl/MbedTLSClient](ltapi/class_mbed_t_l_s_client.md) * [IPv6Address](ltapi/classarduino_1_1_i_pv6_address.md) * [LwIPRxBuffer](ltapi/class_lw_i_p_rx_buffer.md) - * [Update](ltapi/class_update.md) + * [Update](ltapi/class_update_class.md) * [WebServer](ltapi/class_web_server.md) * [WiFiMulti](ltapi/class_wi_fi_multi.md) * [Third party libraries](docs/libs-3rd-party.md) @@ -35,11 +38,12 @@ * [Functions](ltapi/functions.md) * [Macros](ltapi/macros.md) * [File list](ltapi/files.md) -* [OTA format](docs/ota/README.md) +* [✈️ OTA format](docs/ota/README.md) * [uf2ota.py tool](docs/ota/uf2ota.md) * [uf2ota.h library](docs/ota/library.md) * [uf2ota.h reference](ltapi/uf2ota_8h.md) * Platforms + * [Realtek - notes](docs/platform/realtek/README.md) * Realtek AmebaZ Series * Boards * [WR3](boards/wr3/README.md) diff --git a/docs/config.md b/docs/config.md index ae10315..1278577 100644 --- a/docs/config.md +++ b/docs/config.md @@ -1,6 +1,6 @@ # LibreTuya API Configuration -Note: see [LibreTuyaConfig.h](../arduino/libretuya/api/LibreTuyaConfig.h) for most options and their defaults. +Note: see [LibreTuyaConfig.h](../arduino/libretuya/core/LibreTuyaConfig.h) for most options and their defaults. All options are configurable via C++ defines in PlatformIO project file. For example: ```ini diff --git a/docs/implementation-status.md b/docs/implementation-status.md new file mode 100644 index 0000000..9ceba0f --- /dev/null +++ b/docs/implementation-status.md @@ -0,0 +1,7 @@ +# Implementation status + +{% + include-markdown "../README.md" + start="\n## Arduino Core support status\n" + end="\n## License\n" +%} diff --git a/docs/platform/realtek/README.md b/docs/platform/realtek/README.md new file mode 100644 index 0000000..ade3901 --- /dev/null +++ b/docs/platform/realtek/README.md @@ -0,0 +1,26 @@ +# Realtek Ameba - notes + +The logic behind naming of Realtek chips and their series took me some time to figure out: + +- RTL8xxxA - Ameba1/Ameba Series +- RTL8xxxB - AmebaZ Series +- RTL8xxxC - AmebaZ2/ZII Series +- RTL8xxxD - AmebaD Series + +As such, there are numerous CPUs with the same numbers but different series, which makes them require different code and SDKs. + +- [RTL8195AM](https://www.realtek.com/en/products/communications-network-ics/item/rtl8195am) +- RTL8710AF (found in amb1_arduino) +- [RTL8711AM](https://www.realtek.com/en/products/communications-network-ics/item/rtl8711am) +- [RTL8710BN](https://www.realtek.com/en/products/communications-network-ics/item/rtl8710bn) +- RTL8710BX (found in Tuya product pages) +- RTL8710B? (found in amb1_sdk) +- RTL8711B? (found in amb1_sdk) +- [RTL8710CM](https://www.realtek.com/en/products/communications-network-ics/item/rtl8710cm) +- RTL8722CSM (found in ambd_arduino) +- RTL8720DN (found in ambd_arduino) +- [RTL8721DM](https://www.realtek.com/en/products/communications-network-ics/item/rtl8721dm) +- RTL8722DM (found in ambd_arduino) +- and probably many more + +Different Ameba series are not compatible with each other. Apparently, there isn't an official public SDK for AmebaZ that can support C++ properly. diff --git a/docs/platforms.md b/docs/platforms.md new file mode 100644 index 0000000..e0bca23 --- /dev/null +++ b/docs/platforms.md @@ -0,0 +1,16 @@ +# Platforms + +A list of platforms currently available in this project. + +The following list corresponds to UF2 OTA format family names, and is also [available as JSON](../uf2families.json). The IDs are also present in [uf2ota/models.py](../tools/uf2ota/models.py) and [ChipType.h](../arduino/libretuya/core/ChipType.h). + +Platform name | Platform code | Family name & ID | Supported MCU(s) | Arduino Core | Source SDK +-----------------------------------------------------------------------|---------------|-------------------------|------------------|--------------|-------------------------------------------------------------------------- +Realtek Ameba1 | `-` | `RTL8710A` (0x9FFFD543) | - | ❌ | - +[Realtek AmebaZ](https://www.amebaiot.com/en/amebaz/) (`realtek-ambz`) | `ambz` | `RTL8710B` (0x22E0D6FC) | RTL87xxB | ✔️ | `framework-realtek-amb1` ([amb1_sdk](https://github.com/ambiot/amb1_sdk)) +Realtek AmebaZ2 | `-` | `RTL8720C` (0xE08F7564) | - | ❌ | - +Realtek AmebaD | `-` | `RTL8720D` (0x3379CFE2) | - | ❌ | - +Beken 7231T | `-` | `BK7231T` (0x675A40B0) | - | ❌ | - +Beken 7231N | `-` | `BK7231N` (0x7B3EF230) | - | ❌ | - +Boufallo 602 | `-` | `BL602` (0xDE1270B7) | - | ❌ | - +Xradiotech 809 | `-` | `XR809` (0x51E903A8) | - | ❌ | - diff --git a/docs/platforms.py b/docs/platforms.py new file mode 100644 index 0000000..05b606e --- /dev/null +++ b/docs/platforms.py @@ -0,0 +1,81 @@ +# Copyright (c) Kuba Szczodrzyński 2022-05-31. + +import json +from os.path import dirname, isdir, join + +HEADER = """\ +# Platforms + +A list of platforms currently available in this project. + +The following list corresponds to UF2 OTA format family names, and is also [available as JSON](../uf2families.json). The IDs are also present in [uf2ota/models.py](../tools/uf2ota/models.py) and [ChipType.h](../arduino/libretuya/core/ChipType.h). +""" + + +def format_row(row: list, lengths: list) -> str: + row = [col + " " * (lengths[i] - len(col)) for i, col in enumerate(row)] + return " | ".join(row).rstrip() + + +if __name__ == "__main__": + data = join(dirname(__file__), "..", "uf2families.json") + out = join(dirname(__file__), "platforms.md") + with open(data, "r") as f: + data = json.load(f) + + md = [HEADER] + + lengths = [0, 0, 0, 0, 0, 0] + header = [ + "Platform name", + "Platform code", + "Family name & ID", + "Supported MCU(s)", + "Arduino Core", + "Source SDK", + ] + rows = [] + + for family in data: + id = family["id"] + short_name = family["short_name"] + description = family["description"] + platform = family.get("platform", "") + platform_code = family.get("platform_code", "-") + platform_url = family.get("platform_url", "-") + platform_sdk = family.get("platform_sdk", "-") + platform_framework = family.get("platform_framework", "-") + mcus = family.get("mcus", "-") + platform_sdk_name = platform_sdk.rpartition("/")[2] + arduino = ( + isdir(join(dirname(__file__), "..", "arduino", platform)) + if platform + else False + ) + row = [ + f"[{description}]({platform_url}) (`{platform}`)" + if platform + else description, + f"`{platform_code}`", + f"`{short_name}` ({id})", + ", ".join(mcus), + "✔️" if arduino else "❌", + f"`{platform_framework}` ([{platform_sdk_name}]({platform_sdk}))" + if platform + else "-", + ] + rows.append(row) + + for row in [header] + rows: + for i, col in enumerate(row): + lengths[i] = max(lengths[i], len(col)) + + md.append(format_row(header, lengths)) + md.append("-|-".join(length * "-" for length in lengths)) + for row in rows: + md.append(format_row(row, lengths)) + + md.append("") + + with open(out, "w", encoding="utf-8") as f: + f.write("\n".join(md)) diff --git a/docs/project-structure.md b/docs/project-structure.md new file mode 100644 index 0000000..7064dac --- /dev/null +++ b/docs/project-structure.md @@ -0,0 +1,37 @@ +# Project structure + +``` +arduino/ +├─ / Arduino Core for specific SoC +│ ├─ cores/ Wiring core files +│ ├─ libraries/ Supported built-in platform libraries +├─ libretuya/ +│ ├─ api/ Library interfaces +│ ├─ common/ Units common to all platforms +│ ├─ compat/ Fixes for compatibility with ESP32 framework +│ ├─ core/ LibreTuya API for Arduino cores +│ ├─ libraries/ Built-in platform-independent libraries +boards/ +├─ / Board-specific code +│ ├─ variant.cpp Arduino variant initialization +│ ├─ variant.h Arduino variant pin configs +├─ .json PlatformIO board description +builder/ +├─ frameworks/ Framework builders for PlatformIO +│ ├─ -sdk.py Vanilla SDK build system +│ ├─ -arduino.py Arduino Core build system +├─ arduino-common.py Builder to provide ArduinoCore-API and LibreTuya APIs +├─ main.py Main PlatformIO builder +├─ utils.py SCons utils used during the build +docs/ Project documentation, guides, tips, etc. +platform/ +├─ / Platform-specific configurations +│ ├─ bin/ Binary blobs (bootloaders, etc.) +│ ├─ fixups/ Code fix-ups to replace SDK parts +│ ├─ ld/ Linker scripts +│ ├─ openocd/ OpenOCD configuration files +tools/ +├─ / Tools used during the build +platform.json PlatformIO manifest +platform.py Custom PlatformIO script +``` diff --git a/uf2families.json b/uf2families.json new file mode 100644 index 0000000..ce881bb --- /dev/null +++ b/uf2families.json @@ -0,0 +1,50 @@ +[ + { + "id": "0x9FFFD543", + "short_name": "RTL8710A", + "description": "Realtek Ameba1" + }, + { + "id": "0x22E0D6FC", + "short_name": "RTL8710B", + "description": "Realtek AmebaZ", + "platform": "realtek-ambz", + "platform_code": "ambz", + "platform_url": "https://www.amebaiot.com/en/amebaz/", + "platform_sdk": "https://github.com/ambiot/amb1_sdk", + "platform_framework": "framework-realtek-amb1", + "mcus": [ + "RTL87xxB" + ] + }, + { + "id": "0xE08F7564", + "short_name": "RTL8720C", + "description": "Realtek AmebaZ2" + }, + { + "id": "0x3379CFE2", + "short_name": "RTL8720D", + "description": "Realtek AmebaD" + }, + { + "id": "0x675A40B0", + "short_name": "BK7231T", + "description": "Beken 7231T" + }, + { + "id": "0x7B3EF230", + "short_name": "BK7231N", + "description": "Beken 7231N" + }, + { + "id": "0xDE1270B7", + "short_name": "BL602", + "description": "Boufallo 602" + }, + { + "id": "0x51E903A8", + "short_name": "XR809", + "description": "Xradiotech 809" + } +]