ros: mk | rosbash | rosboost_cfg | rosbuild | rosclean | roscreate | rosdep | rosemacs | roslang | roslib | rosmake | rospack | rosunit

Package Summary

Ros tools for those who live in emacs.

• Author: Bhaskara Marthi
• License: BSD
• Repository: ros

Overview

This is an emacs extension for dealing with ros. Simplifies navigating the package system, tracking topics and nodes, and running various commands (roscore, rosrun, roslaunch) directly from emacs.

Setting up rosemacs defines a set of ROS-related emacs commands. These can be either called using the full command names given below (using M-x command-name) or using a keyboard shortcut, if you've set a prefix for the ros-keymap. For example, given the setup above, C-x C-r C-f will find a package or file using rospack. Type C-h f command-name to see if there's a shortcut for a given command. Type C-x C-r C-h to see the entire list of keyboard shortcuts. In this document, we'll list the keyboard shortcut with each command, which has to be preceded with whatever prefix you're using.

The rosemacs extension is still experimental, but it is included with the default ROS installation to provide utility to Emacs users.

Installation

rosemacs is included in a standard ROS install. In order to enable rosemacs, add the following lines to your .emacs. You may use rospack find rosemacs to find out your path:

(add-to-list 'load-path "/path/to/rosemacs")
(require 'rosemacs)
(invoke-rosemacs)

or, to be more generic:

(let* ((result (shell-command-to-string (concat "rospack find rosemacs")))
       (checked-result (if (string-match "[[]" result)
                            (progn (message result) nil)
                          (if (string-match "[ \n]*$" result)
                              (replace-match "" nil nil result)
                            result))))
         (when checked-result
           (progn (add-to-list 'load-path checked-result)
                  (require 'rosemacs)
                  (invoke-rosemacs))))

It's also recommended to set a global shortcut prefix for rosemacs commands, with something like:

(global-set-key "\C-x\C-r" ros-keymap)

IMPORTANT: Make sure the standard ROS variables are set in the emacs process environment. For example, if you use bash, follow the standard ROS installation instructions about sourcing .bashrc.ros in your .bashrc, and launch emacs from a bash shell.

Navigating the ros file system

Visiting files

find-ros-file (C-f)
view-ros-file (f)
find-ros-message (C-m)
view-ros-message (m)
find-ros-service (C-s)
view-ros-service (s)

• The commands {find|view}-ros-{file|message|service} for navigating the ros libraries are available. The file versions take in a package name and relative path, and the message/service versions just take the message/service name. All of these can be tab-completed.

ros-load-package-locations (r)

• rosemacs caches the list of packages for speed. This command causes the list to be reloaded, which is useful if you've just created a new package.

Searching and replacing in packages

ros-rgrep-package (g)

• Recursively grep in a ros package. This command is similar to rgrep but asks for a ROS package instead of a directory.

ros-find-dired

• Execute find in a ROS package and use the output in a dired buffer. This command is similar to find-dired but asks for a ROS package to run find in instead of a directory.

Interacting with a live ROS system

Topic tracking

rosemacs maintains information about current ROS topics. The topic list is used for tab completion, both in the shell and emacs commands, of topics in the appropriate places.

display-ros-topic-info (C-t)

• Display the *ros-topics* buffer, which contains the set of published and subscribed topics

add-hz-update (h)

• Make rosemacs track the hz rate of the topics matching one or more regexps, and display this in the *ros-topics* buffer.

remove-hz-update (H)

• Stop tracking topics matching a given regexp.

echo-ros-topic (t)

• Echo a ROS topic into a new buffer.

Node tracking

Analogous to topic tracking. Provides completion of node names in the appropriate places. Also, when nodes die, displays a message in the minibuffer and the ros-events buffer.

rosemacs/display-nodes (C-n)

• Display current list of ros nodes.

Running/launching things

ros-launch (C-l)

• Start a launch file in an appropriately named buffer. In that buffer, k kills the launch (and the launched processes), r restarts, and q quits.

ros-run (C-r)

• Analogous to ros-launch with the same keybindings.

ros-core (C-c)

• Start a core that sends output to the *ros-core* or switch to that buffer if a core is already active.

Ros events

The *ros-events* buffer contains a timestamped list of noteworthy events in the ros system. Useful for answering the question "did something unexpectedly die?" when your system is behaving strangely. Currently, it keeps track of nodes starting and stopping.

rosemacs/display-event-buffer (C-e)

• Display the ros event buffer

Programming aids

Shell tab completion

By default, ROS tab completion does not work if you use shell-mode in emacs. rosemacs fixes this and adds completion of current nodes and topics. However, a more general way, assuming your prompt contains the directory, is to use dirtrack-mode, which comes with emacs.

yasnippet integration

yasnippet is an Emacs extension that allows you to write snippets, which are templates for recurring patterns in source code. Rosemacs (trunk) provides a few ros-specific ones in the snippets/ directory. E.g., if you enable snippets support and set up your path as per the above instructions, if you open up a new file bar.h in the foo package and type wgh followed by [TAB], it will:

• Figure out that it's in the foo ROS package

• Generate an include guard named FOO_BAR_H

• Add a declaration for namespace foo

• Add a doxygen block for the file

Current package in the Mode Line

You can add the following expression to the customization mode-line-format:

(:eval (ros-current-pkg-modeline-entry))

With this, the current buffer's ROS package becomes part of the mode line.

Editing launch and manifest files

Emacs 22 and later includes NXML mode which, given a RELAX NG schema, validates xml documents online as you edit them and provides intelligent completion. Rosemacs includes schemas for roslaunch and manifest.xml files. To set this all up, put this in your .emacs file after the loading of rosemacs:

(require 'rng-loc)
(condition-case nil ;; error e.g. when running as root
    (push (concat (ros-package-path "rosemacs") "/rng-schemas.xml") rng-schema-locating-files)
  (error nil))
(add-to-list 'auto-mode-alist '("\.launch$" . nxml-mode))
(add-to-list 'auto-mode-alist '("manifest.xml" . nxml-mode))

The last line is unnecessary with Emacs post-23.2, since it uses nxml for xml files by default. The schemas are incomplete but nxml will still work on the parts it recognizes.

Note: the above now (Diamondback and later) automatically happens upon invoking rosemacs, which also adds xml mode for urdf and xacro files, and gdb-script mode for font colors for msg, srv, and action files.

Integration with roslisp and slime

Rosemacs contains a slime contrib to deal with asdf systems in ros packages. The module adds the repl shortcut ros-load-system to the slime repl. To use it extend the slime-setup line in your emacs configuration by the contrib slime-ros. For example:

(slime-setup '(slime-fancy slime-asdf slime-ros))

Please make sure that you have added rosemacs to load-path before executing slime-setup.

Now, by pressing , in an empty repl prompt, you can select the shortcut ros-load-system. Press enter and select a ros package and an asdf system inside this ros package. Slime will set the variable ros-load:*current-ros-package* and perform a load operation on the selected system.

The package contains one customization variable, slime-ros-completion-function. It allows the user to select ido mode completion or similar completion mechanisms. To change its value, use M-x customize-group slime-ros.

Customization

There are various customizable options. You can set these using emacs's customization system (in the rosemacs customization group), or by just doing (setq variable value) in your .emacs.

ros-completion-function

• The default is to use standard emacs completion. You can instead use the awesome ido-mode which already comes with emacs22 and higher. To use this, first activate ido-mode following the instructions at the above page. Then customize ros-completion-function to ido-completing-read.

ros-topic-update-interval

• How often (seconds) rosemacs polls the list of ros topics. Default is 8.

ros-node-update-interval

• How often (seconds) rosemacs polls the list of ros nodes. Default is 8.

Yaml Customization

You may also want to add a yaml mode to your .emacs file.

1. Download a yaml mode .el file from here: http://www.emacswiki.org/emacs/YamlMode and put it next to rosemacs.el or somewhere else in your emacs load path.

2. Add these lines to your .emacs file:

(require 'yaml-mode)
(add-to-list 'auto-mode-alist '("\\.yml$" . yaml-mode))
(add-to-list 'auto-mode-alist '("\\.yaml$" . yaml-mode))