LibOrb Version 0.8 -- Copyright 1997, 1998, John E. Stone (j.stone@acm.org) 
---------------------------------------------------------------------------
** Please read the file "License" included with this distribution which covers
   rules regarding use and distribution of LibOrb.

LibOrb Version 0.8 Release Notes
--------------------------------
  LibOrb is a very simple implementation of a protocol driver
that reads output from the SpaceOrb 360 6DOF 3-D controller 
manufactured by SpaceTec IMC.  Liborb provides a simple interface
to the SpaceOrb 360 on a Unix system through the use of POSIX compliant
termios RS-232 serial communication routines.  Liborb has been successfully
used on Suns running OpenBSD, Solaris 2.5 and Solaris 2.6, SGI's, 
several Linux systems, and recently a Windows NT system.  


Notes on compiling LibOrb and running the test program on Unix systems
----------------------------------------------------------------------
  The Makefile supplied with liborb assumes a generic ANSI C compiler
on a POSIX compliant Unix system.  If your C compiler is named something
other than "cc" or you would like to alter compilation flags etc, go ahead
and edit the Makefile appropriately.  Please send the author any patches
required for building and running liborb on new systems.  To build a 
static link library "liborb.a" and a "testorb" program that displays the
state of the SpaceOrb 360 in a command window, just type "make".
Once liborb.a and the test program have been built, run the test program
with the system serial port device name which the orb is attached to as
an argument.  Example: "testorb /dev/ttya"  If liborb fails to properly
open and initialize the serial port, it will print an error and exit.
If the test program succeeds in opening the serial port, it will begin
printing the status of the attached SpaceOrb as shown below:

  thor - johns:/disk5/users/johns/graphics/liborb % testorb /dev/ttya
  SpaceOrb 360, Unix test program, by John Stone
  Opening SpaceOrb: using port /dev/ttya for I/O
  Sucessfully opened SpaceOrb port.
  Monitoring Orb, press button A on Orb, or ctrl-c to exit.
  
  tx:   5 ty:-123 tz: -98 rx:-117 ry:  36 rz: -29 buttons:00

(after pressing the "a" button on the SpaceOrb, the test program will exit)

  Orb test complete.
  Closing down Orb port.


Notes on compiling LibOrb and running the test program on Windows 95/NT
-----------------------------------------------------------------------
  Mike Connell recently ported LibOrb to windows, and has supplied me
with the changes he made to make it work.  I've made a first attempt
at integrating these changes, and reorganizing the source code as
to accomodate his changes. 

In order to quickly and easily build the testorb program, you can simply
create a new MSVC project, in this case a "console" application, drag
all of the .c files into the project, and build testorb. 

In order to build LibOrb as a library, all you should need to do 
is create a new project on MSVC, and drag orb.c orbserial.c and tty.c 
into the project.  You'll want to set the project type to be a link library, 
either static or dynamic.  You should name the project "liborb", and use
the supplied "liborb.def" file to define the library exports.  I've
provided this info from my previous win32 development experience, but
since I don't currently have a win32 machine to test on, I'm depending
on the Windows users to supply me with corrections to these instructions.  


What is a SpaceOrb 360 and how does it work?
--------------------------------------------
  The SpaceOrb 360 is a spaceball device with a six degree of 
freedom ball controller, and 7 buttons.  The SpaceOrb hereafter 
referred to as the "orb" communicates with the host computer via 
standard RS-232, at 9600 baud, no parity, 8 data bits and 1 stop bit.  
The orb generates bursts of "events" when the ball is pushed or twisted,
or when buttons are pressed.  Since the protocol used by the orb is not 
publicly available, it has been determined experimentally.

A brief summary of my current understanding of the orb protocol is as 
follows:

Communication Parameters:
  RS-232 at 9600,N,8,1

SpaceOrb Events:
  Ball displacement events are generated whenever translational or
rotational force is applied to the ball.  A displacement event packet
begins with 'D' and is 12 bytes in length.  Displacement packets are
organized into translation values for x, y, z, rotation values for x, y, z
and a timer which contains the time since the last packet was transmitted. 
Each of the fields in the displacement event is 10 bits in length, and the
high bit of each byte is always set.  The values for translation and 
rotation are stored as 10-bit 2's complement numbers.  The displacement
packet fields are transmitted by the orb as a string of 12 bytes, which must
be XOR'ed with the string "D.SpaceWare!" in order to properly recover the
raw 2's complement field values.  In order to construct signed integers
from the 10-bit displacement fields, 10 bits are extracted for each field
skipping the high bit of each byte (which is always 1).  
The 2's complement displacement values for each of the 6 translation/rotation
values range from -512 to +511.

** A more detailed description of the bit-fields and their usage will appear
   in future revisions of LibOrb documentation.

  Key/Button events are generated when buttons are pressed and there
is no displacement to report.  Key events begin with 'K' and are 5 bytes long.
One of the 7 buttons on the orb is a special "re-zero" button which will cause
the ball to recalibrate itself so that displacement events will be generated
relative to the new zero.  In order to properly re-zero the orb, you should
depress the reset button on the underside of the orb while the control
ball is not being held.

** Note:
  Since this document is being written several months after the original work
on the orb was done, I'll refrain from adding more detailed information about
the orb protocol until I have a chance to verify the accuracy of bit fields
and some other event packets that exist but are not listed here.


How do I use the SpaceOrb 360 and liborb in a 3-D application?
--------------------------------------------------------------

  The best way to use a SpaceOrb 360 with 3-D applications is to
use the translational and rotational deltas from the orb to alter
transformation matrices used in an application.  In a 3-D cad or
object editing system, the orb might be used to position objects in space.
In a 3-D fly-through, games, or virtual reality type applications, the
SpaceOrb could be used to fly the camera or player around in space.

  In either case, liborb simply provides the translation and rotation
values read directly from the orb itself.  In order to uses these
values, they must be processed and used to create 3-D transformations.
Common processing operations on the raw orb output might include scaling,
value clamping, and software sensitivity controls.  New SpaceOrb users often
find that it is very sensitive and they have a difficult time getting used
to it when its run at full sensitivity.  A better way of using the orb output
is to scale it to some useful units, and to write software that provides
a "NULL" region, or areas where displacements below a certain threshold are
ignored.  This allows new orb users to gradually become accustomed to the 
sensitivity of the device.  As the orb user's skill improves, the size
of the "NULL" region can be decreased allowing the orb to be used at
full precision and sensitivity.

  In order to construct a transformation matrix from the output of the space
orb, it is a good idea to use quaternions for representing rotations.  
Ball rotational displacement events can be easily converted into quaternions,
and the quaternions can be used to generate transformation matrices.

At this time, liborb does not include code for the creation and maintenance
of quaternions or transformation matrices, although such code has been written.
The feedback and suggestions of liborb users will be used to determine
an appropriate set of features for adding such support to liborb.


Writing a code to use LibOrb
----------------------------

  In order to use liborb, the minimal steps necessary to get it initialized
and talking to the attached orb are:

    1) call orb_open() with the tty/serial port device name that the
       SpaceOrb 360 is connected to.  i.e.  orb_open("/dev/ttya");
       orb_init() returns a void * handle which is used in all following
       orb_xxx() calls.  If orb_open() fails to open the tty/serial port
       it will return NULL.

    2) call orb_getstatus() to retrieve current displacement and button
       status.  orb_getstatus() returns an integer flag which is 0 when
       there was no change in status to report, and returns a 1 if status
       information was reported.  The parameters to orb_getstatus() are
       the orb handle, and pointers to integers for tx, ty, tz, rx, ry, rz,
       and buttons.  Buttons are stored as bits in the lowest 7 bits of
       buttons.  Buttons are 1 if pressed, and 0 if unpressed.  
       Orb translation and rotation values are stored in the six integer
       parameters as signed values which range from -512 to +511.
       orb_getstatus() is currently implemented as a polling function,
       and does not actively request a status report from the SpaceOrb,
       so it will only report events that are generated by the SpaceOrb
       itself.

    3) orb_close() free's the orb handle and closes the serial port to
       the SpaceOrb device.

    Other orb_xxx() functions are listed in orb.h, but may not be ready
    for real use at this time.  In this release orb_open() does not
    attempt to perform any auto-detection or verification of the existence
    of a SpaceOrb on the requested tty/serial port, it will assume that
    an orb is there, and will wait for event packets.  Future revisions of
    liborb should perform a verification check on startup to make sure
    that a SpaceOrb is actually present on the serial port, and is 
    communicating properly.  orb_open() will currently return an error
    only if the specified port cannot be opened.

Trademarks
----------
  SpaceOrb 360, and SpaceBall are trademarks of SpaceTec IMC.
  SparcStation, and Ultra are trademarks of Sun Microsystems Inc.
  SGI, and IRIX are trademarks of Silicon Graphics Inc.

