buttonui
--------

Version 1.1
Bob Mottram, fuzzgun@gmail.com

This implements a navigation user interface based upon pressing buttons

Ingredients
-----------

  1 x Arduino (Any model will do, so long as it has at least 5 digital inputs)
  1 x USB cable to connect to the Arduino
  5 x 10K resistors
  5 x Normally open button switches
  A bunch of wire
  Solder and a soldering iron
  A box to put it all in


or

  1 x Arduino (Any model will do, so long as it has at least 5 digital inputs)
  1 x USB cable to connect to the Arduino
  5 x Microswitches with attached buttons
  A bunch of wire
  Solder and a soldering iron
  A box to put it all in

Optionally an emergency stop button can be connected to pin 7.


Circuit diagram for the Arduino
-------------------------------

A circuit diagram which applies for each button switch is shown below.  In this case pins 8-12 are used as digital inputs.  The connector block is merely for convenience, so that switches can be swapped around if needed.

                   ------------------------
                   |                      |         
                   |                      |         
       ---------------                    |         
                  5v |        ----        |         
              Pin  8 |-------o    o-------o
                   9 |       Button       |
                  10 |       Switch       |
       Arduino    11 |                    |
                  12 |                    |
                     |                   10K
                     |                    |
                     |                    |
                     |                    |
                  0v |---------------------
       ---------------

An alternative is to use relays/microswitches, where the normally open side connects the input to 5v and the normally closed connects the input to 0V (ground).  These eliminate the need for additional resistors.

                   ------------------------
                   |                      |         
                   |                      |         
       ---------------                    |         
                  5v |                    o         
              Pin  8 |------------------o   Microswitch
                   9 |                   \ 
                  10 |                    o
       Arduino    11 |                    |
                  12 |                    |
                     |                    |
                     |                    |
                     |                    |
                     |                    |
                  0v |---------------------
       ---------------


Programming the Arduino
-----------------------

There is an Arduino IDE which can be  found in the software center of Ubuntu, or which can be downloaded from the main arduino web site (http://www.arduino.cc).

  sudo apt-get install arduino

Load the file which is contained in the arduino directory and if necessary alter the digital input pin numbers within the buttonPin array.

Make sure that you select the appropriate model type and communications settings for your Arduino from the menu, then save and upload the program.

Use the serial monitor to check that when you press a button a number appears.  When no buttons are pressed you shouldn't see anything happening in the serial monitor window.


Giving the Arduino a consistent device name
-------------------------------------------

You may notice that if you unplug USB devices and then reconnect them that the Arduino gets a different device number.  The way to solve this is to create a udev rules file.

After disconnecting the Arduino type:

  ls /dev/ttyUSB*

Then plug the Arduino USB cable in again and type:

  ls /dev/ttyUSB*

You should notice that the list has changed, and this will indicate which device number the Arduino is using.

Then type:

  udevadm info -a -p $(udevadm info -q path -n /dev/ttyUSB#) | grep "idProduct"

where # is the number being used by the Arduino.  This will list the product ID properties associated with the Arduino.  Look at the ID numbers associated with any other USB devices to determine what is unique to the Arduino.  Keep a note of the product ID number.

Now create a rules file:

  sudo gedit /etc/udev/rules.d/10-arduino.rules

Add the following line:

  KERNEL=="ttyUSB[0-9]*", ATTRS{idProduct}=="myproductid", SYMLINK+="ttyUSB.arduino1"

changing myproductid to the one found previously.  Save and exit, then unplug and reconnect the Arduino.  You should now be able to access the device consistently as /dev/ttyUSB.arduino1, no matter what sequence in which it was connected.

If you have any permissions issues then make sure that 10-arduino.rules is accessible by the current user, and use chown if needed.

Unfortunately this doesn't work with the current Arduino IDE, which seems to only expect ttyUSB# type device files, but it should work with the launch files.


Compilation of the ROS package
------------------------------

To compile the package.

  1.  Make a directory called buttonui
  2.  Copy these files into the buttonui directory
  3.  rosdep install buttonui
  3.  rosmake --pre-clean buttonui

Also you'll need to install espeak.

  sudo apt-get install espeak


Usage
-----

Edit buttonuitest.launch and buttonui.launch and check that the device path and communication settings are correct for the Arduino.

It's worth checking that the buttons are wired up as you expect them to be.  You can find the index numbers within buttonuitest.launch.  Use this launcher to ensure that when you press a button the ROS info message which is displayed is appropriate.  

  roslaunch buttonui buttonuitest.launch

If changes need to be made then edit the launch file accordingly.  Once all buttons are working then you can copy the index number parameters over to the buttonui.launch file.

You may want to edit the placemarks and current_pose_filename parameters within buttonui.launch to place them into your preferred directory.

You should then include buttonui.launch within your main navigation launch file.  An example is shown as follows:

  <launch>

    <!--- Run Robot base -->
    <include file="$(find turtlebot_bringup)/minimal.launch" />

    <!--- Run the kinect -->
    <include file="$(find turtlebot_bringup)/kinect.launch" />

    <!-- Run the map server -->
    <arg name="map_file" default="$(find turtlebot_navigation)/maps/willow-2010-02-18-0.10.yaml"/>
    <node name="map_server" pkg="map_server" type="map_server" args="$(arg map_file)" />

    <!--- Button user interface -->
    <include file="$(find buttonui)/buttonui.launch" />

    <!--- Run AMCL -->
    <include file="$(find turtlebot_navigation)/config/amcl_turtlebot.launch" />

    <!--- Run Move Base -->
    <include file="$(find turtlebot_navigation)/config/move_base_turtlebot.launch" />

  </launch>


Teaching
--------

First of all edit buttonui.launch and define a set of locations within the placenames parameter. These will be the locations that you wish the robot to visit.

Press the start button, and you should hear the robot say "started". If you don't then check that espeak is installed correctly.

Initially you'll need to run Rviz and set the initial pose of the robot. Use the teleoperation system to manually drive the robot to the desired locations. Any hand held device capable of running ssh, such as a netbook or mobile phone, should be sufficient for keyboard based teleoperation.

When the robot is at a location that you wish it to learn then press the location button until you find the current place, then press the learn button twice (this is to help prevent accidental presses). You should hear the robot say that it has remembered the location. Repeat this for however many locations you've specified within the launch file.


Navigating
----------

If you've just started the robot then first press the start button. The robot should say "started".

Place the robot at one of the locations and in the same orientation as it was during the teaching phase. Select the appropriate location by pressing the location button, then press the set button. This sets the robot's initial pose within the map.

Press the location button again to set the goal location, then press the start button. The robot should then try to navigate to the goal. If it can't find a path to the goal then it will say so, and stop.

Once the robot has arrived at a goal location then it will automatically increment the goal location to the next one in the list which you specified within the launch file placenames parameter. This means that just pressing the start button will keep the robot navigating through the locations list in a stepwise fashion, which may be useful for round trip delivery type situations. 


Customising the Audio
---------------------

You can also cusomise the text-to-speech messages by editing the following parameters within buttonui.launch or buttonuitest.launch.

   <param name="speakcommand" value="espeak"/>
   <param name="playcommand" value="aplay"/>
   <param name="startbuttonsound" value="Started"/>
   <param name="stopbuttonsound" value="Stopped"/>
   <param name="learnbuttonsound" value="%s remembered"/>
   <param name="placebuttonsound" value="%s"/>
   <param name="gobuttonsound" value="Going to %s"/>
   <param name="enablesound" value="Button user interface enabled"/>
   <param name="estopactivesound" value="Please release the emergency stop"/>
   <param name="estoppressedsound" value="Emergency stop activated"/>
   <param name="estopreleasedsound" value="Emergency stop released"/>
   <param name="goalarrivedsound" value="Arrived at %s"/>
   <param name="goalfailedsound" value="I can't get to %s"/>

Alternaitively you can also use WAV or MP3 files rather than speech. For example:

   <param name="startbuttonsound" value="start.wav"/>

The playcommand command will be used in order to play the sound file. If you're using MP3 files then you can change playcommand to something like mpg123. Probably it's not a good idea to use an audio file for the place button, since this names the places.