diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index f6b6180..1fc5c62 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -25,8 +25,9 @@ jobs: run: | mkdir -p site/ boardgen ltci - python docs/update_docs.py - python docs/build_json.py + python docs/scripts/update_docs.py + python docs/scripts/prepare_doxygen.py + python docs/scripts/build_json.py cp *.json site/ - name: Set custom domain diff --git a/SUMMARY.md b/SUMMARY.md index 7badd4c..3b6881a 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -1,58 +1,54 @@ * [Home](README.md) +* [](SUMMARY.md) * [😊 Getting started](docs/getting-started/README.md) - * [ESPHome](docs/projects/esphome.md) -* [📲 Flashing/dumping](docs/flashing/) -* [💻 Supported boards & chips](docs/status/supported.md) -* 📖 Reference - * Chip families - * [Beken BK72xx](docs/platform/beken-72xx/README.md) - * [Realtek Ameba - info](docs/platform/realtek-amb/README.md) - * [Realtek AmebaZ](docs/platform/realtek-ambz/README.md) - * [Debugging](docs/platform/realtek-ambz/debugging.md) - * [Exception decoder](docs/platform/realtek-ambz/exception-decoder.md) - * C library - * [Built-in functions](docs/platform/realtek-ambz/stdlib.md) - * [Memory management](docs/platform/realtek-ambz/memory-management.md) - * [🔧 LT configuration](docs/reference/config.md) - * [✔️ Implementation status](docs/status/arduino.md) - * [🔌 Boards documentation](boards/) - * [🔋 Examples](examples/) - * [📖 LibreTuya API](docs/reference/lt-api.md) - * [LT class reference](ltapi/class_libre_tuya.md) - * [Common methods](ltapi/_libre_tuya_a_p_i_8h.md) - * [Wiring custom methods](ltapi/_libre_tuya_custom_8h.md) - * [Logger](ltapi/lt__logger_8h.md) - * [Chip & family IDs](ltapi/_chip_type_8h_source.md) - * [POSIX utilities](ltapi/lt__posix__api_8h.md) - * 📖 Common API - * [FS](ltapi/classfs_1_1_f_s.md) - * [Preferences](ltapi/class_i_preferences.md) +* [💡 ESPHome setup guide](docs/projects/esphome.md) +* [📲 Flashing/dumping guide](docs/flashing/) +* [🔌 How to enter download mode?](docs/flashing/chip-connection/) +* [💻 Supported modules list](docs/status/supported.md) + * [All boards](boards/) +* [](SUMMARY.md) +* 🍪 Chip family docs & info + * [Beken BK72xx](docs/platform/beken-72xx/README.md) + * [Realtek Ameba - info](docs/platform/realtek-amb/README.md) + * [Realtek AmebaZ](docs/platform/realtek-ambz/README.md) + * [Debugging](docs/platform/realtek-ambz/debugging.md) + * [Exception decoder](docs/platform/realtek-ambz/exception-decoder.md) +* [🔧 LT Configuration](docs/dev/config.md) +* 🧑 Programmer's manual + * [🔋 PlatformIO Examples](examples/) + * [📖 LibreTuya API](docs/dev/lt-api.md) + * [C API](ltapi/dir_c7e317b16142bccc961a83c0babf0065.md) + * [C++ API](ltapi/dir_930634efd5dc4a957bbb6e685a3ccda1.md) + * 📚 Arduino Libraries * [SoftwareSerial](ltapi/class_software_serial.md) - * [WiFi API](ltapi/class_wi_fi_class.md) - * [TCP Client](ltapi/class_i_wi_fi_client.md) - * [SSL Client](ltapi/class_i_wi_fi_client_secure.md) - * [TCP Server](ltapi/class_i_wi_fi_server.md) - * [📖 LibreTuya libraries](docs/libs-built-in.md) - * [base64](ltapi/classbase64.md) + * [WiFi](ltapi/class_wi_fi_class.md) + * [](SUMMARY.md) * [Flash](ltapi/class_flash_class.md) - * [HTTPClient](ltapi/class_h_t_t_p_client.md) + * [IPv6Address](ltapi/classarduino_1_1_i_pv6_address.md) + * [MD5](ltapi/libraries_2common_2_m_d5_2_m_d5_8h.md) * [mDNS](ltapi/classm_d_n_s.md) - * NetUtils - * [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_class.md) + * [WiFiClient](ltapi/class_i_wi_fi_client.md) + * [WiFiClientSecure](ltapi/class_i_wi_fi_client_secure.md) + * [WiFiServer](ltapi/class_i_wi_fi_server.md) + * [WiFiUDP](ltapi/class_i_wi_fi_u_d_p.md) + * [](SUMMARY.md) + * [HTTPClient](ltapi/class_h_t_t_p_client.md) + * [StreamString](ltapi/class_stream_string.md) * [WebServer](ltapi/class_web_server.md) * [WiFiMulti](ltapi/class_wi_fi_multi.md) - * [Third party libraries](docs/libs-3rd-party.md) + * [](SUMMARY.md) + * [External compatible libraries](docs/dev/libs-3rd-party.md) * Full documentation * [Classes](ltapi/classes.md) * [Functions](ltapi/functions.md) * [Macros](ltapi/macros.md) * [File list](ltapi/files.md) - * [📁 Project structure](docs/reference/project-structure.md) - * [✈️ OTA format](docs/ota/README.md) - * [uf2ota.py tool](docs/ota/uf2ota.md) - * [uf2ota.h library](docs/ota/library.md) - * [📓 TODO](TODO.md) +* 👷 Contributor's manual (WIP) + * [📁 Project structure](docs/dev/project-structure.md) + * [✈️ OTA format](docs/dev/ota/README.md) + * [uf2ota.py tool](docs/dev/ota/uf2ota.md) + * [uf2ota.h library](docs/dev/ota/library.md) + * [📓 TODO](docs/TODO.md) +* [](SUMMARY.md) * [🔗 Resources](docs/resources/) diff --git a/cores/common/arduino/libraries/api/SoftwareSerial/SoftwareSerial.cpp b/cores/common/arduino/libraries/api/SoftwareSerial/SoftwareSerial.cpp index 00ad31d..af60a5f 100644 --- a/cores/common/arduino/libraries/api/SoftwareSerial/SoftwareSerial.cpp +++ b/cores/common/arduino/libraries/api/SoftwareSerial/SoftwareSerial.cpp @@ -2,7 +2,7 @@ #include "SoftwareSerial.h" -#ifdef LT_ARD_HAS_SOFTSERIAL +#if LT_ARD_HAS_SOFTSERIAL SoftwareSerial::SoftwareSerial(pin_size_t receivePin, pin_size_t transmitPin, bool inverted) { data.rx.buf = NULL; diff --git a/cores/common/arduino/libraries/api/SoftwareSerial/SoftwareSerial.h b/cores/common/arduino/libraries/api/SoftwareSerial/SoftwareSerial.h index 5bcafda..151b194 100644 --- a/cores/common/arduino/libraries/api/SoftwareSerial/SoftwareSerial.h +++ b/cores/common/arduino/libraries/api/SoftwareSerial/SoftwareSerial.h @@ -2,7 +2,7 @@ #pragma once -#ifdef LT_ARD_HAS_SOFTSERIAL +#if LT_ARD_HAS_SOFTSERIAL || DOXYGEN #include #include diff --git a/cores/common/arduino/libraries/common/Update/UpdateUtil.cpp b/cores/common/arduino/libraries/common/Update/UpdateUtil.cpp index 3be655c..59c28b2 100644 --- a/cores/common/arduino/libraries/common/Update/UpdateUtil.cpp +++ b/cores/common/arduino/libraries/common/Update/UpdateUtil.cpp @@ -178,16 +178,12 @@ const char *UpdateClass::getBoardName() { return NULL; } -/** - * @copydoc lt_ota_can_rollback() - */ +/** @copydoc lt_ota_can_rollback() */ bool UpdateClass::canRollBack() { return lt_ota_can_rollback(); } -/** - * @brief See LT.otaRollback() for more info. - */ +/** @copydoc lt_ota_switch() */ bool UpdateClass::rollBack() { if (!lt_ota_can_rollback()) return false; diff --git a/cores/common/arduino/libraries/common/WiFiClient/LwIPClient.h b/cores/common/arduino/libraries/common/WiFiClient/LwIPClient.h index 9593fc9..d4411f9 100644 --- a/cores/common/arduino/libraries/common/WiFiClient/LwIPClient.h +++ b/cores/common/arduino/libraries/common/WiFiClient/LwIPClient.h @@ -2,7 +2,7 @@ #pragma once -#if LT_ARD_HAS_WIFI && LT_HAS_LWIP +#if (LT_ARD_HAS_WIFI && LT_HAS_LWIP) || DOXYGEN #include "WiFiClient.h" diff --git a/cores/common/arduino/libraries/common/WiFiClient/MbedTLSClient.h b/cores/common/arduino/libraries/common/WiFiClient/MbedTLSClient.h index 6f7a263..98f9251 100644 --- a/cores/common/arduino/libraries/common/WiFiClient/MbedTLSClient.h +++ b/cores/common/arduino/libraries/common/WiFiClient/MbedTLSClient.h @@ -2,7 +2,7 @@ #pragma once -#if LT_ARD_HAS_WIFI && LT_HAS_MBEDTLS +#if (LT_ARD_HAS_WIFI && LT_HAS_MBEDTLS) || DOXYGEN #include "WiFiClientSecure.h" diff --git a/cores/common/arduino/libraries/common/WiFiServer/LwIPServer.h b/cores/common/arduino/libraries/common/WiFiServer/LwIPServer.h index d1787ff..ca2e03b 100644 --- a/cores/common/arduino/libraries/common/WiFiServer/LwIPServer.h +++ b/cores/common/arduino/libraries/common/WiFiServer/LwIPServer.h @@ -2,7 +2,7 @@ #pragma once -#if LT_ARD_HAS_WIFI && LT_HAS_LWIP +#if (LT_ARD_HAS_WIFI && LT_HAS_LWIP) || DOXYGEN #include "WiFiServer.h" diff --git a/cores/common/arduino/libraries/common/WiFiUdp/LwIPUdp.h b/cores/common/arduino/libraries/common/WiFiUdp/LwIPUdp.h index b60f18d..7ff6d4a 100644 --- a/cores/common/arduino/libraries/common/WiFiUdp/LwIPUdp.h +++ b/cores/common/arduino/libraries/common/WiFiUdp/LwIPUdp.h @@ -2,7 +2,7 @@ #pragma once -#if LT_ARD_HAS_WIFI && LT_HAS_LWIP +#if (LT_ARD_HAS_WIFI && LT_HAS_LWIP) || DOXYGEN #include "WiFiUdp.h" diff --git a/cores/common/arduino/libraries/common/mDNS/LwIPmDNS.cpp b/cores/common/arduino/libraries/common/mDNS/LwIPmDNS.cpp index e7f6c6c..f590219 100644 --- a/cores/common/arduino/libraries/common/mDNS/LwIPmDNS.cpp +++ b/cores/common/arduino/libraries/common/mDNS/LwIPmDNS.cpp @@ -1,6 +1,6 @@ /* Copyright (c) Kuba Szczodrzyński 2022-05-23. */ -#ifdef LT_HAS_LWIP2 +#if LT_HAS_LWIP2 #include "mDNS.h" #include diff --git a/cores/common/base/api/lt_cpu.h b/cores/common/base/api/lt_cpu.h index 554f0a4..db312c1 100644 --- a/cores/common/base/api/lt_cpu.h +++ b/cores/common/base/api/lt_cpu.h @@ -5,7 +5,7 @@ #include /** - * @brief Get CPU family ID (in ChipFamily enumeration). + * @brief Get CPU family ID (as lt_cpu_family_t enum member). */ lt_cpu_family_t lt_get_cpu_family(); @@ -15,7 +15,7 @@ lt_cpu_family_t lt_get_cpu_family(); const char *lt_get_cpu_family_name(); /** - * @brief Get CPU model ID (in ChipType enumeration). + * @brief Get CPU model ID (as lt_cpu_model_t enum member). */ lt_cpu_model_t lt_get_cpu_model(); diff --git a/TODO.md b/docs/TODO.md similarity index 100% rename from TODO.md rename to docs/TODO.md diff --git a/docs/reference/config.md b/docs/dev/config.md similarity index 91% rename from docs/reference/config.md rename to docs/dev/config.md index be30ec0..465de17 100644 --- a/docs/reference/config.md +++ b/docs/dev/config.md @@ -15,7 +15,7 @@ custom_fw_version = 1.2.0 ## LibreTuya options !!! note - See [LibreTuyaConfig.h](../../ltapi/_libre_tuya_config_8h_source.md) for most options and their defaults. + See [lt_config.h](../../ltapi/lt__config_8h.md) for most options and their defaults. All options are configurable via C++ defines in PlatformIO project file. For example: ```ini title="platformio.ini" @@ -101,18 +101,21 @@ Options for controlling default UART log output. ### Family feature config !!! bug "Warning" - These options are not meant for end-users. They're provided here as a reference for developers. + These options are not meant for end-users. They're provided here as a reference for developers. **Do not set these options manually**. -These options are selectively set by all families, as part of the build process. They are used for enabling LT core API parts, if the family has support for it. +These options are selectively set by all families, as part of the build process. They are used for enabling LT core API parts, if the family has support for it. Files named `lt_defs.h`, containing these options, are read by the PlatformIO builders (note: they're never included by C code). The `LT_ARD_*` options are only used with Arduino frameworks. The meaning of most flags is as follows: +- `LT_HAS_FREERTOS` - FreeRTOS supported and used - `LT_HAS_LWIP` - LwIP in SDK (any version) - `LT_HAS_LWIP2` - LwIP v2.0.0 or newer -- `LT_HAS_FREERTOS` - FreeRTOS supported and used - `LT_HAS_MBEDTLS` - mbedTLS in SDK -- `LT_ARD_HAS_WIFI` - WiFi library implemented, `WiFiData.h` available +- `LT_HAS_PRINTF` - printf library implemented +- `LT_ARD_HAS_SERIAL` - Serial class implemented, `Serial.h` available - `LT_ARD_HAS_SOFTSERIAL` - SoftwareSerial library implemented, `SoftwareSerial.h` available +- `LT_ARD_HAS_WIFI` - WiFi library implemented, `WiFiData.h` available - `LT_HEAP_FUNC` - function name used to get available heap size (for `LT_HEAP_I()`) +- `LT_REALLOC_FUNC` - function name used for `realloc()` call diff --git a/docs/libs-3rd-party.md b/docs/dev/libs-3rd-party.md similarity index 63% rename from docs/libs-3rd-party.md rename to docs/dev/libs-3rd-party.md index 3706f99..bb28472 100644 --- a/docs/libs-3rd-party.md +++ b/docs/dev/libs-3rd-party.md @@ -1,6 +1,6 @@ # Libraries -A page outlining 3-rd party libraries compatible with LibreTuya. +A page outlining 3-rd some party libraries compatible with LibreTuya. !!! note To use some (most? (all?)) of these, a flag in `platformio.ini` is required to disable compatibility checks (because most libs are meant for ESP32/Arduino official framework): @@ -9,27 +9,27 @@ A page outlining 3-rd party libraries compatible with LibreTuya. lib_compat_mode = off ``` -## MQTT +## [256dpi/MQTT](https://registry.platformio.org/libraries/256dpi/MQTT) Tested with `realtek-ambz`. ```ini lib_deps = 256dpi/MQTT@^2.5.0 ``` -## DNSServer +## [bbx10/DNSServer](https://registry.platformio.org/libraries/bbx10/DNSServer) Tested with `beken-72xx`. ```ini lib_deps = bbx10/DNSServer@^1.1.0 ``` This is the same library as in ESP32 Arduino Core. -## AsyncTCP-esphome +## [esphome/AsyncTCP-esphome](https://registry.platformio.org/libraries/esphome/AsyncTCP-esphome) Tested with `beken-72xx` and `realtek-ambz`. ```ini lib_deps = esphome/AsyncTCP-esphome@^2.0.0 ``` This is ESPHome's fork of the original library. -## ESPAsyncWebServer-esphome +## [esphome/ESPAsyncWebServer-esphome](https://registry.platformio.org/libraries/esphome/ESPAsyncWebServer-esphome) Tested with `beken-72xx` and `realtek-ambz`. ```ini lib_deps = esphome/ESPAsyncWebServer-esphome@^3.0.0 diff --git a/docs/dev/lt-api.md b/docs/dev/lt-api.md new file mode 100644 index 0000000..c3ac648 --- /dev/null +++ b/docs/dev/lt-api.md @@ -0,0 +1,173 @@ +# LibreTuya API + +The LibreTuya API is divided in two parts: + +- the C API, available in all families and frameworks +- the C++ API, available in the Arduino framework only. + +The C++ API is a thin wrapper around the C API (using classes with inline functions). +It's provided for less-experienced users, who are used to Arduino IDE's classes like `ESP` (and for backwards compatibility). +It's recommended to use the C API wherever possible. + +## C API + +This API is available using: + +- `#include ` +- `#include ` + +### CPU + +{% + include-markdown "../../ltapi/lt__cpu_8h.md" + start="## Public Functions\n" + end="## Public Functions Documentation" +%} + +### Device + +{% + include-markdown "../../ltapi/lt__device_8h.md" + start="## Public Functions\n" + end="## Public Functions Documentation" +%} + +### Flash + +{% + include-markdown "../../ltapi/lt__flash_8h.md" + start="## Public Functions\n" + end="## Public Functions Documentation" +%} + +### Memory + +{% + include-markdown "../../ltapi/lt__mem_8h.md" + start="## Public Functions\n" + end="## Public Functions Documentation" +%} + +### OTA + +{% + include-markdown "../../ltapi/lt__ota_8h.md" + start="## Public Functions\n" + end="## Public Functions Documentation" +%} + +### Utilities + +{% + include-markdown "../../ltapi/lt__utils_8h.md" + start="## Public Functions\n" + end="## Macros" +%} + +### Watchdog + +{% + include-markdown "../../ltapi/lt__wdt_8h.md" + start="## Public Functions\n" + end="## Public Functions Documentation" +%} + +### Logger + +{% + include-markdown "../../ltapi/lt__logger_8h.md" + start="## Public Functions\n" + end="## Macros" +%} + +### POSIX compatibility API + +A small subset of POSIX functions, commonly present in other Arduino cores, is provided for compatibility. + +{% + include-markdown "../../ltapi/lt__posix__api_8h.md" + start="## Public Functions\n" + end="## Public Functions Documentation" +%} + +## C++ API + +This API is available using: + +- `#include ` + +### LibreTuya + +{% + include-markdown "../../ltapi/class_libre_tuya.md" + start="# Detailed Description\n" + end="## Public Functions Documentation" +%} + +{% + include-markdown "../../ltapi/class_libre_tuya.md" + start="## Public Functions\n" + end="# Detailed Description" +%} + +### LibreTuyaOTA + +{% + include-markdown "../../ltapi/class_libre_tuya_o_t_a.md" + start="# Detailed Description\n" + end="## Public Functions Documentation" +%} + +{% + include-markdown "../../ltapi/class_libre_tuya_o_t_a.md" + start="## Public Functions\n" + end="# Detailed Description" +%} + +### LibreTuyaWDT + +{% + include-markdown "../../ltapi/class_libre_tuya_w_d_t.md" + start="# Detailed Description\n" + end="## Public Functions Documentation" +%} + +{% + include-markdown "../../ltapi/class_libre_tuya_w_d_t.md" + start="## Public Functions\n" + end="# Detailed Description" +%} + +### Arduino custom API + +These functions extend the standard Wiring (Arduino) library, to provide additional features. + +{% + include-markdown "../../ltapi/wiring__custom_8h.md" + start="## Public Functions\n" + end="## Macros" +%} + +### Arduino compatibility API + +These functions and macros provide compatibility between LT and other Arduino cores, such as ESP32. + +{% + include-markdown "../../ltapi/wiring__compat_8h.md" + start="## Public Functions\n" + end="## Macros" +%} + +{% + include-markdown "../../ltapi/wiring__compat_8h.md" + start="## Macros\n" + end="## Public Functions Documentation" +%} + +## Chip & family types + +{% + include-markdown "../../ltapi/lt__types_8h.md" + start="## Public Types Documentation\n" + end="## Macro Definition Documentation" +%} diff --git a/docs/ota/README.md b/docs/dev/ota/README.md similarity index 98% rename from docs/ota/README.md rename to docs/dev/ota/README.md index 72900e1..84dac21 100644 --- a/docs/ota/README.md +++ b/docs/dev/ota/README.md @@ -26,12 +26,6 @@ Each firmware image may be either applicable: For easier understanding, these update types will be referred to in this document using the numbers. -## Custom family IDs - -{% - include-markdown "../status/supported_families.md" -%} - ## Extension tags Standard tags are used: `VERSION`, `DEVICE` and `DEVICE_ID`. diff --git a/docs/ota/library.md b/docs/dev/ota/library.md similarity index 100% rename from docs/ota/library.md rename to docs/dev/ota/library.md diff --git a/docs/ota/uf2ota.md b/docs/dev/ota/uf2ota.md similarity index 100% rename from docs/ota/uf2ota.md rename to docs/dev/ota/uf2ota.md diff --git a/docs/reference/project-structure.md b/docs/dev/project-structure.md similarity index 100% rename from docs/reference/project-structure.md rename to docs/dev/project-structure.md diff --git a/docs/flashing/SUMMARY.md b/docs/flashing/SUMMARY.md index 332d425..625860c 100644 --- a/docs/flashing/SUMMARY.md +++ b/docs/flashing/SUMMARY.md @@ -2,9 +2,7 @@ * [Flashing PlatformIO projects](platformio.md) * [Flashing ESPHome](esphome.md) +* [Dumping stock firmware](dumping.md) * [Using ltchiptool GUI](tools/ltchiptool.md) * [Converting with tuya-cloudcutter](tools/cloudcutter.md) -* 🔌 Chip connection guide - * [Beken BK72xx](../platform/beken-72xx/flashing.md) - * [Realtek RTL8710Bx](../platform/realtek-ambz/flashing.md) * [Auto-download-reboot](tools/adr.md) diff --git a/docs/flashing/chip-connection/SUMMARY.md b/docs/flashing/chip-connection/SUMMARY.md new file mode 100644 index 0000000..2b29f15 --- /dev/null +++ b/docs/flashing/chip-connection/SUMMARY.md @@ -0,0 +1,4 @@ +# Chip connection guides + +* [Beken BK72xx](../../platform/beken-72xx/flashing.md) +* [Realtek RTL8710Bx](../../platform/realtek-ambz/flashing.md) diff --git a/docs/flashing/dumping.md b/docs/flashing/dumping.md new file mode 100644 index 0000000..26b4aa8 --- /dev/null +++ b/docs/flashing/dumping.md @@ -0,0 +1,5 @@ +# Dumping stock firmware + +It is a good idea to dump the stock firmware (full flash contents) of your device before flashing custom firmware. + +Currently, the easiest way to dump firmware is to use [ltchiptool](tools/ltchiptool.md). Download/install the tool, and follow the guide. diff --git a/docs/flashing/inc/ota-cloudcutter.md b/docs/flashing/inc/ota-cloudcutter.md index b99b7a8..02077e2 100644 --- a/docs/flashing/inc/ota-cloudcutter.md +++ b/docs/flashing/inc/ota-cloudcutter.md @@ -3,6 +3,6 @@ !!! note This currently applies to BK7231T and BK7231N only. `tuya-cloudcutter` can't be used for other chips. -Grab the `bk7231x_app.ota.ug.bin` file from the build directory - take care to choose the correct file. It must have "OTA" and "UG" in its name. +Grab the `image_bk7231x_app.ota.ug.bin` file from the build directory - take care to choose the correct file. It must have "OTA" and "UG" in its name. Next, refer to [Using tuya-cloudcutter](../tools/cloudcutter.md) guide. diff --git a/docs/flashing/inc/ota-openbeken.md b/docs/flashing/inc/ota-openbeken.md index 55b8ea3..cafba8d 100644 --- a/docs/flashing/inc/ota-openbeken.md +++ b/docs/flashing/inc/ota-openbeken.md @@ -2,4 +2,4 @@ [OpenBeken](https://github.com/openshwprojects/OpenBK7231T_App) is a custom, Tasmota-like firmware for non-ESP chips. Currently, this part of the guide applies to BK7231 only, as that's the only chip supported both by LT and OBK. -OBK is compatible with standard Beken OTA packages, but the web panel does a filename check to prevent chip type mismatch. Grab the `bk7231x_app.ota.bin` file from build directory (note: without "UG" in the name!), rename it to something like `OpenBK7231T_esphome.rbl` (change T to N depending on the chip type), and drop it on the OTA panel. +OBK is compatible with standard Beken OTA packages, but the web panel does a filename check to prevent chip type mismatch. Grab the `image_bk7231t_app.ota.rbl` file from build directory (note: without "UG" in the name!), rename it to something like `OpenBK7231T_esphome.rbl` (change T to N depending on the chip type), and drop it on the OTA panel. diff --git a/docs/flashing/inc/uart-info.md b/docs/flashing/inc/uart-info.md index 0b16fa9..9467d2d 100644 --- a/docs/flashing/inc/uart-info.md +++ b/docs/flashing/inc/uart-info.md @@ -1 +1 @@ -The device needs to be connected to your PC with a UART-TTL adapter. Refer to chip connection guides (see: menu on the left) to learn how to connect your device. +The device needs to be connected to your PC with a UART-TTL adapter. Refer to [chip connection guides](../chip-connection/SUMMARY.md) to learn how to connect your device. diff --git a/docs/flashing/inc/uart-ltchiptool.md b/docs/flashing/inc/uart-ltchiptool.md index c05bc60..0c15962 100644 --- a/docs/flashing/inc/uart-ltchiptool.md +++ b/docs/flashing/inc/uart-ltchiptool.md @@ -1,6 +1,6 @@ ## Using ltchiptool (wired, via UART) -You can use the [ltchiptool](https://github.com/libretuya/ltchiptool) GUI or CLI to manually flash the firmware. Grab the `firmware.uf2` file from the build directory. Then, follow the [ltchiptool usage guide](../tools/ltchiptool.md) to flash it to the device. +You can use the [ltchiptool](../tools/ltchiptool.md) GUI or CLI to manually flash the firmware. Grab the `firmware.uf2` file from the build directory. Then, follow the [ltchiptool usage guide](../tools/ltchiptool.md) to flash it to the device. !!! tip The UF2 file may have a different name, depending on the project you're building. Usually it's best to grab the latest (sorted by date) file with UF2 extension from the build directory. diff --git a/docs/flashing/tools/adr.md b/docs/flashing/tools/adr.md index 8ae6a7e..357cadb 100644 --- a/docs/flashing/tools/adr.md +++ b/docs/flashing/tools/adr.md @@ -15,4 +15,4 @@ The code listens on UART1 for a link-check command (`01 E0 FC 01 00`). The baudr ## Realtek AmebaZ -This is not yet implemented. +This only works when using [ltchiptool](ltchiptool.md) for flashing. Upon starting UART communication, the tool sends `55 AA 22 E0 D6 FC` (0x55AA followed by the `realtek-ambz` family ID). After detecting that pattern, the chip proceeds to reboot into UART download mode (using [`lt_reboot_download_mode()`](../../../ltapi/lt__device_8h.md)) diff --git a/docs/flashing/tools/ltchiptool.md b/docs/flashing/tools/ltchiptool.md index 3c0c908..cb1c8e9 100644 --- a/docs/flashing/tools/ltchiptool.md +++ b/docs/flashing/tools/ltchiptool.md @@ -45,19 +45,54 @@ Install the package from PyPI, using `pip install ltchiptool`. Run the CLI using ## GUI Usage -The main window is somewhat similar to [NodeMCU PyFlasher](https://github.com/marcelstoer/nodemcu-pyflasher). +The main window is somewhat similar to [NodeMCU PyFlasher](https://github.com/marcelstoer/nodemcu-pyflasher). Available modes of operation are described below. -- For dumping, choose `Read flash`. If you've previously chosen an input or output file, it will generate a dump filename with the current timestamp and chip type. Otherwise, click `Browse` and choose the output file. By default, the tool will attempt to read the entire flash chip (usually 2 MiB). -- For flashing, choose `Write flash`. Click `Browse` and select *any* valid firmware file. The file type and chip type will be auto-detected, along with correct flash offset and length. No need to worry about overwriting the bootloader anymore! - - If the file you're selecting is `Unrecognized` or `Not flashable`, it's most likely not a valid firmware file. Refer to usage guides of the custom firmware project of choice, to find which file is meant for flashing. -- **It's best to leave `Auto-detect advanced parameters` checked**. If you're an experienced user and want to flash custom areas of the flash, uncheck the box and specify the parameters manually. -- When you're ready, hit `Start`. The tool will try to connect to the chip on the selected UART port. The black log window will print any warnings/errors, as well as **a short guide on how to put the chip in download mode**. +### Dumping firmware + +It is a good idea to dump the stock firmware (full flash contents) of your device before flashing custom firmware. + +1. Choose the `Read flash` option. If you've previously chosen an input or output file, it will generate a dump filename based on the current timestamp and chip type. Otherwise, click `Browse` and choose the output file. +2. You need to pick the "family" of your chip (the chip model). If you choose the wrong option, the process will fail, but the device won't be bricked. +3. Now, connect the chip to your PC, according to the [chip connection guides](../chip-connection/SUMMARY.md). Select the COM port that your UART adapter is using. +4. By default, the tool will attempt to read the entire flash chip (usually 2 MiB). Unless you know what you're doing, the default values don't need to be changed. +5. Hit `Start`. The tool will try to connect to the chip on the selected UART port. The black log window will print any warnings/errors. The dumping process should begin shortly. + +### Flashing firmware + +If you want to flash custom firmware, or restore stock firmware from a previously dumped file, follow the steps below. !!! info LibreTuya generates multiple firmware files in the build directory. **You usually want to flash the `.uf2` file**, but since ltchiptool can detect file types, you can choose a different firmware file and it'll tell you if that works. +1. Choose `Write flash`. Click `Browse` and select a valid firmware file. The file type and chip type will be auto-detected, along with correct flash offset and length. No need to worry about overwriting the bootloader anymore! +2. Connect the chip to your PC, according to the [chip connection guides](../chip-connection/SUMMARY.md). Select the COM port that your UART adapter is using. +3. Hit `Start`. The tool will try to connect to the chip on the selected UART port. The black log window will print any warnings/errors. The flashing process should begin shortly. + +!!! info + **It's best to leave `Auto-detect advanced parameters` checked**. If you're an experienced user and want to flash custom areas of the flash, uncheck the box and specify the parameters manually. + + If the file you're selecting is `Unrecognized` or `Not flashable`, it's most likely not a valid firmware file. Refer to usage guides of the custom firmware project of choice, to find which file is meant for flashing. + ## CLI Usage +### Flashing/dumping + +This is for users, who are more experienced with using a terminal. There are three main commands used for flashing: + +- `ltchiptool flash file ` - detect file type based on its contents (i.e. chip from which a dump was acquired), similar to Linux `file` command +- `ltchiptool flash read ` - make a full flash dump of the connected device; specifying the family is required +- `ltchiptool flash write ` - upload a file to the device; detects file type automatically (just like the `file` command above) + +Supported device families can be checked using `ltchiptool list families` command. In the commands above, you can use any of the family names (name/code/short name/etc). + +The upload UART port and baud rate should be detected automatically. To override it, use `-d COMx` or `-d /dev/ttyUSBx`. To change the target baud rate, use `-b 460800`. +Note that the baud rate is changed after linking. Linking is performed using chip-default baud rate. + +It's not required to specify chip family for writing files - `ltchiptool` tries to recognize contents of the file, and chooses the best settings automatically. +If you want to flash unrecognized/raw binaries (or fine-tune the flashing parameters), specify `-f ` and `-s `. + +## CLI Reference + !!! note If you're here to learn how to flash or dump firmware files, use the instructions above. @@ -88,22 +123,6 @@ Commands: uf2 Work with UF2 files ``` -### Flashing/dumping - -There are three main commands used for flashing: - -- `ltchiptool flash file ` - detect file type based on its contents (i.e. chip from which a dump was acquired), similar to Linux `file` command -- `ltchiptool flash read ` - make a full flash dump of the connected device; specifying the family is required -- `ltchiptool flash write ` - upload a file to the device; detects file type automatically (just like the `file` command above) - -Supported device families can be checked using `ltchiptool list families` command. In the commands above, you can use any of the family names (name/code/short name/etc). - -The upload UART port and baud rate is detected automatically. To override it, use `-d COMx` or `-d /dev/ttyUSBx`. To change the target baud rate, use `-b 460800`. -Note that the baud rate is changed after linking. Linking is performed using chip-default baud rate. - -It's not required to specify chip family for writing files - `ltchiptool` tries to recognize contents of the file, and chooses the best settings automatically. -If you want to flash unrecognized/raw binaries (or fine-tune the flashing parameters), specify `-f ` and `-s `. - ### UF2 Example ```console diff --git a/docs/getting-started/README.md b/docs/getting-started/README.md index ed03791..5f37d0d 100644 --- a/docs/getting-started/README.md +++ b/docs/getting-started/README.md @@ -28,7 +28,7 @@ Next, read one of the [flashing guides](../flashing/SUMMARY.md) to run your proj ### LT configuration -LibreTuya has a few configuration options that change its behavior or features. Refer to [LT configuration](../reference/config.md) for details. +LibreTuya has a few configuration options that change its behavior or features. Refer to [LT configuration](../dev/config.md) for details. ### GPIO usage diff --git a/docs/libs-built-in.md b/docs/libs-built-in.md deleted file mode 100644 index beded9d..0000000 --- a/docs/libs-built-in.md +++ /dev/null @@ -1,40 +0,0 @@ -# Built-in libraries -(in alphabetical order) - -## base64 -- [Source](https://github.com/espressif/arduino-esp32/blob/master/cores/esp32/base64.cpp): ESP32 Arduino Core -- [Reference](../ltapi/classbase64.md) - -Helper base64 encoder used in some libs taken from ESP32. - -## HTTPClient -- [Source](https://github.com/espressif/arduino-esp32/tree/master/libraries/HTTPClient): ESP32 Arduino Core -- [Reference](../ltapi/class_h_t_t_p_client.md) -- [Examples](https://github.com/espressif/arduino-esp32/tree/master/libraries/HTTPClient/examples) - -HTTP(S) client. - -## NetUtils - -Utilities and common classes related to network. - -- [ssl/MbedTLSClient.cpp](../ltapi/class_mbed_t_l_s_client.md) ([source](https://github.com/espressif/arduino-esp32/tree/master/libraries/WiFiClientSecure/src): ESP32 WiFiClientSecure) -- [IPv6Address.cpp](../ltapi/classarduino_1_1_i_pv6_address.md) ([source](https://github.com/espressif/arduino-esp32/blob/master/cores/esp32/IPv6Address.cpp): ESP32 IPv6Address) -- [LwIPRxBuffer.cpp](../ltapi/class_lw_i_p_rx_buffer.md) ([source](https://github.com/espressif/arduino-esp32/blob/master/libraries/WiFi/src/WiFiClient.cpp): ESP32 WiFiClient) - -## WebServer -- [Source](https://github.com/espressif/arduino-esp32/tree/master/libraries/WebServer/src): ESP32 Arduino Core -- [Reference](../ltapi/class_web_server.md) -- Examples: - - [HelloServer](https://github.com/espressif/arduino-esp32/blob/master/libraries/WebServer/examples/HelloServer/HelloServer.ino) - - [MultiHomedServers](https://github.com/espressif/arduino-esp32/blob/master/libraries/WebServer/examples/MultiHomedServers/MultiHomedServers.ino) - -## WiFiMulti -- [Source](https://github.com/espressif/arduino-esp32/tree/master/libraries/WiFi/src): ESP32 Arduino Core -- [Reference](../ltapi/class_wi_fi_multi.md) -- [Docs](https://docs.espressif.com/projects/arduino-esp32/en/latest/api/wifi.html#wifimulti) -- Examples: - - [WiFiMulti](https://github.com/espressif/arduino-esp32/blob/master/libraries/WiFi/examples/WiFiMulti/WiFiMulti.ino) - - [WiFiClientBasic](https://github.com/espressif/arduino-esp32/blob/master/libraries/WiFi/examples/WiFiClientBasic/WiFiClientBasic.ino) - -Class for selecting best available AP from a list of several ones. diff --git a/docs/ota/flashing.md b/docs/ota/flashing.md deleted file mode 100644 index f02241e..0000000 --- a/docs/ota/flashing.md +++ /dev/null @@ -1,4 +0,0 @@ -It is possible to upload firmware binaries manually, using the command-line tool `ltchiptool`. For this, you need the `.uf2` file generated after compilation (usually found in `.pio/build/my_board/`). - -1. Install Python. Afterwards, run `pip install ltchiptool`. -2. `ltchiptool uf2 upload my_firmware.uf2 uart COM96` (replace `my_firmware.uf2` with your file name and `COM96` with your upload port). diff --git a/docs/platform/beken-72xx/README.md b/docs/platform/beken-72xx/README.md index cd8ef15..79cbb51 100644 --- a/docs/platform/beken-72xx/README.md +++ b/docs/platform/beken-72xx/README.md @@ -17,7 +17,7 @@ Name There are many chip variations in this SoC family: -- BK7231 - marked BK7321QN40, so we're calling it "BK7231Q" to reduce confusion +- BK7231 - marked BK7231QN40, so we're calling it "BK7231Q" to reduce confusion - BK7231T - BK7231N - BK7231S diff --git a/docs/platform/beken-72xx/flashing.md b/docs/platform/beken-72xx/flashing.md index 541c25a..f8d6954 100644 --- a/docs/platform/beken-72xx/flashing.md +++ b/docs/platform/beken-72xx/flashing.md @@ -33,7 +33,7 @@ Downloading is done using UART. For best experience, you should have two USB<->U Note that the download mode can only be activated when the flasher is running (there's no GPIO-strapping like on ESP8266). Additionally, BK7231T (not N) will exit the download mode when the flasher finishes its work. !!! tip - BK7231N can't be software-bricked, because it has a ROM that contains the download mode. **BK7231T doesn't contain the ROM, so be careful with this one**. + BK7231N can't be software-bricked, because it has a ROM that contains the download mode. **BK7231T doesn't contain it, so be careful with this one**. ## bk7231tools @@ -47,20 +47,20 @@ If you have a recent version of LibreTuya installed on the chip, you can use [Au If you only have a single adapter, or just want to use the UART1 (upload) port only, you can change the logging port. -Refer to [Options & config](../../reference/config.md) (`Serial output` section). Set `LT_UART_DEFAULT_PORT` to `1`, which will use UART1 for all output. +Refer to [Options & config](../../dev/config.md) (`Serial output` section). Set `LT_UART_DEFAULT_PORT` to `1`, which will use UART1 for all output. ## Firmware output files These files are present in the build directory after successful compilation: -File | Description ---------------------------|---------------------------------------- -**firmware.uf2** | **UF2 package for UART and OTA upload** -bk7231t_app.ota.rbl | Beken OTA package (e.g. OpenBeken) -bk7231t_app.ota.ug.bin | Tuya OTA package (incl. Cloudcutter) -bk7231t_app_0x011000.rbl | App partition - flashable at 0x11000 -bk7231t_app_0x011000.crc | Encrypted app image - not for flashing -bk7231t_app_0x129F0A.rblh | RBL header - not for flashing +File | Description +--------------------------------|---------------------------------------- +**firmware.uf2** | **UF2 package for UART and OTA upload** +image_bk7231t_app.ota.rbl | Beken OTA package (e.g. OpenBeken) +image_bk7231t_app.ota.ug.bin | Tuya OTA package (incl. Cloudcutter) +image_bk7231t_app.0x011000.rbl | App partition - flashable at 0x11000 +image_bk7231t_app.0x011000.crc | Encrypted app image - not for flashing +image_bk7231t_app.0x129F0A.rblh | RBL header - not for flashing ## SPI flashing (unbricking BK7231T) diff --git a/docs/platform/realtek-ambz/flashing.md b/docs/platform/realtek-ambz/flashing.md index ee90b37..3fb1e9d 100644 --- a/docs/platform/realtek-ambz/flashing.md +++ b/docs/platform/realtek-ambz/flashing.md @@ -41,8 +41,8 @@ These files are present in the build directory after successful compilation: File | Description ------------------------|------------------------------------------------------------------- **firmware.uf2** | **UF2 package for UART and OTA upload** -image_0x00B000.ota1.bin | OTA 1 image, flashable to 0xB000 -image_0x0D0000.ota2.bin | OTA 2 image, flashable to 0xD0000 (the address might be different) +image_ota1.0x00B000.bin | OTA 1 image, flashable to 0xB000 +image_ota2.0x0D0000.bin | OTA 2 image, flashable to 0xD0000 (the address might be different) ## Other tools/guides diff --git a/docs/platform/realtek-ambz/memory-management.md b/docs/platform/realtek-ambz/memory-management.md deleted file mode 100644 index f65d243..0000000 --- a/docs/platform/realtek-ambz/memory-management.md +++ /dev/null @@ -1,15 +0,0 @@ -# Memory management - -Function | Target | #define location | Notes ---------------|------------------------|---------------------------------------------------|------------------------------------------------------------------------------------------------ -__`malloc`__ | __`pvPortMalloc`__ | `component/common/api/platform/platform_stdlib.h` | -`zalloc` | `os_zalloc` (ROM) | | This is **PROBABLY BROKEN**. ROM disassembly shows it only does memset on a fixed memory range. -__`zalloc`__ | __`pvPortZalloc`__ | `arduino/realtek-ambz/cores/WVariant.h` | Custom implementation in `rtl_sys.cpp` -`calloc` | `os_calloc` | ? | This one is not in ROM. I didn't dig any deeper into it. -`calloc` | `calloc_freertos` | `component/os/freertos/cmsis_os.h` | Probably not used -`calloc` | `__rtl_calloc_r` (ROM) | | Not used, as I preferred to use FreeRTOS memory management. -__`calloc`__ | __`pvPortCalloc`__ | `arduino/realtek-ambz/cores/WVariant.h` | Custom implementation in `rtl_sys.cpp` -__`realloc`__ | __`pvPortRealloc`__ | `arduino/realtek-ambz/cores/WVariant.h` | -__`free`__ | __`vPortFree`__ | `component/common/api/platform/platform_stdlib.h` | - -__Underlined__ item means that it is defined and used in code. diff --git a/docs/platform/realtek-ambz/stdlib.md b/docs/platform/realtek-ambz/stdlib.md deleted file mode 100644 index 17caa3b..0000000 --- a/docs/platform/realtek-ambz/stdlib.md +++ /dev/null @@ -1,189 +0,0 @@ -# C library - -The following is an auto-generated list of C standard library definitions included in the SDK. `Location` column contains the location of a matching symbol. - -## ctype.h - -### Character classification functions - -Definition | Value | Location ------------|------------|--------- -`isalnum` | | -`isalpha` | | -`isblank` | | -`iscntrl` | | -`isdigit` | `in_range` | -`isgraph` | | -`islower` | `in_range` | -`isprint` | `in_range` | -`ispunct` | | -`isspace` | | -`isupper` | | -`isxdigit` | | - -## stdarg.h - -Definition | Value | Location ------------|----------------------|--------- -`va_start` | `__builtin_va_start` | -`va_arg` | `__builtin_va_arg` | -`va_end` | `__builtin_va_end` | -`va_copy` | `__builtin_va_copy` | - -## stddef.h - -Definition | Value | Location ---------------|---------------------|--------- -`ptrdiff_t` | `long int` | -`size_t` | `long unsigned int` | -`max_align_t` | | -`nullptr_t` | | -`NULL` | | - -## stdint.h - -### Types - -Definition | Value | Location ------------------|----------------------|--------- -`intmax_t` | `long int` | -`uintmax_t` | `long unsigned int` | -`int8_t` | `signed char` | -`uint8_t` | `unsigned char` | -`int16_t` | `short int` | -`uint16_t` | `short unsigned int` | -`int32_t` | `int` | -`uint32_t` | `unsigned int` | -`int64_t` | `long int` | -`uint64_t` | `long unsigned int` | -`int_least8_t` | `signed char` | -`uint_least8_t` | `unsigned char` | -`int_least16_t` | `short int` | -`uint_least16_t` | `short unsigned int` | -`int_least32_t` | `int` | -`uint_least32_t` | `unsigned int` | -`int_least64_t` | `long int` | -`uint_least64_t` | `long unsigned int` | -`int_fast8_t` | `signed char` | -`uint_fast8_t` | `unsigned char` | -`int_fast16_t` | `long int` | -`uint_fast16_t` | `long unsigned int` | -`int_fast32_t` | `long int` | -`uint_fast32_t` | `long unsigned int` | -`int_fast64_t` | `long int` | -`uint_fast64_t` | `long unsigned int` | -`intptr_t` | `long int` | -`uintptr_t` | `long unsigned int` | - -## stdio.h - -### Formatted input/output - -Definition | Value | Location -------------|-----------------|----------------- -`fprintf` | | -`fscanf` | | -`printf` | `rtl_printf` | `lib_rtlstd.a` -`scanf` | | -`snprintf` | `rtl_snprintf` | `lib_rtlstd.a` -`sprintf` | `rtl_sprintf` | `lib_rtlstd.a` -`sscanf` | `_sscanf_patch` | `lib_platform.a` -`vfprintf` | | -`vfscanf` | | -`vprintf` | | -`vscanf` | | -`vsnprintf` | `rtl_vsnprintf` | `lib_rtlstd.a` -`vsprintf` | | -`vsscanf` | | - -### Error-handling - -Definition | Value | Location ------------|---------------|------------- -`clearerr` | `__sclearerr` | -`feof` | `__sfeof` | -`ferror` | `__sferror` | -`perror` | | `lib_mdns.a` - -## stdlib.h - -### String conversion - -Definition | Value | Location ------------|------------------|--------- -`atof` | | -`atoi` | `prvAtoi` | ROM -`atol` | `simple_strtol` | ROM -`atoll` | | -`strtod` | | -`strtof` | | -`strtol` | `simple_strtol` | ROM -`strtold` | | -`strtoll` | | -`strtoul` | `simple_strtoul` | ROM -`strtoull` | | - -### Pseudo-random sequence generation - -Definition | Value | Location ------------|--------|--------- -`rand` | `Rand` | ROM -`srand` | | - -### Dynamic memory management - -Definition | Value | Location ------------|----------------|--------- -`calloc` | | -`free` | `vPortFree` | SDK -`malloc` | `pvPortMalloc` | SDK -`realloc` | | - -## string.h - -### Copying - -Definition | Value | Location ------------|-----------------------|--------- -`memcpy` | `_memcpy` | ROM -`memmove` | `__rtl_memmove_v1_00` | ROM -`strcpy` | `_strcpy` | ROM -`strncpy` | `_strncpy` | ROM - -### Concatenation - -Definition | Value | Location ------------|-----------------------|--------- -`strcat` | `__rtl_strcat_v1_00` | ROM -`strncat` | `__rtl_strncat_v1_00` | ROM - -### Comparison - -Definition | Value | Location ------------|-------------|--------- -`memcmp` | `_memcmp` | ROM -`strcmp` | `prvStrCmp` | ROM -`strcoll` | | -`strncmp` | `_strncmp` | ROM -`strxfrm` | | - -### Searching - -Definition | Value | Location ------------|----------------------|--------- -`memchr` | `__rtl_memchr_v1_00` | ROM -`strchr` | `_strchr` | ROM -`strcspn` | | -`strpbrk` | `_strpbrk` | ROM -`strrchr` | | -`strspn` | | -`strstr` | `prvStrStr` | ROM -`strtok` | `prvStrtok` | ROM - -### Other - -Definition | Value | Location ------------|-------------|--------- -`memset` | `_memset` | ROM -`strerror` | | -`strlen` | `prvStrLen` | ROM diff --git a/docs/projects/esphome.md b/docs/projects/esphome.md index 12ab910..2429977 100644 --- a/docs/projects/esphome.md +++ b/docs/projects/esphome.md @@ -133,7 +133,7 @@ Now, refer to the [flashing guide](../flashing/esphome.md) to learn how to uploa !!! note This part is for advanced users. You'll probably be fine with the default options. -All options from [Options & config](../reference/config.md) can be customized in the `libretuya:` block: +All options from [Options & config](../dev/config.md) can be customized in the `libretuya:` block: ```yaml title="yourdevice.yml" libretuya: diff --git a/docs/reference/lt-api.md b/docs/reference/lt-api.md deleted file mode 100644 index f051c1e..0000000 --- a/docs/reference/lt-api.md +++ /dev/null @@ -1,47 +0,0 @@ -# LibreTuya API - -## Class functions - -{% - include-markdown "../../ltapi/class_libre_tuya.md" - start="(class_libre_tuya.md)\n" - end="[More...]" -%} - -{% - include-markdown "../../ltapi/class_libre_tuya.md" - start="# Detailed Description\n" - end="## Public Functions Documentation\n" -%} - -{% - include-markdown "../../ltapi/class_libre_tuya.md" - start="## Public Functions\n" - end="# Detailed Description\n" -%} - -## Common methods - -{% - include-markdown "../../ltapi/_libre_tuya_a_p_i_8h.md" - start="## Public Functions\n" - end="## Public Functions Documentation\n" - heading-offset=1 -%} - -## Wiring custom methods - -{% - include-markdown "../../ltapi/_libre_tuya_custom_8h.md" - start="## Public Functions\n" - end="## Macros\n" -%} - -## Logger - -{% - include-markdown "../../ltapi/lt__logger_8h.md" - start="## Public Functions\n" - end="## Public Functions Documentation\n" - heading-offset=1 -%} diff --git a/docs/build_json.py b/docs/scripts/build_json.py similarity index 100% rename from docs/build_json.py rename to docs/scripts/build_json.py diff --git a/docs/markdown.py b/docs/scripts/markdown.py similarity index 100% rename from docs/markdown.py rename to docs/scripts/markdown.py diff --git a/docs/scripts/prepare_doxygen.py b/docs/scripts/prepare_doxygen.py new file mode 100644 index 0000000..b217af2 --- /dev/null +++ b/docs/scripts/prepare_doxygen.py @@ -0,0 +1,38 @@ +# Copyright (c) Kuba Szczodrzyński 2023-03-11. + +import re +from glob import glob +from os.path import dirname, join + +inputs_path = join(dirname(__file__), "..", "..", "cores/common/base/**/*.*") +outputs_path = join( + dirname(__file__), "..", "..", "cores/common/arduino/libraries/**/*.*" +) +inputs = glob(inputs_path, recursive=True) +outputs = glob(outputs_path, recursive=True) + +functions = {} + +for input in inputs: + with open(input, "r") as f: + code = f.read() + regex = r"\/\*\*(.+?)\*\/\n.+?\s\*?(\w+)\(.*?\);" + for match in re.finditer(regex, code, re.DOTALL): + functions[match[2]] = match[1] + +for output in outputs: + with open(output, "r") as f: + code = f.read() + regex = r"(\t*)\/\*\*.+?@copydoc (\w+)\(\)" + + def transform(match: re.Match): + docs: str = functions.get(match[2], None) + if not docs: + return match[0] + indent = "\n" + match[1] + docs = indent.join(docs.split("\n")) + return match[1] + "/** " + docs + + code = re.sub(regex, transform, code, re.DOTALL) + with open(output, "w") as f: + f.write(code) diff --git a/docs/update_docs.py b/docs/scripts/update_docs.py similarity index 96% rename from docs/update_docs.py rename to docs/scripts/update_docs.py index d1bfd58..fba8978 100644 --- a/docs/update_docs.py +++ b/docs/scripts/update_docs.py @@ -3,7 +3,7 @@ import sys from os.path import dirname, isfile, join -sys.path.append(join(dirname(__file__), "..")) +sys.path.append(join(dirname(__file__), "..", "..")) import re from typing import Dict, List, Set @@ -15,7 +15,7 @@ from ltchiptool.util.fileio import readjson, readtext from ltchiptool.util.misc import sizeof from markdown import Markdown -OUTPUT = join(dirname(__file__), "status") +OUTPUT = join(dirname(__file__), "..", "status") def load_chip_type_h() -> str: @@ -23,6 +23,7 @@ def load_chip_type_h() -> str: join( dirname(__file__), "..", + "..", "cores", "common", "base", @@ -223,7 +224,7 @@ def write_families(): continue docs = None for f in family.inheritance: - readme = join(dirname(__file__), "platform", f.name, "README.md") + readme = join(dirname(__file__), "..", "platform", f.name, "README.md") if isfile(readme): docs = f"../{f.name}/" row = [ @@ -271,7 +272,7 @@ def write_families(): def write_boards_list(boards: List[Board]): - md = Markdown(dirname(__file__), join("..", "boards", "SUMMARY")) + md = Markdown(join(dirname(__file__), ".."), join("..", "boards", "SUMMARY")) items = [] for board in boards: symbol = get_board_symbol(board) @@ -337,7 +338,7 @@ if __name__ == "__main__": "boards_tuya_all", ] for name in boards_all: - file = join(dirname(__file__), f"{name}.json") + file = join(dirname(__file__), "..", f"{name}.json") data = readjson(file) write_unsupported_boards( series=data, diff --git a/docs/status/supported.md b/docs/status/supported.md index 3aed119..8e7c21f 100644 --- a/docs/status/supported.md +++ b/docs/status/supported.md @@ -26,7 +26,7 @@ A list of chip families currently supported by 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](../../families.json). The IDs are also present in [ChipType.h](../../ltapi/_chip_type_8h_source.md). +The following list corresponds to UF2 OTA format family names, and is also [available as JSON](../../families.json). The IDs are also present in [lt_Types.h](../../ltapi/lt__types_8h.md). {% include-markdown "supported_families.md" diff --git a/docs/style.css b/docs/style.css index fddc2c6..469b52d 100644 --- a/docs/style.css +++ b/docs/style.css @@ -18,3 +18,15 @@ a[href^="https://"].md-button::after, div[align="center"] a[href^="https://"]::after { display: none !important; } + +/* ugly but it works ¯\_(ツ)_/¯ */ +a[href="SUMMARY/"], +a[href="../SUMMARY/"], +a[href="../../SUMMARY/"], +a[href="../../../SUMMARY/"], +a[href="../../../../SUMMARY/"], +a[href="../../../../../SUMMARY/"] +{ + height: 8px; + pointer-events: none; +} diff --git a/mkdocs.yml b/mkdocs.yml index 0f2bfec..7403359 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -24,9 +24,10 @@ plugins: projects: # project names must be alphanumeric, else snippets won't work ltapi: - src-dirs: arduino/libretuya/ + src-dirs: cores/common/ doxy-cfg: - PREDEFINED: __cplusplus + OPTIMIZE_OUTPUT_FOR_C: YES + PREDEFINED: __cplusplus DOXYGEN=1 CASE_SENSE_NAMES: NO save-api: . - literate-nav: @@ -34,11 +35,6 @@ plugins: - section-index - include-markdown - search - - git-revision-date-localized: - type: timeago - enable_creation_date: true - exclude: - - ltapi/* extra_css: - docs/style.css