1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
|
Nomad Jukebox API
v1.0.1
2004-06-21
http://libnjb.sourceforge.net/
http://www.sourceforge.net/projects/libnjb/
Release Notes
-------------
This is a first release of the C API for the Nomad Jukebox. The
Nomad Jukebox 1 is fully supported and working fine, other devices
may have their host of bugs and troubles, but as you know an open
source project is always moving. The API 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 5.1-RELEASE (x86)
Linux 2.4.20 (x86)
MacOS X (Darwin, PowerPC)
Microsoft Windows (Win2K)
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. We have not built libnjb for VMS, BeOS, OS/2, Windows and
<insert your favourite obscure OS here>. Help us port it if you're
interested!
These devices are handled, more or less perfect:
* Creative Nomad Jukebox 1 a.k.a. Creative D.A.P.
* Creative Nomad Jukebox 2
* Creative Nomad Jukebox 3
* Creative Nomad Jukebox Zen
* Creative Nomad Jukebox Zen USB 2.0
* Creative Nomad Jukebox NX
* Creative Nomad Jukebox Xtra
* Dell Digital Jukebox ("Dell DJ")
* Creative Nomad Jukebox Touch
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).
Issues with newer jukeboxes
---------------------------
Some users of Nomad Jukebox Xtra have reported problems when using the
library for the first time. This seems to be caused by the playlist
of preloaded content. Try to remove all playlists by using the menus
on the device, and see if this solves your problem.
USB issues
----------
Some users experience problems with USB communication. There are some
hardware USB controllers which is problematic. This might be caused
by either electrical properties of the bus, or by badly programmed
drivers in the host kernel.
nForce 2 motherboards are known to be problematic.
FreeBSD Performance Considerations
----------------------------------
It appears that the uhci device under some FreeBSD releases 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.x-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 and
FreeBSD 5.x.
Compilation of programs under MacOS X
-------------------------------------
Older versions of libusb for Darwin does not handle short USB writes
properly, which is a prerequisite for libnjb to work. This has been
fixed in the CVS version of libusb (which will probably become version
0.1.8). You need to get the CVS version of libusb for Darwin as of
now, see <http://sourceforge.net/cvs/?group_id=1674>
If you're writing your own applications to use libnjb under MacOS X
you will have to add the line "-framework IOKit" to your CFLAGS.
An example of how this is done in Autoconf to affect Darwin only
can be found in the "configure.in" file for libnjb.
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 playlist information
- send and recieve data files
- get data file metadata
- obtain disk usage (free and total bytes)
- get an set the "owner" string
- play tracks
- manipulate sound parameters (volume and EAX)
- full internationalization using UTF-8 unicode
What Will Never Get Done
------------------------
We currently do not support firmware upgrades with this API. This may
disappoint some of you, but we 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) We're not willing to use our own NJBs as a guinea pigs. If we're not
comfortable doing this to ourselves, then we're sure as hell not
going to do it to other people.
Send us guinea pig NJBs and we might support it some day. ;)
Building and Installing
-----------------------
See the "INSTALL" file.
Compiling programs for libnjb
-----------------------------
libnjb has support for the pkg-config script by adding a libnjb.pc
entry in $(prefix)/lib/pkgconfig. To compile a libnjb program,
just write:
gcc -o foo `pkg-config --cflags --libs libnjb` foo.c
This also simplifies compilation using autoconf and pkg-config: just
write e.g.
PKG_CHECK_MODULES(NJB, libnjb)
AC_SUBST(NJB_CFLAGS)
AC_SUBST(NJB_LIBS)
To have libnjb LIBS and CFLAGS defined. Needless to say, this will
only work if you have pkgconfig installed on your system, but most
people have nowadays.
If your library is installed in e.g. /usr/local you may have to tell
this to pkgconfig by setting the PKG_CONFIG_PATH thus:
export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
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.
Did Creative help you with this?
--------------------------------
No. They didn't help us. We did everything by reverse-engineering, by
looking at the USB traffic. We did not disassemble any Creative code.
We did ask Creative for support, but they have not offered assistance
in any official capacity.
Feedback
--------
Send feedback to the user and developer lists at Sourceforge. You may
subscribe to this list through the project web page, see:
http://sourceforge.net/mail/?group_id=32528
|
