E.L.M.P software documentation v1.0
===================================

(This is a pre-1.0 version, consider it beta quality at best!)

Version 1.0 is finally here, this should be the first really useable version, and most
bugs should be gone. If you are upgrading from v0.9 you should note that quite a few
things that weren't very good or flexible in the old version have been changed, the major
things to notice are the use of loadable drivers, and the configurable keys...  Also the
file names on the floppy have changed, and the bitrate used by the uC-Board. Make sure
you update the PIC code and harddisk boot kit if you use it. From now on, no changes will
be made that break things like this release did, and future upgrades should be 100% soft-
ware only. A few mods to the hardware will be designed, but they will be optional.

0) Changelog:
=============

v1.0pr2 (990515):
		 Plug n' Pray support!  Hopefully ISA PnP soundcards work now...
		 File scanning code rewritten by Holger Morgen (no more exec("/bin/find"))
		 Fixed the LCD bugs
		 Made eject work in background
		 Made normal commands work in menus
		 Removed the very broken CD audio stuff
		 Rewrote some sections of this file
		 MPG123 mods: Fixed RIFF/wave header skip code, added code to
		 skip some unknown junk header I found, changed the skip code (long pause
		 and seek delays are gone, but position may not be 100% accurate?) 
		
v1.0pre (990317):
		 Added "seek" support 
	  	 Basic mount/unmount support and playlist regenerate added
		 Optimized LCD update code to minimize writes
		 RC5 remote support added (not widely tested)
		 uC board bitrate changed to 19200bps, update your PIC!
		 Enhanced RTC support (/dev/rtc) to get constant loop timing (for text                       scroll etc...)		 
		 User mapping of keys->commands
		 Switched to MPG123 player
		 Added mixer support, with quick fades to minimize clicks
		 Modular drivers (support for many sound and network cards etc.)
		 Very basic CD audio support (don't even try to use!)
		 Many bugfixes and optimizations
		 Quite a few new bugs added  :-/		 
		 MPG123 mods: Fixed buffer overrun (read 68 bytes into 40 
		 byte buffer = bad idea!)

v0.9b   (990109) 
		 First public release


0a) Planned features (next release?)

A new internal playlist format with support for multiple file types (MP4? MOD? AAC?)
Adding players to handle the other formats, and write a new working CD audio player.

Sorting the playlist (random-play etc)

Saving/loading/importing (.m3u format) playlists

CDDB support

Network remote control support (web based?)

File upload for those with harddrives (FTP server?)

Tell me if you have any good ideas...

0b) Known bugs

Pause and seek delays are gone, but may not jump to the exact correct position 

RC5 decoding is a bit unstable. (But usually works for me at least)
One problem seems to be that most IR modules have inverted output

Sometimes the keys seem to react slowly (you have to press twice before anything happens)
I will rewrite the entire serial handling code to hopefully fix this and make IR better.

Tell me if you find any other problems..

1) Installing the software:
===========================

In the ZIP you downloaded is a file called ELMP.IMG, write this to an empty
floppy disk using the program RAWRITE or similar ('dd' under linux). If
everything worked out you should have a couple of files on the disk now:

ELMP.CFG       - The configuration file you should edit
ELMP.FIL       - The compressed file system
ELMP.KRN       - The compressed Linux kernel
ELMP.MSG       
ELMP.PRG       - The control program itself
LDLINUX.SYS
SYSLINUX.CFG

1a) Drivers

The old (v0.9) kernel had hard-coded support for SoundBlaster 16 and NE2000 cards. 
Now the sound and network drivers have been moved into kernel modules (loadable 
drivers) and you can download drivers for a few different cards at the website.
Each driver comes in a .ZIP file with one or more .DRV files and a .TXT file with
instructions on how to configure the driver. Read this file and edit your ELMP.CFG
and add a section for the driver file. (explained in the .TXT file!)

1b) Booting from a harddisk

Right after v0.9 was released I put together a "harddisk boot kit" which you can
download. All the files from the floppy except ELMP.MSG, LDLINUX.SYS and SYSLINUX.CFG
must be copied to C:\ ...  (read the instructions in the boot kit for more info)
Note: you must use the updated version of the boot kit, because file names have 
changed since v0.9...

2) Configuration:
=================

Open the configuration file in your favorite text editor (Notepad, EDIT,
Joe, vi, EMACS etc..). The format is like that of a Windows .INI file. There
are now many sections like [network], [mounts], [rc5]... the order of
parameters doesn't matter as long as they stay in the right section.

2a) [network]

If you don't have a network card just set "enabled = 0" and skip to the next
section...   If you wan't to use TCP/IP network functions, read on!

ipaddr = aaa.bbb.ccc.ddd

The IP adress of the player in dotted quad format, private networks (without
official IPs) should use reserved IPs such as 192.168.x.y (where x is a number
between 0 and 255 and is the same for all your machines, and y is a number
between 1 and 254, one number per machine). If anyone give their player a
"real" IP number somewhere, tell me! That would be pretty cool...

netmask = aaa.bbb.ccc.ddd

This should usually be 255.255.255.0 (class C network). If you need something
else, you probably know all this already.

gateway = aaa.bbb.ccc.ddd (or gateway = 0)

If you need to connect to machines that are not on your local network, put the
IP of your gateway here...   I hardly think you need this so just put 0 to
disable this.

hostname = abcdefgh

Make up a nice name for your player and put it here, this will be the name
that the player uses to identify itself on a windows workgroup network also.

workgroup = abcdefgh

The windows workgroup you want the player to appear in...

smbuser = abcdefgh / smbpass = abcdefgh

A user name and password the player will use to connect to network shares,
this isn't needed in a typical home, win95 network but on a WinNT or Samba
server you might want to create a user account with minimal rights (just
enough to read those MP3 files!). DO NOT put your own user name and password
here as this is very insecure...

2b) [mounts]

The Linux/UNIX geeks (like myself) probably know what this is...
This is where you tell the player where it can find MP3 files.  You can 
define up to five of these, so the "X" in the examples below should always 
be replaced with a number between one and five..   The ELMP.CFG on the 
distribution disk should have a sample mount for a CDROM drive connected 
as secondary master, and a DOS formatted harddisk as primary master.

mntXname = abcde

This is the name that is displayed in the PLAYLIST menu, it will probably look
best if it's all capital letters, and it should be no longer than six characters.
If you have five mounts they cannot all have names that long, because that won't
fit on the LCD.

mntXtype = iso9660/vfat/ext2/smbfs

This is the type of filesystem to be mounted, the ones above are supported in
the kernel, but with the new modular drivers you could easily add support for
NFS, NTFS or any other filesystem that Linux supports.
For the normal user, a quick guide:

CDROM drives - iso9660
harddisks - vfat
network shares - smbfs

mntXpath = /dev/abc or //abcdef/ghijkl

This is the path to the device file or network share to mount, again a quick
guide for the not-so-linux-literate:

a Harddisk with one partition, connected as primary master - /dev/hda1
a CDROM connected as secondary slave - /dev/hdd
a share called MP3 on a server called KIRK - //kirk/mp3

The device names for IDE devices are as follows:

/dev/hdXY

where X is either a,b,c or d for pr. master, pr. slave, sec. master, sec slave
and Y is nothing at all for CDROMs and usually 1 for harddisks (as long as you
have only one partition on the drive). 

For network shares the format is nearly the same as in windows, just use slash
instead of backslash (\\server\share in windows is //server/share here...).

mntXhost = aaa.bbb.ccc.ddd

Currently, until I get some NetBIOS lookup code going, you will also need to
specify the IP adress of the server when you use network shares, there is no
need to specify this for harddisks or CDROMs, and in the future you won't need
to do this for network shares in most cases either.

2c) driver sections

Drivers can be downloaded from the website, there are no drivers included in
the software ZIP. Each driver has a text file describing how to configure it.
An example for the SoundBlaster driver: 

[sb.drv]
load = yes
options = io=0x220 irq=5 dma=1 dma16=5

2d) [mixer]

Optional section that let's you define default volume setting for master, 
MPEG audio and CD audio...  values range from 0 to 100.

master = 75
mpeg = 90
cdaudio = 80

2e) [rc5]

Skip/remove this section if you don't have a RC5 compatible remote control 
for your player. Keys are defined as "rc5_X_Y" where X is the RC5 adress 
and Y is the RC5 command code. The X will be the same value for all of them
unless you use two remotes or something. I've included a list of RC5 codes
in the .ZIP but the best way is to run the updated test disk (v1.1) which will
show you the codes when you press keys. Oh, and if you want a function to repeat
as you hold the key down, add an "_p" to the key name also. 

Example: 
(use the volume keys on a TV remote to set the volume, and the "1" key to eject)

rc5_0_16_p = 66 66
rc5_0_17_p = 67 67
rc5_0_1 = 69 69

As you can see there are two numbers defined for each key...  The first one defines
the function to perform when not in a menu, and the second one defines what will
happen if the key is pressed when navigating a menu. This way it is possible to
use the same key for both PLAY and SELECT for example. Most normal player functions
work inside menus. You can find the values of the function you want by looking in 
CMD.H which is included in the ZIP...  a value of 0 means do nothing.

2f) [keys]

This sections work just like the above, except that there is only one number
(ranging from 0-15) and there is no "_p" to add for pressed keys (right now)
but there is a "_r" code that will be triggered when the key is released.
The test disk v1.1 has a utility which will tell you the number of a key, an
there are instructions on the website on how you calculate the number.


Example:
(use keys nr 15 and 3 to seek in the file, and to switch items in menus)

keys_15 = 10 32
keys_15_r = 11 0
keys_3 = 9 33
keys_3_r = 11 0

a 0 is a "no-op", command 11 finishes the seek...


You can have a look at the file EXAMPLE.CFG in the ZIP-file, it's my own
current configuration, and the default configuration included on the disk is
made to emulate the old v0.9 keys...

3) Using the player:
====================

OK, put the floppy in the player and boot 'er up! After a while (too long, I
know...) The message "ELMP controller software vx.y" should come up on the LCD
and shortly after that (you may never see the first message) you will be dropped
into the "playlist" menu. Use your "menu_next" key to select "MOUNTS" and press
your "menu_select" key. You should see a list of your configured mounts, and you
can tag the ones you want to scan for files on. Select OK, and the file systems 
should be mounted. (if you have a monitor connected you should see a message or two
about this...) Now select BUILD and the player will scan for files, and then switch
to the player mode shown below (with the first file loaded).

3b) Display layout
                   
 Song title        ________________________________________
 (Scrolling) ---> |Depeche Mode - I Feel You   *** [51/178]| <-- Songnr/Total
 Status --------> |Playing...     [44Khz][128kbit/s][01:16]| <--.
                   ----------------------------------------     |
                                                                |
                                                        Sampling rate,
                                                        Bitrate,
                                                        Position (min:sec)


3c) Key functions

In v1.0 and later you can define your own key and IR remote functions. 
You can only put numerical values into the config file, look at the file 
CMD.H for the numbers...  Below are the functions that work so far.

cmd_prev      : Select the previous song
cmd_next      : Select the next song
cmd_playpause : Start if stopped/paused or pause if playing
cmd_stop      : Stop if playing or paused
cmd_prevgroup : (right now) Jump 10 songs backward
cmd_nextgroup : (right now) Jump 10 songs ahead
cmd_startseekp: Start seeking forward 
cmd_startseekm: Start seeking backward 
cmd_stopseek  : Leave seek mode and actually jump to the new position
cmd_menu_prev : Previous menu item
cmd_menu_next : Next menu item
cmd_menu_select OK!
cmd_menu_cancel oops.. sorry
cmd_menu_pl   : Jump to the PLAYLIST menu
cmd_volu      : Volume UP 5%
cmd_vold      : Volume DOWN 5%
cmd_eject     : Eject the CDROM configured under [cdaudio]
                You must first unmount the disc. 
		(PLAYLIST,MOUNTS,<deselect the CD>,OK)
		This will be more automatic in a later version

------------------------------------------------------------------------------
       http://www.algonet.se/~cyrano/elmp/   -   cyrano@algonet.se
------------------------------------------------------------------------------


