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.

LibreTuya also provides a common interface for all platform implementations. The interface is based on ESP32 official libraries.

Note: this project is work-in-progress.

Usage

Install PlatformIO
platformio platform install libretuya
Create a project, build it and upload!
See the docs for any questions/problems.

Board List

A (mostly) complete* list of Tuya wireless module boards.

	Module Name	MCU	Flash	RAM	Pins**	Wi-Fi	BLE	Platform name
❌	WB1S	BK7231T @ 120 MHz	2 MiB	256 KiB	18 (11 I/O)	✔️	✔️	-
❌	WB2L	BK7231T @ 120 MHz	2 MiB	256 KiB	7 (5 I/O)	✔️	✔️	-
❌	WB2S	BK7231T @ 120 MHz	2 MiB	256 KiB	11 (8 I/O)	✔️	✔️	-
❌	WB3L	BK7231T @ 120 MHz	2 MiB	256 KiB	16 (12 I/O)	✔️	✔️	-
❌	WB3S	BK7231T @ 120 MHz	2 MiB	256 KiB	16 (11 I/O)	✔️	✔️	-
❌	WB3S-IPEX	BK7231T @ 120 MHz	2 MiB	256 KiB	16 (11 I/O)	✔️	✔️	-
❌	WB8P	BK7231T @ 120 MHz	2 MiB	256 KiB	10 (8 I/O)	✔️	✔️	-
❌	WBLC5	BK7231T @ 120 MHz	2 MiB	256 KiB	6 (3 I/O)	✔️	✔️	-
❌	WBLC9	BK7231T @ 120 MHz	2 MiB	256 KiB	8 (6 I/O)	✔️	✔️	-
❌	CB1S	BK7231N @ 120 MHz	2 MiB	256 KiB	18 (11 I/O)	✔️	✔️	-
❌	CB2L	BK7231N @ 120 MHz	2 MiB	256 KiB	7 (5 I/O)	✔️	✔️	-
❌	CB2S	BK7231N @ 120 MHz	2 MiB	256 KiB	11 (8 I/O)	✔️	✔️	-
❌	CB3L	BK7231N @ 120 MHz	2 MiB	256 KiB	16 (11 I/O)	✔️	✔️	-
❌	CB3S	BK7231N @ 120 MHz	2 MiB	256 KiB	22 (14 I/O)	✔️	✔️	-
❌	CB3S-NL	BK7231NL (?) @ 120 MHz	2 MiB	256 KiB	22 (14 I/O)	✔️	✔️	-
❌	CB3SE	BK7231N @ 120 MHz	2 MiB	256 KiB	22 (17 I/O)	✔️	✔️	-
❌	CB8P	BK7231N @ 120 MHz	2 MiB	256 KiB	10 (8 I/O)	✔️	✔️	-
❌	CBLC5	BK7231N @ 120 MHz	2 MiB	256 KiB	6 (3 I/O)	✔️	✔️	-
❌	CBLC9	BK7231N @ 120 MHz	2 MiB	256 KiB	8 (6 I/O)	✔️	✔️	-
❌	CBU	BK7231N @ 120 MHz	2 MiB	256 KiB	21 (18 I/O)	✔️	✔️	-
❌	CBU-IPEX	BK7231N @ 120 MHz	2 MiB	256 KiB	21 (18 I/O)	✔️	✔️	-
❌	CBU-NL	BK7231N (?) @ 120 MHz	2 MiB	256 KiB	21 (18 I/O)	✔️	✔️	-
❌	WR1	RTL8710BN @ 125 MHz	1 MiB	256 KiB	18 (11 I/O)	✔️	❌	-
❌	WR1-IPEX	RTL8710BN @ 125 MHz	1 MiB	256 KiB	18 (11 I/O)	✔️	❌	-
❌	WR1E	RTL8710BN @ 125 MHz	2 MiB	256 KiB	18 (11 I/O)	✔️	❌	-
❌	WR2	RTL8710BN @ 125 MHz	2 MiB	256 KiB	11 (8 I/O)	✔️	❌	-
❌	WR2E	RTL8710BN @ 125 MHz	2 MiB	256 KiB	11 (8 I/O)	✔️	❌	-
❌	WR2L	RTL8710BX @ 62.5 MHz	2 MiB	256 KiB	7 (5 I/O)	✔️	❌	-
❌	WR2LE	RTL8710BX @ 62.5 MHz	2 MiB	256 KiB	7 (5 I/O)	✔️	❌	-
`wr3`	WR3	RTL8710BN @ 125 MHz	2 MiB	256 KiB	16 (12 I/O)	✔️	❌	`realtek-ambz`
❌	WR3E	RTL8710BN @ 125 MHz	2 MiB	256 KiB	16 (12 I/O)	✔️	❌	-
❌	WR3L	RTL8710BX @ 125 MHz (?)	2 MiB	256 KiB	16 (12 I/O)	✔️	❌	-
❌	WR3LE	RTL8710BX @ 62.5 MHz	2 MiB	256 KiB	16 (12 I/O)	✔️	❌	-
❌	WR3N	RTL8710BN @ 125 MHz	2 MiB	256 KiB	16 (10 I/O)	✔️	❌	-
❌	WR4	RTL8710BN @ 125 MHz	1 MiB	256 KiB	16 (12 I/O)	✔️	❌	-
❌	WR5E	RTL8710BX @ 62.5 MHz	2 MiB	256 KiB	15 (12 I/O)	✔️	❌	-
❌	WR6-H	RTL8710BN @ 125 MHz	2 MiB	256 KiB	18 (12 I/O)	✔️	❌	-
❌	WR6	RTL8710BN @ 125 MHz	2 MiB	256 KiB	18 (12 I/O)	✔️	❌	-
❌	WRG1	RTL8711AM @ 166 MHz	4 MiB	2048 KiB	25 (20 I/O)	✔️	❌	-
❌	XR1	XR809 @ 160 MHz	2 MiB	384 KiB	18 (11 I/O)	✔️	❌	-
❌	XR1-IPEX	XR809 @ 160 MHz	2 MiB	384 KiB	18 (11 I/O)	✔️	❌	-
❌	XR3	XR809 @ 160 MHz	2 MiB	384 KiB	22 (17 I/O)	✔️	❌	-
❌	WE1S	ESP8266EX @ 80/160 MHz	2 MiB	36 KiB	18 (11 I/O)	✔️	❌	-
❌	WE2L	ESP8285 @ 80/160 MHz	1 MiB	50 KiB	7 (5 I/O)	✔️	❌	-
❌	WE2S	ESP8285 @ 80/160 MHz	1 MiB	50 KiB	11 (8 I/O)	✔️	❌	-
❌	WE3L	ESP8266 @ 80/160 MHz	2 MiB	50 KiB	16 (12 I/O)	✔️	❌	-
❌	WE3S	ESP8266 @ 80/160 MHz	2 MiB	50 KiB	16 (12 I/O)	✔️	❌	-
❌	WE3SE	ESP32 @ 240 MHz	4 MiB	520 KiB	22 (17 I/O)	✔️	✔️	-
❌	WE5P	ESP8266 @ 80/160 MHz	1 MiB	50 KiB	15 (11 I/O)	✔️	❌	-

* Only modules featuring at least Wi-Fi. WBR, JWBR, CR, (TY)JW and (TY)LC Series are not included here

** 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/                      LibreTuya API (interfaces + LT class) for Arduino frameworks
│  ├─ common/                   Units common to all platforms
│  ├─ compat/                   Fixes for compatibility with ESP32 framework
│  ├─ 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 SoC (`RTL87xxB`)	✔️	`framework-realtek-amb1` (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
RTL8710AF (found in amb1_arduino)
RTL8711AM
RTL8710BN
RTL8710BX (found in Tuya product pages)
RTL8710B? (found in amb1_sdk)
RTL8711B? (found in amb1_sdk)
RTL8710CM
RTL8722CSM (found in ambd_arduino)
RTL8720DN (found in ambd_arduino)
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.

	`realtek-ambz`
Core functions	✔️
GPIO/PWM/IRQ	✔️/❓/✔️
Analog input	❓
UART I/O	✔️
Flash I/O	❓
CORE LIBRARIES
SoftwareSerial	❌
SPI	❌
Wire	❌
OTHER LIBRARIES
Wi-Fi STA/AP/Mixed	✔️
Wi-Fi Client (SSL)	✔️ (✔️)
Wi-Fi Server	✔️
Wi-Fi Events	❌
IPv6	❌
HTTP Client (SSL)	✔️ (❌)
HTTP Server	✔️
NVS / Preferences	❌
SPIFFS	❌
BLE	-
HTTP	❌
NTP	❌
OTA	❌
MDNS	❌
MQTT	✅
SD	❌

Symbols:

✔️ working
✅ tested, external library
❓ untested
❗ broken
❌ not implemented (yet?)
- not applicable

Names:

Core functions - stuff like delay(), millis(), yield(), etc.
CORE LIBRARIES - included normally in all Arduino cores
OTHER LIBRARIES - included in ESP32 core or downloadable

License

See LICENSE. Project is licensed under MIT License.

Parts of the code may come from third parties, vendor SDKs or other open-source projects. Most of these files are marked with appropriate copyright/author/license notices.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.