[docs] Refactor docs structure, add project upload guides
This commit is contained in:
Kuba Szczodrzyński
51
SUMMARY.md
51
SUMMARY.md
@@ -1,40 +1,29 @@
|
||||
* [Home](README.md)
|
||||
* 😊 Getting started
|
||||
* [Start here](docs/getting-started/README.md)
|
||||
* [Uploading](docs/getting-started/uploading.md)
|
||||
* [Options & config](docs/reference/config.md)
|
||||
* Examples
|
||||
* [PinScan](examples/PinScan/README.md)
|
||||
* [ESPHome port](docs/projects/esphome.md)
|
||||
* [Using tuya-cloudcutter](docs/getting-started/cloudcutter.md)
|
||||
* [Auto-download-reboot](docs/getting-started/adr.md)
|
||||
* [💻 Boards & CPU list](docs/status/supported.md)
|
||||
* [✔️ Implementation status](docs/status/arduino.md)
|
||||
* Supported chip families
|
||||
* Beken BK72xx
|
||||
* [General info](docs/platform/beken-72xx/README.md)
|
||||
* [Flashing](docs/platform/beken-72xx/flashing.md)
|
||||
* [Dumping](docs/platform/beken-72xx/dumping.md)
|
||||
* Realtek AmebaZ Series
|
||||
* [General info](docs/platform/realtek/README.md)
|
||||
* [Flashing (AmebaZ)](docs/platform/realtek-ambz/flashing.md)
|
||||
* [Dumping (AmebaZ)](docs/platform/realtek-ambz/dumping.md)
|
||||
* [Debugging](docs/platform/realtek/debugging.md)
|
||||
* [Exception decoder](docs/platform/realtek/exception-decoder.md)
|
||||
* C library
|
||||
* [Built-in functions](docs/platform/realtek-ambz/stdlib.md)
|
||||
* [Memory management](docs/platform/realtek-ambz/memory-management.md)
|
||||
* [All supported boards](boards/)
|
||||
* API & libraries
|
||||
* [Options & config](docs/reference/config.md)
|
||||
* [LibreTuya API](docs/reference/lt-api.md)
|
||||
* [😊 Getting started](docs/getting-started/README.md)
|
||||
* [📲 Flashing/dumping](docs/flashing/)
|
||||
* [💻 Supported boards & chips](docs/status/supported.md)
|
||||
* 📖 Reference
|
||||
* [🔧 LT configuration](docs/reference/config.md)
|
||||
* [✔️ Implementation status](docs/status/arduino.md)
|
||||
* [🔌 Boards documentation](boards/)
|
||||
* [🔋 Examples](examples/)
|
||||
* Chip families
|
||||
* [Beken BK72xx](docs/platform/beken-72xx/README.md)
|
||||
* Realtek AmebaZ Series
|
||||
* [General info](docs/platform/realtek/README.md)
|
||||
* [Debugging](docs/platform/realtek/debugging.md)
|
||||
* [Exception decoder](docs/platform/realtek/exception-decoder.md)
|
||||
* C library
|
||||
* [Built-in functions](docs/platform/realtek-ambz/stdlib.md)
|
||||
* [Memory management](docs/platform/realtek-ambz/memory-management.md)
|
||||
* [📖 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
|
||||
* 📖 Common API
|
||||
* [FS](ltapi/classfs_1_1_f_s.md)
|
||||
* [Preferences](ltapi/class_i_preferences.md)
|
||||
* [SoftwareSerial](ltapi/class_software_serial.md)
|
||||
@@ -42,7 +31,7 @@
|
||||
* [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)
|
||||
* [📖 LibreTuya libraries](docs/libs-built-in.md)
|
||||
* [base64](ltapi/classbase64.md)
|
||||
* [Flash](ltapi/class_flash_class.md)
|
||||
* [HTTPClient](ltapi/class_h_t_t_p_client.md)
|
||||
|
||||
10
docs/flashing/SUMMARY.md
Normal file
10
docs/flashing/SUMMARY.md
Normal file
@@ -0,0 +1,10 @@
|
||||
# Flashing/dumping methods & guides
|
||||
|
||||
* [Flashing PlatformIO projects](platformio.md)
|
||||
* [Flashing ESPHome](esphome.md)
|
||||
* [Using ltchiptool GUI](ltchiptool.md)
|
||||
* [Using tuya-cloudcutter](cloudcutter.md)
|
||||
* Chip connection guide
|
||||
* [Beken BK72xx](../platform/beken-72xx/flashing.md)
|
||||
* [Realtek RTL8710Bx](../platform/realtek-ambz/flashing.md)
|
||||
* [Auto-download-reboot](adr.md)
|
||||
@@ -1,10 +1,12 @@
|
||||
# Flashing with tuya-cloudcutter
|
||||
|
||||
[`tuya-cloudcutter`](https://github.com/tuya-cloudcutter/tuya-cloudcutter) is a tool that disconnects IoT devices from the Tuya cloud, while also allowing **remote firmware flashing**. This means you can flash ESPHome without even connecting USB-UART to the device.
|
||||
!!! note
|
||||
This currently applies to BK7231T and BK7231N only. `tuya-cloudcutter` can't be used for other chips.
|
||||
|
||||
This is an unofficial guide, that worked for me during testing. The steps may not work for every device; you should also refer to the cloudcutter's manual pages.
|
||||
[`tuya-cloudcutter`](https://github.com/tuya-cloudcutter/tuya-cloudcutter) is a tool that disconnects IoT devices from the Tuya cloud, while also allowing **remote firmware flashing**. This means you can flash ESPHome without even disassembling it.
|
||||
|
||||
**Currently, `tuya-cloudcutter` works for BK7231T and BK7231N only.**
|
||||
!!! warning
|
||||
This guide might be outdated. For an up-to-date guide, always refer to [tuya-cloudcutter/INSTRUCTIONS.md](https://github.com/tuya-cloudcutter/tuya-cloudcutter/blob/main/INSTRUCTIONS.md).
|
||||
|
||||
If your device doesn't have a profile yet, it will probably not work. You can contribute by [taking a device dump](https://github.com/tuya-cloudcutter/tuya-cloudcutter#device-dumps) and posting it on cloudcutter's issues page.
|
||||
|
||||
@@ -22,11 +24,11 @@ If your device doesn't have a profile yet, it will probably not work. You can co
|
||||
|
||||
1. [Compile ESPHome](../projects/esphome.md), or your custom firmware based on LibreTuya.
|
||||
2. Get the firmware binary, named `bk7231x_app.ota.ug.bin` from the build directory (`.pio/build/<board>/` or `.esphome/build/<board>/.pioenvs/<board>/`).
|
||||
3. Put the file to `custom-firmware` of tuya-cloudcutter.
|
||||
3. Put it in the `custom-firmware` directory of tuya-cloudcutter.
|
||||
|
||||
### Pairing and flashing
|
||||
|
||||
1. Run `./run_flash.sh` from the cloudcutter directory.
|
||||
1. Run `./tuya-cloudcutter.sh` from the cloudcutter directory.
|
||||
2. Answer questions about the desired firmware file, the device vendor and profile.
|
||||
3. Put the device to AP mode: (**)
|
||||
- Bulbs (devices without buttons) usually need to be power-cycled a few times, until they start blinking slowly.
|
||||
42
docs/flashing/esphome.md
Normal file
42
docs/flashing/esphome.md
Normal file
@@ -0,0 +1,42 @@
|
||||
# Flashing ESPHome
|
||||
|
||||
ESPHome can be flashed in few different ways, depending on your needs.
|
||||
|
||||
## Built-in flasher
|
||||
|
||||
The flasher program built-in LibreTuya is also available for ESPHome.
|
||||
|
||||
- use `python -m esphome run yourdevice.yml` to recompile AND upload the firmware
|
||||
- use `python -m esphome upload yourdevice.yml` to upload without recompiling
|
||||
|
||||
{%
|
||||
include-markdown "inc/uart-info.md"
|
||||
%}
|
||||
|
||||
If your device is already running ESPHome, refer to the OTA guide below.
|
||||
|
||||
## Other methods
|
||||
|
||||
!!! abstract
|
||||
All binary files generated by ESPHome will be in `.esphome/build/<yourdevice>/.pioenvs/<yourdevice>/`. The methods described below may require you to get a file from that directory.
|
||||
|
||||
This path will be referred to as **build directory**.
|
||||
|
||||
## Over-the-Air (OTA)
|
||||
|
||||
This method requires having ESPHome already installed on your device.
|
||||
|
||||
- If you've added the Web Server component, navigate to the device's IP address (or `.local` name) in your web browser. Grab `firmware.uf2` from the build directory and drop it on the "OTA Update" field.
|
||||
- You can also use ESPHome CLI to flash via OTA. Add a `--device` argument to the command, as such: `python -m esphome upload yourdevice.yml --device yourdevice.local`
|
||||
|
||||
{%
|
||||
include-markdown "inc/uart-ltchiptool.md"
|
||||
%}
|
||||
|
||||
{%
|
||||
include-markdown "inc/ota-cloudcutter.md"
|
||||
%}
|
||||
|
||||
{%
|
||||
include-markdown "inc/ota-openbeken.md"
|
||||
%}
|
||||
8
docs/flashing/inc/ota-cloudcutter.md
Normal file
8
docs/flashing/inc/ota-cloudcutter.md
Normal file
@@ -0,0 +1,8 @@
|
||||
## Converting devices with tuya-cloudcutter
|
||||
|
||||
!!! 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.
|
||||
|
||||
Next, refer to [Using tuya-cloudcutter](../cloudcutter.md) guide.
|
||||
5
docs/flashing/inc/ota-openbeken.md
Normal file
5
docs/flashing/inc/ota-openbeken.md
Normal file
@@ -0,0 +1,5 @@
|
||||
## Migrating from OpenBeken (OTA)
|
||||
|
||||
[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.
|
||||
1
docs/flashing/inc/uart-info.md
Normal file
1
docs/flashing/inc/uart-info.md
Normal file
@@ -0,0 +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.
|
||||
6
docs/flashing/inc/uart-ltchiptool.md
Normal file
6
docs/flashing/inc/uart-ltchiptool.md
Normal file
@@ -0,0 +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](../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.
|
||||
100
docs/flashing/ltchiptool.md
Normal file
100
docs/flashing/ltchiptool.md
Normal file
@@ -0,0 +1,100 @@
|
||||
# ltchiptool
|
||||
|
||||
ltchiptool is a universal, easy-to-use GUI flashing/dumping tool for BK7231, RTL8710B and RTL8720C. It also contains some CLI utilities for binary firmware manipulation.
|
||||
|
||||
## Installation
|
||||
|
||||
### GUI package (Windows only)
|
||||
|
||||
Download the latest release .EXE from the [GitHub Releases page](https://github.com/libretuya/ltchiptool/releases/latest). Open the file, and you're ready to go!
|
||||
|
||||
The GUI executable works on Windows 7 and newer.
|
||||
|
||||
### GUI or CLI (Windows/Linux/etc.)
|
||||
|
||||
Install the package from PyPI, using `pip install ltchiptool`.
|
||||
|
||||
This will install `ltchiptool` and `uf2tool` packages. You can start the GUI by typing `python -m ltchiptool gui`.
|
||||
|
||||
## GUI Usage
|
||||
|
||||
The main window is somewhat similar to [NodeMCU PyFlasher](https://github.com/marcelstoer/nodemcu-pyflasher).
|
||||
|
||||
- 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**.
|
||||
|
||||
!!! 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.
|
||||
|
||||
## CLI Usage
|
||||
|
||||
!!! note
|
||||
If you're here to learn how to flash or dump firmware files, use the instructions above.
|
||||
|
||||
The content below serves as a short documentation page for [`ltchiptool`](https://github.com/libretuya/ltchiptool) and is mostly meant for advanced users.
|
||||
|
||||
```shell
|
||||
$ ltchiptool --help
|
||||
Usage: ltchiptool [OPTIONS] COMMAND [ARGS]...
|
||||
|
||||
Tools for working with LT-supported IoT chips
|
||||
|
||||
Options:
|
||||
-v, --verbose Output debugging messages (repeat to output more)
|
||||
-T, --traceback Print complete exception traceback
|
||||
-t, --timed Prepend log lines with timing info
|
||||
-r, --raw-log Output logging messages with no additional styling
|
||||
-i, --indent INTEGER Indent log messages using graph lines
|
||||
-V, --version Show the version and exit.
|
||||
-h, --help Show this message and exit.
|
||||
|
||||
Commands:
|
||||
dump Capture or process device dumps
|
||||
elf2bin Generate firmware binaries from ELF file
|
||||
flash Flashing tool - reading/writing
|
||||
link2bin Link code to binary format
|
||||
list List boards, families, etc.
|
||||
soc Run SoC-specific tools
|
||||
uf2 Work with UF2 files
|
||||
```
|
||||
|
||||
### Flashing/dumping
|
||||
|
||||
There are three main commands used for flashing:
|
||||
|
||||
- `ltchiptool flash file <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 <FAMILY> <FILE>` - make a full flash dump of the connected device; specifying the family is required
|
||||
- `ltchiptool flash write <FILE>` - 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 <FAMILY>` and `-s <START OFFSET>`.
|
||||
|
||||
### UF2 Example
|
||||
|
||||
```shell
|
||||
$ ltchiptool uf2 info ./arduinotest_22.08.01_wb2l_BK7231T_lt0.8.0.uf2
|
||||
Family: BK7231T / Beken 7231T
|
||||
Tags:
|
||||
- BOARD: wb2l
|
||||
- DEVICE_ID: d80e20c2
|
||||
- LT_VERSION: 0.8.0
|
||||
- FIRMWARE: arduinotest
|
||||
- VERSION: 22.08.01
|
||||
- OTA_VERSION: 01
|
||||
- DEVICE: LibreTuya
|
||||
- BUILD_DATE: 6d08e862
|
||||
- LT_HAS_OTA1: 01
|
||||
- LT_HAS_OTA2: 00
|
||||
- LT_PART_1: app
|
||||
- LT_PART_2:
|
||||
Data chunks: 1871
|
||||
Total binary size: 478788
|
||||
```
|
||||
30
docs/flashing/platformio.md
Normal file
30
docs/flashing/platformio.md
Normal file
@@ -0,0 +1,30 @@
|
||||
# Flashing PlatformIO projects
|
||||
|
||||
PlatformIO projects developed with LibreTuya can be flashed just like any other PIO project.
|
||||
|
||||
## Built-in flasher
|
||||
|
||||
LibreTuya has a built-in firmware uploader, based on [ltchiptool](ltchiptool.md). Pressing `Upload` in PlatformIO IDE does all the work for you.
|
||||
|
||||
If you have more than one COM port,configure your PIO project first:
|
||||
|
||||
```ini
|
||||
[env:my_board]
|
||||
monitor_port = COM96
|
||||
upload_port = COM96
|
||||
```
|
||||
|
||||
{%
|
||||
include-markdown "inc/uart-info.md"
|
||||
%}
|
||||
|
||||
## Other methods
|
||||
|
||||
!!! abstract
|
||||
All binary files generated by PlatformIO will be in `.pio/build/<my_board>/`. The methods described below may require you to get a file from that directory.
|
||||
|
||||
This path will be referred to as **build directory**.
|
||||
|
||||
{%
|
||||
include-markdown "inc/uart-ltchiptool.md"
|
||||
%}
|
||||
@@ -13,16 +13,9 @@ Using LibreTuya is simple, just like every other PlatformIO development platform
|
||||
- Click on the board name. From the documentation page, note the board code.
|
||||
- Use this code to create a PlatformIO project.
|
||||
|
||||
## GPIO usage
|
||||
## Run community projects
|
||||
|
||||
!!! important
|
||||
This can be confusing at first, so make sure to read this part carefully to understand it.
|
||||
|
||||
Input/output pin numbers in Arduino code (i.e. `digitalWrite()`) use Arduino pin numbers - for example `D1`, `D3`. This is the same as simply `1` or `3`, but it cannot be confused with CPU GPIO numbers.
|
||||
|
||||
On the board pinout page, the purple blocks represent Arduino pins, while the dark red blocks refer to GPIO numbers.
|
||||
|
||||
Projects like ESPHome also use Arduino pin numbering.
|
||||
LibreTuya was developed with popular community projects in mind. Currently, unofficial [ESPHome port](../projects/esphome.md) is available ([the PR](https://github.com/esphome/esphome/pull/3509) will hopefully be merged into upstream at some point).
|
||||
|
||||
## Develop your own project
|
||||
|
||||
@@ -31,8 +24,24 @@ If you're developing your own embedded software, and want it to run on LibreTuya
|
||||
- use PlatformIO IDE (PIO Home -> Open -> New Project)
|
||||
- run `pio project init` in your desired project directory
|
||||
|
||||
Next, read [Uploading](uploading.md) guide to run your project!
|
||||
Next, read one of the [flashing guides](../flashing/SUMMARY.md) to run your project!
|
||||
|
||||
## Run community projects
|
||||
### LT configuration
|
||||
|
||||
LibreTuya was developed with popular community projects in mind. Currently, unofficial [ESPHome port](../projects/esphome.md) is available ([the PR](https://github.com/esphome/esphome/pull/3509) will hopefully be merged into upstream at some point).
|
||||
LibreTuya has a few configuration options that change its behavior or features. Refer to [LT configuration](../reference/config.md) for details.
|
||||
|
||||
### GPIO usage
|
||||
|
||||
!!! important
|
||||
This can be confusing at first, so make sure to read this part carefully to understand it.
|
||||
|
||||
Input/output pin numbers in Arduino code (i.e. `digitalWrite()`) use Arduino pin numbers - for example `D1`, `D3`. This is the same as simply `1` or `3`, but it cannot be confused with CPU GPIO numbers.
|
||||
|
||||
On the board pinout page, the purple blocks represent Arduino pins, while the dark red blocks refer to GPIO numbers.
|
||||
|
||||
### Examples
|
||||
|
||||
{%
|
||||
include-markdown "../../examples/SUMMARY.md"
|
||||
start="# Examples\n"
|
||||
%}
|
||||
|
||||
@@ -1,8 +0,0 @@
|
||||
# Uploading
|
||||
|
||||
The uploading/flashing procedure is different for every chip family:
|
||||
|
||||
- BK72xx / BK7231 - [click here](../platform/beken-72xx/flashing.md)
|
||||
- Realtek AmebaZ (RTL8710BN/BX) - [click here](../platform/realtek-ambz/flashing.md)
|
||||
|
||||
Also see [Auto-download-reboot](adr.md) for an easier way of uploading code.
|
||||
@@ -3,11 +3,11 @@
|
||||
A page outlining 3-rd 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):
|
||||
```ini
|
||||
[env:my_board]
|
||||
lib_compat_mode = off
|
||||
```
|
||||
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):
|
||||
```ini
|
||||
[env:my_board]
|
||||
lib_compat_mode = off
|
||||
```
|
||||
|
||||
## MQTT
|
||||
Tested with `realtek-ambz`.
|
||||
|
||||
@@ -26,15 +26,15 @@ Utilities and common classes related to network.
|
||||
- [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)
|
||||
- [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)
|
||||
- [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.
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
LibreTuya's OTA updating is based on [Microsoft's UF2 specification](https://microsoft.github.io/uf2/). Some aspects of the process, such as OTA1/2 support and target partition selection, have been customized with extension tags.
|
||||
|
||||
!!! note
|
||||
Just like in UF2, all values in this format are little-endian.
|
||||
Just like in UF2, all values in this format are little-endian.
|
||||
|
||||
## Firmware images
|
||||
|
||||
@@ -29,7 +29,7 @@ For easier understanding, these update types will be referred to in this documen
|
||||
## Custom family IDs
|
||||
|
||||
{%
|
||||
include-markdown "../status/supported_families.md"
|
||||
include-markdown "../status/supported_families.md"
|
||||
%}
|
||||
|
||||
## Extension tags
|
||||
@@ -84,17 +84,12 @@ OTA2 images are not stored directly, as that would needlessly double the UF2 fil
|
||||
There can be at most one binpatch tag in a UF2 block. It has the following format:
|
||||
|
||||
- opcode (1 byte) - operation type:
|
||||
|
||||
- `DIFF32` (0xFE) - difference between 32-bit values
|
||||
|
||||
- `DIFF32` (0xFE) - difference between 32-bit values
|
||||
- length (1 byte) - data length
|
||||
- data (`length` bytes)
|
||||
|
||||
- for `DIFF32`:
|
||||
|
||||
- difference value (signed int 32-bit)
|
||||
|
||||
- offset table (`length-4` bytes)
|
||||
- for `DIFF32`:
|
||||
- difference value (signed int 32-bit)
|
||||
- offset table (`length-4` bytes)
|
||||
|
||||
The presented structure can be repeated in a single binpatch tag.
|
||||
|
||||
|
||||
@@ -41,7 +41,7 @@ upload_port = COM96
|
||||
## Manually - using `uf2upload`
|
||||
|
||||
{%
|
||||
include-markdown "../../ota/flashing.md"
|
||||
include-markdown "../../ota/flashing.md"
|
||||
%}
|
||||
|
||||
## Manually - using raw binaries/BkWriter
|
||||
|
||||
@@ -23,7 +23,7 @@ upload_port = COM60
|
||||
## Manually - using `uf2upload`
|
||||
|
||||
{%
|
||||
include-markdown "../../ota/flashing.md"
|
||||
include-markdown "../../ota/flashing.md"
|
||||
%}
|
||||
|
||||
## Manually - using raw binaries/BkWriter
|
||||
|
||||
@@ -28,13 +28,13 @@ Check out [RPi BCM2711 GPIOs](https://elinux.org/RPi_BCM2711_GPIOs) to read more
|
||||
TL;DR: Install OpenOCD. Conenct A14 to BCM GPIO#11, A15 to BCM GPIO#25. Remember to join GND together. Refer to [boards/](../../../boards/) for pinouts.
|
||||
|
||||
!!! note
|
||||
On Raspberry Pi 4, additional config might be needed:
|
||||
```
|
||||
bcm2835gpio peripheral_base 0xFE000000
|
||||
bcm2835gpio speed_coeffs 236181 60
|
||||
```
|
||||
Save the lines to a .cfg file, and pass it to OpenOCD using `-f file.cfg`.
|
||||
Read more [here](https://forums.raspberrypi.com/viewtopic.php?p=1541631&sid=915e8d039f24301b85c060318a44b7f0#p1541631).
|
||||
On Raspberry Pi 4, additional config might be needed:
|
||||
```
|
||||
bcm2835gpio peripheral_base 0xFE000000
|
||||
bcm2835gpio speed_coeffs 236181 60
|
||||
```
|
||||
Save the lines to a .cfg file, and pass it to OpenOCD using `-f file.cfg`.
|
||||
Read more [here](https://forums.raspberrypi.com/viewtopic.php?p=1541631&sid=915e8d039f24301b85c060318a44b7f0#p1541631).
|
||||
|
||||
Start OpenOCD like this (you also need your config file in the working directory):
|
||||
```shell
|
||||
|
||||
@@ -1,31 +1,32 @@
|
||||
# ESPHome
|
||||
|
||||
!!! important
|
||||
Read [Getting started](../getting-started/README.md) first.
|
||||
Read [Getting started](../getting-started/README.md) first - most importantly, the first part about installation.
|
||||
|
||||
**It is very important that you have the latest version of LibreTuya installed** (not `libretuya-esphome`) **so that you don't face issues that are already resolved**.
|
||||
**It is very important that you have the latest version of LibreTuya installed** (not `libretuya-esphome` - this is a different thing!) **so that you don't face issues that are already resolved**.
|
||||
|
||||
## Install ESPHome
|
||||
## Download ESPHome
|
||||
|
||||
Because ESPHome does not natively support running on non-ESP chips, you need to use a fork of the project.
|
||||
|
||||
Assuming you have PlatformIO, git and Python installed:
|
||||
|
||||
1. Open a terminal/cmd.exe, create `esphome` directory and `cd` into it.
|
||||
2. `git clone https://github.com/kuba2k2/libretuya-esphome -b platform/libretuya` (you need the `platform/libretuya` branch)
|
||||
2. `git clone https://github.com/kuba2k2/libretuya-esphome`
|
||||
3. `cd` into the newly created `libretuya-esphome` directory.
|
||||
4. Check if it works by typing `python -m esphome`
|
||||
|
||||
!!! note
|
||||
!!! tip
|
||||
For Linux users (or if `python -m esphome` doesn't work for you):
|
||||
|
||||
- unistall ESPHome first: `pip uninstall esphome`
|
||||
- uninstall ESPHome first: `pip uninstall esphome`
|
||||
- install the forked version: `pip install -e .`
|
||||
|
||||
## Create your device config
|
||||
|
||||
1. Go to [Boards & CPU list](../status/supported/), click on your board and remember your board code.
|
||||
1. Go to [Boards & CPU list](../status/supported/), click on your board and remember the **`Board code`**.
|
||||
2. Create a YAML config file for your device. You can either:
|
||||
- use `python -m esphome wizard yourdevice.yml` - type answers to the six questions the wizard asks, OR:
|
||||
- if your board isn't available in the wizard yet, use the manual YAML method below
|
||||
- write a config file manually:
|
||||
```yaml
|
||||
esphome:
|
||||
@@ -50,7 +51,25 @@ Assuming you have PlatformIO, git and Python installed:
|
||||
password: "Dv2hZMGZRUvy"
|
||||
```
|
||||
|
||||
## Configuration options
|
||||
## Add components
|
||||
|
||||
Now, just like with standard ESPHome on ESP32/ESP8266, you need to add components for your device. Visit [ESPHome homepage](https://esphome.io/) to learn about YAML configuration. If you want, you can upload an "empty" config first, and add actual components later.
|
||||
|
||||
!!! danger "Important"
|
||||
It's highly recommended to **always** include the [`web_server`](https://esphome.io/components/web_server.html) and [`captive_portal`](https://esphome.io/components/captive_portal.html) components - **even in your first "empty" upload**.
|
||||
|
||||
Adding these two components will safeguard you against accidentally soft-bricking the device, by e.g. entering invalid Wi-Fi credentials. The Web Server provides an easy way to flash a new image over-the-air, and the Captive Portal allows to easily open the Web Server on a fallback AP.
|
||||
|
||||
## Build & upload
|
||||
|
||||
The command `python -m esphome compile yourdevice.yml` will compile ESPHome.
|
||||
|
||||
You probably want to refer to the [flashing guide](../flashing/esphome.md) to learn how to upload ESPHome to your device. There's also info on using `tuya-cloudcutter` in that guide.
|
||||
|
||||
## Advanced: LT configuration
|
||||
|
||||
!!! 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:
|
||||
|
||||
@@ -81,18 +100,3 @@ libretuya:
|
||||
gpio_recover: true
|
||||
```
|
||||
(these values are defaults)
|
||||
|
||||
## Compile & upload
|
||||
|
||||
- `python -m esphome compile yourdevice.yml` - this will only compile the code
|
||||
- `python -m esphome upload yourdevice.yml` - this will upload the previously compiled code
|
||||
- `python -m esphome run yourdevice.yml` - this will compile and upload the code
|
||||
|
||||
!!! info
|
||||
If you want to flash manually:
|
||||
|
||||
The binary file, ready for uploading, will be in `.esphome/build/yourdevice/.pioenvs/yourdevice/`.
|
||||
|
||||
Refer to your board README to find appropriate flashing instructions.
|
||||
|
||||
Or [flash with `tuya-cloudcutter`](../getting-started/cloudcutter.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 [LibreTuyaConfig.h](../../ltapi/_libre_tuya_config_8h_source.md) for most options and their defaults.
|
||||
|
||||
All options are configurable via C++ defines in PlatformIO project file. For example:
|
||||
```ini
|
||||
@@ -24,8 +24,8 @@ build_flags =
|
||||
-D LT_LOGLEVEL=LT_LEVEL_DEBUG
|
||||
```
|
||||
|
||||
!!! hint
|
||||
Values in parentheses represent the defaults for the config options.
|
||||
!!! tip
|
||||
Values in parentheses represent the defaults for the config options.
|
||||
|
||||
### Logger
|
||||
|
||||
@@ -64,16 +64,16 @@ To see debug messages from i.e. OTA, loglevel must also be changed.
|
||||
- `LT_DEBUG_LWIP` (0) - enables `LWIP_DEBUG`, provides `LWIP_PLATFORM_DIAG`; per-module options (i.e. `TCP_DEBUG`) are off by default and need to be enabled separately
|
||||
- `LT_DEBUG_LWIP_ASSERT` (0) - enables assertions within lwIP (doesn't need `LT_DEBUG_LWIP`)
|
||||
|
||||
!!! hint
|
||||
Enabling `LT_DEBUG_ALL` doesn't mean that *every* debugging message will be printed. If loglevel is i.e. `WARN`, debug messages won't be visible anyway.
|
||||
!!! tip
|
||||
Enabling `LT_DEBUG_ALL` doesn't mean that *every* debugging message will be printed. If loglevel is i.e. `WARN`, debug messages won't be visible anyway.
|
||||
|
||||
This can be used, for example, to enable only "important" messages:
|
||||
```ini
|
||||
[env:my_board]
|
||||
build_flags =
|
||||
-D LT_LOGLEVEL=LT_LEVEL_WARN
|
||||
-D LT_DEBUG_ALL=1 # will print only warnings and errors from all modules
|
||||
```
|
||||
This can be used, for example, to enable only "important" messages:
|
||||
```ini
|
||||
[env:my_board]
|
||||
build_flags =
|
||||
-D LT_LOGLEVEL=LT_LEVEL_WARN
|
||||
-D LT_DEBUG_ALL=1 # will print only warnings and errors from all modules
|
||||
```
|
||||
|
||||
### Serial output
|
||||
|
||||
@@ -86,20 +86,23 @@ Options for controlling default UART log output.
|
||||
- `LT_UART_SILENT_ALL` (0) - disable all SDK output (LT output and logger still work)
|
||||
|
||||
!!! info
|
||||
Values 0, 1 and 2 correspond to physical UART port numbers (refer to board pinout for the available ports).
|
||||
Values 0, 1 and 2 correspond to physical UART port numbers (refer to board pinout for the available ports).
|
||||
|
||||
Serial class instances (`Serial0`, `Serial1`, `Serial2`) use the respective port numbers for printing.
|
||||
Serial class instances (`Serial0`, `Serial1`, `Serial2`) use the respective port numbers for printing.
|
||||
|
||||
If `LT_UART_DEFAULT_LOGGER` is not set, it is chosen by the family code - whichever port is most appropriate (i.e. LOG_UART (2) on Realtek, RX2/TX2 on Beken).
|
||||
If `LT_UART_DEFAULT_LOGGER` is not set, it is chosen by the family code - whichever port is most appropriate (i.e. LOG_UART (2) on Realtek, RX2/TX2 on Beken).
|
||||
|
||||
### Misc options
|
||||
|
||||
- `LT_USE_TIME` (0) - enables implementation of `gettimeofday()` and `settimeofday()`; checks for `millis()` overflows periodically
|
||||
- `LT_MICROS_HIGH_RES` (1) - count runtime microseconds using a high-resolution timer; disable if your application doesn't need `micros()`
|
||||
- `LT_AUTO_DOWNLOAD_REBOOT` (1) - automatically reboot into "download mode" after detecting a flashing protocol command; [read more](../getting-started/adr.md)
|
||||
- `LT_AUTO_DOWNLOAD_REBOOT` (1) - automatically reboot into "download mode" after detecting a flashing protocol command; [read more](../flashing/adr.md)
|
||||
|
||||
### 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 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.
|
||||
|
||||
The `LT_ARD_*` options are only used with Arduino frameworks.
|
||||
|
||||
@@ -3,19 +3,19 @@
|
||||
## Class functions
|
||||
|
||||
{%
|
||||
include-markdown "../../ltapi/class_libre_tuya.md"
|
||||
include-markdown "../../ltapi/class_libre_tuya.md"
|
||||
start="(class_libre_tuya.md)\n"
|
||||
end="[More...]"
|
||||
%}
|
||||
|
||||
{%
|
||||
include-markdown "../../ltapi/class_libre_tuya.md"
|
||||
include-markdown "../../ltapi/class_libre_tuya.md"
|
||||
start="# Detailed Description\n"
|
||||
end="## Public Functions Documentation\n"
|
||||
%}
|
||||
|
||||
{%
|
||||
include-markdown "../../ltapi/class_libre_tuya.md"
|
||||
include-markdown "../../ltapi/class_libre_tuya.md"
|
||||
start="## Public Functions\n"
|
||||
end="# Detailed Description\n"
|
||||
%}
|
||||
@@ -23,7 +23,7 @@
|
||||
## Common methods
|
||||
|
||||
{%
|
||||
include-markdown "../../ltapi/_libre_tuya_a_p_i_8h.md"
|
||||
include-markdown "../../ltapi/_libre_tuya_a_p_i_8h.md"
|
||||
start="## Public Functions\n"
|
||||
end="## Public Functions Documentation\n"
|
||||
heading-offset=1
|
||||
@@ -32,7 +32,7 @@
|
||||
## Wiring custom methods
|
||||
|
||||
{%
|
||||
include-markdown "../../ltapi/_libre_tuya_custom_8h.md"
|
||||
include-markdown "../../ltapi/_libre_tuya_custom_8h.md"
|
||||
start="## Public Functions\n"
|
||||
end="## Macros\n"
|
||||
%}
|
||||
@@ -40,7 +40,7 @@
|
||||
## Logger
|
||||
|
||||
{%
|
||||
include-markdown "../../ltapi/lt__logger_8h.md"
|
||||
include-markdown "../../ltapi/lt__logger_8h.md"
|
||||
start="## Public Functions\n"
|
||||
end="## Public Functions Documentation\n"
|
||||
heading-offset=1
|
||||
|
||||
@@ -1,3 +1,4 @@
|
||||
mkdocs-material
|
||||
mkdocs-same-dir
|
||||
mkdocs-literate-nav
|
||||
mkdocs-section-index
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# Implementation status
|
||||
|
||||
{%
|
||||
include-markdown "../../README.md"
|
||||
include-markdown "../../README.md"
|
||||
start="\n## Arduino Core support status\n"
|
||||
end="\n## License\n"
|
||||
%}
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
## Board list
|
||||
|
||||
{%
|
||||
include-markdown "supported_boards.md"
|
||||
include-markdown "supported_boards.md"
|
||||
%}
|
||||
|
||||
\* I/O count includes GPIOs, ADCs, PWM outputs and UART, but doesn't count CEN/RST and power pins.
|
||||
@@ -13,7 +13,7 @@
|
||||
Chips currently supported by the project:
|
||||
|
||||
{%
|
||||
include-markdown "supported_chips.md"
|
||||
include-markdown "supported_chips.md"
|
||||
%}
|
||||
|
||||
This list is not exhaustive, i.e. a similar chip (but different package) might work just fine, but there's no board definition for it yet.
|
||||
@@ -24,12 +24,12 @@ If you have an unsupported chip, feel free to reach out using Issues or on the D
|
||||
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 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).
|
||||
|
||||
{%
|
||||
include-markdown "supported_families.md"
|
||||
include-markdown "supported_families.md"
|
||||
%}
|
||||
|
||||
## Unsupported boards
|
||||
@@ -37,8 +37,8 @@ The following list corresponds to UF2 OTA format family names, and is also [avai
|
||||
### Tuya Inc.
|
||||
|
||||
!!! note
|
||||
Only modules featuring at least Wi-Fi are included in the table. (TY)JW, (TY)WE and (TY)LC Series are omitted, as they contain Espressif chips.
|
||||
Only modules featuring at least Wi-Fi are included in the table. (TY)JW, (TY)WE and (TY)LC Series are omitted, as they contain Espressif chips.
|
||||
|
||||
{%
|
||||
include-markdown "unsupported_boards_tuya_all.md"
|
||||
include-markdown "unsupported_boards_tuya_all.md"
|
||||
%}
|
||||
|
||||
@@ -36,7 +36,7 @@ Switching to another UART port is possible (for example if the default port is o
|
||||
|
||||
By setting `USE_WIFI` in `main.h` to 1, a Telnet server is enabled on port 23. This allows to test I/O pins without having physical, wired access to the device (i.e. using OTA). Make sure to specify correct WiFi credentials.
|
||||
|
||||
!!! hint
|
||||
!!! tip
|
||||
If your board isn't supported by LT yet, use one of the generic boards.
|
||||
|
||||
If your board doesn't even have a known pinout, use `d`/`s` commands of PinScan to ease the mapping of all board pins.
|
||||
@@ -65,7 +65,7 @@ Commands:
|
||||
|
||||
Screen contents will update when voltage on one of the pins changes. Pins marked with `--` mean the currently used UART port (which can be changed using `s` command; after reboot).
|
||||
|
||||
!!! tldr
|
||||
!!! abstract "TL;DR"
|
||||
Try pressing a button to see which pin changes.
|
||||
|
||||
### Read one pin continuously
|
||||
@@ -81,7 +81,7 @@ Enter the pin number, it will be probed until you press `q`.
|
||||
|
||||
A pin will be toggled every 500ms, starting with D0. Type `n` to move to the next pin.
|
||||
|
||||
!!! tldr
|
||||
!!! abstract "TL;DR"
|
||||
Go through the pins to see which lights up an LED.
|
||||
|
||||
### Write HIGH/LOW to a pin
|
||||
@@ -94,7 +94,7 @@ Outputs can be toggled by using internal pull-up/pull-down resistors, or by simp
|
||||
|
||||
This affects scan and write high/low commands.
|
||||
|
||||
!!! tldr
|
||||
!!! abstract "TL;DR"
|
||||
Use `write` output mode (carefully) if there's an LED which doesn't light up with default pull mode.
|
||||
|
||||
## Analog pins
|
||||
|
||||
3
examples/SUMMARY.md
Normal file
3
examples/SUMMARY.md
Normal file
@@ -0,0 +1,3 @@
|
||||
# Examples
|
||||
|
||||
* [PinScan](PinScan/README.md)
|
||||
Reference in New Issue
Block a user