download jar

ATHLETE Direct Manipulation INterface

ATHLETE Direct Manipulation INterface (ADMIN) is a 1/8 scale sensed but un-actuated model of one leg of JPL's ATHLETE robot, designed to be used as a human-interface device to aid operations.

ADMIN features

• rotary sensors (potentiometers) for each ATHLETE kinematic DoF, and an extra rotary sensor for the wheel rotation
• spring-loaded friction bearings to hold joint pose against gravity
• joint mobility, link bounding volumes, and hence reachable workspace similar to ATHLETE
• tri-color R/G/B LEDs at each joint and the wheel
• two momentary-contact tactile pushbuttons at each joint and the wheel
• USB (1.1 and 2.0 compatible) communications and power
• on-board firmware with calibration storage and ASCII monitor
• host-side Java interface library

ADMIN Hardware

The ADMIN hardware was designed and fabricated using various rapid-prototyping strategies. It is functional but should be considered experimental, and should be treated with some care. It does not include protective casings. While this does not present any safety issue to the operator due to the low voltages involved, the operator should take care to discharge him/herself (e.g. by touching a large, preferably grounded, metal object) prior to handling the device. Also the device should not be operated in environments with significant dust or moisure.

The hardware is powered via USB with a maximum current draw of approximately 75mA. This is within the 100mA allowed current draw for a USB device which does not explicitly negotiate for more. A self-resetting fuse is included to protect the host USB hardware under any unforseen power conditions.

Communications is also performed over USB. The interface should be USB 1.1/2.0-compatible. The device will appear as a generic USB serial port when attached to a host, e.g. /dev/ttyUSB0 on Linux. The firmware communicates at 115.2kbps with 8 data bits, no parity, one stop bit (8N1), and no flow control. Normally the provided Java host library is used to communicate with the firmware over this port. It is also possible to exercise the various firmware functions with a generic terminal program, see below.

The USB-to-serial chip is in the same family as chips commonly used in USB-to-serial dongles, and may require non-standard drivers on some hosts. The chip manufacturer provides these drivers here. No driver installation should be required on modern Linux systems.

The joint angles are sensed with commodity ALPS RDC506002A potentiometers designed for low price miniature robotics applications. They have no hardstops and 320 degrees of electrical range (see below for details). They are specified with +/-2% linearity and are not mapped or otherwise calibrated for linearity in the current implementation. In the worst case this could mean that the joint angles are reported with up to about +/-6 degrees of error; in practice the actual error appears to be much smaller. The pot readings are digitized with 10 bits of precision, giving about 0.3 degrees resolution.

The ADMIN firmware samples all pots constantly at a configurable rate and then applies a moving-window averaging low-pass filter with configurable window size. The default sample period is 10ms and the default window size is 16, which yeilds about a 5Hz cutoff frequency. Jitter of about +/- 1 count is still to be expected in consecutive steady-state filtered pot readings (i.e. as reported by the firmware to the host) as in practice the pot will never physically be exactly at one count. The host polls the firmware for mechanism state updates and is thus in control of the highest-level update period; 100ms is a reasonable minimum host-to-firmware polling period as it will satisfy Nyquist with respect to the firmware 5Hz low-pass filter. Longer host-to-firmware polling periods are also reasonable since in practice with ADMIN highly dynamic motions will generally be transient anyway.

The firmware also stores, for each pot,

• An additive offset O which gives the raw counts when the corresponding ATHLETE joint is at zero rotation. These offsets constitute the zero calibration and are stored in nonvolatile memory on the hardware. See below for calibration procedures.
• A sign bias S, either +1 or -1, that gives the correspondence between positive pot counts and positive rotation of the associated joint. These bias values are intrinsic to the hardware design but are reported by the firmware to allow future design revisions.

joint angle in degrees = S*(R-O)*(333.3 degrees)/(2^10-1)

Some effort was expended to match the ADMIN joint ranges of motion, link geometry, and overall reachable workspace to ATHLETE. For example, the ADMIN knee can tuck into the thigh, as in ATHLETE:

• collision with the ADMIN support shaft; in particular, this limits hip yaw to just over +/- 90 degrees
• ADMIN cable wrapping
• other ADMIN self-collision.

The special case mobility for the ankle roll 1 joint is not implemented.

The knee pitch joint is handled as a special case, since for that joint the ADMIN hardware contains a secondary pot that extends the electrical range of the first. The firmware simply treats the two knee roll pots independently. The Java host library contains code to merge the two readings correctly to report a single aggregate knee pitch angle. The first pot is used unless

• its raw count is within a hardcoded slop factor of either 0 or the maximum possible raw count, (2^10-1)
• the joint is above the positive softstop.

Calibration

For each pot, the firmware stores an additive offset which gives the raw counts when the corresponding ATHLETE joint is at zero rotation. These offsets constitute the zero calibration and are stored in nonvolatile memory on the hardware. The Java host library provides several high-level methods to update the offsets. In addition, a physical calibration template is provided, which an operator can use to physically pose ADMIN in the ATHLETE nominal driving configuration: -30 degrees hip pitch, -90 degrees knee pitch, +30 degrees ankle pitch, all other joints 0. The host library contains a one-shot method to compute and update the pot offsets with ADMIN in this pose; this is the preferred calibration method.

There are a few details to consider when using the nominal pose template to calibrate the pot offsets:

• The template must be held completely flush to all contact surfaces, and the notch at the end of the template arm must be seated in the mating slot in the ankle.
• The knee and ankle roll DoF are insufficiently constrained by the template. This is a design flaw. The operator can work around this issue by visually zeroing those joints.
• The wheel is not constrained by the template. Again, the operator can visually align the silver mark on the wheel axle to (e.g.) point straight down in nominal pose.

The nominal pose template can also be used during operation to positively configure the leg into the nominal driving pose, without updating the calibration offsets.

• The red hip yaw LED is used as a firmware error indicator, see below.
• The transverse hip yaw pushbutton is checked at firmware boot; if pressed the firmware enters ASCII monitor mode.

The ADMIN firmware normally converses in a polled binary protocol with a USB-connected host running the Java host library. Holding the transverse hip yaw pushbutton while the firmware boots causes it to enter a special monitor mode (a historical name). In this mode the firmware offers the same core functionality but uses a human-readable ASCII communication protocol instead of its usual binary protocol. A generic terminal program, such as c-kermit, can then be used to interact directy for the firmware. A Kermit script is provided in the admin/firmware directory in the distribution jar, on Linux it is invoked like this: kermit admin/firmware/kermit.scr /dev/ttyUSB0. Other terminal programs can be used; the communications parameters are 115.2kbps 8N1 (no flow control, VT100 escape codes). A prompt and simple command line editing is provided. The "h" command dumps a list of the available commands. If the Java host library connects to the firmware while it is in monitor mode it will switch to binary mode.

The red hip yaw LED is used as a firmware error indicator. It will go on and stay on (until firmware reset) in the event of an unexpected and serious firmware-level error, such as host-to-firmware input buffer overflow.

The Java host library exposes most of the firmware functionality as a Java API, and also adds some higher-level functionality such as calibrated joint angle computation. It is intended that applications which use the ADMIN hardware do so via the ADMIN host library. The host library javadoc gives further details and the typical usage recipe.

An executable REPL-style interactive JScheme interpreter is also included. This is a high-level way to exercise the functionality of the device "out of the box". It is mainly intended for debugging.

The full ADMINShell JScheme API is defined in admin-shell-api.scm, with additional scheme sugar in admin-shell-extra.scm. In general, the JScheme api is a thin cover over the corresponding Java API, which itself is mapped fairly directly to the firmware monitor. For example, the JScheme command (gp hy) is equivalent to the firmware monitor command gp hy, which gets the raw reading of the hip yaw pot.

You can run ADMINShell by executing java -jar ADMIN-R33_2008-07-11.jar. You interact with the interpreter via the console, though it may be more convenient to use a console with specific support for scheme interaction, for example, Emacs Quack (tip: open admin-shell-api.scm and admin-shell-extra.scm in the same Emacs session and you'll get M-/ name completion for the ADMIN API).

• On some recent versions of Mac OS X the OS may hang after unplugging the USB cable. This issue is not specific to ADMIN but is a bug with the FTDI USB to serial driver on that platform which also affects commercial dongles using FTDI chips.
• On some recent versions of Mac OS X the RXTX library must be built and installed from current CVS; the most recent RXTX stable release does not work properly.
• On some linux distros (including current Ubuntu), there is a conflict between the brltty package and the FTDI USB-to-serial drivers. This can prevent the virtual serial port for ADMIN from appearing. A bug report has been filed. The workaround is to remove the brltty package (assuming you are not blind and using it): sudo apt-get remove brltty.
• The support shaft and cabling restrict the reachable workspace relative to the actual workspace of the ATHLETE hardware. In particular, the hip yaw DoF is limited to just over +/- 90 degrees.
• The knee and ankle roll DoF can be physically configured outside both the corresponding ATHLTE softstops and the ADMIN pot electrical range of motion. Readings will be indeterminate in this range.If the knee pitch DoF is extended past its +155 degree softstop and beyond the primary knee pitch pot range of motion there will be transient spurious readings of the knee pitch for a few seconds. This does not occur if the knee pitch is rotated in the other direction past the primary pot range of motion, in that case the secondary pot correctly takes over.
• The knee pitch angle will change sign immediately after the +155 degree softstop.
• The wheel rotation pot has a 40 degree dead-zone in which the reading will be indeterminate.
• There is no provision to calibrate the wheel rotation using the calibration template.
• The calibration template does not sufficiently restrict knee roll. The operator must visually adjust knee roll during calibration.
• The LED brightness is limited due to USB power constraints.
• The cabling may obscure some LEDs and pushbuttons in some configurations.
• The cabling may catch and require manual intervention in some configurations (e.g. extreme knee roll, knee tuck).
• USB sleep and power-down modes are not implemented.
• Firmware update requires external hardware, e.g. AVR ISP MKII.
• The Java process may have high CPU usage when using RXTX to communicate with the hardware and the hardware has been unplugged.
• Communications will fail when using RXTX and the hardware has been unplugged and re-plugged (may be platform-dependent).
• Proxy-process communications is untested in the current version of the host code.
• The file I/O communications implementation requires the serial port parameters (115.2kbps, 8N1, no flow control, no special characters) to be set externally.

The ADMIN host Java code can establish a connection to the firmware either via file I/O on a platform-dependent serial port device file, or it can use the RXTX Java serial port library for platform-independent serial port access. In the latter case you'll need to install RXTX separately.

ADMIN is released in precompiled source form under the GNU LGPL.

The distribution jar comes with everything rolled into one: java source, C source, scheme source, html (m4) source, the makefiles and related stuff, plus precompiled versions of everything (java class files, binaries compiled from C code, html, and javadoc). Further, it includes the pure java dependencies of ADMIN, which are at the time of this writing just (a slightly modified) JScheme. A lighter-weight jar is also available which does not include the java dependencies. You do not need JScheme unless you are actually running ADMINShell.

Build Requirements

The ADMIN build has been tested on Linux. Other platforms may work. You should only need to (re)build the code if you have made a change; it is distributed with pre-built binaries.

The build system is based on the Super-Ninja Makefile. You'll need

• a 1.5+ JDK with the binaries on your path
• (GNU) make and m4
• avr-gcc and avrlibc to (re)build the firmware, if desired
• avrdude, and an AVR programing device such as AVR ISP MKII to (re)flash the firmware, if desired
• the RXTX library.

The build depends on the RXTX library for portable access to serial ports. This is not a pure java dependency, RXTX contains both Java and native code. You'll need to manually install it before the build will succeed.

Note that the RXTX library need not be present at run-time unless you actually use it. For example, if you choose the direct file I/O communications option, the pre-compiled host library should not complain if RXTX is not available.

You'll probably want to create a directory into which to unpack the jar (jar xvf ADMIN-R33_2008-07-11.jar). The code for ADMIN proper will be under the unpacked directory admin/; other unpacked directories contain the bundled pure-Java dependencies.

From within the admin/ directory,

• make makefiles generates makefiles in any subpackages
• make project-clean removes most precompiled stuff
• make project-realclean removes all precompiled stuff
• make project (re)builds the binary files for the project
• make (re)builds the binary files in the current directory
• make project-javadoc (re)builds the project documentation

Disclaimer

THIS INFORMATION, SOFTWARE, AND HARDWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS INFORMATION AND/OR SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.