CSE466 Lab 6

CSE466 Lab 6: Conductor

Resources:

http://www.palm.com/devzone/docs/palmos/ (Programmers's Companion and SDK Reference

http://www.palm.com/devzone/docs/pptdg/TableOfContents.htm (On-line version of Palm Book. Focus on Chap.4,6,9)

New versions of midi to cse converter for NT/Cygnus and for Unix. This new version uses 0 for the stop opcode instead of 2, it has a new parameter for song title (last parameter), and it includes the title length and song title at the beginning of the hex file. See below for format specifications. The old version for NT/Cygnus is still where it was, but I clobbered the Unix one. Let me know if you still need it.

Requirements:

For Lab 6, please implement the pilot-player interface and UI for the following state transition diagram:

Based on feedback from class today, I’ve concluded that the students were basically right…we should design our interface to match that of standard tape/CD players:

A user pause command stops immediately and leaves the buffer full as is.
A user stop command has two possibilities: if the player is currently streaming we stop the music and clear the buffer, otherwise we just clear the buffer by sending a 'C' command.
A user play command resumes streaming if currently paused. Incoming music is put into the queue behind what is already there. If a user selects a new song to play after hitting pause, then the Pilot should probably send a 'C' to clear the buffer. This would be the same as hitting stop the selecting a new song.

Format and Interface Specs

Music Packet format: .
TNE.CHAN,(CHAN==0?OPCODE:TONE),[TONE,[TONE]]
OPCODES are

STOP packet = TNE.0,0 or TNE.0,2 (might as well support 2 so that we can still play old music
PAUSE packet = TNE.0,3 (okay, lets use 3 instead of 2, so that you can still use 2 to mean stop)

STOP or PAUSE packets are inserted into the stream by the Pilot in response to user buttons; it is the responsibility of the Pilot to insert such commands at packet boundaries. The music hex data will always have a STOP packet at the end, so the pilot doesn’t need to worry about it. The music should stop if the queue becomes empty anyway.

Song format
In the Palm database, songs are in the following ASCII string format, all fields are in HEX unless “ASCII” is specified: LEN,(MESSAGE IN ASCII),TEMPO, [MUSIC PACKETS]*
Fields:
LEN: number of bytes in the ASCII message section (0-255). Format is HEX
MESSAGE: An ASCII string of length LEN. Any ASCII character is acceptable here
MUSIC: As specified above, format is HEX.

Your Pilot program will have to convert the hex data (ASCII chars 0-9, a-f, A-F) into binary bytes to send to the player. For example the string “09STAIRWAY!12FF1010100000” is a 17 byte song with 7 bytes of music. It is up to the pilot SW to transmit only the 7 bytes of music data, including the one-byte tempo (18 millisecond/timeslice), a four-byte music packet, and finally the two-byte stop packet.

Adam and I will provide software for:

Creating song files from MIDI source (fixed for new STOP code, and to include ASCII message header (see above)
Building pilot song databases from song files

Implementation Notes:

It's up to you whether you use the suggested functions and data types listed in the instructions below. The links above, particularly the SDK Reference will be very helpful for using any of these functions. If you find a better function or a better way to do something feel free to do so. The API is pretty straight forward and easy to understand.

1. Create the Palm database that you will use. Use the files2pdb program to create a database from your data files. As the database name use "CSE466DB". To use the program (on Unix or NT) type

java files2pdb -n CSE466DB -t Data outfile infiles

for infiles use a list of the song files you want to add to your database. This will create a separate record in your database for each file. Feel free to share songs you have compiled with each other, but you should build your own database..

2. Create a new project. Under the File menu select New... and in the dialog box that comes up select "Palm OS 3.1 Stationery" after entering a project name. In the next dialog box, select "Palm OS C App." This will create a new project which includes the basic header and source files, including the main functions for a Palm app (Starter.c contains this code).

3. Create the user interface. Use the Constructor program to create the graphical interface that you want to use. If you double click on the Starter.rsrc file under the AppResources folder in the project panel, the Constructor should open and display the resources in the Starter.rsrc file. The interface should include buttons for Stop and Play. If you have trouble putting the components together, Chap.5 in the Palm Book link above has some simple instructions.

4. Write code to open the database and record. You will probably want to find and open the database in AppStart function. Use something like:

#include <DataMgr.h>

LocalID dbID = DmFindDatabase(0,"CSE466DB");

DmOpenRef gDB = DmOpenDatabase (0, dbID, dmModeReadOnly);

to do this (note that gDB should be a global so you can access it from other functions). You should handle failures appropriately (quit the application or display an error alert).

The following code snippet shows you how to get a handle to record (in this case the first record in the database, denoted by a zero) once you have a database reference. Once you have a handle to the record you must lock it before it can be used. The MemHandleLock function returns a VoidPtr which you should cast to some other type of pointer (here a char *). Once you're done operating on the record, unlock it.

VoidHandle songHandle = DmGetRecord(gDB,0);
char *song = MemHandleLock(songHandle);

/* do stuff here */

MemHandleUnlock(songHandle);

5. Write the code to stream the song over the serial port. Don't forget the Serial Communication Tutorial that you read. This code should be tied to your user interface appropriately.

6. Connect the Palm and let'er rip!!! Get a serial cable for the palm and connect it to the serial connector from the microcontroller with a null modem in between. Place the Palm in the cradle and debug the program on your Palm (Ctrl + F5). You have to write a sequence of character on the plam to put in debug mode. This sequence is "Shortcut . . 2". The shortcut looks like an upside-down gamma. You won't really be able to debug because you need to take the Palm out of the cradle and connect it to your microcontroller. You can also use a pilot simulator for debugging the UI and the database accesses. Ask your TA for help if you would like to try this.