Fix #42 issue and add gitignore file

.gitignore

@@ -0,0 +1,106 @@
+
+# Created by https://www.gitignore.io/api/python
+
+### Python ###
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*,cover
+.hypothesis/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# dotenv
+.env
+
+# virtualenv
+.venv
+venv/
+ENV/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# End of https://www.gitignore.io/api/python
+# temporary files
+*~

README.md

@@ -1,8 +1,32 @@
+**UNSTABLE BRANCH**
+
+This branch is under active development and is not likely to work.  Please use the official hydro-devel or indigo-devel branch for ROS Hydro or ROS Indigo, respectively.
+
+Table of Contents
+=================
+
+* [Overview](#overview)
+* [Official ROS Documentation](#official-ros-documentation)
+* [System Requirements](#system-requirements)
+* [Preparing your Serial Port under Linux](#preparing-your-serial-port-under-linux)
+* [Installation of the ros_arduino_bridge Stack](#installation-of-the-ros_arduino_bridge-stack)
+* [Loading the ROSArduinoBridge Sketch](#loading-the-rosarduinobridge-sketch)
+* [Firmware Commands](#firmware-commands)
+* [Testing your Wiring Connections](#testing-your-wiring-connections)
+* [Configuring the ros_arduino_python Node](#configuring-the-ros_arduino_python-node)
+* [Launching the ros_arduino_python Node](#launching-the-ros_arduino_python-node)
+* [Viewing Sensor Data](#viewing-sensor-data)
+* [Sending Twist Commands and Viewing Odometry Data](#sending-twist-commands-and-viewing-odometry-data)
+* [ROS Services for Sensors and Servos](#ros-services-for-sensors-and-servos)
+* [ROS Joint Topics and Services](#ros-joint-topics-and-services)
+* [Using the on-board wheel encoder counters (Arduino Uno only)](#using-the-on-board-wheel-encoder-counters-arduino-uno-only)
+* [NOTES](#notes)
+
 Overview
 --------
 This branch (indigo-devel) is intended for ROS Indigo and above, and uses the Catkin buildsystem. It may also be compatible with ROS Hydro.
 
-This ROS stack includes an Arduino library (called ROSArduinoBridge) and a collection of ROS packages for controlling an Arduino-based robot using standard ROS messages and services.  The stack does **not** depend on ROS Serial.
+This ROS metapackage includes an Arduino library (called ROSArduinoBridge) and a collection of ROS packages for controlling an Arduino-based robot using standard ROS messages and services.  The stack does **not** depend on ROS Serial.
 
 Features of the stack include:
 
@@ -23,7 +47,9 @@ the PC. The base controller requires the use of a motor controller and encoders
 * Pololu VNH5019 dual motor controller shield (http://www.pololu.com/catalog/product/2502) or Pololu MC33926 dual motor shield (http://www.pololu.com/catalog/product/2503).
 
 * Robogaia Mega Encoder shield
-(http://www.robogaia.com/two-axis-encoder-counter-mega-shield-version-2.html) or on-board wheel encoder counters.
+(http://www.robogaia.com/two-axis-encoder-counter-mega-shield-version-2.html)
+
+* Instead of the Encoder shield, wheel encoders can be [connected directly](#using-the-on-board-wheel-encoder-counters-arduino-uno-only) if using an Arduino Uno
 
 **NOTE:** The Robogaia Mega Encoder shield can only be used with an Arduino Mega. The on-board wheel encoder counters are currently only supported by Arduino Uno.
 
@@ -38,6 +64,10 @@ http://www.ros.org/wiki/ros_arduino_bridge
 
 System Requirements
 -------------------
+**ROS Dependencies**
+
+    $ sudo apt-get install ros-indigo-diagnostic-updater ros-indigo-control-msgs ros-indigo-nav-msgs
+
 **Python Serial:** To install the python-serial package under Ubuntu, use the command:
 
     $ sudo apt-get install python-serial
@@ -71,7 +101,7 @@ http://www.robogaia.com/uploads/6/8/0/9/6809982/__megaencodercounter-1.3.tar.gz
 These libraries should be installed in your standard Arduino
 sketchbook/libraries directory.
 
-Finally, it is assumed you are using version 1.0 or greater of the
+Finally, it is assumed you are using version 1.6.6 or greater of the
 Arduino IDE.
 
 Preparing your Serial Port under Linux
@@ -129,45 +159,49 @@ To install the ROSArduinoBridge library, follow these steps:
 
 where SKETCHBOOK_PATH is the path to your Arduino sketchbook directory.
 
-    $ cp -rp `rospack find ros_arduino_firmware`/src/libraries/ROSArduinoBridge ROSArduinoBridge
+    $ \cp -rp  `rospack find ros_arduino_firmware`/src/libraries/ROSArduinoBridge -T ROSArduinoBridge
 
-This last command copies the ROSArduinoBridge sketch files into your sketchbook folder.  The next section describes how to configure, compile and upload this sketch.
+This last command copies the ROSArduinoBridge sketch files into your sketchbook folder and overwrites any existing files with the same name.  The next section describes how to configure, compile and upload this sketch.
 
 
 Loading the ROSArduinoBridge Sketch
 -----------------------------------
 
 * If you are using the base controller, make sure you have already installed the appropriate motor controller and encoder libraries into your Arduino sketchbook/librariesfolder.
 
-* Launch the Arduino 1.0 IDE and load the ROSArduinoBridge sketch.
+* Launch the Arduino IDE and load the ROSArduinoBridge sketch.
   You should be able to find it by going to:
 
     File->Sketchbook->ROSArduinoBridge
 
-NOTE: If you don't have the required base controller hardware but
-still want to try the code, see the notes at the end of the file.
+**NOTE:** If you have the required hardware to use the base controller, uncomment the line that looks like this:
+
+<pre>
+//#define USE_BASE
+</pre>
 
-Choose one of the supported motor controllers by uncommenting its #define statement and commenting out any others.  By default, the Pololu VNH5019 driver is chosen.
+so it looks like this:
 
-Choose a supported encoder library by by uncommenting its #define statement and commenting out any others.  At the moment, only the Robogaia Mega Encoder shield is supported and it is chosen by default.
+<pre>
+#define USE_BASE
+</pre>
 
-If you want to control PWM servos attached to your controller, change
-the two lines that look like this:
+You will also need to choose one of the supported motor controllers by uncommenting its #define statement and commenting out any others.  By default, the Pololu VNH5019 driver is chosen.
+
+Choose a supported encoder library by by uncommenting its #define statement and commenting out any others.  At the moment, the two options are the Robogaia Mega Encoder shield (chosen by default) and the directo connection ARDUINO_ENC_COUNTER option that works for Arduino Uno compatible boards.
+
+By default, the sketch will provide support to control PWM servos attached to your Arduino.  If you do not need servo support, you can comment out the line that looks like this:
 
 <pre>
-//#define USE_SERVOS
-#undef USE_SERVOS
+#define USE_SERVOS2
 </pre>
 
-to this:
+so that it looks like this:
 
 <pre>
-#define USE_SERVOS
-//#undef USE_SERVOS
+//#define USE_SERVOS2
 </pre>
 
-You must then edit the include file servos.h and change the N_SERVOS
-parameter as well as the pin numbers for the servos you have attached.
 
 * Compile and upload the sketch to your Arduino.
 
@@ -185,14 +219,20 @@ The list of commands can be found in the file commands.h.  The current list incl
 #define PIN_MODE       'c'
 #define DIGITAL_READ   'd'
 #define READ_ENCODERS  'e'
+#define CONFIG_SERVO   'j'
 #define MOTOR_SPEEDS   'm'
 #define PING           'p'
 #define RESET_ENCODERS 'r'
 #define SERVO_WRITE    's'
 #define SERVO_READ     't'
 #define UPDATE_PID     'u'
+#define SERVO_DELAY    'v'
 #define DIGITAL_WRITE  'w'
 #define ANALOG_WRITE   'x'
+#define ATTACH_SERVO   'y'
+#define DETACH_SERVO   'z'
+#define LEFT            0
+#define RIGHT           1
 </pre>
 
 For example, to get the analog reading on pin 3, use the command:
@@ -211,6 +251,18 @@ To move the robot forward at 20 encoder ticks per second:
 
 m 20 20
 
+To intialize a PWM servo on pin 3 with speed delay 100ms:
+
+j 3 100
+
+To move the servo on pin 3 to position 120 degrees:
+
+s 3 120
+
+To detach servo on pin 3:
+
+z 3
+
 
 Testing your Wiring Connections
 -------------------------------
@@ -278,8 +330,16 @@ sensors: {
   #motor_current_right:  {pin: 1, type: PololuMotorCurrent, rate: 5},
   #ir_front_center:      {pin: 2, type: GP2D12, rate: 10},
   #sonar_front_center:   {pin: 5, type: Ping, rate: 10},
-  arduino_led:          {pin: 13, type: Digital, rate: 5, direction: output}
+  onboard_led:           {pin: 13, type: Digital, rate: 5, direction: output}
 }
+
+# Joint name and configuration is an example only
+joints: {
+    head_pan_joint: {pin: 3, init_position: 0, init_speed: 90, neutral: 90, min_angle: -90, max_angle: 90, invert: False, continous: False},
+    head_tilt_joint: {pin: 5, init_position: 0, init_speed: 90, neutral: 90, min_angle: -90, max_angle: 90, invert: False, continous: False}
+}
+
+
 </pre>
 
 **NOTE**: Do not use tabs in your .yaml file or the parser will barf it back out when it tries to load it.   Always use spaces instead.  **ALSO**: When defining your sensor parameters, the last sensor in the list does **not** get a comma (,) at the end of the line but all the rest **must** have a comma.
@@ -324,6 +384,12 @@ to define an output pin, set the direction explicitly to output.  In
 the example above, the Arduino LED (pin 13) will be turned on and off
 at a rate of 2 times per second.
 
+_Defining Servo Configurations_
+
+The *joints* parameter defines a dictionary of joint names and servo parameters.  (You can name each joint whatever you like but rememember that joint names will become part of the servo's ROS topic and service names.)
+
+The most important parameter is *pin* which of course must match the pin the servo attaches to on your Arduino.  Most PWM servos operate from 0 to 180 degrees with a "neutral" point of 90 degrees. ROS uses radians instead of degrees for joint positions but it is usually easier for programmers to specify the angular limits in the config file using degrees.  The ROS Arduino Bridge pacakge takes care of the conversion to radians.  An *init_position* of 0 therefore means 0 degrees relative to the neutral point of 90 degrees.  A *max_angle* of 90 degrees maps into 180 degrees at the servo. 
+
 _Setting Drivetrain and PID Parameters_
 
 To use the base controller, you will have to uncomment and set the
@@ -413,9 +479,9 @@ or
 
    $ rxplot -p 60 /odom/pose/pose/position/x:y, /odom/twist/twist/linear/x, /odom/twist/twist/angular/z
 
-ROS Services
-------------
-The ros\_arduino\_python package also defines a few ROS services as follows:
+ROS Services for Sensors and Servos
+-----------------------------------
+The ros\_arduino\_python package also defines a few ROS services for sensors and servos as follows:
 
 **digital\_set\_direction** - set the direction of a digital pin
 
@@ -441,6 +507,40 @@ where id is the index of the servo as defined in the Arduino sketch (servos.h) a
 
 where id is the index of the servo as defined in the Arduino sketch (servos.h)
 
+ROS Joint Topics and Services
+-----------------------------
+At the ROS level, a servo is called a joint and each joint has its own topics and services.  To change the position of a joint, publish the position
+in radians to the topic:
+
+**/\<joint_name\>/command**
+
+For example, a joint called head_pan_joint in the YAML config file can be controlled using the topic:
+
+**/head_pan_joint/command**
+
+which takes a Float64 argument specifying the desired position in radians.  For example, the command:
+
+    $ rostopic pub -1 /head_pan_joint/command std_msgs/Float64 -- 1.0
+
+will move the servo to angle 1.0 radians from the neutral point; i.e. about 147 degrees when using the default neutral point of 90 degrees.  Using a negative value moves the servo in the other direction:
+
+    $ rostopic pub -1 /head_pan_joint/command std_msgs/Float64 -- -1.0
+
+A number of services are also available for each joint:
+
+**/\<joint_name\>/enable** - Enable or disable a joint.  Disabling also detachs the underlying servo so that it can be moved by hand.
+
+    $ rosservice call /head_pan_joint/enable false
+
+**/\<joint_name\>/relax** - Another way to detach the underlying servo so that it can be moved by hand.
+
+    $ rosservice call /head_pan_joint/relax
+
+**/\<joint_name\>/set_speed** - Set the movement speed of servo in radians per second.
+
+    $ rosservice call /head_pan_joint/set_speed 1.0
+
+
 Using the on-board wheel encoder counters (Arduino Uno only)
 ------------------------------------------------------------
 The firmware supports on-board wheel encoder counters for Arduino Uno.
@@ -473,21 +573,21 @@ follow the instructions below so that you can still use your
 Arduino-compatible controller to read sensors and control PWM servos.
 
 First, you need to edit the ROSArduinoBridge sketch. At the top of
-the file, change the two lines that look like this:
+the file, comment out the line that looks like this:
 
 <pre>
 #define USE_BASE
-//#undef USE_BASE
 </pre>
 
-to this:
+so it looks like this:
 
 <pre>
 //#define USE_BASE
-#undef USE_BASE
 </pre>
 
-**NOTE:** You also need to comment out the line that looks like this in the file encoder_driver.ino:
+(You may find that it is already commented out.)
+
+**NOTE:** If you are using a version of the Arduino IDE earlier than 1.6.6, then you also need to comment out the line that looks like this in the file encoder_driver.ino:
 
     #include "MegaEncoderCounter.h"