positron/doc/config.html

   1 <html>
   2 <head>
   3   <link rel="stylesheet" type="text/css" href="style.css" />
   4   <style type="text/css">
   5      h4 { margin-top: 1em; }
   6   </style>
   7   <title>Positron User's Guide: Configuration</title>
   8 </head>
   9 <body>
  10 <h1>Positron User's Guide: Configuration</h1>
  11
  12 <p>
  13 Now that you've got the operating system all set, and positron
  14 installed, it's time to create a positron configuration file.  Login
  15 as a normal user, connect your Neuros to your computer, and mount it.
  16 </p>
  17
  18 <h2>Guided Configuration</h2>
  19
  20 <p>
  21 Positron includes a command to help you generate and modify the
  22 configuration file.  The next few sections will guide you through a
  23 sample configuration.  To begin configuration, type the following:
  24
  25 <pre>
  26 positron config
  27 </pre>
  28 Positron will now ask you a series of questions that will allow it
  29 to generate a configuration file for you.
  30 </p>
  31
  32 <h3>Setting the Mountpoint</h3>
  33
  34 <p>
  35 <pre>
  36 Positron configuration
  37
  38 Please connect your Neuros to your computer and mount it.
  39 Press return when ready.
  40 </pre>
  41
  42 Hopefully, you've already done this.  If not, now is the time.
  43 </p>
  44
  45 <p>
  46 <pre>
  47 Where is your Neuros mounted? []
  48 </pre>
  49
  50 This the mountpoint you specified during
  51 <a href="install.html#mount">installation</a>.  If you followed the
  52 example, your answer will be <tt>/mnt/neuros</tt>.  Pressing enter
  53 without typing anything will automatically select the answer given in
  54 brackets.  Since you don't already have a configuration file, nothing
  55 is shown in the brackets.
  56 </p>
  57
  58 <p>
  59 If your Neuros is mounted to the directory you type in, you should see
  60 the message:
  61 <pre>
  62 Neuros found at that mountpoint.
  63 </pre>
  64 If it is not mounted, or you type the wrong directory, you will see
  65 the message:
  66 <pre>
  67 Warning: A Neuros does not appear to be mounted at /blah.
  68 Would you like to try a different mountpoint? [Y/n]
  69 </pre>
  70 Here you can type <tt>y</tt> to go back and change your answer.
  71 </p>
  72
  73 <h3>Synchronizing Recordings</h3>
  74
  75 <p>
  76 Once you select the mountpoint, the config script will ask you:
  77 <pre>
  78 Positron can copy new FM and microphone recordings from your Neuros to your
  79 computer when you synchronize with "positron sync".
  80
  81 Would you like to enable this feature? [Y/n]
  82 </pre>
  83 This is a useful feature if you want the recordings you make with
  84 the Neuros to be saved to your computer's hard disk automatically
  85 during synchronization.  If you select this option, you will be asked
  86 to pick a directory:
  87 <pre>
  88 Where should recordings be copied to? []
  89 =>
  90 </pre>
  91 You can pick any directory, include one inside a directory you plan to
  92 make a synchronization point (see next question).
  93 </p>
  94
  95 <h3>Selecting syncpoints</h3>
  96
  97 <p>
  98 <pre>
  99 Positron can automatically find new music files in the directories you
 100 specify and copy them to the Neuros during synchronization.
 101
 102 Would you like to configure this? [Y/n]
 103 </pre>
 104
 105 This question is asking if you want to select one or more directories
 106 (called "synchronization points" or "syncpoints" for short in this
 107 document) to watch for new music files.  Whenever you run <tt>positron
 108 sync</tt>, positron will search all of the syncpoints, and all of
 109 their subdirectories, for files that have not been loaded onto the
 110 Neuros and copy them.  This is very convenient if you want to keep a
 111 copy of your entire music collection on the Neuros.  If you have a 128
 112 MB Neuros, you probably will not want to use this feature, as it is
 113 very likely your music collection is bigger than 128 MB.  You can
 114 manually add and remove files without defining syncpoints, as
 115 described in the section on <a href="common-tasks.html#add">adding
 116 music tracks</a>.
 117 </p>
 118
 119 <p>
 120 If you choose to configure syncpoints, you will be taken to a menu:
 121 <pre>
 122 Synchronized directories
 123 ------------------------
 124 (Format: [source directory] => [subdirectory on neuros]
 125
 126 No synchronized directories specified!
 127
 128 [a]dd another synchronized directory
 129 [r]emove a synchronized directory
 130 [d]one configuring
 131 Command? [a]
 132 </pre>
 133
 134 Since this is your first time configuring, no syncpoints are defined.
 135 The <tt>a</tt> option will let you create a new syncpoint:
 136 <pre>
 137 Enter the directory on your computer to synchronize with.
 138 =>
 139 </pre>
 140
 141 Type the name of the music folder on your computer here.
 142 (For example, I store all my music in <tt>/home/stan/music</tt>.)
 143
 144 <pre>
 145 Enter the subdirectory on the Neuros to copy files to.  Do not include the path
 146 to the Neuros mountpoint. [Leave blank to use default]
 147 =>
 148 </pre>
 149
 150 Files and directories inside the syncpoint you specified
 151 above will be copied into this directory on the Neuros.
 152 <tt>MUSIC<tt> is the default answer to this question.
 153 </p>
 154
 155 <p>
 156 To see how this works, consider the following scenario:
 157 <ul>
 158   <li>Your Neuros is mounted at <tt>/mnt/neuros</tt>.</li>
 159   <li><tt>/home/stan/music</tt> is a syncpoint.</li>
 160   <li><tt>tunes</tt> is the corresponding destination directory</li>
 161 </ul>
 162 Then the file <tt>/home/stan/music/a.mp3</tt> will be copied to
 163 </tt>/mnt/neuros/tunes/a.mp3</tt> when you synchronize.
 164 </p>
 165
 166 <h3>Finishing</h3>
 167
 168 <p>
 169 Once you have the syncpoints configred to your satisfaction, you can
 170 say that you are done configuring:
 171
 172 <pre>
 173 Synchronized directories
 174 ------------------------
 175 (Format: [source directory] => [subdirectory on neuros]
 176
 177 1) /home/stan/music => MUSIC
 178
 179 [a]dd another synchronized directory
 180 [r]emove a synchronized directory
 181 [d]one configuring
 182 Command? [d] d
 183
 184
 185 New Configuration
 186 -----------------
 187
 188 Neuros Mountpoint = /mnt/neuros
 189 Recording Directory = /home/stan/music/recordings
 190
 191 Synchronized directories
 192 ------------------------
 193 (Format: [source directory] => [subdirectory on neuros]
 194
 195 1) /home/stan/music => MUSIC
 196
 197 Write this configuration to disk? [Y/n]
 198 </pre>
 199 If you say yes here, the configuration will be written, and you
 200 will be ready to start using positron.
 201 </p>
 202
 203 <h2>Configuration File Format</h2>
 204
 205 <p>
 206 You can also edit the configuration file directly.  The positron
 207 config files is stored by default in <tt>~/.positron/config</tt>.  You
 208 can edit it as a normal text file.  It is composed of two types of entries:
 209
 210 <ul>
 211
 212   <li>Key-value pair - This is a name followed by an equal sign,
 213   followed by the value.  Spaces around the value are trimmed, and if
 214   the value needs to contain a space, it should be enclosed in
 215   quotes.</li>
 216
 217   <li>Block - This starts with <tt>begin</tt> and the name of the type
 218   of block, and is followed by <tt>end</tt> and the name of the
 219   block.  Inside the block are key-value pairs.</li>
 220
 221 </ul>
 222 </p>
 223
 224 <p>
 225 A sample configuration file is shown below.
 226 </p>
 227
 228 <pre>
 229 mountpoint=/mnt/neuros
 230 recordingdir=/home/stan/music/recordings
 231 neuros_musicdir=MUSIC
 232 sort_database=true
 233
 234 begin sync
 235   src=/home/stan/music
 236   dest=tunes
 237 end sync
 238 </pre>
 239
 240 <h3>Allowed Keys</h3>
 241
 242 <dl>
 243 <dt>mountpoint</dt>
 244 <dd>The directory where the Neuros is mounted.</dd>
 245
 246 <dt>recordingdir</dt>
 247 <dd>The directory where recordings on the Neuros are copied to during
 248 synchronziation.</dd>
 249
 250 <dt>neuros_musicdir</dt>
 251 <dd>The subdirectory on the Neuros (inside the mountpoint) where music
 252 files are copied to by default.  This is used both by the add and by
 253 the sync command as the default destination. The default value for
 254 this if not specified is <tt>MUSIC</tt>.</dd>
 255
 256 <dt>sort_database</dt>
 257
 258 <dd>A boolean key that sets whether the database should be sorted
 259 after new entries are added.  This affects the display of songs on the
 260 Neuros.  If this value is set to false, new songs will be shown at the
 261 end of lists. Allowed values are <tt>true</tt>, <tt>yes</tt>,
 262 <tt>false</tt>, or <tt>no</tt>.
 263 </dd>
 264
 265 <dt>oggvorbis_support</dt>
 266
 267 <dd>A boolean key that sets whether positron should recognize Ogg
 268 Vorbis files as music files.  Setting this to <tt>true</tt> will allow
 269 Ogg Vorbis files to be uploaded to the Neuros. <em>Warning: If your
 270 Neuros does not have a version of the firmware which supports Ogg
 271 Vorbis files, DO NOT TURN THIS ON.</em> This option defaults to
 272 <tt>false</tt>.  </dd> </dl>
 273
 274 <dt>mp3_support</dt>
 275
 276 <dd>A boolean key that sets whether positron should recognize MP3
 277 files as music files.  Setting this to <tt>true</tt> will allow MP3s
 278 to be uploaded to the Neuros.  You would normally only set this option
 279 to <tt>false</tt> if your firmware lacks MP3 support for some reason.
 280 This option defaults to <tt>true</tt>.  </dd> </dl>
 281
 282 <h3>Blocks</h3>
 283
 284 <h4>sync</h4>
 285
 286 <p>
 287 Zero or more sync blocks are allowed in the configuration file.
 288 The sync block defines a syncpoint.  Music files are copied from the
 289 syncpoint to the specified destination directory on the Neuros.  The keys that can appear inside a sync block are:
 290 </p>
 291
 292 <dl>
 293 <dt>src</dt>
 294
 295 <dd>(Required) The directory on the computer where music files should be copied
 296 from.  All subdirectories of this directory will also be searched.</dd>
 297
 298 <dt>dest</dt>
 299
 300 <dd>(Optional) The subdirectory on the Neuros (inside the mountpoint)
 301 where music files from <tt>src</tt> should be copied.  If not
 302 specified, <tt>neuros_musicdir</tt> will be used by default.</dd>
 303 </dl>
 304
 305 </body>
 306 </html>