added comments

platformio.ini

@@ -287,6 +287,7 @@ build_flags =
   -DEMSESP_DEFAULT_LOCALE=\"en\" -DEMSESP_DEFAULT_TX_MODE=8 -DEMSESP_DEFAULT_VERSION=\"3.8.0-dev.0\" -DEMSESP_DEFAULT_BOARD_PROFILE=\"S32\"
 
 ; Modbus
+;  Creates the file modbus_entity_parameters.hpp
 ;  Creating the modbus registers is a multi-step process. Before it was in a shell script called generate_csv_and_headers.sh
 ;  but now moved to pio so everything is in python and cross-platform. The logic is as follows:
 ;  1. create a dummy modbus_entity_parameters.hpp file so the first pass compiles
@@ -295,15 +296,9 @@ build_flags =
 ;  4. use the dump_entities.csv file with update_modbus_registers.py script to generate the modbus_entity_parameters.hpp file
 ;  5. clean up everything and start again with the EMSESP_STANDALONE flag set
 ;  6. run the entity_dump test command again to create the real dump_entities.csv file
-;  7. create the Modbus-Entity-Registers.md file
-;  8. create the dump_telegrams.csv file
 ;
-;  To run this in pio use the steps
+;  To use, run:
 ;   pio run -e build_modbus -t clean -t build
-;   pio run -e build_standalone -t clean -t build
-
-# builds the modbus_entity_parameters.hpp header file
-# pio run -e build_modbus -t clean -t build
 [env:build_modbus]
 extends = env:native
 targets = build
@@ -315,8 +310,11 @@ custom_test_command = entity_dump
 custom_output_file = dump_entities.csv
 custom_post_script = scripts/build_modbus_entity_parameters_post.py
 
-; builds the real dump_entities.csv and dump_telegrams.csv files, and also the Modbus-Entity-Registers.md file
+; builds the real dump_entities.csv and dump_telegrams.csv files
-; to be run after build_modbus with: pio run -e build_standalone -t clean -t build
+; and also the Modbus-Entity-Registers.md file which is used in the emsesp.org documentation
+;
+; To use, run after build_modbus environment, with:
+; pio run -e build_standalone -t clean -t build
 [env:build_standalone]
 extends = env:native
 targets = build
@@ -326,4 +324,3 @@ build_flags = -DEMSESP_STANDALONE
 custom_test_command = entity_dump
 custom_output_file = dump_entities.csv
 custom_post_script = scripts/build_standalone_post.py
-

scripts/build_modbus_entity_parameters_post.py

@@ -4,6 +4,9 @@ import sys
 import shutil
 from pathlib import Path
 
+# This script is used to update the modbus_entity_parameters.hpp file with the data from the dump_entities.csv file.
+# It is used in the build_modbus target.
+
 def get_python_executable():
     """Get the appropriate Python executable for the current platform."""
     # Try different Python executable names

scripts/build_modbus_entity_parameters_pre.py

@@ -2,6 +2,9 @@ from pathlib import Path
 import os
 Import("env")
 
+# This script is used to create a dummy modbus_entity_parameters.hpp so the first pass compiles.
+# It is used in the build_modbus target.
+
 def create_dummy_modbus_header():
     """Create a dummy modbus_entity_parameters.hpp so the first pass compiles."""
     header_content = '''#include "modbus.h"

scripts/build_run_test.py

@@ -4,6 +4,12 @@ import subprocess
 import sys
 Import("env")
 
+# This script is used to build the program and run the test command.
+# It is used in the build_modbus and build_standalone targets.  
+# Reads configuration from platformio.ini (output file path and test command)
+# Runs the executable with streaming input, sending it the test command and capturing output to a file
+# Optionally runs a post-processing script if defined in the configuration
+
 # Import the streaming function from the separate module
 from run_executable import run_with_streaming_input
 

scripts/build_standalone_post.py

@@ -9,7 +9,8 @@ from pathlib import Path
 # - Modbus-Entity-Registers.md
 # - dump_telegrams.csv
 
-# Import the streaming function from the separate module
+# Modbus-Entity-Registers.md is used in the emsesp.org documentation. You can also create it manually with the generate-modbus-register-doc.py script.
+# cat ./docs/dump_entities.csv | python3 ./scripts/generate-modbus-register-doc.py    # Import the streaming function from the separate module
 from run_executable import run_with_streaming_input