Orb Handbook

Basic Orb Terms

The project name is SWARM, always in all caps. A single spherical robot is an Orb. The shell is the aluminum exterior that spins.The axle runs from side to side inside the shell. Note the axle does not spin, but the shell spins around the axle. The chassis is the part with the motors and battery tray that is fixed to the axle. Above the axle, the chassis also carries the sound module -- the black tube with speakers, and the Zigbee enclosure, the tan box with the clear lid. Zigbee enclosures are labeled with the Orb Number to identify individual Orbs. Right now, Orbs are numbered 60 through 65 -- this is the last octet of the Orb's IP address. The Orbs and remote controls are labeled with the last digit of this, 0 --5. Illuminators are the circuit boards with light-emitting diodes fixed to the end of the Zigbee enclosure.

The chassis carries two motors: the drive motor is the silvery one with the metal chain, the steering motor is the black one with the rubber belt. The SPU dome is the dark shiny hemisphere with the electronics inside, so called because it contains the SWARM Processing Unit or SPU (pronounced "spoo").

The front of the orb is towards the steering pulley, the back is towards the SPU dome.

The charging connector is a white 6-pin Molex connector attached to the left axle inside the shell. The orbs are charged through this connector. Also, a loopback plug called a "fakey" is used as a main power switch by plugging it into the charging connector. The fakey is tethered so it doesn't get lost.

The kill dongle is another loopback connector that plugs into a 4-pin Molex connector on the right axle, outside the shell. The kill dongle is used as an emergency stop switch: disconnecting the dongle disables power to the motors. When not in use, kill dongles are kept in the Magic Box, which contains tools and supplies for the Orbs. A recent upgrade uses killswitches instead of kill dongles. They are gray plastic switches that protrude from the right axle, labeled with black marker in the "on" position, and like the dongles they control power to the motors. Check the killswitch is off before reaching inside the Orb! Check the killswitch is on if the Orb doesn't move.

The Yellow SWARM Toolbox contains tools and spare parts. It would be a bad bad thing to lose it or the tools inside, so keep an eye on it.

The H-Bridges are the power controllers for the motors. They are the aluminum boxes attached to the lower sides of the chassis near the motor they control. Drive H-bridges have current sensors; steering H-bridges do not. Drive H-bridges can be identified by their blue motor+ output wire (steering bridges have red).

The Mother Node is the computer that controls all the Orbs. Typically your joystick is connected to the Mother Node, which then sends remote control commands to the individual Orbs.

In some cases, we will be using Zigbee Remote Controls instead of the Mother Node, so in that case disregard any instructions about the Mother Node.

How To Run Them Orbs

Insert fakey plug on left orb axle (inside shell). This is the main power.
Power up SPU dome with switch on back (up is ON).
Test serial communication by sending LED commands. If not OK, see troubleshooting below
Turn on kill switch on right orb axle (outside shell) to enable motors.

Disable Orb motors by turning off kill switch when not under direct control or if Orb misbehaves!

How To Shut Down Them Orbs

Do not insert hands inside shell with kill switch on!

Turn off kill switch. If using kill dongles, remove, and replace in Magic Box.
Power down SPU dome by turning off switch in back of dome). OFF is down.
Remove "fakey" plug from charging connector on left orb axle (inside shell).

After running orbs, please log any problems in the Maintenance Blog. Otherwise we will have an unpleasant surprise the next time we want to run them!

How To Drive Them Orbs

If you've tried it, you know they are a little more challenging to drive than RC cars.

The right joystick operates motion. Up/down is forward/back on the drive motor, left-right is ditto on the steering.
Start with simple forward/back motion. Learn how to stop -- that's important. Learn how to counter forward momentum with a momentary rearward motion.
Know which way the Orb is facing. Getting it wrong can confuse the driver. The dome -- with the blinky red light -- is in the back. If you can see it (the blinky red light), the Orb is facing away from you.
Keep the Orb close enough that you can see it and the people around it.
Note the joysticks have limited range and can't transmit through many materials, and the range decreases as the batteries get weak. If you are having control issues, first try getting closer to the Orb.
When you are comfortable with forward/back, try steering. It's pretty easy to do donuts if you peg the steering hard left or hard right (on flat surfaces, anyway).
When you can do donuts, try for figure-eights and follow-the-leader.
See the later section for how to control lights and sounds and extra remote control features.

Don'ts

Don't lose control. Heavy-handed steering will causes the Orb to rock sideways, from which it's hard to recover.
Don't hit people or things. The orbs are heavy and sharp and can hurt people, gouge furniture and walls and break things, not least themselves!
Don't hit other Orbs. Yes, they seem sturdy, but the shells are getting dented and that's basically unfixable.
If you hear a gear grinding noise from the orb (it sounds a bit like a person grinding the gears on a manual transmission car) slow down and play more gently! That is the sound of gears grinding, which is not good. (Or it could be a loose steering belt which needs to be fixed).
Avoid electric wires, air hoses and the like, even once. The sharp edges of the shell may damage them!

Driving Musts

You MUST be aware of which way the Orb is facing at all times. Once again, the front of the orb is towards the steering pulley, the back is towards the SPU dome. Unlike RC cars and planes, it's not obvious, and if you get it wrong you will run into things, with possibly catastrophic consequences. If the Orb is facing you, you must mentally reverse left and right to steer correctly. Practice putting yourself in the place of the Orb.

Driving Hints

They can be very sensitive to inclines. If the orb keeps leaning in one direction, it may be because it's on a slight hill.
Drive gently. To keep them from swaying left and right uncontrollably, change your drive controls slowly.
The controls are proportional. Lean the joystick a little bit to the left and the orb will lean a little bit to the left.
An orb will turn only when it's moving. It helps to start driving forward and then start your turn. Start your turn slowly else the orb may start swaying left and right uncontrollably.
If an orb is swaying left and right dramatically, you can help it stop by countering the motion with left and right motions from the joystick. This can be very tricky; you have to lead your target by several seconds.

For a more complete discussion on driving orbs, see detailed driving guide

Interacting with Foolish Humans

One of the most rewarding (and frustrating) things is to operate an Orb in a crowd and see how people interact with them. Typically, people will stand right in front of your orb. Resist the temptation to take them out, and reverse direction. No doubt someone will then stand behind your Orb blocking motion: in this case, trigger lights and sounds, and perhaps wobble with the steering. Under no circumstances should you attempt to nudge someone out of the way -- at some point they will get board and let you through. FIRST LAW OF ORB OPERATION: NEVER WILLINGLY CONTACT A HUMAN. Orbs are heavy and sharp and it's impossible to calibrate how much force you are actually contacting people with.

Occasionally foolish humans will attempt to push an Orb: please stop this quickly! Sharp words are warranted here. Pushing them in the axis direction of the axle can put a lot of strain on the steering mechanism and can actually damage them. Standing on an Orb or pouring beverages on them is also not welcome.

Dedicated Remote Controls

Right joystick controls power and steering. (This is reversed from the computer version, so you can control it with only your right hand, and keep the control at your side or back) Pressing down on right joystick hard triggers "identify" sequence: orb flashes white so you can see which one you are driving.

Left stick controls lights. Up/down is brighntness, left/right is color hue. Pressing down on left joystick hard triggers "All Stop:" sends zero commands to power and steering. (Note that a better way to stop when rolling is to reverse power briefly).

Right triggers control sounds. There is a list of sounds that gets cycled through. Pressing the bottom trigger plays the sound and goes to the previous one on the list, wrapping around if necessary. Pressing the top trigger plays the sound and goes to the next one on the list. Yes, you can't play the same sound more than once: kind of by design.

Left triggers control lights and sound. The top trigger cycles through a number of colors. The bottom trigger stops the currently playing sound and turns off all the lights.

The "Macro" button to the bottom left of the left joystick causes left joystick color commands to be transmitted to all orbs. Not tested on all joysticks, YMMV.

Turbo mode: The "vibration" switch on the bottom of the stick, when set to "MAX" gives additional power to the drive motor, if needed for a low-battery situation or otherwise. If you don't need it don't use it. Some switches are reversed, so "OFF" is max power. You can tell when you are in turbo mode as the heartbeat LED will flash twice as fast.

Shelling and Unshelling an Orb

Tools live in the Yellow SWARM Toolbox. Make sure they are replaced there or we are screwed!

Tools you will need:

7/16 low-profile ratchet (for shell bolts)
3/16 ball-end hex key, aka Allen wrench (for shaft collars)
Two-by-four scrap or soft mallet (to center the chassis)

Very important: Make sure the shell slots are vertical. The drive shaft has tangs that fit into slots welded to the inside of one half shell. These slots should be vertical. If they aren't, the weight of the chassis can bend or break them. Always check this before shelling or unshelling an Orb.

It's easiest to shell/unshell an orb on a table, but you can do it on the floor.

Shelling an Orb

Shelling an orb is at least a two-person job. Really. Three people make fastening the bolts go faster. Make sure everything you need (tools, bolts, shell halves) are within easy reach before you start. It's easier to do on a table but the ground works too.

Start with the shell half that has the drive slots. Person A holds the shell nearly on edge, remembering to keep the drive slots vertical. Person B twists the driveshaft on the chassis so the tangs are vertical. Then person B lifts the chassis, and guides the axle into the bearing, making sure the tangs mate with the shell slots. Person A can help spot the axle through the bearing. Note that the bearing is inside a ball joint and may not be aligned with the shell: you can realign it to better match the incoming axle.

Once the axle is through, Person B fits the other end of the axle through the bearing on the other half of the shell, while Person A keeps the first half nearly vertical. This may be tricky.

Once the axle is through, align the shell halves. You will need to push them together and rock them in the direction of the axle so both are vertical. Try to make sure the chassis is centered.

Install the shell bolts every 4th hole. Note that every other hole is not usable as the shell ribs are too close. (these are called "fake" holes). Thus insert a bolt every second "real" [usable] hole, or every fourth hole. Start with the real hole closest to the top. You can then spin the orb around the axle to reach all the holes. Tighten the nuts securely but don't overtighten.

Once the shell is bolted, check that the chassis is centered. In some cases you might need to persuade the chassis back to center by whacking the axle with a soft mallet or scrap of wood. (Don't use a metal implement: you risk mushrooming the axle, making it impossible to remove.) When the chassis is centered, install both shaft collars. They don't need clearance from the bearing as the part they touch doesn't rotate.

Congratulations, you have shelled an orb.

Unshelling an Orb

Unshelling an Orb is basically reverse the procedure. When pulling apart the shells, MAKE SURE THE TANG IS VERTICAL, and be careful the heavy chassis doesn't drop as the axle slides out of the bearing.

Don't lose the hardware. I repeat, Don't lose the hardware. If the Orb is to be apart for any length of time, put the hardware in the left tray on the lid of the Yellow SWARM Toolbox.

Gigging With Them Orbs

Orbs are too heavy for one person to lift, even if you crazy strong like Hulk. Don't risk your back or an Orb: lift them with two people. Hold them by the axle, or the rim of the shell by the axle (but note that if you lift the shell the chassis may swing). Bystanders are usually happy to help, and with two people it's light enough for most anyone.

One person can roll an orb. They roll much better when powered down (remove the fakey).

Ideally, when we move Orbs they are in crates. Realistically we will need to cram them into whatever vehicles we have appropriated. Strap them down if there is any chance of rolling. Pad the contact points so they don't chew each other up or your vehicle, which they will. Moving blankets and/or cardboard work well.

When returning Orbs to the shop, make sure they are charged and covered to protect them from metal shop dust. Clean them if necessary, and don't forget to add notes to the Orb Maintenance page (even if everything went fine, that's good to know).

Using stands? Here's how to set them up: Orb_Stands#Using_the_Stands

Organizing and Troubleshooting

Orb Performance Checklist

Bring the Orbs
1. If uncrated, straps, tie-downs and pads for transportation
2. If crated, a screw gun and bits to uncrate
Bring the Mothernode
1. The Mothernode computer with appropriate software. (Not all computers play nicely with multiple joysticks; if in doubt, test it out BEFORE the gig).
The Magic Box should theoretically have everything else necessary
1. Kill Dongles for each Orb, plus spares
2. Enough joysticks for each orb
3. USB hub for multiple joysticks
4. Spare joystick batteries (2 AA per joystick)
5. Zigbee transmitter
6. Serial or USB-serial cable
7. Power supply for Zigbee transmitter
8. Tools, including pliers to fix kill dongles
Bring the chargers if necessary
1. Power strip. Bring a spare and make friends.
2. If you don't bring an extension cord Murphy's law guarantees you will need one. Bring it.
Bring the stands (if using them)
1. Bring a 3/16 hex key to tighten the shaft collars. Don't lose shaft collar hardware.
2. Don't lose the struts that hold the stand legs apart (each has two).
Supplementary
1. 2 pair of light gloves to lift orbs with
2. padding (cardboard etc...) to protect them in transit
3. Stickers
4. Mailing list sign-up sheet
5. Other schwag
6. Signage, etc.
7. A small table for the Mothernode, and/or schwag

(from the top of my head: anything else? Jtfoote 09:24, 8 November 2007 (MST))

Orb Maintenance

Chains need to be cleaned and lubed on occasion.
The shells have been successfully deplayafied with a pressure wash at the 24-hour car wash at Potrero & Caesar Chavez.
On occasion push some lube through the flange and pillow block bearings on the shells with a grease gun

When not in use, keep the batteries full. Either leave them on an automatic charger (the SWARM chargers are automatic) or charge every 2 months. Charge the orbs on the "2 Amp" and "Gel Cell" charger settings.

Troubleshooting

Problem: Chain derailled. Reinstall chain using master link (remove/reinstall with needle-nose pliers). Though it is sometimes possible to reinstall the chain by "walking" it around the sprocket, this puts a lot of tension on the motor mount so it is not recommended. Check tension on motor: are the mounts slipping?

Problem: No motion. Check:

Kill dongle is installed and firmly seated or killswitch is on and connections are good.
Kill dongles are prone to accidents. Inspect wiring, crimps, pins, and sockets for damage.
Check fakey is firmly seated.
Check 24V battery bus by measuring voltage between kill dongle connector and axle (one pin will have a higher voltage, use that) -- it should be above 24 volts.
Check SPU power (below).
Check communications

Test: Daughterboard LED inside dome should blink red immediately after power applied. Fix: Check Fakey is completely inserted. Check SPU power switch (on back of dome) is on. Check dome fuse in fuse block (lower left), master fuse (lower right)

Test: SPU inside dome should blink green after boot (3-4 seconds after power applied) Fix: Check Fakey is completely inserted. Check SPU power switch (on back of dome) is on. Check dome fuse in fuse block (lower left), master fuse (lower right). Check electronics power is 12V or more (Measure voltage at 12V power stud on back lower right of SPU dome (when facing dome) and chassis).

Test: LEDs on power up should all light very dimly Fix: Check fakey, check 24V bus

Test: Aggregator is powered on and the leds on the board are blinking(see section on serial troubleshooting for more details) Fix: Check if SPU is powered on. Check PS2 serial connector that connects the GPS to the aggregator, make sure aggregator is connected to the spu via the serial cable connected to the dome, check batteries in remote, check electronics power.

Test: Zigbee module has power, blinks red light Fix: check Zigbee fuse in fuse block, 12V power bus

Test: No sound Fix: Check amplifier fuse in fuse block. Listen for faint hum. If still no sound, see "communication troubleshooting" below.

Serial troubleshooting

If using XBee receiver board(v1.0)

Test Zigbee transceiver power: Check: red light blinks on Zigbee

Test: connection from mothernode computer to Zigbee transciever. Zigbee green LED should light on transmit. Sanity check: from SPU testcom program send '+++' to COM2; Zigbee chip transciever should respond with 'OK'. Use 38400 serial baud connection, 8-1-N, no flow control.

Test: Commands from mothernode to Orb Zigbee. Check: Orb Zigbee module yellow LED will blink on receipt of serial data.

Test: Commands from mothernode to SPU: Check: SPU red LED will blink (don't confuse SPU red LED with daughterboard red LED. SPU red LED is immediately to the left of the green SPU LED.) Check: COM2 Serial connection to back left of dome is plugged in, Zigbee power as above

Test: Commands from mothernode through zigbee, spu to LED board: Check: COM3 serial connection on back right of dome is plugged in. LED pods have screw-terminal serial connections which can be problematic: check these for continuity.

If using aggregators(v2.1)

There are two green leds on the aggregator board that signal XBee and GPS activity. The one closest to the blue XBee chip indicates XBee serial activity. The other led indicates GPS serial data.

Test: Toggling a remote should make the XBee led blink. Check: Remote, spu and aggregator power check

Test: The GPS led should be blinking contiously

Test: If still not working check brownout fuse in aggregator. It should be set at 2.7 V. Easily done using avr studio.

Swarm serial protocols

The complete list of messages is under Communications in the Mother Node page http://wiki.orbswarm.com/index.php?title=Mother_Node

Illuminator protocol is defined here - http://svn.lee.org/swarm/trunk/Illuminator/illuminator_src/Illuminator_API.txt

Motor Control/Daughter Board protocol is defined here - http://svn.lee.org/swarm/trunk/motorControl/dboard/MCU_API.txt

Steering troubleshooting

The steering motor is servo-controlled in a feedback loop that depends on a sensing potentiometer to report the correct angle of the chassis. If the feedback loop is broken due to mechanical or electrical problems, the steering motor won't stop and will force the chassis against the axle.

Problem	Cause	Solution
Intermittent, loud "clicking" or "snapping" sound	Steering belt is slipping	Tighten steering belt
Steering is far off center	Steering pot is not centered	Recenter pot or recalibrate
Steering goes immediately off to one side	Steering pot shaft is loose	Check steering pot shaft setscrew
Steering goes immediately off to one side	Steering pot feedback	Check steering pot connections, including header inside SPU dome

Serial Information

The SPU communicates with the Zigbee on COM2, with the motor controller on COM5, and with the LED/sound chain on COM3. COM4 is not used; COM1 is the DB-9 on the SPU board which is used as a login of last resort (if the ethernet is dead).

SPU programs

Each SPU has a command called 'testcom' which acts like a (particularly dumb) terminal. It takes stdin from the keyboard and pipes it to the selected com port, and takes data from the com port and prints it. It is hardwired to 38400 baud using the same code that opens the com port for the other SPU programs. The com port is selected with a single argument which is a digitl thus "testcom 5" opens com5. You can use testcom to test the various serial ports; for example to test the motor controller, you can send a $?* query to the daughterboard motor controller by typing the following:

>testcom 5
$?*

Testcom is not good about echoing remote input: you may need to hit return a few times to see it.

NOTE to use testcom you must kill any other process talking to the serial port, such as the dispatcher which is automatically started at powerup. Do a

ps -a

to see other processes are running. If you have trouble with testcom, ensure the green light is not blinking.

To test LED pods, log into the SPU, kill the dispatcher and anything else that might be talking to com3. Then run "testcom 3" and type the following example command:

<LG255><LF>

This will set all green LEDs to maximum brightness on all pods. To test individual pods are addressed with numbers from 0 to 3. To test addressing an individual pod (say pod 2), type

<L2R255><LF>

which will set the red LEDs on pod 2 only to full brightness. You can probably guess the illumination control syntax from these examples, for full documentation and more examples see the API here: http://svn.lee.org/swarm/trunk/Illuminator/illuminator_src/Illuminator_API.txt

Avoid "LA" commands as these will change the address of all the pods!

Serial Pinouts

The Zigbee/Aggregator connector (COM2) is the DB9 on the left side of the bulkhead (facing the dome). COM2 is a female connector but looks like DCE -- that is, you will need a null modem to talk to it from a computer. The Zigbee enclosure is wired as DTE: if you unplug it you can talk to it without a null modem but you will need a female-female DB9 gender changer.

The LED/sound chain (COM3) serial port is the DB9 is on the right (again, facing the dome). This is also wired as DCE, but it has a male connector (so as not to be inadvertently mistaken for COM2). You can talk to the LED chain by unplugging it. It should work with a straight serial cable.

Fuses and the Fuse Block

If a fuse blows, something is badly wrong. Unless you are absolutely sure you know what you are doing, do not replace the fuse, and do not continue to run the orb. Whatever condition blew the fuse could very well destroy expensive electronics or even cause the batteries to explode.

There are two 24V motor fuses, one for each H-bridge. They are located very near each H-bridge on the input 24V wire. We have been using 20A fuses.

There is a 12V fuse block on the inside of the chassis towards the back. In normal operation this has four fuses; all can be 5A or 10A. The fuse at lower right (facing the fuse block) is the master fuse for the block. The three fuses on the left are, from top to bottom, the Zigbee fuse, the sound/amplifier fuse, and the SPU fuse. Any subsystem can be disconnected for testing or other reasons by pulling its fuse. The two open locations at top right are used to store spare fuses.

In the current design, the LED pods run on 24V and are not fused. If this strikes you as suboptimal, you are correct.