Improve documentation for upload via cable

[christian-heusel]

I wanted to upload the built binary to the esp via cable and modified the config something like this:

diff --git a/platformio.ini b/platformio.ini
index c644e94..830576d 100644
--- a/platformio.ini
+++ b/platformio.ini
@@ -25,7 +25,7 @@ extra_scripts =
 ; ----------------------------------------------------------------
 ; OPTION 1: direct cable upload
 ; ----------------------------------------------------------------
-;upload_port = /dev/cu.usbserial-0258166D
+upload_port = /dev/cu.usbserial-0258166D
 ;upload_port = /dev/cu.usbserial-0001

 ; ----------------------------------------------------------------
@@ -42,8 +42,8 @@ extra_scripts =
 ; ----------------------------------------------------------------

-upload_protocol = custom
-upload_url = http://192.168.178.40:8080/update   ; Conneted to Router
+; upload_protocol = custom
+; upload_url = http://192.168.178.40:8080/update   ; Conneted to Router

but then got the following error:

Using manually specified: /dev/cu.usbserial-0258166D
Uploading .pio/build/esp32/firmware.bin
*** [upload] InvalidProjectConfError : Invalid '/home/chris/Documents/shared_projects/ESP_Buderus_KM271/platformio.ini' (project configuration file): 'No option 'upload_url' in section: 'env:esp32''
Traceback (most recent call last):
  File "/usr/lib/python3.11/configparser.py", line 805, in get
    value = d[option]
            ~^^^^^^^^
  File "/usr/lib/python3.11/collections/__init__.py", line 1004, in __getitem__
    return self.__missing__(key)            # support subclasses that define __missing__
           ^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.11/collections/__init__.py", line 996, in __missing__
    raise KeyError(key)
KeyError: 'upload_url'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/usr/lib/python3.11/site-packages/platformio/project/config.py", line 348, in get
    value = self.getraw(section, option, default)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.11/site-packages/platformio/project/config.py", line 275, in getraw
    default if default != MISSING else self._parser.get(section, option)
                                       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.11/configparser.py", line 808, in get
    raise NoOptionError(option, section)
configparser.NoOptionError: No option 'upload_url' in section: 'env:esp32'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/home/chris/.platformio/packages/tool-scons/scons-local-4.5.2/SCons/Action.py", line 1310, in execute
    result = self.execfunction(target=target, source=rsources, env=env)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chris/Documents/shared_projects/ESP_Buderus_KM271/platformio_upload.py", line 29, in on_upload
    upload_url = env.GetProjectOption('upload_url')
                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chris/.platformio/packages/tool-scons/scons-local-4.5.2/SCons/Util/envs.py", line 242, in __call__
    return self.method(*nargs, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.11/site-packages/platformio/builder/tools/pioproject.py", line 28, in GetProjectOption
    return env.GetProjectConfig().get("env:" + env["PIOENV"], option, default)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.11/site-packages/platformio/project/config.py", line 350, in get
    raise exception.InvalidProjectConfError(self.path, str(exc))
platformio.project.exception.InvalidProjectConfError: Invalid '/home/chris/Documents/shared_projects/ESP_Buderus_KM271/platformio.ini' (project configuration file): 'No option 'upload_url' in section: 'env:esp32''

maybe extra_scripts = ... should also be moved to option3 or the script should become a nullop when upload_url is not specified?

[dewenni]

ok, thanks for that hint. I will check how to improve this. The first Skript is a general one that I habe implemented to automatically generate the .bin files for initial Flash and OTA Update. The second one is for the OTA Update via platformio IDE. But it is not allowed to habe multiple "extra_scripts" sections.

extra_scripts=
  platformio_release.py ; Skript to create binary files for Flash tools and OTA Update
  platformio_upload.py  ; Skript for OTA Update