Software prerequisites

MammalBot is being developed with the MiRo robot as a principal testbed, so you will currently need access to either a virtual or physical MiRo to develop or use MammalBot. Assuming you don't have access to a physical robot, you will need:

• Gazebo 7 for simulating a virtual MiRo robot, which requires
• ROS Kinetic, the latest ROS version compatible with Gazebo 7, which requires
• Ubuntu 16.04 (or an Ubuntu 16-based fork such as Linux Mint 18.3), the latest Ubuntu release compatible with ROS Kinetic
• The MiRo Developer Kit, which includes Gazebo files for the virtual MiRo
• SpineCreator and the associated programs SpineML PreFlight, SpineML to BRAHMS, and the simulation engine BRAHMS to view, edit, and run MammalBot models

If you do have access to a physical MiRo robot and don't intend to use Gazebo, then newer versions of ROS and any compatible Linux distribution should work fine, though Ubuntu is still recommended.

Installation

There are two paths to getting set up:

Docker

Installing and configuring multiple interreliant software packages can be a time-consuming project in itself, so the MammalBot repo includes a Docker Compose file that will launch a stack of Docker containers with preconfigured versions of all necessary software. This is the recommended method for setting up MammalBot in most circumstances.

This should work on any version of Linux but won't work on macOS, as xhyve (on which Docker for Mac is built) doesn't support GPU passthrough required for Gazebo's 3D rendering.

Installation

1. Install Docker and Docker Compose, ideally following the post-install instructions to avoid running Docker as root
2. Clone the MammalBot repository to your machine
3. From the repo directory, run docker-compose up --no-start to download all required images

Starting up

Model development

Run docker-compose run --rm spinecreator spinecreator to open a SpineCreator instance in which to develop or test a standalone SpineML model.

Model execution

1. Run docker-compose start to start the MammalBot stack. A Gazebo window should appear with a virtual MiRo in a walled arena
   • Gazebo will sometimes quit prematurely due to a known bug; if the Gazebo window doesn't appear, run docker-compose start again
2. Run docker exec -it mammalbot_spinecreator ./ros_entrypoint.sh bash to open a Bash prompt inside the SpineCreator container. This should look similar to docker@7c74d48ac35b:/$. From here, you can run specific MammalBot experiments

Shutting down

1. If you are at the Bash prompt inside the SpineCreator container, run exit to return to your host shell; or if you are in the SpineCreator application, save your work and close the window
2. Run docker-compose stop to shut down the MammalBot stack

Native

If you are already running Ubuntu 16.04 or are willing to install it, you may install and configure the required software yourself.

• Follow these instructions to install ROS, the MiRo MDK, and Gazebo
• Follow these instructions to install SpineCreator and associated packages
  • You must set the flag -DCOMPILE_PYTHON_BINDING=ON when compiling BRAHMS to enable Python components