From 9a33fc0a696317d0828bd1438d94d5f9d4aa27f8 Mon Sep 17 00:00:00 2001 From: Anna <16231288+HumbleDeer@users.noreply.github.com> Date: Tue, 20 Feb 2024 17:14:12 +0100 Subject: [PATCH] [docs] Improve getting started guide (#252) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Update Readme & improve md layout - ESPHome now supports LibreTiny natively - Added extra PIO docs references - Reworded some sections slightly, to accomodate proper grammar - PIO deprecated the `platformio platform install` command, replaced this with the official recommendation/replacement * Use backslash for line break, revert changing indent --------- Co-authored-by: Kuba Szczodrzyński --- docs/getting-started/README.md | 46 ++++++++++++++++++++++------------ mkdocs.yml | 2 ++ 2 files changed, 32 insertions(+), 16 deletions(-) diff --git a/docs/getting-started/README.md b/docs/getting-started/README.md index 634e9d473..734556b68 100644 --- a/docs/getting-started/README.md +++ b/docs/getting-started/README.md @@ -3,46 +3,60 @@ Using LibreTiny is simple, just like every other PlatformIO development platform. 1. [Install PlatformIO](https://platformio.org/platformio-ide) -2. `platformio platform install -f https://github.com/libretiny-eu/libretiny` +2. `pio pkg install --platform libretiny` !!! tip See the [Cloudcutter video guide](https://www.youtube.com/watch?v=sSj8f-HCHQ0) for a complete tutorial on flashing with [Cloudcutter](https://github.com/tuya-cloudcutter/tuya-cloudcutter) and installing [LibreTiny-ESPHome](../projects/esphome.md). **Includes Home Assistant Add-On setup.** + More information on Cloudcutter can be found in the [Tuya Cloudcutter GitHub repository](https://github.com/tuya-cloudcutter/tuya-cloudcutter). + ## Board selection -- Go to [Boards & CPU list](../status/supported.md). -- Find the board your device has (usually, the model number is written on the silkscreen). - - If your board isn't available yet, use one of the "Generic" boards that matches the CPU you have. -- Click on the board name. From the documentation page, note the board code. -- Use this code to create a PlatformIO project. +1. Navigate to the [supported boards & CPUs](../status/supported.md) list. +2. Find the board your device has (usually, the model number is written on the silkscreen). \ + *If your board isn't available yet, use one of the "Generic" boards that matches the CPU you your board has.* +3. Click on the board name. A new page opens with information about the selected board name. +4. Scroll down to the "Usage" section of the page, and copy the configuration section that is relevant to your use case. ## Run community projects -LibreTiny 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). +LibreTiny was developed with popular community projects in mind. + +There is an official [ESPHome port](../projects/esphome.md) available and integrated into the ESPHome project. No extra downloads or code compilations are needed to use ESPHome with LibreTiny-supported platforms. ## Develop your own project -If you're developing your own embedded software, and want it to run on LibreTiny-supported chips, create a project. +Developing your own embedded software that runs on LibreTiny-supported platforms. + +To get started with LibreTiny on your chosen platform, create a new project using your preferred method. -- use PlatformIO IDE (PIO Home -> Open -> New Project) -- run `pio project init` in your desired project directory +There's a few ways to create a new PlatformIO Project. For example: -Next, read one of the [flashing guides](../flashing/SUMMARY.md) to run your project! +- using the PlatformIO IDE graphical interface (PIO Home -> Open -> New Project) +- by running the `pio project init` command in your desired project directory \ + *See the [PlatformIO Core (CLI) documentation] for information on `pio project init` and other command line usage.* -### LT configuration +Next, read one of the [flashing guides](../flashing/SUMMARY.md) to upload and run your project! -LibreTiny has a few configuration options that change its behavior or features. Refer to [LT configuration](../dev/config.md) for details. +### Config options (platformio.ini) + +LibreTiny has a few configuration options that allow you to change its behavior or features. These can be defined, specified or changed in the platformio.ini configuration file for your project. + +Refer to the LibreTiny [Configuration](../dev/config.md) manual for details. ### GPIO usage - important change !!! important - Since v1.0.0, GPIOs are no longer meant to be referenced by `D#` numbers. + As of LibreTiny release v1.0.0, references to GPIO pins using their `D#` numbers has been **deprecated** and should **no longer be used** in new projects. - If your program is using Arduino I/O functions, refer to the [Migration guide](../dev/migration_v1.0.0.md) to modify your program accordingly. + If your program is using Arduino I/O functions, please refer to the [migration guide](../dev/migration_v1.0.0.md) on how to modify your code accordingly. ### Examples {% include-markdown "../../examples/SUMMARY.md" - start="# Examples\n" + start="# Examples\n" %} + + +[PlatformIO Core (CLI) documentation]: https://docs.platformio.org/en/stable/core/quickstart.html#setting-up-the-project diff --git a/mkdocs.yml b/mkdocs.yml index 395cc8e8b..ff9c70abd 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -67,6 +67,8 @@ markdown_extensions: anchor_linenums: true - pymdownx.tabbed: alternate_style: true + - pymdownx.escapeall: + hardbreak: true - pymdownx.inlinehilite - pymdownx.details - pymdownx.superfences