From 9e4b4c1e675e8c1a249852a2687255b901a17468 Mon Sep 17 00:00:00 2001
From: Ivan Perez <ivan.perezdominguez@nasa.gov>
Date: Wed, 22 May 2024 07:37:20 +0000
Subject: [PATCH 1/2] ogma-cli: Document format of variable DB. Refs #143.

The README does not explain the structure that the variable DB files for
ROS should have. Because ogma doesn't give much information to users
when a variable cannot be found in the var DB, users do not know what to
put in each field in the variable DB, and what effect it will have in
the program.

This commit adds a subsection to the ROS section of the README
explaining the structure and format of the variable DB.
---
 ogma-cli/README.md | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/ogma-cli/README.md b/ogma-cli/README.md
index c7e7309..6d22e14 100644
--- a/ogma-cli/README.md
+++ b/ogma-cli/README.md
@@ -231,6 +231,34 @@ compile the image with:
 docker build .
 ```
 
+### Format of the Variables DB File
+
+The argument variable DB passed to the ROS backend should contain a list of
+variables, together with their types and the corresponding ROS topic in which
+those variables are passed. Each line in that file has the format:
+
+```
+("<NAME>","<TYPE>","<TOPIC_NAME>","<RESERVED_FOR_FUTURE_USE>")
+```
+
+For example, an input variable called "temperature" of type 64-bit signed
+integer coming in a ROS topic called "/battery/temperature" should have a
+matching entry in the variable DB file like the following:
+
+```
+("temperature","int64_t","/battery/temperature","ignore")
+```
+
+There should never be two lines in the same file with the same variable name.
+Variables in the DB that are not not used in any of the properties being
+monitored and/or are not listed in the variable file passed as argument to the
+ROS command will be ignored.
+
+For a more concrete example, see the files in `ogma-cli/examples/ros-copilot/`
+and the last step of the script
+`.github/workflows/repo-ghc-8.6-cabal-2.4-ros.yml`, which generates a ROS
+monitor with multiple variables and compiles the resulting code.
+
 ### Current limitations
 
 The user must place the code generated by Copilot monitors in two files,

From ab8e8ac7294a9c25237d08dd302690fd6f05e39d Mon Sep 17 00:00:00 2001
From: Ivan Perez <ivan.perezdominguez@nasa.gov>
Date: Wed, 22 May 2024 07:39:01 +0000
Subject: [PATCH 2/2] ogma-cli: Document changes in CHANGELOG. Refs #143.

---
 ogma-cli/CHANGELOG.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/ogma-cli/CHANGELOG.md b/ogma-cli/CHANGELOG.md
index 9f59a42..5a49fc9 100644
--- a/ogma-cli/CHANGELOG.md
+++ b/ogma-cli/CHANGELOG.md
@@ -5,6 +5,7 @@
 * Introduce CI test job (#139).
 * Introduce test job for ROS package generation (#136).
 * Add a float and a double input variable to ROS example (#138).
+* Document format of variable DB (#143).
 
 ## [1.3.0] - 2024-03-21