Infplay (c) 2009-2010 by Malte Marwedel

SEE features.txt *BEFORE* USE!
Bitte features.txt beachten, *bevor* sie benutzt wird!

My parts of this software can be used under the terms of the GPL license 2.0 or later.

See www.marwedels.de/malte/mp3player1 for more information.
Or write me at m.marwedel AT onlinehome DOT de

== Hardware needed to use the software ==
Arthernet Board: http://ispf.de/modules.php?name=News&file=article&sid=5
with:
  512KB external RAM
  CLPD
  Small MMC Card (I tested successfully a 64 MB MMC, 512MB SD card and a 4096MB SD-HC card)
  ATmega128 with a 16MHZ crystal
  Optional a RS232 port for debugging

Extensions for the board:
  Rotation Decoder
  128x64 LCD
  VS1002 decoder and a 5-> 3.3V logic converter IC
  Optional is a IR receiver

== Thanks ==
Thanks to all those nice people at mikrocontroller.net and Nut/OS mailing list, who helped me on may problems during the development:
http://www.mikrocontroller.net/topic/18571
http://www.mikrocontroller.net/topic/136517
http://www.mikrocontroller.net/topic/160222
http://www.mikrocontroller.net/topic/155576
http://www.mikrocontroller.net/topic/143553
http://www.mikrocontroller.net/topic/156550
http://www.mikrocontroller.net/topic/12216#1427055
http://lists.egnite.de/pipermail/en-nut-discussion/2009-April/010733.html
http://lists.egnite.de/pipermail/en-nut-discussion/2009-August/011030.html

== Compiling ==
As setting up the Nut/OS environment is somewhat difficult, there is the build_everything.sh script.
Assuming that all things like avr-gcc, avr-libc, lua etc are properly installed, it does everything:
Downloading Nut/OS, unpacking, configuring, patching, compiling.
Moreover, I put a binary .hex files to the source.
infplay-final1-Os-memdebug.hex: Compiled with -Os option and memory debugging features

If you wonder how to generate the menudata-progmem.c and menu-interperter-config.h from the menu-012.xml, see menudesigner.sourceforge.net. menu-011.xml contains a GUI with the same functions, but a little bit different design and was only tested with older versions.

In order to compile without the memory debugging, you have to remove the "-DNUTDEBUG_CHECK_STACK -DNUTDEBUG_HEAP -DNUTMEM_GUARD" part from the two files "ethernut/nutapp_arthernet/UserConf.mk" and "ethernut/nutbld_arthernet/UserConf.mk". Then recompile library and player as described below. This will save ~5,5KB flash, some RAM and makes the program a little bit faster. Please note, that I only have tested this with very early versions.

By default, the program is compiled for smallest size (-Os) this can be changed to more speed (-O2) and will need additional ~7KB flash. Replace the two "-Os" in the file "ethernut/ethernut-4.8.6/Makedefs.avr-gcc" by "-O2" and the one in "ethernut/ethernut-4.8.6/app/Makedefs.avr-gcc". Then recompile library and player as described below (and look if it is still small enough to fit into the AVR). Please note, that I never have tested this.

== The PC version ==
The pc version uses the same code as the player, but no code (except headers) from Nut/OS. It is intended as proof-of-concept and not as player for the daily use. In order to hear the played files and streams, the player mpg123 must be installed. The PC version does not provide the FTP server and some statistic functions are missing. The playtime is only correct if the source is 128KBit/s. The threading of the PC version is not as quick as the one on the AVR, because file access is used blocking on the PC (but not with Nut/OS on the AVR).
The GUI can either be use very simple ASCII (good for debugging) or the ncurses lib (looks better).
Please do not try to play files while using a file as output. The player copies the data as fast as the source provides and as fast as the target accepts data. If source and target are both files, this will be very fast and easily fills up all your disk space.
The PC version sometimes just terminates, because sometimes mpg123 tends to close the pipe at the end of a stream.
Start the PC version with the script 'startinfplay.sh'.

== Recompiling ==
The Nut/OS library can be recompiled by running "make clean all install" in the directory "ethernut/nutbld_arthernet". (Yes, you really need the install.)

The player can be recompiled by running "make clean all" in the directory "final1". (The clean is needed whenever the menu was changed, the library was changed, the header files were changed or the compiler settings were changed.)

== Adding a station ==
For each station, the player expects a file containing an URL. This URL may refer to a playlist or directly to a station.
You can add (shoutcast) stations by the following way:
1. Create a directory 'stations' on the root of the SD card.
2. Copy the URL provided on the streaming website into a new file and save it with the ending .url
3. Put this file into the 'stations' folder. Feel free to create sub-folders for categorizing.

Example:
Website is: http://somafm.com/play/lush
There is a "Start stream in external player" link pointing to "http://somafm.com/startstream=lush.pls"
Create a file 'Lush.url' with "http://somafm.com/startstream=lush.pls" as content.

There is a 'stations' folder with some example sations.

In the case the playlist format is not recognized or there are other problems, you can
download the playlist with "wget" and put the first URL you found in the playlist directly in the .url file.

To the format of the .url file (parser: connurl.c):
The URL must be within the first 384 bytes of the file. This part is searched for the substring 'http://'. From this point to the end of the line (use Unix linebreaks) or end of file is interpreted as URL.

== Lastfm support ==
Add a file with your username and the md5sum of your password into the file "lastfm-auth.txt" on the root directory of the SD card.
There is a shell script (make-lastfm-auth.sh) for generating a proper file.
Once the FTP connection is closed, the content is copied into the EEPROM and the file is deleted to prevent future readouts.
Security issue: The 'first' lastfm authentication, which the player uses, is insecure. The md5sum of your password is transmitted over the internet WITHOUT ENCRYPTION AND WITHOUT SALT. This means unless you use a very long password, someone could easily restore your password with a rainbow table. Moreover the md5sum can be used to play songs with your account regardless if he has your password or not.
Lastfm supports a more secure authentication method (using the time as salt), however I did not get it working. I properly get a session id, but can not set a station name with it.

Funny note: You can switch the station while playing, using your PC. Just use the PC test program "./lastfm".

== Add a Lastfm station ==
Put the name of the artist into a file with the ending '.lfm'
A heuristic function automatically detects if umlauts are iso8859 or utf-8 encoded.
To prevent wrong detections:
If you use iso8859, do not include Â or Ã. If you use utf-8, at least one char representable in iso8859 must be included.
Moreover you can use the currently playing artist as new station name.

== Hidden "Features" ==
The LCD background flickers with 2,5Hz for some time and then the player resets...
  This is the panic output if the system detected something very bad. Currently this only happens if malloc, calloc, realloc returned
  an address pointing to an invalid location... like I/O memory. Its a bug!
"Save settings" writes the misc settings, remote values and networks settings into the internal EEPROM.
"Shutdown" and "Reboot" are writing the current played source, the volume, if played or reaming time is displayed, file play mode and recording mode into the EEPROM.
Changing the network settings gets activated immediately, except for DHCP, which runs only once if enabled on power up.
The player sends out status information over RS232 with 9600 baud.
Leave the "Stats" menu, to get a faster FTP transfer. (the difference is ~10KB/s)

== Recording ==
Generates a mp3 file in the directory "records" with the ID3 tags showing the song played when recording started.

== Record later ==
Generates a 10 byte hash value from the title and artist. Up to 100 hash values can be stored.
If a song with the same hash value starts to play, the song is recorded and the hash value is removed from the list.

== If nothing works ==
The very first thing the program does is to print out "BOOT" on the serial port. This happens before any initialization of external devices. So if you don't even see this string, there could be several very basic things gone wrong:
 * You may have electrical problems
 * Your PC has wrong settings for the serial port
 * You use a wrong crystal or the AVR fuses are wrong
 * Your bootloader wont start the program
 * Flashing the program was not successful
