scratch/libretiny
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[docs] Move sections from README to docs, add uf2families.json

Browse Source
This commit is contained in:
Kuba Szczodrzyński
2022-05-31 11:54:05 +02:00
parent 1ea6420bbc
commit 12aa7fef04
9 changed files with 229 additions and 82 deletions
Download Patch File Download Diff File Expand all files Collapse all files

80
README.md
View File

@@ -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. ** I/O count includes GPIOs, ADCs, PWM outputs and UART, but doesn't count CEN/RST and power pins.
## Project structure
```
arduino/
├─ <platform name>/ 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 name>/ Board-specific code
│ ├─ variant.cpp Arduino variant initialization
│ ├─ variant.h Arduino variant pin configs
├─ <board name>.json PlatformIO board description
builder/
├─ frameworks/ Framework builders for PlatformIO
│ ├─ <platform name>-sdk.py Vanilla SDK build system
│ ├─ <platform name>-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 name>/ Platform-specific configurations
│ ├─ bin/ Binary blobs (bootloaders, etc.)
│ ├─ fixups/ Code fix-ups to replace SDK parts
│ ├─ ld/ Linker scripts
│ ├─ openocd/ OpenOCD configuration files
tools/
├─ <tool name>/ 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 ## Arduino Core support status
Note: this list will probably change with each functionality update. Note: this list will probably change with each functionality update.
@@ -188,13 +115,12 @@ Wi-Fi Events | ✔️
IPv6 | ❌ IPv6 | ❌
HTTP Client (SSL) | ✔️ (✔️) HTTP Client (SSL) | ✔️ (✔️)
HTTP Server | ✔️ HTTP Server | ✔️
NVS / Preferences | ❌ NVS / Preferences | ✔️
SPIFFS | ❌ SPIFFS | ❌
BLE | - BLE | -
HTTP | ❌
NTP | ❌ NTP | ❌
OTA | ❌ OTA | ❓
MDNS | ❌ MDNS | ✔️
MQTT | ✅ MQTT | ✅
SD | ❌ SD | ❌

12
SUMMARY.md
View File

@@ -1,6 +1,9 @@
* [Home](README.md) * [Home](README.md)
* [Configuration](docs/config.md) * [💻 Platform list](docs/platforms.md)
* Reference * [✔️ 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) * [LibreTuya API](docs/reference/lt-api.md)
* [Class reference](ltapi/class_libre_tuya.md) * [Class reference](ltapi/class_libre_tuya.md)
* [Static functions](ltapi/_libre_tuya_a_p_i_8cpp.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) * [ssl/MbedTLSClient](ltapi/class_mbed_t_l_s_client.md)
* [IPv6Address](ltapi/classarduino_1_1_i_pv6_address.md) * [IPv6Address](ltapi/classarduino_1_1_i_pv6_address.md)
* [LwIPRxBuffer](ltapi/class_lw_i_p_rx_buffer.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) * [WebServer](ltapi/class_web_server.md)
* [WiFiMulti](ltapi/class_wi_fi_multi.md) * [WiFiMulti](ltapi/class_wi_fi_multi.md)
* [Third party libraries](docs/libs-3rd-party.md) * [Third party libraries](docs/libs-3rd-party.md)
@@ -35,11 +38,12 @@
* [Functions](ltapi/functions.md) * [Functions](ltapi/functions.md)
* [Macros](ltapi/macros.md) * [Macros](ltapi/macros.md)
* [File list](ltapi/files.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.py tool](docs/ota/uf2ota.md)
* [uf2ota.h library](docs/ota/library.md) * [uf2ota.h library](docs/ota/library.md)
* [uf2ota.h reference](ltapi/uf2ota_8h.md) * [uf2ota.h reference](ltapi/uf2ota_8h.md)
* Platforms * Platforms
* [Realtek - notes](docs/platform/realtek/README.md)
* Realtek AmebaZ Series * Realtek AmebaZ Series
* Boards * Boards
* [WR3](boards/wr3/README.md) * [WR3](boards/wr3/README.md)

2
docs/config.md
View File

@@ -1,6 +1,6 @@
# LibreTuya API Configuration # 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: All options are configurable via C++ defines in PlatformIO project file. For example:
```ini ```ini

7
docs/implementation-status.md Normal file
View File

@@ -0,0 +1,7 @@
# Implementation status
{%
include-markdown "../README.md"
start="\n## Arduino Core support status\n"
end="\n## License\n"
%}

26
docs/platform/realtek/README.md Normal file
View File

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

16
docs/platforms.md Normal file
View File

@@ -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) | - | ❌ | -

81
docs/platforms.py Normal file
View File

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

37
docs/project-structure.md Normal file
View File

@@ -0,0 +1,37 @@
# Project structure
```
arduino/
├─ <platform name>/ 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 name>/ Board-specific code
│ ├─ variant.cpp Arduino variant initialization
│ ├─ variant.h Arduino variant pin configs
├─ <board name>.json PlatformIO board description
builder/
├─ frameworks/ Framework builders for PlatformIO
│ ├─ <platform name>-sdk.py Vanilla SDK build system
│ ├─ <platform name>-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 name>/ Platform-specific configurations
│ ├─ bin/ Binary blobs (bootloaders, etc.)
│ ├─ fixups/ Code fix-ups to replace SDK parts
│ ├─ ld/ Linker scripts
│ ├─ openocd/ OpenOCD configuration files
tools/
├─ <tool name>/ Tools used during the build
platform.json PlatformIO manifest
platform.py Custom PlatformIO script
```

50
uf2families.json Normal file
View File

@@ -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"
}
]