positron/doc/troubleshooting.html

   1 <html>
   2 <head>
   3   <link rel="stylesheet" type="text/css" href="style.css" />
   4   <title>Positron User's Guide: Troubleshooting</title>
   5 </head>
   6 <body>
   7 <h1>Positron User's Guide: Troubleshooting</h1>
   8
   9 <p>
  10 As you might expect, things can and will go wrong with technology.
  11 This document will give some hints as to how to deal with problems.
  12 </p>
  13
  14 <h2>Operating System Issues</h2>
  15
  16 <p>
  17 A common problem is that you plug my Neuros in to my computer, but it is never
  18 assigned a device.  There are several possible causes for this:
  19 <ul class="biglist">
  20
  21   <li>The <a href="install.html#reqmodules">required kernel
  22   modules</a> are not loaded.  Usually most of them are autoloaded,
  23   but there are some systems where <tt>usb-storage</tt> needs to be
  24   forced in by hand.  The
  25   <a href="install.html#setupkernel">installation guide</a> gives some
  26   explanation of how to do this.</li> You can use <tt>lsmod</tt> to
  27   verify the modules are loaded and <tt>dmesg</tt> to see if there are
  28   any informative kernel messages.</li>
  29
  30   <li>Some kernels just don't seem to work.  All the correct modules
  31   are loaded, but the usb modules just lock up when a Mass Storage
  32   device is attached.  This can even be a semi-random failure, like
  33   lockups during transfers.  Unfortunately, there is not much you
  34   can do in this case but upgrade your kernel.  The latest kernels
  35   (>= 2.4.20) seem to work well.</li>
  36
  37   <li>The firmware on your Neuros might also contribute to this
  38   problem.  There have been reports that the 1.34 beta firmware causes
  39   periodic freezing in Linux during transfers.  If this is the
  40   firmware you are running, downgrading to the latest stable firmware
  41   might help.</li>
  42
  43 </ul>
  44 </p>
  45
  46 <h2>Database Problems</h2>
  47
  48 <p>
  49 Database problems frequently cause the unit to freeze while you are
  50 using it, or they cause songs to be missing or misfiled.  This is
  51 usually caused when the connection between the Neuros and the computer
  52 is interrupted during transfer.  If the OS freezes, the Neuros
  53 freezes, or the link cable is disconnected before you unmount the
  54 device, the database can be corrupted.  To fix this, use the following command:
  55 <pre>
  56 positron rebuild
  57 </pre>
  58
  59 This will reconstruct your databases from scratch based upon the music
  60 files it finds on the Neuros.  If problems persist, there is a good
  61 chance you found a bug in positron.  Please report it to us using one
  62 of the <a href="#contact">methods</a> outlined below.  You will
  63 probably want to zip up your <tt>WOID_DB</tt> subdirectory on the Neuros and
  64 include it with the bug report.
  65 </p>
  66
  67 <h2>Filesystem Problems</h2>
  68
  69 <p>
  70 Another class of problems generates errors like:
  71 <ul>
  72   <li>Input/Output errors (visible using the dmesg program)</li>
  73   <li>Linux thinks the filesystem is read-only.</li>
  74   <li>mount won't recognize the filesystem on your Neuros.</li>
  75   <li>Files on your Neuros have been damaged or destroyed.</li>
  76   <li>The Neuros freezes when playing certain files.</li>
  77 </ul>
  78 These symptoms suggest the filesystem on the Neuros has been corrupted
  79 in some way.  Filesystem corruption is usually caused in the same way
  80 as database corruption, though it is generally less common.
  81 Unfortunately, the best way to fix a corrupted file system is to
  82 format the Neuros and start over.
  83 </p>
  84
  85 <p>
  86 WARNING: The following operation erases the contents of your Neuros
  87 and should only be attempted as a last resort.
  88 </p>
  89
  90 <ul>
  91   <li>Disconnect the USB cable between your Neuros and your computer.</li>
  92
  93   <li>Turn off your Neuros.</li>
  94
  95   <li>Press and hold the 1, 5, and Play buttons.  You should press the
  96    Play button slightly before the other two.</li>
  97
  98   <li>When "SAFE MODE" menu appears, release the buttons and select
  99   "Format Hard Disk" if you have the hard disk model or select
 100   "Format NAND Disk" if you have the flash memory model.</li>
 101
 102   <li>When the format finishes, select "Exit," and the Neuros will
 103   continue its normal boot sequence, and tell you it is creating
 104   databases.</li>
 105
 106   <li>Connect your Neuros back to the USB port on your computer.
 107   Mount the disk, and run <tt>positron rebuild</tt>.  It is important
 108   that you do this immediately after formating because the Neuros
 109   firmware produces several incorrect databases after a format
 110   operation.  The <a href="commands.html#rebuild">rebuild</a> command
 111   corrects this problem.</li>
 112
 113   <li>Your Neuros is now ready for normal use again.</li>
 114 </ul>
 115
 116
 117 <h2>Music File Detection Problems</h2>
 118
 119 <p>
 120 While we've tested positron on a wide variety of MP3s, sometimes we
 121 stumble across one that is not identified by positron, so it will
 122 refuse to add it to the Neuros database.  Quite often, this is because
 123 the file is corrupted in some way.  Many MP3 players are
 124 <em>extremely</em> tolerant of damaged MP3s, so some of these files
 125 are actually playable.  At this time, positron has no override switch
 126 to allow you to force a file to be uploaded.  This may or may not be a
 127 good thing because it is unclear how the Neuros firmware would handle
 128 such damaged files.  Our suggestion is that you try to acquire the
 129 file from another source or recreate it using a different tool.
 130 Please contact us about problem files: we are interested in improving
 131 our detection algorithm if it fails on legitimate files.
 132 </p>
 133
 134 <h2 id="contact">If All Else Fails</h2>
 135
 136 <p>
 137 If you can't seem to resolve a problem, you have a couple options:
 138 </p>
 139
 140 <ul>
 141
 142   <li>Report a bug - Use Bugzilla at http://bugs.xiph.org. We prefer bug
 143   reports to be filed this way.  Please file them against the 'positron'
 144   product.</li>
 145
 146   <li>Ask on the mailing list - See http://www.xiph.org/archives.
 147   Look for the positron list.</li>
 148
 149   <li>Find us on IRC - #positron on irc.freenode.net.</li>
 150
 151   <li>Email the author - You may contact the author directly at <a
 152   href="mailto:volsung@xiph.org">volsung@xiph.org</a>, but please only
 153   do this as a last resort.</li>
 154
 155 </ul>
 156
 157 </body>
 158 </html>