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

[core] Use term "family" instead of "platform"

Browse Source
This commit is contained in:
Kuba Szczodrzyński
2022-06-02 18:21:00 +02:00
parent 9c7ea46ec3
commit 50f26f546c
17 changed files with 83 additions and 84 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
README.md
View File

@@ -18,10 +18,10 @@
PlatformIO development platform for IoT modules manufactured by Tuya Inc.
The main goal of this project is to provide a usable build environment for IoT developers. While also providing vendor SDKs as PlatformIO cores,
the project focuses on developing working Arduino-compatible cores for supported platforms. The cores are inspired by Espressif's official core for ESP32,
which should make it easier to port/run existing ESP apps on Tuya IoT (and 3-rd party) platforms.
the project focuses on developing working Arduino-compatible cores for supported families. The cores are inspired by Espressif's official core for ESP32,
which should make it easier to port/run existing ESP apps on Tuya IoT (and 3-rd party) modules.
LibreTuya also provides a common interface for all platform implementations. The interface is based on ESP32 official libraries.
LibreTuya also provides a common interface for all family implementations. The interface is based on ESP32 official libraries.
**Note:** this project is work-in-progress.
@@ -36,7 +36,7 @@ LibreTuya also provides a common interface for all platform implementations. The
A (mostly) complete* list of Tuya wireless module boards.
  | Module Name | MCU | Flash | RAM | Pins** | Wi-Fi | BLE | Platform name
  | Module Name | MCU | Flash | RAM | Pins** | Wi-Fi | BLE | Family name
------------------------------|------------------------------------------------------------------------------------------------|-------------------------|-------|----------|-------------|-------|-----|---------------
❌ | [WB1S](https://developer.tuya.com/en/docs/iot/wb1s?id=K9duevbj3ol4x) | BK7231T @ 120 MHz | 2 MiB | 256 KiB | 18 (11 I/O) | ✔️ | ✔️ | -
❌ | [WB2L](https://developer.tuya.com/en/docs/iot/wb2l-datasheet?id=K9duegc9bualu) | BK7231T @ 120 MHz | 2 MiB | 256 KiB | 7 (5 I/O) | ✔️ | ✔️ | -

4
SUMMARY.md
View File

@@ -1,5 +1,5 @@
* [Home](README.md)
* [💻 Platform list](docs/platforms.md)
* [💻 Family list](docs/families.md)
* [✔️ Implementation status](docs/implementation-status.md)
* [🔧 Configuration](docs/config.md)
* [📁 Project structure](docs/project-structure.md)
@@ -42,7 +42,7 @@
* [uf2ota.py tool](docs/ota/uf2ota.md)
* [uf2ota.h library](docs/ota/library.md)
* [uf2ota.h reference](ltapi/uf2ota_8h.md)
* Platforms
* Families
* [Realtek - notes](docs/platform/realtek/README.md)
* Realtek AmebaZ Series
* Boards

8
arduino/libretuya/core/LibreTuyaAPI.h
View File

@@ -61,10 +61,10 @@ void hexdump(uint8_t *buf, size_t len, uint32_t offset, uint8_t width);
/**
* @brief Main LibreTuya API class.
*
* This class contains all functions common amongst all platforms.
* Implementations of these methods may vary between platforms.
* This class contains all functions common amongst all families.
* Implementations of these methods may vary between families.
*
* The class is accessible using the `LT` global object (defined by the platform).
* The class is accessible using the `LT` global object (defined by the family).
*/
class LibreTuya {
public: /* Common methods - note: these are documented in LibreTuyaAPI.cpp */
@@ -90,7 +90,7 @@ class LibreTuya {
// inline bool partitionWrite(const esp_partition_t *partition, uint32_t offset, uint32_t *data, size_t size) {}
// inline bool partitionRead(const esp_partition_t *partition, uint32_t offset, uint32_t *data, size_t size) {}
public: /* Platform-defined methods */
public: /* Family-defined methods */
/**
* @brief Reboot the CPU.
*/

2
arduino/libretuya/libraries/NetUtils/ssl/MbedTLSClient.h
View File

@@ -5,7 +5,7 @@
#include <api/WiFiClient.h>
#include <api/WiFiClientSecure.h>
#include <WiFiClient.h> // extend platform's WiFiClient impl
#include <WiFiClient.h> // extend family's WiFiClient impl
#ifdef __cplusplus
extern "C" {

2
arduino/libretuya/libraries/Update/uf2ota/uf2priv.h
View File

@@ -2,7 +2,7 @@
#pragma once
// include platform stdlib APIs
// include family stdlib APIs
#include <WVariant.h>
#include "uf2binpatch.h"

2
arduino/realtek-ambz/cores/arduino/Arduino.h
View File

@@ -23,7 +23,7 @@ extern uint32_t SystemCoreClock;
#define interrupts() vPortClearInterruptMask(0)
#define noInterrupts() ulPortSetInterruptMask()
// Include platform-specific code
// Include family-specific code
#include "WVariant.h"
// Include board variant
#include "variant.h"

2
builder/frameworks/realtek-ambz-sdk.py
View File

@@ -203,7 +203,7 @@ env.AddLibrary(
],
)
# Sources - platform fixups
# Sources - family fixups
env.AddLibrary(
name="ambz_fixups",
base_dir="$FIXUPS_DIR",

4
builder/main.py
View File

@@ -52,8 +52,8 @@ if flash_layout:
env.Append(CPPDEFINES=defines.items())
env.Replace(**defines)
# Platform builders details:
# - call env.AddDefaults("platform name", "sdk name") to add dir paths
# Family builders details:
# - call env.AddDefaults("family name", "sdk name") to add dir paths
# - call env.AddLibrary("lib name", "base dir", [sources]) to add lib sources
# - call env.BuildLibraries() to build lib targets with safe envs
# - configure LINK, UF2OTA and UPLOAD_ACTIONS

16
builder/utils.py
View File

@@ -12,20 +12,20 @@ platform = env.PioPlatform()
board = env.BoardConfig()
def env_add_defaults(env, platform_name: str, sdk_name: str):
def env_add_defaults(env, family_name: str, sdk_name: str):
vars = dict(
SDK_DIR=platform.get_package_dir(sdk_name),
LT_DIR=platform.get_dir(),
# Root dirs
BOARD_DIR=join("${LT_DIR}", "boards", "${VARIANT}"),
ARDUINO_DIR=join("${LT_DIR}", "arduino", platform_name),
PLATFORM_DIR=join("${LT_DIR}", "platform", platform_name),
ARDUINO_DIR=join("${LT_DIR}", "arduino", family_name),
FAMILY_DIR=join("${LT_DIR}", "platform", family_name),
TOOLS_DIR=join("${LT_DIR}", "tools"),
# Platform-specific dirs
BIN_DIR=join("${PLATFORM_DIR}", "bin"),
FIXUPS_DIR=join("${PLATFORM_DIR}", "fixups"),
LD_DIR=join("${PLATFORM_DIR}", "ld"),
OPENOCD_DIR=join("${PLATFORM_DIR}", "openocd"),
# Family-specific dirs
BIN_DIR=join("${FAMILY_DIR}", "bin"),
FIXUPS_DIR=join("${FAMILY_DIR}", "fixups"),
LD_DIR=join("${FAMILY_DIR}", "ld"),
OPENOCD_DIR=join("${FAMILY_DIR}", "openocd"),
# Board config variables
MCU=board.get("build.mcu").upper(),
FAMILY=board.get("build.family"),

8
docs/config.md
View File

@@ -29,7 +29,7 @@ build_flags =
The following options enable library-specific debugging messages. They are only effective if `LT_LOGLEVEL` is set below INFO. All of them are disabled by default.
Platforms should generally call i.e. WiFiClient debugging for client-related code, even if the `WiFiClient.cpp` file is physically absent.
Families should generally call i.e. WiFiClient debugging for client-related code, even if the `WiFiClient.cpp` file is physically absent.
- LT_DEBUG_WIFI - `WiFi.cpp`
- LT_DEBUG_WIFI_CLIENT - `WiFiClient.cpp`
@@ -37,7 +37,7 @@ Platforms should generally call i.e. WiFiClient debugging for client-related cod
- LT_DEBUG_WIFI_STA - `WiFiSTA.cpp`
- LT_DEBUG_WIFI_AP - `WiFiAP.cpp`
## Platform options
## Family options
- LT_HAS_LWIP - whether platform SDK has LwIP. This causes `LwIPRxBuffer.cpp` to be compiled for platform libraries to use.
- LT_HAS_LWIP2 - whether platform has LwIP v2.0.0 or newer. This causes `LwIPmDNS.cpp` to be compiled.
- LT_HAS_LWIP - whether family SDK has LwIP. This causes `LwIPRxBuffer.cpp` to be compiled for family libraries to use.
- LT_HAS_LWIP2 - whether family has LwIP v2.0.0 or newer. This causes `LwIPmDNS.cpp` to be compiled.

18
docs/families.md Normal file
View File

@@ -0,0 +1,18 @@
# Families
A list of families currently available in this project.
**Note:** the term *family* was chosen over *platform*, in order to reduce possible confusion between LibreTuya supported "platforms" and PlatformIO's "platform", as an entire package. *Family* is also more compatible with the UF2 term.
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).
Full name | Code | Short 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) | - | ❌ | -

42
docs/platforms.py → docs/families.py
View File

@@ -4,9 +4,11 @@ import json
from os.path import dirname, isdir, join
HEADER = """\
# Platforms
# Families
A list of platforms currently available in this project.
A list of families currently available in this project.
**Note:** the term *family* was chosen over *platform*, in order to reduce possible confusion between LibreTuya supported "platforms" and PlatformIO's "platform", as an entire package. *Family* is also more compatible with the UF2 term.
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).
"""
@@ -18,8 +20,8 @@ def format_row(row: list, lengths: list) -> str:
if __name__ == "__main__":
data = join(dirname(__file__), "..", "uf2families.json")
out = join(dirname(__file__), "platforms.md")
data = join(dirname(__file__), "..", "families.json")
out = join(dirname(__file__), "families.md")
with open(data, "r") as f:
data = json.load(f)
@@ -27,9 +29,9 @@ if __name__ == "__main__":
lengths = [0, 0, 0, 0, 0, 0]
header = [
"Platform name",
"Platform code",
"Family name & ID",
"Full name",
"Code",
"Short name & ID",
"Supported MCU(s)",
"Arduino Core",
"Source SDK",
@@ -40,29 +42,23 @@ if __name__ == "__main__":
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", "-")
name = family.get("name", "")
code = family.get("code", "-")
url = family.get("url", "-")
sdk = family.get("sdk", "-")
framework = family.get("framework", "-")
mcus = family.get("mcus", "-")
platform_sdk_name = platform_sdk.rpartition("/")[2]
sdk_name = sdk.rpartition("/")[2]
arduino = (
isdir(join(dirname(__file__), "..", "arduino", platform))
if platform
else False
isdir(join(dirname(__file__), "..", "arduino", name)) if name else False
)
row = [
f"[{description}]({platform_url}) (`{platform}`)"
if platform
else description,
f"`{platform_code}`",
f"[{description}]({url}) (`{name}`)" if name else description,
f"`{code}`",
f"`{short_name}` ({id})",
", ".join(mcus),
"✔️" if arduino else "❌",
f"`{platform_framework}` ([{platform_sdk_name}]({platform_sdk}))"
if platform
else "-",
f"`{framework}` ([{sdk_name}]({sdk}))" if name else "-",
]
rows.append(row)

16
docs/platforms.md
View File

@@ -1,16 +0,0 @@
# 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) | - | ❌ | -

15
docs/project-structure.md
View File

@@ -2,15 +2,15 @@
```
arduino/
├─ <platform name>/ Arduino Core for specific SoC
├─ <family name>/ Arduino Core for specific SoC
│ ├─ cores/ Wiring core files
│ ├─ libraries/ Supported built-in platform libraries
│ ├─ libraries/ Supported built-in family libraries
├─ libretuya/
│ ├─ api/ Library interfaces
│ ├─ common/ Units common to all platforms
│ ├─ common/ Units common to all families
│ ├─ compat/ Fixes for compatibility with ESP32 framework
│ ├─ core/ LibreTuya API for Arduino cores
│ ├─ libraries/ Built-in platform-independent libraries
│ ├─ libraries/ Built-in family-independent libraries
boards/
├─ <board name>/ Board-specific code
│ ├─ variant.cpp Arduino variant initialization
@@ -18,20 +18,21 @@ boards/
├─ <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
│ ├─ <family name>-sdk.py Vanilla SDK build system
│ ├─ <family 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
├─ <family name>/ Family-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
families.json List of supported device families
platform.json PlatformIO manifest
platform.py Custom PlatformIO script
```

10
uf2families.json → families.json
View File

@@ -8,11 +8,11 @@
"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",
"name": "realtek-ambz",
"code": "ambz",
"url": "https://www.amebaiot.com/en/amebaz/",
"sdk": "https://github.com/ambiot/amb1_sdk",
"framework": "framework-realtek-amb1",
"mcus": [
"RTL87xxB"
]

8
platform.py
View File

@@ -201,7 +201,7 @@ class LibretuyaPlatform(PlatformBase):
args.extend(
[
"-f",
"$LTPATH/platform/$LTPLATFORM/openocd/%s"
"$LTPATH/platform/$LTFAMILY/openocd/%s"
% debug.get("openocd_config"),
]
)
@@ -226,7 +226,7 @@ class LibretuyaPlatform(PlatformBase):
opts = debug_config.env_options
server = debug_config.server
lt_path = dirname(__file__)
lt_platform = opts["framework"][0].rpartition("-")[0]
lt_family = opts["framework"][0].rpartition("-")[0]
if not server:
debug_tool = opts.get("debug_tool", "custom")
board = opts.get("board", "<unknown>")
@@ -244,8 +244,8 @@ class LibretuyaPlatform(PlatformBase):
"-f",
"interface/%s.cfg" % opts.get("openocd_interface"),
] + server["arguments"]
# replace $LTPLATFORM with actual name
# replace $LTFAMILY with actual name
server["arguments"] = [
arg.replace("$LTPLATFORM", lt_platform).replace("$LTPATH", lt_path)
arg.replace("$LTFAMILY", lt_family).replace("$LTPATH", lt_path)
for arg in server["arguments"]
]

2
tools/link2bin.py
View File

@@ -218,7 +218,7 @@ if __name__ == "__main__":
description="Link to BIN format",
prefix_chars="@",
)
parser.add_argument("soc", type=str, help="SoC name/platform short name")
parser.add_argument("soc", type=str, help="SoC name/family short name")
parser.add_argument("ota1", type=str, help=".LD file OTA1 pattern")
parser.add_argument("ota2", type=str, help=".LD file OTA2 pattern")
parser.add_argument("args", type=str, nargs="*", help="Linker arguments")