positron/doc/install.html

   1 <html>
   2 <head>
   3   <link rel="stylesheet" type="text/css" href="style.css" />
   4   <title>Positron User's Guide: Installation</title>
   5 </head>
   6 <body>
   7 <h1>Positron User's Guide: Installation</h1>
   8
   9 <p>
  10 The only prerequisites for running positron are a UNIX-like operating
  11 system that supports USB Mass Storage devices and Python 2.2.1 or
  12 later.  These directions focus specifically on Linux, though positron
  13 is certainly not Linux-specific.  (Warning to the adventurous:
  14 positron should work on MacOS X, however a USB bug on the Neuros makes
  15 it appear as a read-only device on OS X.  Hopefully a fix will be
  16 available soon.)
  17
  18 <p>
  19 If you do not have Python 2.2.1 installed on your system, you should
  20 install it before continuing.  You can get Python from the <a
  21 href="http://www.python.org/">Python website</a>, but all modern Linux
  22 distributions package it, so you should look for one of those packages
  23 first.
  24 </p>
  25
  26 <p>
  27 There are three parts to installing positron: setting up the kernel
  28 for USB, making the Neuros mountable, and installing the positron
  29 software itself.
  30 </p>
  31
  32 <h2>Setting up the Kernel</h2>
  33
  34 <p>
  35 The Neuros requires no custom drivers because it interfaces with the
  36 computer using the USB Mass Storage standard used by USB hard disks
  37 and other storage devices.  If you already have Linux setup to do
  38 this, you can skip to the next section.
  39 </p>
  40
  41 <p>
  42 First make sure you are using a Linux 2.4 kernel.  It appears that the
  43 reliability of USB Mass Storage in the 2.4 series has varied quite a
  44 bit, so using the newest kernel you can is suggested.  Kernels 2.4.20
  45 and later have been reported to work well on several platforms, though
  46 your milage may vary.
  47 </p>
  48
  49 <p>
  50 The next thing to check is that you have the required kernel modules.
  51 </p>
  52
  53 <ul id="reqmodules">
  54
  55   <li>usbcore - This is required for any USB device.</li>
  56   <li>usb-uhci/usb-ohci - One of these is used depending upon
  57   your USB host controller</li>
  58   <li>usb-storage - For using USB Mass Storage devices</li>
  59   <li>scsi_mod and sd_mod - USB Mass Storage devices show up as SCSI
  60   disks, so you'll need SCSI support.</li>
  61
  62 </ul>
  63
  64 <p>
  65 Nearly all current Linux distributions come with these modules
  66 precompiled and many automatically load some or all of them for you.
  67 If you need to load them manually, you can use
  68
  69 <pre class="console">
  70 modprobe [name of module]
  71 </pre>
  72
  73 to load a module once, or edit /etc/modules or /etc/modules.conf to
  74 have the module automatically loaded for you.  If you find that you
  75 are missing one or more of these modules, you will have to recompile
  76 kernel to get them.  Kernel compilation is beyond the scope of this
  77 document, but you can read the
  78 <a href="http://www.tldp.org/HOWTO/Kernel-HOWTO/index.html">Kernel HOWTO</a>
  79 for more information.
  80 </p>
  81
  82 <h2 id="mount">Making the Neuros Mountable</h2>
  83
  84 <p>
  85 Now that you have all the kernel modules loaded, you can plug your
  86 Neuros into your computer using the USB cable that came with it.
  87 Within a couple seconds, the kernel will recognize the device and (if
  88 all goes well) assign it a SCSI device.  Run
  89 <pre>
  90 dmesg
  91 </pre>
  92 as the root user, and you should see messages that look like this:
  93 <pre>
  94 hub.c: new USB device 10:18.0-1, assigned address 2
  95 scsi1 : SCSI emulation for USB Mass Storage devices
  96   Vendor: NEUROS    Model: dig. audio comp.  Rev: 1.00
  97   Type:   Direct-Access                      ANSI SCSI revision: 02
  98 Attached scsi removable disk sda at scsi1, channel 0, id 0, lun 0
  99 SCSI device sda: 39070048 512-byte hdwr sectors (20004 MB)
 100 sda: test WP failed, assume Write Enabled
 101  /dev/scsi/host1/bus0/target0/lun0: p1
 102 WARNING: USB Mass Storage data integrity not assured
 103 USB Mass Storage device found at 2
 104 </pre>
 105
 106 The line that says "SCSI device sda" tells you that device name Linux
 107 assigned to your Neuros is /dev/sda.  The Neuros has only one
 108 partition, so you will be mounting /dev/sda1.
 109 </p>
 110
 111 <p>
 112 Next, make the directory /mnt/neuros.  (Of course, you can name this
 113 whatever you like, just be consistent through the remainder of the
 114 directons.)  Edit /etc/fstab and add the following line:
 115 <pre>
 116 /dev/sda1 /mnt/neuros vfat user,noauto,umask=0    0 0
 117 </pre>
 118
 119 This will permit normal users to mount and access the Neuros, so you
 120 won't have to use positron as the root user.
 121 </p>
 122
 123 <p>
 124 Finally, login as a normal user and mount the Neuros:
 125 <pre>
 126 mount /mnt/neuros
 127 </pre>
 128
 129 You should be able to change to the /mnt/neuros directory and list the
 130 contents.  There should already be files and directories on your
 131 Neuros, even if you just bought it.  Note that these directions are
 132 the same regardless of whether you have a 128 MB or 20 GB Neuros
 133 (although the storage capacity shown by the kernel above will vary).
 134 </p>
 135
 136 <p>
 137 Before you unplug your Neuros, make sure to unmount it:
 138 <pre>
 139 umount /mnt/neuros
 140 </pre>
 141 </p>
 142
 143 <h2>Installing the Positron Software</h2>
 144
 145 <p>
 146 The hard part is over!  Now you just have to install positron itself,
 147 if you have not done so already.  The method you use will depend on your
 148 setup.
 149 </p>
 150
 151 <h3>RPM Based Distributions (RedHat, Mandrake)</h2>
 152
 153 <p>
 154 Download the latest positron RPM from the
 155 <a href="http://www.xiph.org/positron/">positron homepage</a>.  (Note:
 156 you do not need the Source RPM.)  As the root user run:
 157 <pre>
 158 rpm -Uvh positron*.rpm
 159 </pre>
 160
 161 This will also upgrade your current version of positron if you already
 162 have an older version installed.
 163 </p>
 164
 165 <h3>DEB Based Distributions (Debian, Knoppix, etc.)</h2>
 166
 167 <p>
 168 Add the following lines to your /etc/apt/source.list
 169 <pre>
 170 deb http://i.cantcode.com/~jack/debian unstable main contrib
 171 deb-src http://i.cantcode.com/~jack/debian unstable main contrib
 172 </pre>
 173
 174 Then type:
 175 <pre>
 176 apt-get update
 177 apt-get install positron
 178 </pre>
 179 You can rerun this later to upgrade to a newer version of positron.
 180 </p>
 181
 182 <h3>Gentoo</h3>
 183
 184 <p>
 185 There is an ebuild for positron.  To install type:
 186 <pre>
 187 emerge positron
 188 </pre>
 189 and it should download the source and install it for you.
 190 </p>
 191
 192 <h3>Installing from Source</h3>
 193
 194 <p>
 195 If for some reason one of the above methods do not apply to you, or
 196 you just want to install positron from source, download the source
 197 tarball from the <a href="http://www.xiph.org/positron/">positron
 198 homepage</a>.  Untar the tarball and cd to the positron source
 199 directory.  If you want to install positron to the default location of
 200 the /usr directory, run the following as the root user:
 201 <pre>
 202 python setup.py install
 203 </pre>
 204 If you want to install to a different prefix (like /usr/local), run
 205 <pre>
 206 python setup.py install --prefix=/some/prefix
 207 </pre>
 208 or:
 209 <pre>
 210 python setup.py install --home=/some/prefix
 211 </pre>
 212 Please see "Installing Python Modules" at
 213 http://www.python.org/doc/current/inst/inst.html
 214 for more information on how to use python distutils.
 215 </p>
 216
 217 </body>
 218 </html>