Ylink readme
This is ylink, a yampp-link tool for Linux, Mac OS X and Windows.
To build on Linux or Mac OS X:
./mk
To build on Windows:
Cygwin: ./mk
VC6: just use the supplied project/workspace
To compile ylink with Cygwin you need to install the following packages
besides a "normal" installation: gcc, make & perl
For people who isn't familiar with Cygwin it is kind of "Unix-on-Windows"
and allows Unix applications to be compiled and executed in Windows. The
resulting executable can be used outside of Cygwin if the 'cygwin1.dll'
is in the PATH or the same dir as the ylink executable.
For help output:
ylink (or ./ylink if '.' isn't in your PATH)
Some example commands:
ylink ping
ylink dir
ylink put out.mp3 : dir
ylink put 21 out.mp3
ylink del 0 : put new.mp3
And for editing playlists:
ylink plget
emacs playlist.txt
ylink plput
And for using option '-s':
(Windows)
dir /b *.mp3 | ylink -s put 210
dir /b /s *.mp3 | ylink -s put 210
(Linux)
ls -1 *.mp3 | ylink -s put 21
Note: When using stdin ylink accepts only one command
(same as for low-level commands).
And so on.
Transfer modes
==============
ylink supports three different modes, one has nothing to do with the
player but is useful for testing and understanding YADL. The *nix/Cygwin
version has all modes built-in whereas the Windows version needs DLLs
to support the transfer mode. Currently there is no 'file' DLL for ylink
so this option is not supported on Windows.
disk: Talks directly to a physical disk formatted in YADL. The *nix/Cygwin
version needs the device specified with '-d'. The Windows version
works only on NT/2k/XP and scans automatically for a connected disk.
Windows version searches first for 'RdWrDisk.dll' and if not found it
will search for 'RdWr.dll'.
Usage: -t disk -d
file: Talks to a file. This mode cannot be use to transfer any data to the
player, instead it is provided for test purposes. Currently not
supported in the Windows version due to lack of DLL.
Usage: -t file -d
First you need to create the file you want to use,
'touch '
Next you have to format the file, with ylink. Now the file is ready
to use just as a normal disk or player.
usb: Talks directly to the player through the USB-port. This is the
default mode and is used if nothing is specified on the command
line. Windows version searches first for 'RdWrUSB.dll' and if not
found it will search for 'RdWr.dll'.
Optional Usage: -t usb -d
Caching
=======
ylink supports caching to improve transfer speed when used together with
a player that has a large disk. This is done by storing the system sectors
in a file stored locally on the disk. The rootsector from the player is
compared with the cachefile at every access and if they are identical the
cachefile is used instead of reading from the player. Writing is done in a
similar way but only sectors that are different from the cachefile will be
written to the player. The format of the cachefile is pure binary so it is
an exact copy of the yampp sectors.
The cachefile is unique for each yampp and uses the disks identity
(the name supplied when formatting the disk) to know which file to use.
These files are stored in a specific ".ylink" directory which ylink tries
to put in one of four places. The three first locations are normally set
by environment variables. The fourth is a "fallback" location in case no
environment variable is found.
1: YLINKDIR, a new ylink-only variable
2: HOME, the users home directory
3: TEMP, the users temp directory
4: the global temp directory, "/tmp" on *nix and "c:\temp" on Windows
The caching function is disabled by default and is enabled by using
option '-c' in the global options.
Color LCD
=========
For using ylink to create the bin-file with all the bitmaps for the color
LCD, just run 'ylink pack-color-bmp' in the directory where you keep all
the required bitmaps. Ylink will search the current directory for all
'bmp[0..].bmp' files and then all 'icon[00..].bmp' and pack them together.
This way you can change the number of bitmaps in your firmware without
having to update ylink.
To pack the bitmaps and upload the binfile in one go:
ylink pack-color-bmp : put-color-bmp Datas.bin
Backup & Restore
================
Ylink features two commands that can be used to make a security copy of
your players data section. This can be very useful to prevent data loss
so that you in case of problems don't have to upload all songs again.
Use command 'backup' to save a backup copy on your harddisk and command
'restore' to write the file back to the player. When ylink restores the
file to the player a check is made against the disksize to prevent you
from writing a file that doesn't match the disk to the player.
Generic upload (Yampp LoadFile)
===============================
Ylink features the possibility to write a binary file to any location in
the players eeprom/disk. This can be useful if you are experimenting with
new features in the firmware and need a way to put data in the player.
This is made possible through an 'ylf-file' which is a simple textfile
that contains necessary information to upload the file. The original
idea for this function came from Uli :-)
YLF-file specification:
* The parsing is case insensitive so you don't need to use capital letters
except for the first row that is used to identify the file.
* You may not have empty rows inside the ylf file between two keys.
Example ylf-file:
-----
#YLF CONTROL FILE
HEADER= (not used by ylink, but will be used as header in a gui dialog)
TARGET= (DISK or EEPROM)
SECTOR= (0 or WASTELAND) (not valid for EEPROM)
OFFSET= (Offset from 'SECTOR' for DISK, and offset from '0' for EEPROM)
LENGTH= (0 == transfer whole file, not 0 == transfer part of the file)
SOURCE= (the file to upload, relative or full path)
-----
GUI-mode
========
As of version 0.9.6 ylink can output specially formatted printouts that is
adapted for easy parsing for a GUI-application. These printouts are printed
on one line in tab-separated form.
The special printout formats are:
dir: "%5d\t%s\t%s\t%d:%02d"
songnumber,
artist,
title,
sb->play_time / 60,
sb->play_time % 60
put: "%5d\t%s\t%s\t%d:%02d\t%d\t%d\t%d\t%d"
songnumber,
artist,
title,
play_time / 60,
play_time % 60,
start_offset,
bitrate,
vbr, (1 == VBR, 0 == CBR)
flag (1 == new song, 0 == old song)
pldir: "%5d\t%s\t%s\t%d:%02d"
songnumber,
artist,
title,
sb->play_time / 60,
sb->play_time % 60
plget: "%5d\t%s\t%s\t%d:%02d"
songnumber,
artist,
title,
sb->play_time / 60,
sb->play_time % 60
Additionally the following commands accepts input from stdin in GUI-mode:
get, del, put, plput
Together with these changes option '-s' can now use more command on one
command-line.
In GUI-mode ylink expects the input to be sent with one argument per line
separated with '\n' and stop with EOF.
Example for put: song1.mp3\n
song2.mp3\n
EOF
The documentation below is pulled from the 'ylink' command help
output, and the top of the ylink.c source file. Major limitations of
this version of ylink are listed near the bottom.
/Roger
