Evolving codebase for a SLAM-capable robot using the RoboPeak LIDAR sensor

All directories and files used by the SLAMbot.

Current stable release of our slambotgui package. To install on your machine, download and unzip the file, then run the setup.py script with command-line option install. To download and unzip:

wget https://github.com/AerospaceRobotics/RPLidar-SLAMbot/raw/master/SLAMBotGUI-0.2.tar.gz
tar -zxvf SLAMBotGUI-0.2.tar.gz
cd SLAMBotGUI-0.2/

If you do not want to install the package yet, you can test the distribution now (there are several user preference flags near the top of the readLogData python file, which you should play around with to ensure full functionality):

python readLogData.py

To install the package:

sudo python setup.py install

If you received no errors, test your install by:

sudo rm -rf slambotgui/
python readLogData.py

If that works, congratulations, it's installed! You can now do global imports of any of our provided classes into your code. If you have a LIDAR unit with an Arduino interface, check out the comms module and how we use it in baseStationMain.py, also included in the distribution.

The files required by the robot to run its sensors and support its functionality.

The libraries we use in the Base Station code, but are not required, are PIL and OpenCV. We also use numpy, scipy, and matplotlib, which need to be installed explicitly:

sudo apt-get install python-numpy python-matplotlib python-scipy

Although not required, OpenCV dramatically improves the performance of this library. Matplotlib can only achieve a refresh rate of 2hz, while also bogging down the rest of the program. Installing OpenCV is notoriously tricky, but we've had the pleasure of figuring out the best way to do it so that you don't have to (link). * To start off, you'll need to download the highest version number opencv.sh from this repository. We've included the current one (2.4.9; as of this writing) in our repo for your convenience:

wget https://raw.githubusercontent.com/AerospaceRobotics/RPLidar-SLAMbot/master/libraries/opencv_ubuntu.sh
chmod +x opencv_ubuntu.sh
./opencv_ubuntu.sh

This will take a long time, so go ahead and give the rest of this README a looksy while you wait! If it fails, check out the link above.

*working on an ODROID? Do this instead:
Try the steps immediately following this paragraph. We got this from the ODROID forum, and it works for us on our ODROID XU3-Lite which is running the Lubuntu image from ODROID.

wget https://raw.githubusercontent.com/AerospaceRobotics/RPLidar-SLAMbot/master/libraries/opencv_odroid.sh
chmod +x opencv_odroid.sh
./opencv_odroid.sh

Python and C++ files to enable SLAM, released as open-source BreezySLAM (link).

Allows precise, high-frequency, low-overhead encoder monitoring (link).

Provides simple methods for retrieving data from the RPLidar sensor (link).

Arduino code for the Seeeduino Mega on our slamBot. Encoder and RPLidarDriver should be placed in the sketchbook folder to be properly added by the Arduino compiler at compile-time. Cannot be run on an Arduino with fewer than 4 serial ports if full functionality is to be maintained. Hence, we recommend the Arduino Mega, or the Seeeduino Mega, which has more features.

Working directory for our slambotgui package, which combines serial protocol, XBee configuration, robot control, SLAM processing, and several GUI options for any robotics system (currently designed for use with an Arduino-based SLAM-enabled robot).

Contains all base station code to run the slamBot. BreezySLAM for Python must already be installed on your machine to use this code. Written in Python 2.7.6, tested and functioning in Python 3.4.0. Written and tested in Ubuntu 14.04, however should run on all Linux machines. Have not tested in Windows or OS X. BreezySLAM does not support Python 3.x as of this writing, however we are working on that. OpenCV does not currently support Python 3.x, however the dev build is available and reportedly functioning (link). We highly recommend running Python 2, but are trying to support Python 3 through a possible future transition to PyQt from Tkinter.

Stripped-down version of baseStationMain.py designed to be used to read log files without communication with the robot.

Script used to create tarball file and install package.

Main package directory.

Serial communication thread. Custom serial protocol very easy to implement.

Physical robot parts, including the specific hardware we're using in our project. Contains generalized Robot and Laser classes.

Tkinter frames used in our GUI. If FAST_MAPPING is true, only EntryButtons is used, which serves as the robot control panel alongside the OpenCV display window.

Data objects to store map information.

BreezySLAM-base SLAM classes.

OpenCV helper class from the BreezySLAM creator, Simon D. Levy. We made minor modifications and use it for rapid-mapping (matplotlib is very slow).

Log files included with current stable distribution.

File we've created using baseStationMain.py to allow for project demonstation without the accompanying hardware. The file is ascii-encoded space-delimited decimal, where scans are newline-delimited, and each scan takes the following format:

<int16_t left_wheel_ticks> <int16_t right_wheel_ticks> <uint16_t counter_ms> <scan value at 0deg> <scan value at 1deg> ...

List of all files in current stable distribution.

Images generated by baseStationMain.py.

Image file created by reading the log data in the corresponding log file. Just as in the naming of the log file, room_size in the file name denotes the approximate size of the room mapped in the log file.

Note: If you receive the "Invalid serial port," it is likely due to serial port permissions. Fix with: sudo gpasswd --add ${USER} dialout then log out and back in. Allows you to use non-standard baud rates on a Linux machine (more info: link). If you receive the error "Inappropriate ioctl for device", traced back to within pySerial, apply this patch. Please note that this appears to be fixed in the current (accessed 29DEC2014) release of pySerial. If you try to apply the patch and the patch fails, the problem has probably already been fixed in your version of pySerial.

Contains all the patch information for Python 2.x.

Created with diff -u serialposix_old.py serialposix_new.py > pyserial.patch.

To use:

cd /usr/lib/python2.7/dist-packages/serial

or

cd /usr/local/lib/python2.7/dist-packages/serial

depending on where pySerial is installed on your machine. Then do:

sudo patch serialposix.py < /[path of patch file]pyserial.patch

which would probably look like:

sudo patch serialposix.py < /[path of this repo]/Linux\ Custom\ Baud\ Hack/Python2/pyserial.patch

if you've simply cloned this repo instead of downloading just the patch file.

This is our backup of the serialposix.py file.

This is what your serialposix.py file should look like after applying the patch.

If you receive the error TypeError: 'str' does not support the buffer interface, traced back to within pySerial, apply this patch (more info: link). The second patch in the patch file addresses this issue (the first is the baud rate hack).

Created with diff -u serialposix_old.py serialposix_new.py > pyserial.patch.

To use:

cd /usr/lib/python3/dist-packages/serial
sudo patch serialposix.py < /[path of patch file on your machine]/pyserial.patch

This is our backup of the serialposix.py file.

This is what your serialposix.py file should look like after applying the patch.

Fixes list_ports in Python 3. Do not apply this patch to pySerial if you are running Python 2.x.

If you receive the error TypeError: can't use a string pattern on a bytes-like object, traced back to within pySerial, apply this patch (more info: link).

Created with diff -u list_ports_posix_old.py list_ports_posix_new.py > listports.patch.

To use:

cd /usr/lib/python3/dist-packages/serial
sudo patch tools/list_ports_posix.py < /[path of patch file on your machine]/listports.patch

This is our backup of the list_ports_posix.py file.

This is what your list_ports_posix.py file should look like after applying the patch.

Enables pin control for digital 70-85 on Seeed Studio's Mega. Ubuntu has patch and diff built-in, but if you're using a different OS, we recommend manually replacing the files. Note that the first patch is optional, but we recommend it as it allows easily switching back to the unmodified Arduino IDE code.

Contains the location of the files we're modifying, on both Windows and Ubuntu. Note that your installation may be in a different location. You will need to find it before applying the patches.

Add "Seeeduino Mega" board type to Arduino IDE menu. Created with diff -u boards_old.txt boards_new.txt > seeedmega_menuctl.patch.

To use:

cd /usr/share/arduino/hardware/arduino/
sudo patch boards.txt < /[path of patch file on your machine]/seeedmega_menuctl.patch

This is our backup of the boards.txt file.

This is what your boards.txt file should look like after applying the patch.

Add new board type defining the Seeeduino Mega's pin definitions. Created with diff -u mega/pins_arduino.h seeed/pins_arduino.h > seeedmega_pindef.patch.

To use:

cd /usr/share/arduino/hardware/arduino/variants/
sudo cp -R mega seeed
sudo patch seeed/pins_arduino.h < /[path of patch file on your machine]/seeedmega_pindef.patch

This is our backup of the mega/pins_arduino.h file.

This is what your new seeed/pins_arduino.h file should look like after applying the patch.

Example Seeeduino Mega code demonstrating use of extra pins, with some low-level stuff.