Package: catmux
CatmuxAboutCatmux is a little helper to run a tmux session with multiple windows and panes with just one
command. It is inspired and functionally very similar totmuxinator, but without the project management feature
which is in my opinion kind of an overhead.Session configs can be stored anywhere and have to be given as an argument.MotivationIn most of our ROS projects at work we use shell output for almost all nodes to get log information
during runtime. Having all this in one window where you start your "Start it all"-launchfile makes
it very hard to follow the log of a specific node. Starting everything in separate windows is quite
a lot of work and requires documentation overhead in sense of documenting which launchfiles or nodes
have to be started.At a conference I caught the idea to use tmux scripting to orchestrate all this in one tmux session.
However, quickly I noticed that creating these scripts is a daunting task as you'll have to type in
a lot of commands over and over again and as soon as you wanted to do things a little different such
as not starting a particular launchfile if a certain parameter was set, things got complicated.I liked the yaml-syntax oftmuxinator, but that tool
didn't quite hit the spot. I wanted to have something that can be easily integrated into a ROS
project and I definitely wanted something that saves the config per project and not all configs at
one central spot on a particular machine.InstallationCatmux is a pure python package and the installation viapip3 install --user catmuxis recommended.You can also install it by cloning this repository and callingpip3 install --user .in the
repository's root directory. If you use this option, please be aware that some examples behave
differently if you have installed catmux this way and are calling it from the repository directory.
Calling them from outside the directory (e.g. after leaving viacd) is fine and should result in
the same behavior as with the recommended installation method.UsageCurrently, there is no full-blown documentation, but the example config file incatmux/resources/example_session.yamlgives a detailed insight on possible commands.Running the example the most simple wayAfter installation, you can run a simple example by calling the following command:catmux_create_session $(python3 -m catmux.prefix)/example_session.yamlTo see further options, simply run it with argument-h:$ catmux_create_session -h
usage: catmux_create_session [-h] [-n SESSION_NAME] [-t TMUX_CONFIG] [-d] [--overwrite OVERWRITE]
                             session_config

Create a new catmux session

positional arguments:
  session_config        Session configuration. Should be a yaml-file.

optional arguments:
  -h, --help            show this help message and exit
  -n SESSION_NAME, --session_name SESSION_NAME
                        Name used for the tmux session
  -t TMUX_CONFIG, --tmux_config TMUX_CONFIG
                        This config will be used for the tmux session
  -d, --detach          Start session in detached mode
  --overwrite OVERWRITE
                        Overwrite a parameter from the session config. Parameters can be specified
                        using a comma-separated list such as '--overwrite param_a=1,param_b=2'.Full blown exampleTo make use of all catmux features, run the following example command:catmux_create_session $(python3 -m catmux.prefix)/example_session.yaml \
  --tmux_config $(python3 -m catmux.prefix)/tmux_default.conf \
  --session_name example_session \
  --overwrite show_layouts=True,replacement_param="new catmux user"Killing a catmux sessionIf you are not that familiar with tmux: To kill a session, simply typetmux kill-sessionin any
terminal window. In thecatmux/resources/tmux_default.confthere is a key-binding for that, seeetc/readme_tmux.txtfor details.Tmux server to be usedBy default, catmux spawns its own tmux server calledcatmux. Therefore, a simpletmux list-sessions(ortmux ls) will not list thecatmuxsession. To list thecatmuxsession, usetmux -L catmux list-sessions. You can change the server's name by specifying the-L <server_name>parameter tocatmux_create_session. That mechanism ensures that the environment
in whichcatmux_create_sessionis started, will be used inside the catmux session (as long as no
other session previously exists on that particular tmux server).To make things a bit easier, there is a convenience script installed with this
package:catmux. It is basically a wrapper aroundtmux -L <server_name>. For example, you cancatmuxattach# attach to the latest running catmux sessioncatmuxls# list current catmux sessionscatmuxkill-session-texample_session# kill session 'target session'In case you use another tmux server thancatmux, you can set the environment
variableCATMUX_DEFAULT_SERVERto that name and continue using thecatmuxscript.Migrating from the catkin version of catmuxWith the spread of ROS2, the need for a catkin-independent catmux has emerged.
Catmux is now a plain python package without the ROS integration.
Therefore, it is installed via pip and no longer needs to be part of a catkin workspace.
This opens the possibility to easily use catmux outside of robotics application, e.g. for server
administration or other development tasks.Catmux no longer has thepackage://<your_package_name>lookup capabilities.
To achieve the same outcome, simply use rospack:catmux_create_session $(rospack find <your_package_name>)/path/to/<your_catmux_session_config.yaml>For ROS2, the same is achievable withros2 pkg prefixbut the yaml has to be installed (similar
to, for example, a launch file) and the installation path has to be specified:catmux_create_session $(ros2 pkg prefix <your_package_name>)/path/to/the/installed/<your_catmux_session_config.yaml>

# for example: $ catmux_create_session $(ros2 pkg prefix catmux_test_pkg)/share/catmux_test_pkg/catmux_session.yaml