mini-ARC README version 1.4, May 1996 copyright 1996, Newton Labs, Inc. mini-ARC is software for owners of a Pioneer 1 Mobile Robot equipped with a Fast Track Vision System (FTVS). It lets you directly communicate with and control the Cognachrome Vision System from Newton Labs, Inc. that has been integrated as an onboard robotic sensor. mini-ARC's primary function is to custom configure the FTVS for later use by the SaphiraŞ client software licensed from SRI, Inc. which accompanies every Pioneer robot. As the name implies, mini-ARC is a subset of a much larger collection of routines for operation and development of vision-based applications. For more information, additional version, and detailed documentation, browse Newton Labs' World Wide Web pages. Currently, mini-ARC is available only for most Unix and Linux workstations. http://www.newtonlabs.com/arc or download and print (Postscript) the comprehensive manual: http://www.newtonlabs.com/arc/dist/arc-manual-1.0.ps.Z For a complete guide to the Cognachrome Vision System, either download and print (Postscript) the comprehensive manual: http://www.newtonlabs.com/cognachrome/dist/cognachrome-manual-1.3.ps.Z or browse the aforementioned website for online (HTML) documentation. ***********Installation Inflate the mini-ARC software and set a $PATH to that directory. When first executed, the software may ask you for a name and password: Key user: Pioneer User Key: 46201-35099-11819-11 ***********Operation mini-ARC communicates directly with Pioneer's onboard vision system hardware through the radio modems or by direct serial tether to the serial port on the back panel of the Pioneer console (not the connector on top of the console). When executed, mini-ARC opens a window and displays the "arc>" prompt. To interact with the FTVS in Saphira mode, invoke mini-Arc with the command flag: arc -saphira The flag instructs mini-ARC to bring up a special Saphira interaction window from which you send commands in Saphira communication protocol to the FTVS for receiving/displaying frame uploads and for "training" the onboard EEPROMs. This is the native mode for the Pioneer vision system. Under special circumstances such as when custom programming the FTVS, you may interact with the FTVS in ARC communication protocol. Invoke mini-ARC with the flag: arc -pioneer (or -saphira_stop) The flag instructs mini-ARC to send a special "exit saphira mode" packet to the vision system, after which the software interacts with FTVS using standard ARC protocols. The vision system menus accessible from this mode are described in the Cognachrome Vision System Manual manual. Either the "-saphira" or "-pioneer" flag will set the serial connection baud rate to 9,600 bps. ARC's standard baud rate is 38,400 bps. Accordingly, if you invoke mini-ARC with the "-pioneer" flag to interact with the FTVS, you may type the command "baud 38400" at the " arc>" prompt to increase the baud rate. This is particularly useful for long software downloads. ************ Saphira Interaction Commands Use these commands from the Saphira interaction window when you start mini-ARC with the "-saphira" flag. You can get a listing by typing `help' at the "saphira>" prompt. Channel commands (replace % with a, b, or c): s%: Train on color in center of given channel j%: Incrementally add to training for given channel <%: Shrink accepted color set for given channel >%: Expand accepted color set for given channel a%: Display tracking output of given channel on "video out" The channel commands behave the same as their counterparts in standard ARC. See the Cognachrome Vision System manual for detailed instructions. Frame commands In the following, replace "#" with 0, 1, or 2 for the amount of compression. Experiment to achieve the desired picture quality: G#: Grab and display a color frame E#: Grab a frame, run edge detection, and display the result D: Grab a frame and display "visual sonars": distances to the nearest obstacle in each of eight directions DB,DE: Start, stop the continuous update of "visual sonar" display T#%: Grab a frame and display the part included by the color tracking for the given channel These commands are case-sensitive, so be sure to use uppercase. Most of the frame commands upload a 64x48 pixel frame and display the frame grab using "xv". Currently, the only compression performed is by reducing the number of bits per pixel and, sacrificing picture quality. In the future, other compression means (such as jpeg) may be incorporated. 0: No compression, highest quality. 1: 2x compression. Moderate quality. 2: 4x compression. Low quality. There are a few things to know about displaying frames with "xv". Be sure you have "xv" installed and that it is in your $PATH. The default settings are for an 8-bit display. For xv to display a frame with acceptable quality on an 8-bit display, it must construct an appropriate 8-bit colormap. Xv creates a window with a private colormap, so move the mouse inside the window to see what the frame really looks like (with the mouse outside, you're likely to see some pretty strange artifacts). "DB" and "DE" start and stop the continuous update of a window showing the output of the edge-based obstacle detection. Eight lines in eight columns represent the closest obstacle detected in each of the eight directions; the functionality is meant to mimic sonars. These eight virtual sensors notice some obstacles that sonars miss, but can be fooled by things like changes in carpet color. The distance measurement is based on the assumption an obstacle touches the floor. You can adjust the sensitivity of the obstacle avoidance by setting the persistent variable "edge_thresh" to a value between 1 and 255. 100 is the default. Lower values increase sensitivity, and higher values decrease sensitivity. (Persistents are viewed and set with the "P" command, described in the next section). "DB" and "DE", unlike the other frame-based commands, display real time data through "gnuplot". A statically-linked version of "gnuplot" is included with "arc" for this purpose. Miscellaneous commands: S: Save current color settings and persistents to EEPROM R: Restore current color settings and persistents from EEPROM Ppersist[=val]: Query or set persistent value v: Print software version info q: Exit saphira mode The P command is used for reading and setting persistents. For example, to decrease the sensitivity of the edge detection, type: Pedge_thresh=200 To set it back to normal, type: Pedge_thresh=100 To find out what it's set to, type: Pedge_thresh ************** Training the FTVS One of the demonstration FTVS-enabled Saphira intentions (complex tasks) for Pioneer has the robot seek and track a specially colored object ("blob"). (You invoke the intention from the Saphira client "Intentions" window. See the Pioneer 1 Software Manual for details.) To work, you must prepare the FTVS by training one, two, or all three of its color channels to the blob's color. 1. Invoke mini-ARC in Saphira mode ("arc -saphira") 2. Place the blob object in front of the Pioneer camera. Good blob choices are very brightly colored, such as a florescent tennis ball or lime-green polyester pants. 3. Grab ("G0") an image and adjust the blob's position in front of the camera. Repeat until the blob is fairly well centered in the image. 4. Use the greater-than (">") and less-than ("<") commands to limit or broaden the color range the FTVS uses to identify the blob. 5. Use the "T" command to examine the FTVS' identification of the blob. 6 Repeat step 4&5 (">a" followed by "T0a", for example) until the vision system displays only the blob with little or no background noise. 7. Repeat steps 2-6 for each channel a, b, and c. 8. Use the mini-ARC "S" command to save the trained channel values to non-volatile memory on the FTVS.