Bwi update

bwi-update (github) is a simple ROS-specific configuration management script written in python in an attempt to maintain experimental code consistency over various user accounts and machines. Here is what the tool does:

1. Manages a set of system packages through apt on the machine.
   1. Install the default ROS repository in your apt-get sources
   2. Install all required ROS system packages
2. Manages a local rosbuild and catkin workspace (with proper overlay).
3. Manages a number of arbitrary generic workspaces to download code from an svn/git/hg repo. For instance, a generic workspace is used to download gazebo models from the OSRF bitbucket repository.
4. Applies patches to packages in workspaces.

Note:

1. The bwi-update tool should be used with care if you are using ROS outside the bwi project. It's main purpose is to facilitate code consistency over a large number of machines and user account, but may not fit well with your existing ROS workspaces.
2. It is a good idea to understand the rosws and wstool workspace management tools along-side bwi-update to manipulate your workspaces.

This documentation is current as of bwi-update v0.3.0

Motivation

We use a large number of packages from the open source community. If a bug appears in external code that we can patch, we temporarily shift to local patched copies of the code (facilitated by the bwi-update tool). Once the patch propagates to the release deb in the external package, we switch back to the release version. The goal of the tool is to ensure that all machines involved in the BWI ecosystem are using the same code at a given point in time.

System side management

This section is useful if you are the system administrator on your machine. You should NOT have to follow any step in this section if you're working on a CS Department machine, a BWI Lab CSRES Machine or one of the robots, unless you are an administrator on one of these machines.

Installation

You can install/upgrade this tool from launchpad

sudo apt-add-repository ppa:piyushk/bwi sudo apt-get update && sudo apt-get install bwi-update

We don't perform a system-wide installation of the bwi-update on the CS Department machines. On the CS filesystem, you can use the following script on a CS Department machine:

/u/piyushk/bwi-update

Obtaining a system config location

Before performing a system wide update, you'll have to get a link for a configuration file for the bwi-update tool. You don't need to download this file, but simply need to copy the web link below for the next step:

• Master repository configuration file: You should use this configuration file if you are an active developer on the BWI Project, or wish to run the code.

https://raw.github.com/utexas-bwi/bwi/master/bwi-update-config/system_config.yaml

• FRI Class configuration file: You should use this configuration file if you are a student or staff for the BWI project.

https://raw.github.com/bwi-spring-2013/bwi/master/bwi-update-config/system_config.yaml

Supplying the configuration

This step needs to be performed whenever you wish to change the configuration. It is quite likely that you will only perform this step once. Use the config file location you have selected from the previous step.

sudo bwi-update --system --config 

Here, the configuration file location can be an absolute location on your machine or on the web. This generates an entry in /etc/bwi/bwi-update/config that resolves to the location you supplied. This means that you can update the configuration on github, and call synchronize on machines without having to do anything else.

Synchronizing

This step will match current system packages to the one supplied by the configuration. All packages are added automatically through apt. If any packages are to be removed, then the script asks for confirmation for every system package before removing it. Note: Any packages in the unmanaged category will not be removed with future update (such as vim, subversion, openssh-server etc.).

sudo bwi-update --system --sync

This step can take extremely long if a large number of ROS components are being upgraded (happens every month).

User side management

Each user on a given machine will have to do some user side management to download and build code locally. A user configuration sets up appropriate workspaces (rosbuild, catkin or general repository workspace), installs and patches packages locally as needed. These downloaded packages can be modified by the user.

Performing a user update

Each system configuration includes a pointer to a default user configuration, which can be overwritten as specified in these 2 steps. To see what the default configuration is, use the following command:

cat /etc/bwi/bwi-update/config

Before performing a user side update, you'll have to get a link for a configuration file for the bwi-update tool. You don't need to download this file, but simply need to copy the web link below for the next step:

• Master repository configuration file (NOT recommended - this configuration file requires REQUIRES PRIOR COMMIT ACCESS TO the utexas-bwi GITHUB ACCOUNT, as well as SSH keys setup on github for the machine you are working on.):

https://raw.github.com/utexas-bwi/bwi/master/bwi-update-config/user_config.yaml

• Master repository read-only configuration file (Recommended): You should use this configuration file if you wish to get the master branch of the BWI code.

https://raw.github.com/utexas-bwi/bwi/master/bwi-update-config/user_config.ro.yaml

• FRI Class configuration file: You should use this configuration file if you are a student or staff for the FRI Class.

https://raw.github.com/bwi-spring-2013/bwi/master/bwi-update-config/user_config.yaml

Supplying the configuration

This step needs to be performed whenever you wish to change the configuration. It is quite likely that you will only perform this step once.

bwi-update --config 

Here, the configuration file location can be an absolute location on your machine or on the web. This generates an entry in .bwi/config that resolves to the location you supplied. This means that you can update the configuration on github, and call synchronize on machines without having to do anything else.

Synchronizing

bwi-update --sync

This will synchronize your local workspaces to the one supplied by the configuration file. If any local packages or workspaces are to be removed, then the tool will ask for confirmation. Be careful while removing packages or workspaces, as any changes that have not been pushed upstream will be lost. You should run this command often.

Under the hood

The system side installation is a copy of the ROS Installation instructions, found here. The following steps are carried out:

1. Install ROS Debian repository source to apt
2. Get the ROS Key to verify signed packages
3. Update the apt cache (sudo apt-get update)
4. Install packages defined in the configuration file. Remove managed packages as necessary.
5. Initialize rosdep

The user side installation does the following

1. Creates an empty direcotry for a catkin ws (typically /ros/catkin_ws/src) and a rosbuild ws (/ros/rosbuild_ws)
2. Sources the ROS root setup file (typically source /opt/ros/groovy/setup.bash). Calls catkin_make in the root catkin ws (typically ~/ros/catkin_ws).
3. At this point, all you need to do to run the ROS system is to source the catkin ws setup file (typically ~/ros/catkin_ws/devel/setup.bash)
4. We chain 1 rosbuild_ws on top of the catkin_ws by calling rosws init (typically rosws init . ~/ros/catkin_ws/devel) inside the rosbuild ws (typically ~/ros/rosbuild_ws).
5. Finally to use these workspaces, you need to simply source the rosbuild ws (~/ros/rosbuild_ws/setup.bash)

Finally, to manipulate these workspaces, you need to use the rosws (rosbuild) or wstool (catkin) tools

1. Inside the catkin ws (~/ros/catkin_ws/src), use wstool to manipulate the workspace
2. Inside the rosbuidl ws (~/ros/rosbuild_ws), use rosws to manipulate the workspace
3. Based on the user configuration file, it installs/updates or removes packages when called. It also has an additional feature to download arbitary pieces of code into generic workspaces (for instance, gazebo models). It can also apply patches once downloaded.

Updating the bwi-update tool

1. Bump the version number. You'll have to modify the text accordingly, and ensure that the author name is absolutely correct

dch -i