ogma-cli: Document format of variable DB. Refs #143.

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
 

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,