[Docs] Updates and fixes, November 2024

docs/source/Participate/PlatformIO.rst

@@ -6,7 +6,7 @@ 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.
+We *strongly* advise 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.
 
@@ -68,6 +68,7 @@ For development of ESPEasy, a number of extensions has to be installed in VS-Cod
 
 * PlatformIO IDE (by PlatformIO)
 * C/C++ IntelliSense (by Microsoft)
+* C/C++ Extension Pack (by Microsoft)
 * Uncrustify (by Zachary Flower, originally by Laurent Tréguier)
 
 Optional, but highly recommended:
@@ -81,6 +82,7 @@ Optional, but highly recommended:
 * reStructuredText Syntax highlighting (by Trond Snekvik)
 * Extension pack for reStructuredText (by LeXtudio Inc.)
 * Markdown All in One (by Yu Zhang)
+* WSL (by Microsoft) (when using WSL2 as documented below)
 
 
 Uncrustify
@@ -92,6 +94,8 @@ For new code contributions, it is highly appreciated if the code is formatted us
 
 NB: Uncrustify has to be installed separately, as it is not included in the plugin! Download `Uncrustify from Sourceforge.net <https://sourceforge.net/projects/uncrustify/>`_
 
+When using a Linux OS, f.e. WSL with Ubuntu, uncrustify can be installed via the regular package manager (shown below). It is strongly advised to use version 0.78 or newer, as older versions seem to have some bugs, causing document formatting to fail.
+
 To do so:
 
 * Right click mouse in editor
@@ -176,10 +180,66 @@ All these mainly apply to the latest ESP32-xx builds using ESP-IDF5.x.
 On a beefy desktop PC, like an AMD Ryzen9 with 12 CPU cores, building a ``MAX`` build for ESP32-S3 takes about 10 - 15 minutes on Windows.
 The same build when using WSL2 via VS-Code takes only 2 minutes to build.
 
+When using VS-Code with WSL2, the VS-Code editor application runs on Windows, and, via the WSL plugin, communicates with a VS-Code server component on a Linux instance, running on WSL, that has the source code repository available, and where the build process is executed.
+
 
 Installing WSL2
 ---------------
 
+For installing WSL2 a couple of steps are needed. Assumption here is that the default Linux distribution for WSL is used, currently Ubuntu (24.04 LTS), using apt-get as the package manager. Other Linux distributions may use a different package manager, like dnf, zypper or yum, using somewhat different commands. Those commands are not documented here.
+
+Install WSL2 - The Windows part
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Open a Windows Command prompt, preferrably Powershell, with Administrator privileges (Press the Windows key and start typing ``powershell``, then select Run as administrator)
+
+* Type the command ``wsl --install`` and press <Enter>, this will start the installation procedure, ask for permissions via User Account Control where needed (that must be confirmed), and download and install what's required.
+
+* Once this part of the installation is complete, the computer must be restarted. This will install any additional Windows components that weren't installed yet.
+
+* After logging in to Windows, the installation procedure will be further completed, and you will be asked to enter a username and password for your day-to-day Linux user. This password will be needed later, f.e. when starting the WSL Linux instance, so best practice is to store it in a password safe of some sort (or write it on a Post-It note and stick that under your keyboard ;-)) 
+
+Install WSL2 - The Linux part
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Now that Linux is installed, it's strongly advised to get it up to date with the latest patches, similar to Windows Update. This should be repeated on a regular basis to keep your installation up to date:
+
+.. highlight::sh
+
+.. code-block::
+
+    sudo apt-get update
+    sudo apt-get upgrade
+
+NB: The ``sudo`` command will ask for your current account password once, (and maybe later again after some time has passed). When asked for confirmation, confirm the installation of any needed updates, or add the ``-y`` parameter to the ``upgrade`` command to continue without questions.
+
+Additionally some tools need to be installed so PlatformIO can be properly installed later, and we can use the Uncrustify plugin in VS-Code to format the code nicely:
+
+.. highlight::sh
+
+.. code-block::
+
+    sudo apt-get install python3-venv
+    sudo apt-get install python3-pip
+    sudo apt-get install uncrustify
+
+Once this is completed, you can get the ESPEasy code in your WSL Linux file system. By default your Linux instance has access to the same internet connection as the host-computer that's running WSL, so the commands are the same as below for cloning a repository (**Clone your forked repositoryto your computer**)
+
+Start VS-Code from Linux
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Now that the repository is available locally, you can start VS-Code from the root folder of this repository:
+
+.. highlight::sh
+
+.. code-block::
+
+    cd ESPEasy
+    code .
+
+This will install, or update, the VS-Code server component in Linux and then open the VS-Code IDE in your Windows environment, assuming you have installed the suggested WSL plugin in VS-Code.
+
+
 
 Linking USB serial adapter to WSL2
 ----------------------------------
@@ -190,7 +250,7 @@ After the USB device is 'bound' (shared), it must be attached to a specific wsl
 N.B. this must be repeated after a device was unplugged and replugged.
 
 The required steps are described `here <https://learn.microsoft.com/en-us/windows/wsl/connect-usb#attach-a-usb-device>`_
-However since this is rather tedious and error prone, it is strongly adviced to use a GUI tool like `WSL USB Manager <https://gitlab.com/alelec/wsl-usb-gui>`_ to perform these steps.
+However since this is rather tedious and error prone, it is strongly advised to use a GUI tool like `WSL USB Manager <https://gitlab.com/alelec/wsl-usb-gui>`_ to perform these steps.
 
 After attaching an USB device to a WSL instance, it is best to check whether it was found using `dmesg` via the command line on WSL2.
 
@@ -201,7 +261,7 @@ If only an USB device was detected but no `/dev/ttyUSBxx` was assigned, then a m
 * ``sudo modprobe cp210x`` - For FTDI CP210x USB to serial chips (small square form factor)
 * ``sudo modprobe ftdi_sio`` - For FTDI USB to serial chips with multiple serial ports like the FTDI4232H which has 4 serial ports.
 
-After calling these 'modprobe' commands, the result can be verified using ``lsmod`` and rechecking ``dmesg`` to see which ``/dev/ttyUSBxx`` ports were assigned.
+After calling these 'modprobe' commands, the result can be verified using ``lsmod`` and re-checking ``dmesg`` to see which ``/dev/ttyUSBxx`` ports were assigned.
 
 The ownerchip and permissions of these ``/dev/ttyUSBxx`` are probably set like this:
 
@@ -455,7 +515,7 @@ Writing documentation
 
 Updating, or adding if it does not yet exist, the documentation is a useful activity that should be part of changing or adding to the ESPEasy code. Some of the optional VSCode extensions are specifically aimed at that task.
 
-The documentation is created in the reStructuredText format, using mostly a ``.rst`` extension, and can be built locally by installing the sphinx tool. This can be installed manually by opening a Terminal window in VSCode (an already open Terminal can also be used) and issuing these commands:
+The documentation is created in the reStructuredText format, using mostly a ``.rst`` extension, and can be built locally by installing the sphinx tool. This can be installed manually by opening a PlatformIO Terminal window in VSCode (an already open PIO Terminal can also be used, when using WSL2 a PlatformIO Terminal is *required* to execute in the correct Python Virtual Environment (venv)) and issuing these commands:
 
 .. code-block::
 

docs/source/Plugin/P022_commands.repl

@@ -7,7 +7,7 @@
 
   ``[<taskname>].pwm,<pcagpio>,<value>[,<duration>]``
 
-  pcagpio: 0 ... 255
+  pcagpio: 0 ... 15
 
   value: 0 ... 4096
 
@@ -25,7 +25,7 @@
   "
   ``[<taskname>].gpio,<pcagpio>,<value>``
 
-  pcagpio: 0 ... 255/all
+  pcagpio: 0 ... 15/all
 
   value: 0/1
   ","
@@ -36,7 +36,7 @@
   "
   ``[<taskname>].pulse,<pcagpio>,<value>,<duration>[,<resettimeout>|auto]``
 
-  pcagpio: 0 ... 255
+  pcagpio: 0 ... 15
 
   value: 0/1