The robmuxinator script serves as a command-line tool to manage and control tmux sessions on multiple hosts of your robot. If you use tmux you will love robmuxinator! It is designed to simplify the execution of various commands. You can for example launch processes of your ROS bringup and application or run a Docker container with it.
It is also helpful for local development to start multiple commands easily with one command.
Install the robmuxinator with one simple command (execute in the robmuxinator package)
sudo pip install .
After that, you have to ensure that the root user has SSH access to every user which is used by robmuxinator. Simply copy your SSH credentials to the user by ssh-copy-id username@hostname
robmuxinator is also a Nix Flake and available as package under github:mojin-robotics/robmuxinator#robmuxinator.
Execute the steps from Prerequisites.
Local Development
To get started locally with robmuxinator, this would be a robot.yaml for local development.
timeout: 120
hosts:
localhost:
user: $USER
sessions:
roscore:
user: $USER
host: localhost
prio: 0
command: roscore
wait_for_core: false
bringup:
user: $USER
host: localhost
prio: 1
command: echo 'starting bringup...'
To start the tmux sessions use robmuxinator -c ~/path-to-file start. Now, you are able to see your sessions with tmux ls
and you can attach to them with all your favorite tmux commands. For reference see this cheatsheet.
Remote Hosts
For remote hosts the following YAML config can be used. This starts two sessions on host 1 (h1) and host 2 h2.
The port is used to check wether the host is ready to receive commands.
timeout: 120
hosts:
h1:
user: robot
port: 22
h2:
user: robot
port: 22
sessions:
roscore:
user: robot
host: h1
prio: 0
command: roscore
wait_for_core: false
bringup:
user: robot
host: h2
prio: 1
command: echo 'starting bringup...'
start: Start specified sessions on all hosts.stop: Stop specified sessions on all hosts.restart: Restart specified sessions on all hosts.shutdown: Execute shutdown procedures on all hosts.reboot: Execute reboot procedures on all hosts.
command: Choose one of the available commands (start, stop, restart, shutdown, reboot).-cor--config: Specify the path to the YAML configuration file that defines the hosts, sessions, and other settings. The default configuration file path is "/etc/ros/upstart_robot.yaml."-sor--sessions: Optionally, specify which sessions should be started or stopped. You can provide multiple session names as arguments.-for--force: Use this flag to force the closure of sessions, even if they are locked.-l <L>or--logging_level <L>: Use this flag to set the logging level, ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]--instance_id <N>: An unique id used to prepend to each session name and used within multi-robot setups.
- The script relies on a YAML configuration file to define hosts, sessions, and other parameters. The YAML file should include information about the hosts, their operating systems (Linux, Windows, online), session details, and more.
Global Options
timeout: int(mandatory): Seconds to wait for a host on startup.
Hosts of Robot
os: string{linux, windows, online} (mandatory): Operating system of the host. Hosts of typeonlinewill only be checked for network availability.user: string(optional, default: robot): User on the host machine used for sending SSH commands.port: int(optional, default: none): The port that is checked to determine if a service on the host is already up.ssh_port: int(optional, default:22): The port that is used for SSH connections to the host.hostname: string(optional, default:<key>ofhostssection): The hostname of the host PC.check_nfs: bool(optional, default: true): Whether the host should be checked for NFS status. Only supported on Linux.
Sessions of the Hosts
command: string(mandatory): Bash command executed in thetmuxsession. A session without thecommandkey will result in an exception.host: string(optional, default: hostname of localhost): Target host of thetmuxsession.user: string(optional, default: robot): Target user of thetmuxsession.wait_for_core: bool(optional, default: true): Starts the session only afterroscoreis available.prio: int(optional, default: 10): Priority of starting the session. Sessions with the same priority start concurrently. Smaller numbers have higher priority.prio_stop: int(optional, default:prio): Priority of stopping the session. Sessions with the same priority stop concurrently. Higher numbers have higher priority.locked: bool(optional, default: false): Locked sessions won't be closed onstoporrestart(only if forced).pre_condition: string(optional): Bash command used as a condition that must be fulfilled before the session can start.
This is s summary of useful commands for working with tmux.
- Start a New Session:
tmux - Detach from Session:
Ctrl-b d - Attach to a Session:
tmux attach-session -t session_name
- Create a Named Session:
tmux new-session -s session_name - List Sessions:
tmux list-sessions - Switch to Another Session:
tmux switch-client -t session_name - Kill a Session:
tmux kill-session -t session_name
- List Windows:
Ctrl-b w - Switch to Next Window:
Ctrl-b n - Switch to Previous Window:
Ctrl-b p
- Enter Copy Mode:
Ctrl-b [ - Exit Copy Mode:
q - Scroll Up:
Ctrl-b [, then use arrow keys or Page Up/Down - Search Forward:
Ctrl-b [, then/, type search text, and press Enter - Search Backward:
Ctrl-b [, then?, type search text, and press Enter
Apache License Version 2.0, January 2004