Add new command definition tree

docs/api.rst

@@ -44,17 +44,6 @@ Module
 .. automodule:: tmtccmd
    :noindex:
 
-Configuration Package 
---------------------------
-
-.. automodule:: tmtccmd.config
-   :noindex:
-
-.. toctree::
-   :maxdepth: 3
-
-   api/config
-
 Core Package 
 -----------------
 
@@ -86,6 +75,17 @@ Telecommand Handling Package
 
    api/tc
 
+Application Configuration Package 
+===================================
+
+.. automodule:: tmtccmd.config
+   :noindex:
+
+.. toctree::
+   :maxdepth: 3
+
+   api/config
+
 Miscellaneous Modules 
 =========================
 

docs/api/config.rst

@@ -1,69 +1,76 @@
 Configuration Package
 ======================
 
-Module contents
----------------
+Module
+----------
 
 .. automodule:: tmtccmd.config
    :members:
    :undoc-members:
    :show-inheritance:
 
-Submodules
-----------
-
-tmtccmd.config.defs module
---------------------------
+Configuration Hook Submodule
+-----------------------------
 
-.. automodule:: tmtccmd.config.defs
+.. automodule:: tmtccmd.config.hook
    :members:
    :undoc-members:
    :show-inheritance:
 
-tmtccmd.config.args module
---------------------------
+Argument Parsing Submodule
+-----------------------------
 
 .. automodule:: tmtccmd.config.args
    :members:
    :undoc-members:
    :show-inheritance:
 
-tmtccmd.config.cfdp module
---------------------------
+TMTC Configuration Submodule
+-----------------------------
 
-.. automodule:: tmtccmd.config.cfdp
+.. automodule:: tmtccmd.config.tmtc
    :members:
    :undoc-members:
    :show-inheritance:
 
-tmtccmd.config.hook module
+CFDP Configuration Submodule
 -----------------------------
 
-.. automodule:: tmtccmd.config.hook
+.. automodule:: tmtccmd.config.cfdp
    :members:
    :undoc-members:
    :show-inheritance:
 
-tmtccmd.config.com module
------------------------------
+Communication Configuration Submodule
+---------------------------------------
 
 .. automodule:: tmtccmd.config.com
    :members:
    :undoc-members:
    :show-inheritance:
 
-tmtccmd.config.globals module
------------------------------
+Configuration Definitions Submodule
+------------------------------------
 
-.. automodule:: tmtccmd.config.globals
+.. automodule:: tmtccmd.config.defs
    :members:
    :undoc-members:
    :show-inheritance:
 
-tmtccmd.config.objects module
+Objects Submodule
 -----------------------------
 
 .. automodule:: tmtccmd.config.objects
    :members:
    :undoc-members:
    :show-inheritance:
+
+Global Module [deprecated]
+-----------------------------
+
+This module is deprecated, and usage is discouraged.
+
+.. automodule:: tmtccmd.config.globals
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/gettingstarted.rst

@@ -7,24 +7,119 @@ Example Project
 
 The `example application <https://github.com/robamu-org/tmtccmd/tree/main/examples/app>`_ is the
 best way to learn how this framework works and to get started. It shows how to set up handler
-classes for TC and TM handling and then ties together all components.
+classes for TC and TM handling and then ties together all components. You can also run this
+application in GUI mode by passing the ``-g`` GUI flag to the example application.
 
 Some explanation of classes and modules inside the example are given here.
 
-The example hook class
-______________________
+The Configuration Hook Class
+==============================
 
 The class `ExampleHookClass` is the example configuration class implementing
 the :py:class:`tmtccmd.config.hook.HookBase`.
 
-1. The :py:meth:`tmtccmd.config.hook.HookBase.assign_communication_interface` method
+1. The :py:meth:`tmtccmd.config.hook.HookBase.get_communication_interface` method
    is used to return a communication interface given a string identifier. You can read more
    about the communication abstraction in the :ref:`com` chapter.
-2. The :py:meth:`tmtccmd.config.hook.HookBase.get_tmtc_definitions` returns a configuration
-   wrapper which determines the commands displayed when using the interactive CLI mode or the GUI.
+2. The :py:meth:`tmtccmd.config.hook.HookBase.get_command_definitions` returns a tree of
+   command definition which can be used by both users and developers to specify the available
+   commands and procedures.
+
+TC Command Definition Specification
+--------------------------------------
+
+The command tree mechanism provides a flexible mechanism to also model the command definitions
+for more complex systems. These systems are oftentimes structured into dedicated modules.
+For exampe, the command tree for a satellite system might look like this:
+
+
+.. image:: images/example_system.png
+    :align: center
+
+
+For a system like this, it makes a lot of sense to also model the command definitions similarly
+to the system. An example tree modelling the system shown in the example above would look like this
+when printing one built using the :py:class:`tmtccmd.config.tmtc.CmdTreeNode`:
+
+.. code-block:: console
+
+  /                                   [ Root Node ]
+  ├── ping                            [ Send PUS ping command ]
+  ├── test                            [ Test Node ]
+  │  └── event                        [ Send PUS event test command ]
+  ├── system                          [ System Commands ]
+  ├── acs                             [ ACS Subsystem ]
+  │  ├── acs_ctrl                     [ ACS Controller ]
+  │  ├── mgt                          [ Magnetorquer ]
+  │     └── set_dipoles               [ Set MGT Dipoles ]
+  │  ├── mgm0                         [ Magnetometer 0 ]
+  │     └── other cmds                [ Other MGM commands ]
+  │  └── mgm1                         [ Magnetometer 1 ]
+  │     └── other cmds                [ Other MGM commands ]
+  ├── tcs                             [ TCS Subsystem ]
+  │  ├── tcs_ctrl                     [ TCS Controller ]
+  │  ├── pt1000                       [ Temperature Sensor ]
+  │  └── heater                       [ Heater ]
+  ├── com                             [ COM Subsystem ]
+  │  └── uhf_transceiver              [ UHF Transceiver ]
+  └── eps                             [ EPS Subsystem ]
+     └── pcdu                         [ PCDU ]
+        ├── channel_0_on              [ Channel 0 on ]
+        ├── channel_0_off             [ Channel 0 off ]
+        ├── channel_1_on              [ Channel 1 on ]
+        └── channel_1_off             [ Channel 1 off ]
+
+and the code to create this tree would look like this:
+
+.. code-block:: python
+
+    root_node = CmdTreeNode.root_node()
+    root_node.add_child(CmdTreeNode("ping", "Send PUS ping command"))
+    root_node.add_child(CmdTreeNode("test", "Test Node"))
+    root_node.children["test"].add_child(
+        CmdTreeNode("event", "Send PUS event test command")
+    )
+    root_node.add_child(CmdTreeNode("system", "System Commands"))
+    root_node.add_child(CmdTreeNode("acs", "ACS Subsystem"))
+    root_node["acs"].add_child(CmdTreeNode("acs_ctrl", "ACS Controller"))
+    root_node["acs"].add_child(CmdTreeNode("mgt", "Magnetorquer"))
+    root_node["acs"]["mgt"].add_child(CmdTreeNode("set_dipoles", "Set MGT Dipoles"))
+    root_node["acs"].add_child(CmdTreeNode("mgm0", "Magnetometer 0"))
+    root_node["acs"].add_child(CmdTreeNode("mgm1", "Magnetometer 1"))
+    mgm_node = CmdTreeNode("other cmds", "Other MGM commands")
+    root_node["acs"]["mgm0"].add_child(mgm_node)
+    root_node["acs"]["mgm1"].add_child(mgm_node)
+    root_node.add_child(CmdTreeNode("tcs", "TCS Subsystem"))
+    root_node["tcs"].add_child(CmdTreeNode("tcs_ctrl", "TCS Controller"))
+    root_node["tcs"].add_child(CmdTreeNode("pt1000", "Temperature Sensor"))
+    root_node["tcs"].add_child(CmdTreeNode("heater", "Heater"))
+    root_node.add_child(CmdTreeNode("com", "COM Subsystem"))
+    root_node["com"].add_child(CmdTreeNode("uhf_transceiver", "UHF Transceiver"))
+    root_node.add_child(CmdTreeNode("eps", "EPS Subsystem"))
+    root_node["eps"].add_child(CmdTreeNode("pcdu", "PCDU"))
+    root_node["eps"]["pcdu"].add_child(CmdTreeNode("channel_0_on", "Channel 0 on"))
+    root_node["eps"]["pcdu"].add_child(
+        CmdTreeNode("channel_0_off", "Channel 0 off")
+    )
+    root_node["eps"]["pcdu"].add_child(CmdTreeNode("channel_1_on", "Channel 1 on"))
+    root_node["eps"]["pcdu"].add_child(
+        CmdTreeNode("channel_1_off", "Channel 1 off")
+    )
+
+You could return this root node in your
+:py:meth:`tmtccmd.config.hook.HookBase.get_command_definitions` implementation.
+You can now specify your commands as command paths, which will then serve as identifier for single
+command or command stacks and procedures. The command path will be passed on as the `cmd_path`
+parameter of the :py:class:`tmtccmd.tmtc.procedure.DefaultProcedureInfo` which is passed to
+the :py:class:`tmtccmd.tmtc.handler.TcHandlerBase` implementation of the user.
+
+It is also possible to pass the command path as a CLI argument. For example, you can use
+``./tmtcc.py -p /test`` to send a ping command with the example application. Passing the
+command tree definition to the framework also allows it to provide a GUI command path selector
+for the GUI mode.
 
 The TC handler
----------------
+==============================
 
 This object is responsible for the telecommand handling. Therefore this object implements
 the :py:class:`tmtccmd.tmtc.handler.TcHandlerBase`.
@@ -40,7 +135,7 @@ the queue can also contain something like log requests or delay requests, or eve
 custom requests. These requests can then be handled by the user.
 
 The PUS TM handler
---------------------
+==============================
 
 This object is responsible for the handling of PUS telemetry. In the example case, the
 handler object is responsible space packets with a certain application process identifier (APID).