From 1d2c3ef87b4ed4ee244f03b1d80bee7ca9509096 Mon Sep 17 00:00:00 2001 From: Gijs Noorlander Date: Sun, 11 Aug 2019 21:32:08 +0200 Subject: [PATCH] [Docs] Building ESPeasy using PlatformIO in VS-Code As discussed on the [Forum](https://www.letscontrolit.com/forum/viewtopic.php?f=6&t=6922&p=38512#p38512) --- docs/source/Participate/PlatformIO.rst | 112 +++++++++++++++++++++++++ docs/source/index.rst | 1 + 2 files changed, 113 insertions(+) create mode 100644 docs/source/Participate/PlatformIO.rst diff --git a/docs/source/Participate/PlatformIO.rst b/docs/source/Participate/PlatformIO.rst new file mode 100644 index 000000000..3e8837ace --- /dev/null +++ b/docs/source/Participate/PlatformIO.rst @@ -0,0 +1,112 @@ +PlatformIO +********** + +ESP easy can be built using the Arduino IDE or PlatformIO (PIO). +Arduino IDE is not being used during development, so it may take some more effort to get it setup for building ESPeasy. + +We advice to use PlatformIO as build environment. + +PlatformIO is just the build, test and upload environment for many micro controllers like the ESP8266 and ESP32 we use. + +On top of that you need to use an editor, or so called IDE in which PlatformIO will be used. + +The two main choices are: + +* Atom +* Microsoft Visual Studio Code. (MS VS-Code) + +Both are free to use and are available for Windows, MacOS and Linux. + +Apart from these two, there are more available, like Eclipse and probably more. + +PlatformIO with Atom +==================== + + + +PlatformIO with VS-Code +======================= + +install +------- + +For development of ESPeasy, a number of extensions has to be installed in VS-Code: + +* PlatformIO IDE (by PlatformIO) +* C/C++ IntelliSense (by Microsoft) +* Arduino for Visual Studio Code (by Microsoft) +* Uncrustify (by Laurent Tréguier) + +Uncrustify +---------- + +The extension Uncrustify is mainly to format the code using a standard code format definition. +This code format standard is defined in the file uncrustify.cfg in the main directory of this repository. +For new code contributions, it is highly appreciated if the code is formatted using this tool. + +To do so: + +* Right click mouse in editor +* "Format Document" + +The first time (after installing uncrustify) it must be confirmed to use Uncrustify as formatter and using the default suggested config file. + + +Load a project using PlatformIO +------------------------------- + +If you have PIO installed and the source tree cloned to your hard drive, then you can open the main dir of the repository. +The main directory of the repository is the level with platformio.ini in it. + +Then in a few moments after opening the directory, on the left there will appear an alien logo, the logo of PlatformIO. +If you click that one, you will get a tree with lots and lots of project tasks and environments. + +It is important to note that PlatformIO does everything based on environments, which are defined in the platformio.ini file. +In the PlatformIO menu (on the left) everything is grouped per environment. + +An environment entry has several tasks, like: + +* Build +* Upload +* Monitor +* Upload and Monitor +* ... many more. + +Some of these options only are available when you have registered with PlatformIO and some are only for paid subscriptions. +At least the basic ones used for almost any user are available with the free account. + +The environment definitions all have at least the used micro controller in the name and the amount of flash memory used. + +For example: + +* ..._ESP8266_4M -> ESP8266 has external flash, which can vary in size from 512 kB to 16 MB. +* ..._ESP8285_1M -> ESP8285 has the flash internal, so is always 1 MB. +* ..._ESP32_1M8_partition -> ESP32 with 4 MB flash and a 1.8 MB partition for the sketch. + +Make a custom build using PlatformIO +------------------------------------ + +The easiest is to go for the environment "env:custom_ESP8266_4M" and unfold that one. +Then select "Build" to see if it will start building. + +If that's working, you can open the file "pre_extra_script.py" and add or remove the plugins and controllers you need. +That Python file is used in the "env:custom_ESP8266_4M" to define what should be embedded and what not. + +For example to have only the controller "C014", you can remove "CONTROLLER_SET_ALL", and just add "USES_C014", +The same for the plugins you need. + +The file is built in the ".pio/build/...." directory right under the main repository directory (the one with the platformio.ini in it) + +All builds will be made in a directory with the same name as the environment used. + + + +Upload to ESP +============= + + + +Linux +----- + +For Linux, you may need to install 99-platformio-udev.rules to make PlatformIO upload tools work in vscode. \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst index 0e81c4cd4..22cdcdad4 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -27,6 +27,7 @@ Welcome to ESP Easy's documentation! :maxdepth: 2 :caption: Appendix + Participate/PlatformIO.rst Participate/Documentation.rst Reference/Safety.rst Reference/Command.rst