Welcome to the atlasbuggy repository! This readme will serve as a high level design document. This code package is an attempt at making developing DIY robots easy, fun, and pythonic.
Atlasbuggy mostly uses modules in python's standard library. So the only critical dependency is python 3.5 or higher. Atlasbuggy utilizes asyncio which was made standard in 3.5.
Most dependencies can be installed with python's "pip." Depending on your installation, pip can be run by either typing "pip" or "pip3" in the terminal. Make sure you know what version of pip you have so you don't install modules to the wrong place! I'm going to assume you're on macOS or linux and pip is installed under pip3.
If you encounter permission errors on macOS or linux, try adding sudo to the beginning of your command.
However, there are some dependencies you'll want to get if you want to get the most out of this repository:
-
pyserial - for working with usb serial devices such as arduino
pip3 install pyserial
-
opencv - for camera visualization. https://www.pyimagesearch.com has some great tutorials on how to get this set up
-
flask - website hosting for remote control of robots
pip3 install flask
-
matplotlib - for data visualization
pip3 install matplotlib
-
picamera - for accessing the raspberry pi camera (obviously only get this if you're on a raspberry pi)
pip3 install picamera
-
scipy and numpy - advanced matrix manipulation. Essential for autonomous algorithms. (Numpy is a dependency of scipy and opencv)
pip3 install numpy scipy
That should be it!
Since atlasbuggy is not on pip, you can't install it that way. Python packages are installed in either dist-packages or site-packages on your computer somewhere.
Boot up your terminal application and download the repository into the directory of your choice. It will create a folder called atlasbuggy and fill it with the repository:
git clone https://github.com/AtlasBuggy/atlasbuggy.gitTo find this directory, type the following:
$ python3 # or whatever command starts the python repl for you
>>> import sys
>>> sys.pathLook for the path that ends with site-packages. If you can't find it, sys.path lists every path it checks for modules in. Search those directories until you find site-packages.
On macOS and linux, to create a link between folders (or a symlink), type the following:
sudo ln -s $PWD/atlasbuggy /usr/local/lib/python3.6/site-packagesThis is assuming my site-packages folder is called /usr/local/lib/python3.6/site-packages, I've installed atlasbuggy in ~/Documents, and I'm currently in the Documents directory. It's important to symlink absolute directories (not ../some_other_directory) so that links don't confused. $PWD inserts the current directory you're in. This operation requires administrator privileges.
Try it out:
python3
>>> import atlasbuggy
>>> atlasbuggy.get_platform() # for me this returns 'mac'
macI highly recommend PyCharm if you're developing in python: https://www.jetbrains.com/pycharm/. It's a battery guzzler, but it's free and offers some really fantastic features like jump to definition, code reformatting, and refactoring (moving and renaming elements without breaking code) to name a few. It's not necessary but PyCharm is worth at least checking out.
If you plan on creating your own robot, I recommend getting an SFTP and SSH client. Most robots run headless (without a display). SFTP and SSH allow you to access another computer's file system and terminal remotely provided you know the address, username, and password and the computer is broadcasting itself. I won't give details here since everyone's setup varies. For macOS users, I recommend Transmit by Panic (https://www.panic.com/transmit/).
Developing robotic systems is difficult. ROS (http://www.ros.org) made me an unhappy programmer, so I decided to write my own robotics development package; one that I would enjoy working with.
I used this framework I created on two robots: RoboQuasar (URL on the way),
and Naboris (https://github.com/AtlasBuggy/Naboris)
I've had a fun time developing this platform. My goal is to offer people frustrated with ROS an alternative.
By creating a pythonic collection of code that lets vastly different pieces of software play nice together independent of hardware platform. This should sound familiar to ROS. The only difference is the implementation and a few key design decisions.
We need a way of managing data transfer, low level hardware devices, high level algorithms, and user interfaces and a way to make all of this manageable and accessible.
This translates to concurrency and multitasking, low level byte transfer via protocols, subscriptions, and microcontroller programming. Thankfully, Python and Arduino (as well as other languages and platforms) makes this feasible and, for some, fun. All of these concepts will be detailed in the coming sections.
This project is a portion of a larger autonomous vehicle project. The repository can already pilot complex robotics systems, but has yet to get the autonomous vehicle across the finish line. So the main deadline as of now is April 2018, but hopefully the project will continue indefinitely.
Generally, the timeline is get the repository tested and running before returning to the main robot in fall, make sure the old low level Arduino code on the main robot still works with current system (there should be minimal changes), get manual mode operational, develop autonomous algorithms with the available sensors, perform tests, iterate until the deadline.
The audience is primarily anyone on the Atlas team, but because of the flexible nature of the code, the audience is also anyone interested in building their own robot.
Atlasbuggy will be running on all of our robots including test rigs (such as Naboris). It will be running while the robot is driving the course and offline in simulations.
Here's a collection of examples on how to use this repository effectively. I will be walking through code I've written on a high level. If you want to drive into the code, feel free. I'm doing my best to keep my comments up to date. The first two examples are in the examples folder. Each link redirects to the example's folder containing the walkthrough.