feat: add configurable params dir for SITL, improve logging and make generators write-if-changed

PonomarevDA · PonomarevDA · commit 9c95a8654fe8 · 2026-01-30T08:49:40.000+03:00
diff --git a/include/libparams/storage.h b/include/libparams/storage.h
@@ -108,6 +108,18 @@ int8_t paramsSave();
  */
 int8_t paramsResetToDefault();
 
+/**
+ * @brief           Set directory for params files (SITL).
+ * @return          LIBPARAMS_OK on success, otherwise < 0.
+ */
+int8_t paramsSetDir(const char* dir);
+
+/**
+ * @brief           Get directory for params files (SITL).
+ * @return          C-string on success, otherwise empty string.
+ */
+const char* paramsGetDir();
+
 /**
  * @note            Get the parameter name
  * @return          C-string on success, otherwise NULL.
diff --git a/platform_specific/ubuntu/SimpleLogger.hpp b/platform_specific/ubuntu/SimpleLogger.hpp
@@ -19,14 +19,14 @@ class SimpleLogger {
     void info(Args... args) {
         std::stringstream ss;
         (ss << ... << args);
-        std::cout << module << ": " << ss.str() << std::endl;
+        std::cout << "[" << module << "] [INFO]: " << ss.str() << std::endl;
     }
 
     template <typename... Args>
     void error(Args... args) {
         std::stringstream ss;
         (ss << ... << args);
-        std::cerr << module << ": " << ss.str() << std::endl;
+        std::cerr << "[" << module << "]: [ERROR]: " << ss.str() << std::endl;
     }
 
 private:
diff --git a/platform_specific/ubuntu/YamlParameters.cpp b/platform_specific/ubuntu/YamlParameters.cpp
@@ -54,42 +54,52 @@ int8_t YamlParameters::set_temp_file_name(std::string file_name) {
     return LIBPARAMS_OK;
 }
 
-int8_t YamlParameters::read_from_dir(const std::string& path) {
-    if (path.empty()) {
-        return LIBPARAMS_WRONG_ARGS;
+
+int8_t YamlParameters::read_from_dir(const std::string& path_str) {
+    namespace fs = std::filesystem;
+    if (!path_str.empty()) {
+        logger.info("Initializing with ", "LIBPARAMS_PARAMS_DIR=", fs::absolute(fs::path(path_str)).lexically_normal());
     }
+
+    if (path_str.empty()) return LIBPARAMS_WRONG_ARGS;
+
+    // Make the base directory absolute (no filesystem access needed)
+    fs::path base = fs::absolute(fs::path(path_str)).lexically_normal();
+
     int8_t res;
-    char file_name[256];
     uint16_t int_param_idx = 0;
     uint16_t str_param_idx = 0;
-    // read params values for each page
+
     for (uint16_t idx = 0; idx < flash.num_pages; idx++) {
         std::ifstream params_storage_file;
 
-        // check if temp file for the page already exists, else read from init file
-        snprintf(file_name, sizeof(file_name), "%s/%s_%d.yaml",
-                 path.c_str(), temp_file_name.c_str(), idx);
-        params_storage_file.open(file_name, std::ios_base::in);
+        fs::path temp = base / (temp_file_name + "_" + std::to_string(idx) + ".yaml");
+        params_storage_file.open(temp, std::ios_base::in);
+
         if (!params_storage_file) {
-            logger.info(file_name, " could not be opened for reading!");
-            snprintf(file_name, sizeof(file_name), "%s/%s_%d.yaml",
-                     path.c_str(), init_file_name.c_str(), idx);
-            params_storage_file.open(file_name, std::ios_base::in);
+            logger.info(temp.string(), " could not be opened for reading!");
+
+            fs::path init = base / (init_file_name + "_" + std::to_string(idx) + ".yaml");
+            params_storage_file.open(init, std::ios_base::in);
+
             if (!params_storage_file) {
-                logger.error(file_name, " could not be opened for reading!");
+                logger.error(init.string(), " could not be opened for reading!");
                 return LIBPARAMS_WRONG_ARGS;
             }
+
+            logger.info("Reading params from the init file ", init.string(), ":");
+        } else {
+            logger.info("Reading params from the temp file ", temp.string(), ":");
         }
-        logger.info("data read from ", file_name);
 
         if ((int_param_idx > params.num_int_params) || (str_param_idx > params.num_str_params)) {
             break;
         }
+
         res = __read_page(params_storage_file, &int_param_idx, &str_param_idx);
         params_storage_file.close();
-        if (res != LIBPARAMS_OK) {
-            return res;
-        }
+
+        if (res != LIBPARAMS_OK) return res;
     }
 
     if (int_param_idx != params.num_int_params || str_param_idx != params.num_str_params) {
diff --git a/platform_specific/ubuntu/YamlParameters.hpp b/platform_specific/ubuntu/YamlParameters.hpp
@@ -13,7 +13,7 @@
 #include "SimpleLogger.hpp"
 #include "FlashMemoryLayout.hpp"
 
-static SimpleLogger logger("YamlParameters");
+static SimpleLogger logger("libparams-ubuntu");
 class YamlParameters {
     ParametersLayout_t params;
     std::string init_file_name = "init_params";
diff --git a/platform_specific/ubuntu/flash_driver.cpp b/platform_specific/ubuntu/flash_driver.cpp
@@ -109,9 +109,17 @@ uint16_t flashGetPageSize() {
 }
 
 int32_t __save_to_files() {
-    return yaml_params.write_to_dir(LIBPARAMS_PARAMS_DIR);
+    const char* dir = paramsGetDir();
+    if (dir == nullptr || dir[0] == '\0') {
+        return LIBPARAMS_WRONG_ARGS;
+    }
+    return yaml_params.write_to_dir(dir);
 }
 
 int8_t __read_from_files() {
-    return yaml_params.read_from_dir(LIBPARAMS_PARAMS_DIR);
+    const char* dir = paramsGetDir();
+    if (dir == nullptr || dir[0] == '\0') {
+        return LIBPARAMS_WRONG_ARGS;
+    }
+    return yaml_params.read_from_dir(dir);
 }
diff --git a/scripts/generate_docs.py b/scripts/generate_docs.py
@@ -18,6 +18,8 @@
 
 from params import IntegerParam, StringParam
 
+LOG_PREFIX = "[libparams-doc]"
+
 logger = logging.getLogger(__name__)
 
 LANGUAGE_C = 0
@@ -82,6 +84,18 @@ def write_parameters(file, all_params : list) -> None:
     else:
         file.write("The node doesn't have registers:\n\n")
 
+def _write_if_changed(path, content: str) -> str:
+    if os.path.exists(path):
+        with open(path, 'r', encoding="utf-8") as existing_file:
+            if existing_file.read() == content:
+                return "unchanged"
+        status = "updated"
+    else:
+        status = "added"
+    with open(path, 'w', encoding="utf-8") as out_file:
+        out_file.write(content)
+    return status
+
 def generate_markdown_doc(cyphal_pubs : dict,
                           cyphal_subs : dict,
                           all_params : list,
@@ -91,21 +105,53 @@ def generate_markdown_doc(cyphal_pubs : dict,
     assert isinstance(all_params, list)
     assert isinstance(output_markdown_filename, str)
 
-    with open(output_markdown_filename, 'w', encoding="utf-8") as file:
-        if len(cyphal_pubs) + len(cyphal_subs) >= 1:
-            file.write("The node has the following interface:\n\n")
+    content = ""
+    if len(cyphal_pubs) + len(cyphal_subs) >= 1:
+        content += "The node has the following interface:\n\n"
+
+    if len(cyphal_pubs) >= 1:
+        content += "Cyphal Publishers:\n"
+        content += _render_cyphal_topics(cyphal_pubs)
+
+    if len(cyphal_subs) >= 1:
+        content += "Cyphal Subscribers:\n"
+        content += _render_cyphal_topics(cyphal_subs)
 
-        if len(cyphal_pubs) >= 1:
-            file.write("Cyphal Publishers:\n")
-            write_cyphal_topics(file, cyphal_pubs)
+    content += _render_parameters(all_params)
 
-        if len(cyphal_subs) >= 1:
-            file.write("Cyphal Subscribers:\n")
-            write_cyphal_topics(file, cyphal_subs)
+    content += "> This docs was automatically generated. Do not edit it manually.\n\n"
+    return _write_if_changed(output_markdown_filename, content)
 
-        write_parameters(file, all_params)
+def _render_cyphal_topics(cyphal_topics: dict) -> str:
+    assert isinstance(cyphal_topics, dict)
 
-        file.write("> This docs was automatically generated. Do not edit it manually.\n\n")
+    content = "| Data type and topic name  | Description |\n"
+    content += "| ------------------------- | ----------- |\n"
+    for port_name, port_info in cyphal_topics.items():
+        data_type = port_data_type_to_md(port_info['data_type'])
+        topic_name = port_name[11:]
+        note = port_info.get('note')
+        note = note.replace('\n', '</br>') if note is not None else ""
+        content += f"| {data_type} </br> {topic_name} | {note}|\n"
+    content += "\n"
+    return content
+
+def _render_parameters(all_params : list) -> str:
+    assert isinstance(all_params, list)
+
+    content = ""
+    if len(all_params) >= 1:
+        content += "The node has the following registers:\n\n"
+        content += "| Register name           | Description |\n"
+        content += "| ----------------------- | ----------- |\n"
+
+        for param in all_params:
+            param.name = param.name.replace('"', '')
+            content += f"| {param.name.ljust(23)} | {param.note} |\n"
+        content += "\n"
+    else:
+        content += "The node doesn't have registers:\n\n"
+    return content
 
 def parse_yaml_files(input_yaml_files : list) -> Tuple[dict, dict, list]:
     assert isinstance(input_yaml_files, list) and len(input_yaml_files) != 0
@@ -147,16 +193,17 @@ def parse_yaml_files_and_generate_doc(input_yaml_files : list, output_markdown_p
         os.makedirs(directory)
 
     cyphal_pubs, cyphal_subs, all_params = parse_yaml_files(input_yaml_files)
-    generate_markdown_doc(cyphal_pubs, cyphal_subs, all_params, output_markdown_path)
+    return generate_markdown_doc(cyphal_pubs, cyphal_subs, all_params, output_markdown_path)
 
 if __name__=="__main__":
-    logging.basicConfig(level=logging.INFO)
+    logging.basicConfig(level=logging.INFO, format=f"{LOG_PREFIX} [%(levelname)s] %(message)s")
     logger.setLevel(logging.INFO)
 
     parser = ArgumentParser(description=__doc__)
     parser.add_argument('files', nargs='+', help='YAML files to process')
     parser.add_argument("--output", type=str, required=False, default='README.md')
     args = parser.parse_args()
 
-    print("Params docs generator:")
-    parse_yaml_files_and_generate_doc(args.files, args.output)
+    logger.info("Generating docs: output=%s, files=%d", args.output, len(args.files))
+    status = parse_yaml_files_and_generate_doc(args.files, args.output)
+    logger.info("Docs %s", status)
diff --git a/scripts/generate_params.py b/scripts/generate_params.py
@@ -8,6 +8,7 @@
 
 """Parameters generator."""
 
+import logging
 import os
 import sys
 from color_logging import log_err
@@ -56,45 +57,65 @@ def add_string(self, param : StringParam):
     def generate(self):
         if not os.path.exists(self.dir):
             os.makedirs(self.dir)
-        with open(f"{self.dir}/{self.name}.cpp", 'w', encoding="utf-8") as cpp_file:
-            cpp_content = (
-                f"{LICENSE_HEADER}\n"
-                "#include \"params.hpp\"\n"
-                "\n"
-                "IntegerDesc_t integer_desc_pool[] = {\n"
-                f"{self.integers_array}"
-                "};\n"
-                "IntegerParamValue_t "
-                "integer_values_pool[sizeof(integer_desc_pool) / sizeof(IntegerDesc_t)];\n"
-                "\n"
-                "StringDesc_t string_desc_pool[NUM_OF_STR_PARAMS] = {\n"
-                f"{self.strings_array}"
-                "};\n"
-                "StringParamValue_t "
-                "string_values_pool[sizeof(string_desc_pool) / sizeof(StringDesc_t)];\n"
-            )
-            cpp_file.write(cpp_content)
-
-        with open(f"{self.dir}/{self.name}.hpp", 'w', encoding="utf-8") as hpp_file:
-            hpp_content = (
-                f"{LICENSE_HEADER}\n"
-                "#pragma once\n"
-                "#include \"storage.h\"\n\n"
-                "enum IntParamsIndexes {\n"
-                f"{self.integers_enums}\n"
-                "    INTEGER_PARAMS_AMOUNT\n"
+        cpp_content = (
+            f"{LICENSE_HEADER}\n"
+            "#include \"params.hpp\"\n"
+            "\n"
+            "IntegerDesc_t integer_desc_pool[] = {\n"
+            f"{self.integers_array}"
+            "};\n"
+            "IntegerParamValue_t "
+            "integer_values_pool[sizeof(integer_desc_pool) / sizeof(IntegerDesc_t)];\n"
+            "\n"
+            "StringDesc_t string_desc_pool[NUM_OF_STR_PARAMS] = {\n"
+            f"{self.strings_array}"
+            "};\n"
+            "StringParamValue_t "
+            "string_values_pool[sizeof(string_desc_pool) / sizeof(StringDesc_t)];\n"
+        )
+        cpp_status = _write_if_changed(f"{self.dir}/{self.name}.cpp", cpp_content)
+
+        hpp_content = (
+            f"{LICENSE_HEADER}\n"
+            "#pragma once\n"
+            "#include \"storage.h\"\n\n"
+            "enum IntParamsIndexes {\n"
+            f"{self.integers_enums}\n"
+            "    INTEGER_PARAMS_AMOUNT\n"
+            "};\n"
+        )
+        if self.strings_amount > 0:
+            hpp_content += (
+                "enum StrParamsIndexes {\n"
+                f"{self.strings_enums}\n"
                 "};\n"
-
             )
-            if self.strings_amount > 0:
-                hpp_content += (
-                    "enum StrParamsIndexes {\n"
-                    f"{self.strings_enums}\n"
-                    "};\n"
-                )
 
-            hpp_content += f"#define NUM_OF_STR_PARAMS {self.strings_amount}\n"
-            hpp_file.write(hpp_content)
+        hpp_content += f"#define NUM_OF_STR_PARAMS {self.strings_amount}\n"
+        hpp_status = _write_if_changed(f"{self.dir}/{self.name}.hpp", hpp_content)
+        return cpp_status, hpp_status
+
+def _write_if_changed(path, content):
+    if os.path.exists(path):
+        with open(path, 'r', encoding="utf-8") as existing_file:
+            if existing_file.read() == content:
+                return "unchanged"
+        status = "updated"
+    else:
+        status = "added"
+    with open(path, 'w', encoding="utf-8") as out_file:
+        out_file.write(content)
+    return status
+
+def _setup_logger():
+    logger = logging.getLogger("libparams-gen")
+    if not logger.handlers:
+        handler = logging.StreamHandler()
+        formatter = logging.Formatter("[libparams-gen] [%(levelname)s] %(message)s")
+        handler.setFormatter(formatter)
+        logger.addHandler(handler)
+    logger.setLevel(logging.INFO)
+    return logger
 
 if __name__=="__main__":
     from argparse import ArgumentParser
@@ -105,11 +126,13 @@ def generate(self):
     parser.add_argument('-f','--files',     type=str, required=True,    help='', nargs='+')
     args = parser.parse_args()
 
-    print("Parameters generator:")
-    print("1. out_dir:", args.out_dir)
-    print("2. language:", args.language)
-    print("3. out-file-name:", args.out_file_name)
-    print("4. files:", args.files)
+    logger = _setup_logger()
+    logger.info(
+        "Generating params: out_dir=%s, out_file=%s, files=%d",
+        args.out_dir,
+        args.out_file_name,
+        len(args.files),
+    )
 
     # Check args for basic errors
     for yaml_file_path in args.files:
@@ -140,4 +163,5 @@ def generate(self):
                     log_err(f"Unknown type: {param_name}.type={data['type']}!")
                     sys.exit(1)
 
-    gen.generate()
+    cpp_status, hpp_status = gen.generate()
+    logger.info("params.cpp %s / params.hpp %s", cpp_status, hpp_status)
diff --git a/src/storage.c b/src/storage.c

Original file line number	Diff line number	Diff line change
`@@ -109,9 +109,17 @@ uint16_t flashGetPageSize() {`
`109`	`109`	`}`
`110`	`110`
`111`	`111`	`int32_t __save_to_files() {`
`112`		`- return yaml_params.write_to_dir(LIBPARAMS_PARAMS_DIR);`
	`112`	`+ const char* dir = paramsGetDir();`
	`113`	`+ if (dir == nullptr \|\| dir[0] == '\0') {`
	`114`	`+ return LIBPARAMS_WRONG_ARGS;`
	`115`	`+ }`
	`116`	`+ return yaml_params.write_to_dir(dir);`
`113`	`117`	`}`
`114`	`118`
`115`	`119`	`int8_t __read_from_files() {`
`116`		`- return yaml_params.read_from_dir(LIBPARAMS_PARAMS_DIR);`
	`120`	`+ const char* dir = paramsGetDir();`
	`121`	`+ if (dir == nullptr \|\| dir[0] == '\0') {`
	`122`	`+ return LIBPARAMS_WRONG_ARGS;`
	`123`	`+ }`
	`124`	`+ return yaml_params.read_from_dir(dir);`
`117`	`125`	`}`