Merge branch 'release-1.5.0'. Refs #178.

nasa · Nov 22, 2024 · 2dfcf4a · 2dfcf4a
2 parents 08bbdb9 + 53df563
commit 2dfcf4a
Show file tree

Hide file tree

Showing 47 changed files with 874 additions and 1,017 deletions.
diff --git a/docs/fret.png b/docs/fret.png
diff --git a/docs/xplane.png b/docs/xplane.png
diff --git a/ogma-cli/CHANGELOG.md b/ogma-cli/CHANGELOG.md
@@ -1,5 +1,15 @@
 # Revision history for ogma-cli
 
+## [1.5.0] - 2024-11-21
+
+* Version bump 1.5.0 (#178).
+* Provide ability to customize template in cfs command (#157).
+* Provide ability to customize template in ros command (#162).
+* Introduce new standalone command (#170).
+* Update README to demonstrate robotics (#172).
+* Remove unused resources (#174).
+* Add version bounds to base (#180).
+
 ## [1.4.1] - 2024-09-21
 
 * Version bump 1.4.1 (#155).

diff --git a/ogma-cli/README.md b/ogma-cli/README.md
@@ -27,6 +27,12 @@ verification framework that generates hard real-time C99 code.
   <i>Integration of monitors into larger applications (e.g., simulators).</i>
 </p>
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/nasa/ogma/gh-pages/images/ros.gif" alt="Monitoring within ROS simulation video">
+  <br />
+  <i>Integration of monitors into robotics applications.</i>
+</p>
+
 ## Table of Contents
 
 - [Installation](#installation)
@@ -115,9 +121,10 @@ flags to customize the list of known variables, so that projects can maintain
 their own variable databases beyond what Ogma includes by default.
 
 cFS applications are generated using the Ogma command `cfs`, which receives
-three main arguments:
+four main arguments:
 - `--app-target-dir DIR`: location where the cFS application files must be
   stored.
+- `--app-template-dir DIR`: location of the cFS application template to use.
 - `--variable-file FILENAME`: a file containing a list of variables that must
 be made available to the monitor.
 - `--variable-db FILENAME`: a file containing a database of known variables,
@@ -187,6 +194,45 @@ void COPILOT_ProcessIcarousPosition(void)
 }
 ```
 
+### Template Customization
+
+By default, Ogma uses a pre-defined template to generate the cFS monitoring
+application. It's possible to customize the output by providing a directory
+with a set of files with a cFS application template, which Ogma will use
+instead.
+
+To choose this feature, one must call Ogma's `cfs` command with the argument
+`--app-template-dir DIR`, where `DIR` is the path to a directory containing a
+cFS application template. For example, assuming that the directory
+`my_template` contains a custom cFS application template, one can execute:
+
+```
+$ ogma cfs --app-template-dir my_template/ --variable-db examples/cfs-variable-db --variable-file examples/cfs-variables
+```
+
+Ogma will copy the files in that directory to the target path, filling in
+several holes with specific information:
+
+- `{{variablesS}}`: this will be replaced by a list of variable declarations,
+  one for each global variable that holds information read from the cFS
+software bus that must be made accessible to the monitoring code.
+
+- `{{msgSubscriptionsS}}`: this will be replaced by a list of calls to
+  `CFE_SB_Subscribe`, subscribing to the necessary information coming in the
+software bus.
+
+- `{{msgCasesS}}`: this will be replaced by a switch case statements that match
+  the ID of an incoming message, to handle information being received that must
+be updated and would trigger a re-evaluation of the monitors.
+
+- `{{msgHandlerS}}`: this will be replaced by function definitions of the
+  functions that will be called to actually update the variables with
+information coming from the software bus, and re-evaluate the monitors.
+
+We understand that this level of customization may be insufficient for your
+application. If that is the case, feel free to reach out to our team to discuss
+how we could make the template expansion system more versatile.
+
 ## ROS Application Generation
 
 The Robot Operating System (ROS) is a framework to build robot applications.
@@ -196,9 +242,10 @@ the data needed by the monitors and report any violations. At present, support
 for ROS app generation is considered preliminary.
 
 ROS applications are generated using the Ogma command `ros`, which receives
-four main arguments:
+five main arguments:
 - `--app-target-dir DIR`: location where the ROS application files must be
   stored.
+- `--app-template-dir DIR`: location of the ROS application template to use.
 - `--variable-file FILENAME`: a file containing a list of variables that must
 be made available to the monitor.
 - `--variable-db FILENAME`: a file containing a database of known variables,
@@ -259,6 +306,74 @@ 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.
 
+### Template Customization
+
+By default, Ogma uses a pre-defined template to generate the ROS monitoring
+package. It's possible to customize the output by providing a directory with a
+set of files with a ROS package template, which Ogma will use instead.
+
+To choose this feature, one must call Ogma's `ros` command with the argument
+`--app-template-dir DIR`, where `DIR` is the path to a directory containing a
+ROS 2 package template. For example, assuming that the directory `my_template`
+contains a custom ROS package template, one can execute:
+
+```
+$ ogma ros --app-template-dir my_template/ --handlers filename --variable-file variables --variable-db ros-variable-db --app-target-dir ros_demo
+```
+
+Ogma will copy the files in that directory to the target path, filling in
+several holes with specific information. For the monitoring node, the variables
+are:
+
+- `{{variablesS}}`: this will be replaced by a list of variable declarations,
+  one for each global variable that holds information read from the ROS
+software bus that must be made accessible to the monitoring code.
+
+- `{{msgSubscriptionsS}}`: this will be replaced by a list of calls to
+  `create_subscription`, subscribing to the necessary information coming in the
+software bus.
+
+- `{{msgPublisherS}}`: this will be replaced by a list of calls to
+  `create_publisher`, to create topics to report property violations on the
+software bus.
+
+- `{{msgHandlerInClassS}}`: this will be replaced by the functions that will be
+  called to report a property violation via one of the property violation
+topics (publishers).
+
+- `{{msgCallbacks}}`: this will be replaced by function definitions of the
+  functions that will be called to actually update the variables with
+information coming from the software bus, and re-evaluate the monitors.
+
+- `{{msgSubscriptionDeclrs}}`: this will be replaced by declarations of
+  subscriptions used in `{{msgSubscriptionsS}}`.
+
+- `{{msgPublisherDeclrs}}`: this will be replaced by declarations of publishers
+  used in `{{msgPublishersS}}`.
+
+- `{{msgHandlerGlobalS}}`: this will be replaced by top-level functions that
+  call the handlers from the single monitoring class instance (singleton).
+
+Ogma will also generate a logging node that can be used for debugging purposes,
+to print property violations to a log. This second node listens to the messages
+published by the monitoring node in the software bus. For that node, the
+variables used are:
+
+- `{{logMsgSubscriptionsS}}`: this will be replaced by a list of calls to
+  `create_subscription`, subscribing to the necessary information coming in the
+software bus.
+
+- `{{logMsgCallbacks}}`: this will be replaced by function definitions of the
+  functions called to report the violations in the log. These functions are
+used as handlers to incoming messages in the subscriptions.
+
+- `{{logMsgSubscriptionDeclrs}}`: this will be replaced by declarations of
+  subscriptions used in `{{logMsgSubscriptionsS}}`.
+
+We understand that this level of customization may be insufficient for your
+application. If that is the case, feel free to reach out to our team to discuss
+how we could make the template expansion system more versatile.
+
 ### Current limitations
 
 The user must place the code generated by Copilot monitors in two files,

diff --git a/ogma-cli/ogma-cli.cabal b/ogma-cli/ogma-cli.cabal
@@ -32,7 +32,7 @@ cabal-version:       2.0
 build-type:          Simple
 
 name:                ogma-cli
-version:             1.4.1
+version:             1.5.0
 homepage:            https://github.com/nasa/ogma
 license:             OtherLicense
 license-file:        LICENSE.pdf
@@ -50,9 +50,8 @@ description:         Ogma is a tool to facilitate the integration of safe runtim
                      .
                      Some use cases supported by Ogma include:
                      .
-                     - Translating requirements defined in
-                       <https://github.com/NASA-SW-VnV/fret NASA requirements elicitation tool FRET>
-                       into corresponding monitors in Copilot.
+                     - Translating requirements defined in structured natural
+                       language into monitors in Copilot.
                      .
                      - Generating the glue code necessary to work with C
                        structs in Copilot.
@@ -91,20 +90,15 @@ description:         Ogma is a tool to facilitate the integration of safe runtim
                      >  handlers                 Generate message handlers from C structs
                      >  cfs                      Generate a complete CFS/Copilot application
                      >  fprime                   Generate a complete F' monitoring component
-                     >  fret-component-spec      Generate a Copilot file from a FRET Component
-                     >                           Specification
-                     >  fret-reqs-db             Generate a Copilot file from a FRET Requirements
-                     >                           Database
                      >  ros                      Generate a ROS 2 monitoring application
+                     >  standalone               Generate a Copilot file from an input specification
                      .
                      For further information, see:
                      .
                      - <https://github.com/nasa/ogma The Ogma repository>.
                      .
                      - <https://copilot-language.github.io/ The Copilot web page>.
                      .
-                     - <https://github.com/NASA-SW-VnV/fret The FRET repository>.
-                     .
                      - <https://cfs.gsfc.nasa.gov/ The NASA Core Flight System web page>.
                      .
                      - <https://ros.org/ The Robot Operating System (ROS 2) web page>.
@@ -132,16 +126,15 @@ executable ogma
     CLI.CommandCStructs2Copilot
     CLI.CommandCStructs2MsgHandlers
     CLI.CommandFPrimeApp
-    CLI.CommandFretComponentSpec2Copilot
-    CLI.CommandFretReqsDB2Copilot
     CLI.CommandROSApp
+    CLI.CommandStandalone
     CLI.CommandTop
     CLI.Result
 
   build-depends:
       base                 >= 4.11.0.0 && < 5
     , optparse-applicative
-    , ogma-core            >= 1.4.1 && < 1.5
+    , ogma-core            >= 1.5.0 && < 1.6
 
   hs-source-dirs:
     src
@@ -160,7 +153,7 @@ test-suite test-ogma
     Main.hs
 
   build-depends:
-      base
+      base                 >= 4.11.0.0 && < 5
     , HUnit
     , process
     , test-framework

diff --git a/ogma-cli/src/CLI/CommandCFSApp.hs b/ogma-cli/src/CLI/CommandCFSApp.hs
@@ -56,9 +56,10 @@ import Command.CFSApp ( ErrorCode, cFSApp )
 
 -- | Options needed to generate the cFS application.
 data CommandOpts = CommandOpts
-  { cFSAppTarget   :: String
-  , cFSAppVarNames :: String
-  , cFSAppVarDB    :: Maybe String
+  { cFSAppTarget      :: String
+  , cFSAppTemplateDir :: Maybe String
+  , cFSAppVarNames    :: String
+  , cFSAppVarDB       :: Maybe String
   }
 
 -- | Create <https://cfs.gsfc.nasa.gov/ NASA core Flight System> (cFS)
@@ -68,7 +69,11 @@ data CommandOpts = CommandOpts
 -- This is just an uncurried version of "Command.CFSApp".
 command :: CommandOpts -> IO (Result ErrorCode)
 command c =
-  cFSApp (cFSAppTarget c) (cFSAppVarNames c) (cFSAppVarDB c)
+  cFSApp
+    (cFSAppTarget c)
+    (cFSAppTemplateDir c)
+    (cFSAppVarNames c)
+    (cFSAppVarDB c)
 
 -- * CLI
 
@@ -87,6 +92,13 @@ commandOptsParser = CommandOpts
         <> value "copilot-cfs-demo"
         <> help strCFSAppDirArgDesc
         )
+  <*> optional
+        ( strOption
+            (  long "app-template-dir"
+            <> metavar "DIR"
+            <> help strCFSAppTemplateDirArgDesc
+            )
+        )
   <*> strOption
         (  long "variable-file"
         <> metavar "FILENAME"
@@ -106,6 +118,11 @@ commandOptsParser = CommandOpts
 strCFSAppDirArgDesc :: String
 strCFSAppDirArgDesc = "Target directory"
 
+-- | Argument template directory to cFS app generation command
+strCFSAppTemplateDirArgDesc :: String
+strCFSAppTemplateDirArgDesc =
+  "Directory holding cFS application source template"
+
 -- | Argument variable list to cFS app generation command
 strCFSAppVarListArgDesc :: String
 strCFSAppVarListArgDesc =