Nomad Jukebox API
v0.9b
2002-05-25

http://www.sourceforge.net/projects/libnjb/


Release Notes
-------------

This is a beta release of the C API for the Nomad Jukebox.  That
means that the API is still a work in progress, but is not expected
to change much more over time.  As such, it is okay to use these
libraries for application development

These libraries have successfully been built and tested under:

   FreeBSD 4.5-RELEASE (x86)
   Linux 2.4.18 (x86)

NetBSD users may be able to build these libraries as well, with
minimal or no porting, due to the fact that FreeBSD uses the NetBSD
USB stack.


NJB Issues
----------

It's pretty easy to "wedge" your JukeBox during a session.  If you get
stuck with a "Host is in control" message, simply disconnect the USB
cable and reconnect it.  Apparently, the documentation that Creative
provides warns against this activity, but USB devices are hot-pluggable,
so it won't hurt anything (the standard disclaimers apply, of course).


Shared Library Support
----------------------

Shared library support has been added as of v0.9b, though it has not 
been fully tested.  You will need to 'make install' the library before
you can execute the sample binaries, or add the libnjb src directory to
your shared library search path (generally the LD_LIBRARY_PATH environment
variable).


libusb Support
--------------

Linux users can compile this package as normal and link their end
applications against libusb with no problems.  If your system did
not ship with libusb, you can obtain it from the URL given below.

libusb support for BSD has been added as of version 0.4a, but it
is recommended that BSD users build with native USB support instead
(this is the default under BSD).  

If you choose to build with libusb support, anyway, be aware that
the libusb provided in /usr/lib on FreeBSD and NetBSD systems as
of 4.5-RELEASE is NOT the same libusb that supports generic USB
devices, and is NOT the libusb I am referring to.  Get libusb from
sourceforge at:

   http://www.sourceforge.net/projects/libusb/

Becuase these two versions of libusb have the same name, you have
to force your applications to link against the desired libusb
explicitely.  This is done with --enable options to configure (run
configure with --help for syntax).


FreeBSD Performance Considerations
----------------------------------

It appears that the uhci device under FreeBSD performs poorly on
bulk data transfers.  The USB 1.1 specification defines 1000 "frames"
every second, for 1 frame per ms.  The host controller determines
how many packets to place in each frame, based on available bandwidth
and bandwidth requirements.  This is called "bandwidth reclaimation",
and the FreeBSD USB stack does not do this as of 4.5-RELEASE.  The
end result is only one packet sent per frame, which severely limits
the transfer rate: the NJB uses 64-byte packets, and the math gives
us a data transfer rate of 64,000 bytes/second.  Yuck.

If you have a UHCI USB controller, this will bite you.  If you have
an OHCI USB controller, the ohci device driver "does the right
thing", and will give you 430kb/second (or so).  However, there is
a caveat: I have noticed some instabilities in the ohci driver, so
you may have problems here, too.

This problem with the uhci stack has been fixed under NetBSD, but 
this new code has not yet been ported to FreeBSD.


What Works
----------

Most of the functions in the API have been tested and documented.
Right now, using the API, you can:

   - transfer audio tracks to and from the NJB
   - delete audio tracks
   - manage playlists (create, rename, update and delete)
   - get audio track lists
   - get playlist information
   - get datafile information
   - obtain disk usage (free and total bytes)
   - get an set the "owner" string
   - play tracks


What Hasn't Been Fully Tested or is Broken
------------------------------------------

There's a function stub for sending (downloading) data files, but
it is not complete and it won't work.


What Will Never Get Done
------------------------

I will never support firmware upgrades with this API.  This may
disappoint some of you, but I don't care, because:

   1) Creative doesn't release the firmware as standalone data blocks
      for transferring.

   2) Of all the functions in the USB protocol, the firmware update 
      is the only one that could potentially render your NJB unusable.

   3) I'm not willing to use my own NJB as a guinea pig.  If I'm not
      comfortable doing this to myself, then I'm sure as hell not 
      going to do it to other people.


Building and Installing
-----------------------

To build the library, libnjb.a:

   1) cd src

   2) make

   3) copy libnjb.h and libusb.a to wherever you want them to live, or
      do a 'make install' to throw them in /usr/local

To build the sample files:

   1) cd sample

   2) make


Documentation
-------------

Man pages for most of the functions are in man.  The documentation is
sparse, but it does cover the basics for the NJB_* functions.  Use the
sample programs as guides for your own development and testing.  The
NJB USB Protocol Guide, available from SourceForge from the same place
where you got libnjb, has some nice info on proper NJB social engineering.

The man pages for the songid and playlist methods are under
construction.  Again, use the sample programs to get an idea on how
this stuff works.  The header file libnjb.h will help, too.


Feedback
--------

Before writing to me, please note the following:

   1. I am doing this in my spare time.

   2. I have a demanding job, which means my spare time is limited.

   3. I am married, and my wife takes precendence over everything
      else.

Please don't send me feature enhancement requests at the current
time.  I am mostly interested in just getting all of the USB protocol
implemented and working, finding and fixing any bugs in the current
code, porting assistance and suggestions for improving coding style.

Send feedback to seagull@aracnet.com

Please don't be offended if I don't write back.  It may be that I am
really busy, or that you're the 1000th person to report the same
issue/bug/problem.

