Dev Environment Setup
This wiki will describe the repos our code lives in and how to clone them into a coherent codebase, suitable for development.
If you don't have the required packages installed, I suggest going ahead and doing that first. Here's a wiki that describes how to do so.
We currently use a number of repos to version control our code. Each repo contains a more or less distinct project. Our main codebase is a repo called bot, or IEEERobotics/bot. Our other repos are dependencies of bot, which have been broken out to allow reuse by other projects and a cleaner architecture.
Bot is our main repo, with our main codebase.
This repo is our Android interface. Its code is in Java, as is typical for Android apps.
This is the repo for DMCC code. We're currently working from an unmerged fork, which we intend to merge back into Exadler's codebase after SoutheastCon.
The main pybbb project provides easy to understand, pure Python support for interacting with the BeagleBone Black's hardware, such as its GPIO and PWM pins. We're currently working from an unmerged fork, which we intend to merge back into Jeff's codebase after SoutheastCon.
This project provides a very cool way of building a generic I2C device that can support diverse hardware, given a YAML description of the hardware's I2C configuration.
If you're not familiar with Git, I suggest taking a detour and learning the basics. See our Git wiki for resources.
Devs will need to clone the various projects onto their local machines for development. The rest of this section will assume that you're in the directory in which you wish to store our code.
In order to avoid having to type your GitHub authentication information painfully frequently, you'll want to generate a public key pair for authentication with GitHub.
[~/robot/current]$ ssh-keygen
Generating public/private rsa key pair.
Enter file in which to save the key (/home/daniel/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /home/daniel/.ssh/id_rsa.
Your public key has been saved in /home/daniel/.ssh/id_rsa.pub.
<snip>
You now have a public key pair, composed of a public and private RSA key, in ~/.ssh.
[~/.ssh]$ ls
config id_rsa id_rsa.pub known_hosts
On GitHub, navigate to your profile, then select "Edit Your Profile" from the upper right corner, and finally choose "SSH Keys" from the field on the left.
Choose the "Add SSH Key" option and give your key a name. Finally, copy the complete contents of ~/.ssh/id_rsa.pub into the "Key" field.
Click the green "Add Key" button to submit the key.
You'll now be able to authenticate to GitHub from this machine, using your new keypair.
Start by cloning our main repo and the IEEERobotics/pybbb repo, as a submodule:
[~/robot/current]$ git clone --recursive [email protected]:IEEERobotics/bot.git
Cloning into 'bot'...
<snip>
Submodule 'pybbb' ([email protected]:IEEERobotics/pybbb.git) registered for path 'pybbb'
Cloning into 'pybbb'...
<snip>
Submodule path 'pybbb': checked out 'c43a62d47729afd918d6771da880de5887373142'
Note that the --recursive flag pulls the pybbb submodule in a single, easy step. If for some reason you already have IEEERobotics/bot and just need the submodule (bot2014/pybbb is empty), then run the following from the root of the repo:
git pull # Always a good idea
git submodule init
git submodule update
To clone the DMCC library, navigate to the directory above the main codebase and clone it in the normal way:
[~bot]$ cd ..
[~/robot/current]$ ls
bot
[~/robot/current]$ git clone [email protected]:IEEERobotics/DMCC_Library.git
Cloning into 'DMCC_Library'...
Warning: Permanently added the RSA host key for IP address '192.30.252.128' to the list of known hosts.
remote: Reusing existing pack: 165, done.
remote: Total 165 (delta 0), reused 0 (delta 0)
Receiving objects: 100% (165/165), 54.42 KiB | 0 bytes/s, done.
Resolving deltas: 100% (75/75), done.
Checking connectivity... done.
From the dir above the main codebase (same one that contains DMCC_Library and bot dirs):
[~/robot/current]$ git clone [email protected]:jschornick/i2c_device.git
Cloning into 'i2c_device'...
Host key fingerprint is 16:27:ac:a5:76:28:2d:36:63:1b:56:4d:eb:df:a6:48
+--[ RSA 2048]----+
| . |
| + . |
| . B . |
| o * + |
| X * S |
| + O o . . |
| . E . o |
| . . o |
| . . |
+-----------------+
remote: Reusing existing pack: 142, done.
remote: Counting objects: 3, done.
remote: Compressing objects: 100% (3/3), done.
remote: Total 145 (delta 0), reused 0 (delta 0)
Receiving objects: 100% (145/145), 30.70 KiB | 0 bytes/s, done.
Resolving deltas: 100% (69/69), done.
Checking connectivity... done.
For easier development, we suggest installing jschornick/i2c_device and IEEERobotics/DMCC_Library to a virtual environment. This is basically just a directory that contains a copy of the Python binary and a bunch of other Python-relevant files. When you source the virtualenv, that new Python binary is added to the front of your path, and future searches for code are relative to the location of that binary. If you don't have virtualenv installed, you'll need to go ahead and do that.
[~/robot/current]$ virtualenv --clear --system-site-packages venv
Not deleting venv/bin
New python executable in venv/bin/python
Installing Setuptools..............................................................................................................................................................................................................................done.
Installing Pip.....................................................................................................................................................................................................................................................................................................................................done.
You can now source the ./venv/bin/activate script to load the virtual environment.
[~/robot/current]$ source venv/bin/activate
(venv)[~/robot/current]$
Notice that it modified my $PROMPT environment variable to add the name of the virtualenv that's active.
Prompt without virtualenv:
[~]$ echo $PROMPT
%{$fg[cyan]%}[%~% ]%(?.%{$fg[green]%}.%{$fg[red]%})%B$%b
Prompt with virtualenv:
(venv)[~/robot/current]$ echo $PROMPT
(venv)%{$fg[cyan]%}[%~% ]%(?.%{$fg[green]%}.%{$fg[red]%})%B$%b
More importantly, notice that the path to the virtualenv is now the first entry in my $PATH (so it will be searched first when looking for things like the Python binary).
Path without virtualenv:
[~]$ echo $PATH
/home/daniel/bin:/usr/local/bin:/usr/lib64/qt-3.3/bin:/usr/local/bin:/usr/bin:/bin:/home/daniel/bin:/usr/local/sbin:/usr/sbin
Path with virtualenv:
(venv)[~/robot/current]$ echo $PATH
/home/daniel/robot/current/venv/bin:/home/daniel/bin:/usr/local/bin:/usr/lib64/qt-3.3/bin:/usr/local/bin:/usr/bin:/bin:/home/daniel/bin:/usr/local/sbin:/usr/sbin
You can now install jschornick/i2c_device and IEEERobotics/DMCC_Library to the virtualenv. Be sure that your virtualenv is active, as described above.
Install jschornick/i2c_device:
(venv)[~/robot/current]$ ls
bot DMCC_Library i2c_device venv
(venv)[~/robot/current]$ cd i2c_device
(venv)[~/robot/current/i2c_device]$ python setup.py install
running install
<snip>
Install IEEERobotics/DMCC_Library:
(venv)[~/robot/current]$ ls
bot DMCC_Library i2c_device venv
(venv)[~/robot/current]$ cd DMCC_Library
(venv)[~/robot/current/DMCC_Library]$ python setup.py install
running install
<snip>
If you've completed all of the above steps, and installed the required third party packages, you should be ready to contribute to the codebase. Congrats!
Note that it's currently required to run the unittests with ./start.py -t to create the simulated hardware files before issuing commands like the example below. See issue #112 for details.
(venv)[~bot]$ ./start.py -Tsc
Using simulated hardware
Starting server
ctrl_server.py | __init__ | 84 | INFO | CtrlServer running in test mode
<snip>
ctrl_server.py | __init__ | 109 | INFO | Control server initialized
ctrl_server.py | listen | 137 | INFO | Control server: tcp://*:60000
Starting CLI
CtrlClient connected to CtrlServer at tcp://127.0.0.1:60000
SubClient subscribed to PubServer at tcp://127.0.0.1:60001
bot$ ping
CtrlServer response time: 1.29008293152ms
bot$