Using the Bot
This page will document how to get the bot up and running, including powering it, connecting to it and controlling it.
There are two sides of the bot's power systems: the logic side and the motor side. The logic side powers the BeagleBone Black, the wireless NICs, the ultrasonic sensors and the IR sensors. The motor side powers the drive motors, gun motors and turret servos. You can use the systems on the logic side without the motor side being powered, but you can't do intelligent things with the systems on the motor side without the logic side.
When turning on the bot, be sure to turn on the logic side first (switch 1) and turn the motor side (switch 2) off first when turning it off.
The logic side is physically located on the right side of the bot (using the standard convention that the bone is the front). By "physically located", I'm talking about its green, rectangular voltage regulators and its on/off switch.
The motor side is physically located on the right side of the bot. It has the same style on/off switch, but uses a red voltage regulator with a prominent black and copper circle.
When using the bot on the bench, it's best to power it from a bench power supply, in order to preserve the batteries. This very helpful video describes how to start with a fresh-from-the-locker bot and get it powered from a bench PSU.
Battery power is much simpler, but is only recommend if you're going to do testing that requires the bot to be mobile or away from the bench. Our batteries drain fairly quickly and charge slowly, so plan accordingly.
TODO: Video link
The bot's USB port runs to a USB hub, which drives two wireless network interface cards (WNICs).
One WNIC is set to automatically connect to the ncsu network at boot. The other is set to broadcast a wireless access point, just like your home router.
Once the 'ieeebot' network pops up, connect to it as you would any other network.
The two interfaces are bridged, which implies that while connected to the bot's ieeebot network, you'll still have a connection to the Internet through the ncsu network. See the wiki page dedicated to this subject for more details (TODO: Make this page).
The bone listens for SSH connections on the IP address 10.2.1.1 by default. After you're connected to the ieeebot wireless network, you can SSH into the bone with ssh root@10.2.1.1. The password is root.
You're now connected to the bot via it's wireless network. Congrats!
Once you've connected to the bot via one of the methods above, you have a shell and the power is yours.
To export the various pins used by the robot (PWMs, GPIOs), you'll need to run setup_all.sh, which is located in /root/startup/.
root@bot:~# ./startup/setup_all.sh
Module am33xx_pwm already loaded
It doesn't seem to be necessary to re-run setup_all.sh unless you reboot.
The start.py script in the root of the project repo (/root/bot/) is your entry point to everything in the codebase. All important actions, like starting a server, a client, an interface or running unit tests should be done from start.py. If at any time you need help with start.py, see it's built-in help by using ./start.py -h:
daniel@daniel-u bot$ ./start.py -h
ImportError: smbus module not found; I2C communication disabled
usage: start clients, servers, interfaces or tests [-h] [-T] [-8] [-t] [-s]
[-a | -c]
optional arguments:
-h, --help show this help message and exit
-T, --test-mode use simulated hardware, to allow running off the bone
-8, --pep8 run script to check PEP8 style conformance
-t, --tests run all unit tests
-s, --server start server to provide for controlling the bot
-a, --auto autonomously solve the course
-c, --cli CLI interface for controlling the bot
Before you can connect to the bot with any client, the CLI or the android client, you will need to start a control server.
The Control Server (CtrlServer, server/ctrl_server.py) is the instantiater of all of the bot's systems. For example, it builds the line follower and the gunner, which in turn build and own systems like the driver, the IR hub, the gun and the turret.
Once a CtrlServer is running, it will listen for connections via ZMQ from Control Client (CtrlClient, client/ctrl_client.py). Clients are owned by interfaces, like the CLI and Android app. They offer a service to the interface, which is to arbitrate communication with CtrlServer, thereby controlling the bot.
You can and should start a CtrlServer process on the bone by using ./start.py -s:
TODO: Update this to be an example from an on-bot run
daniel@daniel-u bot$ ./start.py -Ts # The -T flag is because I'm off the bot
ImportError: smbus module not found; I2C communication disabled # As is this error
Using simulated hardware # As is this note
Starting server
ImportError: smbus module not found; I2C communication disabled # As is this error
ctrl_server.py | __init__ | 84 | INFO | CtrlServer running in test mode # And this
us.py | __init__ | 60 | WARNING | US abstraction not implemented, range will be 0.
us.py | __init__ | 60 | WARNING | US abstraction not implemented, range will be 0.
us.py | __init__ | 60 | WARNING | US abstraction not implemented, range will be 0.
us.py | __init__ | 60 | WARNING | US abstraction not implemented, range will be 0.
ctrl_server.py | __init__ | 109 | INFO | Control server initialized
ctrl_server.py | listen | 137 | INFO | Control server: tcp://*:60000
The bot's Command Line Interface (CLI, interface/cli.py) is the canonical interface for interacting with the bot. Any functionally that is exposed by the bot will be accessible from the CLI. Other interfaces may be better at some tasks (like the Android app for driving), but none of them will expose a behavior of the bot that isn't accessible from the CLI. It's like a Swiss Army Knife - not the best at some things, but it has all the options.
The CLI can be run on or off the bot. If you run it off of the bot, you'll need to update the bot's IP address in bot/config.yaml (TODO: Directions).
You can start the CLI by using ./start.py -c:
daniel@daniel-u bot$ ./start.py -c
ImportError: smbus module not found; I2C communication disabled
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$
Get familiar with the CLI by exploring some of its built-in documentation:
bot$ help
Documented commands (type help <topic>):
========================================
EOF die exit_ctrl help list ping shell sub sub_add sub_del
bot$ help ping
ping
Ping the control server on the bot.
bot$ help list
list
List on-bot objects and methods exposed by the API.
bot$ help sub_add
sub_add <topic>
Subscribe to a published topic.
bot$ help sub_del
sub_del <topic>
Unsubscribe from a published topic.
bot$ help sub
sub
Print messages subscribed to. Ctrl+c to exit.
bot$ help exit_ctrl
exit_ctrl
Ask the CtrlServer to exit.
bot$ help die
die
Disconnect from servers and close CLI.
bot$ help shell
!|shell [command]
Send command to underlying system shell (like Bash).
bot$ help EOF
ctrl+d
Disconnect from servers and close CLI with ctrl+d.
bot$ help help
help [command]
Provide help on given command. If no argument, list commands.
Here are some examples of running these commands:
bot$ ping
CtrlServer response time: 2.02798843384ms
bot$ sub_add ir_cached
bot$ sub
Printing messages, ctrl+c to quit loop...
"ir_cached {'fresh': True, 'time': 1391759371.383329, 'readings': {'front': [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], 'right': [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], 'back': [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], 'left': [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]}}"
"ir_cached {'fresh': True, 'time': 1391759372.768573, 'readings': {'front': [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], 'right': [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], 'back': [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], 'left': [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]}}"
"ir_cached {'fresh': True, 'time': 1391759374.153081, 'readings': {'front': [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], 'right': [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], 'back': [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], 'left': [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]}}"
^C
bot$ sub_del ir_cached
bot$ sub
Printing messages, ctrl+c to quit loop...
^C
bot$ shell ls
client follower interface logs README.md start.py
config.yaml gunner lib os scripts start.pyc
doc hardware LICENSE.txt planner server tests
driver __init__.py localizer pybbb simulator
bot$ !ls
client follower interface logs README.md start.py
config.yaml gunner lib os scripts start.pyc
doc hardware LICENSE.txt planner server tests
driver __init__.py localizer pybbb simulator
bot$ exit_ctrl
ctrl_server.py | handle_msg | 181 | INFO | Received message to die. Bye!
bot$ die
Disconnecting...
Bye!
daniel@daniel-u bot$
The functionally that has been exposed by the API can be viewed with the list command:
bot$ list
Available bot objects and methods
ctrl:
- echo
- exception
- spawn_pub_server
driver:
- compound_move
- drive
- jerk
- move
- move_forward_strafe
- rotate
follower:
gun:
- fire
- fire_burst
- get_laser
- get_spin
- get_wheel_speed
- set_laser
- set_spin
- set_wheel_speed
gunner:
- aim_turret
- auto_fire
ir_hub:
turret:
To issue a command exported by the API, use the format obj method key:value, where obj is selected from the first level of list's output, method is selected from the second level, and zero or more key:value pairs provide any arguments required by the given method. It's not currently possible to see the required params from the CLI, so you'll have to either guess (they are frequently what you'd expect), check the error messages returned or look at the code (never be afraid to dig into the code - it's extremely well documented and friendly to understand!).
bot$ ctrl echo msg:blah
--> {'msg': 'Called ctrl.echo', 'type': 'call_reply', 'call_return': 'blah'}
bot$ gun fire
--> {'msg': 'Called gun.fire', 'type': 'call_reply', 'call_return': True}
bot$ driver move speed:100 angle:0
--> {'msg': 'Called driver.move', 'type': 'call_reply', 'call_return': None}
bot$ ctrl spawn_pub_server
ctrl_server.py | spawn_pub_server | 283 | INFO | Spawned pub server
--> {'msg': 'Called ctrl.spawn_pub_server', 'type': 'call_reply', 'call_return': 'Spawned pub server'}
bot$ gunner aim_turret pitch:90 yaw:90
--> {'msg': 'Called gunner.aim_turret', 'type': 'call_reply', 'call_return': None}
bot$ driver jerk
--> {'msg': 'Called driver.jerk', 'type': 'call_reply', 'call_return': None}
bot$ gun get_laser
--> {'msg': 'Called gun.get_laser', 'type': 'call_reply', 'call_return': 0}
bot$ gun set_laser state:1
--> {'msg': 'Called gun.set_laser', 'type': 'call_reply', 'call_return': None}
bot$ gun get_laser
--> {'msg': 'Called gun.get_laser', 'type': 'call_reply', 'call_return': 1}
bot$
Using the wired USB connection is easy and reliable, but has some major drawbacks. It's only suited for bench work do to your wired tether. Also, you'll lose your connection to the Internet unless you do some additional work. Unless the wireless setup is flaking out, it's best to use that method.
From the cables box, which typically lives in locker 43, you'll need a USB to Mini-USB cable. Plug the USB end into your laptop and the Mini-USB end into the bone, as pictured below.
If the bone is already booted (which implies that it's getting power from the bot), then you may need to reset it once you plug in the USB cable. Almost nothing on the bone is plug-and-play - plugging in anything new requires a reboot.
This tiny switch labeled "reset" is located on the side of the bone with an Ethernet port, near the heartbeat lights (which flash when the bone is on and not crashed). Pressing it hard-resets the bone. There are actually two switches in that area, but the reset switch is clearly labeled "reset" and is closer to the back of the bot.
On your laptop, once the bone comes up (which typically takes 30-45 seconds, but could take longer if the WNICs have trouble) you should see a new network interface:
daniel@daniel-u ~$ ifconfig
<snip>
eth4 Link encap:Ethernet HWaddr c8:a0:30:b5:4d:52
inet addr:192.168.7.1 Bcast:192.168.7.255 Mask:255.255.255.0
inet6 addr: fe80::caa0:30ff:feb5:4d52/64 Scope:Link
UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
RX packets:36 errors:0 dropped:0 overruns:0 frame:0
TX packets:647 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:1000
RX bytes:4548 (4.5 KB) TX bytes:91191 (91.1 KB)
<snip>
You can recognize the new interface by the 192.168.7.1 IP network address. You can now use SSH (or on windows, an ssh client such as putty) to connect to the bone:
daniel@daniel-u ~$ ssh root@192.168.7.2
Host key fingerprint is 11:46:25:3b:bb:8e:0a:90:5a:c1:00:f8:18:0f:fd:ea
+--[ECDSA 256]---+
|=. .=.. |
|+o. . + |
| *o. + |
|..o.. + |
|o .. S |
|.o. . |
|... . |
| E. o |
| ... . |
+-----------------+
root@192.168.7.2's password:
Linux arm 3.8.13-bone32 #1 SMP Fri Dec 13 16:57:41 UTC 2013 armv7l
The programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.
Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
Last login: Wed Dec 18 01:21:40 2013 from daniel-u.local
root@arm:~#
Root's password is root (robotics seems incompatible with security, as much as that pains me, lol). There's also typically a user called ncsubot, which uses the password bot2014. Note that you'll need to be root when doing most actions on the bot (like running setup_all.sh or starting a Control Server, see below).
You're now connected to the bot via USB. Congrats!