Programmer S Practice to The

CD player

Example 1

Programmer’s Practice to the CoBox

with UPnP and CGI

Version 5.01 (2001-07-31)

(Official revision)

Before starting…

Before starting, it is a good idea to read Programmer’s Guide to the CoBox, Programmer’s Practice to the CoBox (version 4.3) and UPnP documentation (www.upnp.org). However, if you have some practice with C, HTML, Visual Basic, and Visual Basic Script, and approximately understand what is the CoBox and for what it could be used, you can begin immediately. So, let’s go…

Hardware requirements

On beginning to develop the Cobox with UPnP, you must have the following tools:

·  PC having a serial port and connected to local Network (LAN). It is better to have the second PC with Windows Me for testing your UPnP connecting to CoBox. The best decision is to have more the third PC (for example, laptop) for independently capturing the IP-packets. However, minimally you can use for all these aims one PC only with Windows Me.

·  CD-ROM, Sound Card and audio CD

·  RS-232 serial cable with the corresponding connector DB-25

·  Network RJ-45 TP-cord

·  Socket-block with a switch for power supplying.

Software requirements

On your PC, you must have:

·  Windows (the best, Windows Me with Visual Studio 6 and Office 2000)

·  LAN connection with TCP/IP protocol. The best variant is the constant IP-addresses both your PC and your CoBox – please, ask your LAN administrator to do it.

All necessary software for developing a program to CoBox is offered you in given set CPK 5.0, and in Programmer’s Guide to the CoBox you can see how better to organize your project and library directories. For our experiments, we are also in need of some additional programs:

·  Terminal program to analyze a serial port’s flow. If you have no another preferences, you can use the standard Windows Hyperterminal. Do not forgot to tune it as your Cobox’s serial ports default – 9600 Baud, 8 data bits, no parity bit, and 1 stop bit.

·  Network Terminal. For TCP connection (for example, for setup configuration), you can use the standard Windows Telnet. For UDP connection (for example, for debugging) Windows has no terminal client. We offer you to use the additional utility UDPCBXTest.exe attached to CPK 5.0.

·  TFTP client. Use the tftp.exe of standard Windows NT (it works under Windows Me too) or another client that is comfortable for you and can work in your operational system.

·  So-called network “sniffer” for monitoring a Network activity, however such programs delivered separately by its manufacturers and in CPK 5.0 are not included.

What is CoBox?

CoBox is approximately the PC XT. A general purpose of CoBox is transferring data between COM-port and Network. However, really on the CoBox’s base, you can develop different programs, because by this data way the CoBox’s processor can totally reform them.

In this case, we will implement a fresh CoBox’s feature – UPnP. We will see that this little box give your serial devices the absolutely new and wonderful possibilities and we will learn programming and controlling it.

What is UPnP?

UPNP (Universal Plug and Play) protocol is described in special documents (for example, “Universal Plug and Play Device Architecture”, Version 1.0, 08 Jun 2000, © 1999-2000 Microsoft Corporation), which you can find on www.upnp.org. It seems to have a wonderful future for non-professional using in home networks for different home devices (for example, TV-sets, musical centers or refrigerators) to provide them controlling by PC or some special controlling units. In addition, it allows connecting and tuning any network devices automatically simply by binding and switching power on.

What is CGI?

CGI (Common Gateway Interface) is protocol for data exchanging between client’s browser and server’s program (so-calling CGI script) that client can remotely run by special GET or POST request on server by using HTTP protocol. The result of this script work the server sends back to client as usual HTML page that client’s browser can just show or client’s script can handle to imitate monitoring or controlling the server (host) device. In contrast with UPnP it can work with any browser under any OS (not only under Windows Me).

How you could write and check the CoBox’s programs?

I recommend you to use the following order of actions:

1. Write or edit your program by any editor
2. Make the program by the Borland C tools and convert it to ROM-file by the e2i.exe utility (we usually use the batch file t.bat included in CPK 4.3)
3. Download the ROM-file into CoBox by TFTP client

for example: tftp.exe –i <CoBox_IP> PUT <program_name>.rom 3Q

1. If it is necessary, set up new CoBox’s parameters in SETUP by Telnet or Terminal

for example: telnet.exe <CoBox_IP> 9999

1. Start the necessary utilities for looking (Telnet, COM Terminal, UDP-client, etc.)
2. If it is necessary, power off/on to reset CoBox
3. See how your program works and think why it does not work

Our Serial Device

This is the main thing! All our future actions will be built on the base of understanding what we want to do with this device. Each of yours further will have a concrete device of your firm and must hardly understand that your success of UPnP implementation will be depended firstly on right description of this real device.

If you know the OOP (Object-Oriented Programming) principles, you will understand it very easy – just you must build the class for your device, i.e. describe it as unity of properties and methods. Usually for it, you should not analyze the functionality of your device – you can consider that it is just “black box”, but you must analyze obligatory its serial interface – if this device does anything, it means that its serial commands and replies describe totally all its important variables and actions. You must only connect it to whole picture.

On www.upnp.org you can find many examples of descriptions of different devices. For our practice, I have written for some days a simple CD Player with Visual Basic 6, assembling it from some MSDN library examples. In correcting many errors in these examples, I have got the normal working program of CD Player with Volume Tuning in what I have inserted additional own serial interface for controlling Player through COM1.

You can see yourself the source texts of this example in CPK 5.0. For us it is important only the following below description of my own serial interface that just imitates serial interface of any similar device. Assume that this is not our own emulator, but any “black box” device and you just read its manual where there is the following text:

“By using this CD Player, you can control it both from frontal panel, and from serial interface RS-232C. Use the following input commands:

“CD IN PREV” for moving to previous track or to beginning of current one,

“CD IN NEXT” for moving to next track,

“CD IN PLAY” for playing current track or restoring play after pause,

“CD IN PAUSE” for pausing current track,

“CD IN STOP” for stopping and returning to track #1,

“CD IN EJECT” for ejecting current disk or inserting new disk,

“CD IN VOL_UP” for increasing volume by 1024 units until 65535 (maximal),

“CD IN VOL_DOWN” for decreasing volume by 1024 units until 0 (minimal),

“CD IN VOL_CHANGE x” for changing volume to “x” value,

“CD IN INIT” for re-asking current state of the CD Player variable.

After each input command, the CD Player will reply the following answer, where “cmd” is considerable part (bold font above) of the input command received before:

“CD EV COMMAND_ERROR cmd” if this is a wrong command, or

“CD EV COMMAND_REPLY cmd” if this is an acceptable command.

Beside that, if there are any actions of user from frontal panel, the CD Player sends to COM1 the following messages:

“CD EV PREV_CLICK” if “Previous” button is clicked,

“CD EV NEXT_CLICK” if “Next” button is clicked,

“CD EV PLAY_CLICK” if “Play” button is clicked,

“CD EV PAUSE_CLICK” if “Pause” button is clicked,

“CD EV STOP_CLICK” if “Stop” button is clicked,

“CD EV EJECT_CLICK” if “Eject” button is clicked,

“CD EV VOL_UP_CLICK” if “Up” button is clicked,

“CD EV VOL_DOWN_CLICK” if “Down” button is clicked.

At last, your CD Player constantly looks after the different events and additionally sends to COM1 the following messages:

“CD EV TRACK_CHANGE x” if track number is changed to new “x” (any way),

“CD EV MODE_CHANGE x” if mode number is changed to new “x” (any way),

“CD EV VOL_CHANGE x” if volume value is changed to new “x” (any way),

“CD EV LOAD_DISK” if a disk is loaded (any way),

“CD EV LOAD_FORM” if a screen form is loaded (any way),

“CD EV UNLOAD_FORM” if a screen form is unloaded (any way).

This way you can totally control this CD Player through any serial terminal.”

In reading this, you must decide what variables and actions of your CD Player you can really use for UPnP controlling through the Network and CoBox.

Firstly, you can see that all input commands have prefix “CD IN”, but all output event messages – “CD EV”.

Secondly, you can see that there are three clear variables: track, mode and volume. Obviously, that these variables are good candidate for properties of our class “CD Player”. The “track” variable matches the current disk track (if disk is absent, track = 0). The “mode” variable matches the current state of CD Player – this is standard value of MCI (Multimedia Control Interface) minus 500 (only for economy of place with transferring), i.e. 24 = “not open”, 25 = “stopped”, 26 = “playing”, 27 = “recording”, 28 = “seeking”, 29 = “paused” and 30 = “ready” (really this codes work not always correctly, but all questions to Microsoft, please). At last, the “volume” variable matches the 16-bits volume level from 0 to 65535.

Thirdly, obviously, that all “CD IN” commands are good candidate for methods of our class “CD Player”, because of the first eight commands directly match “button” commands of CD Player, but last two commands give a wonderful possibility directly to control the volume level from remote UPnP controlling unit and to catch up the current state of CD Player.

Other possible events are not so important and their result we always can know from values of our variables. Finally, our class “CD Player” has three properties and ten methods.

Our UPnP Device

This is the next important step on our way. The main that you must understand here is that your UPnP Device is very similar, but not equivalent to your Serial Device described above, because UPnP Device consists not only of your Serial Device, but also of your CoBox that provides the external UPnP interface and translates UPnP commands to serial commands and vice versa.

Your UPnP Device can be described as a class too, however this description already is not your choice, but has a specific template that is fixed in UPnP documentation and protocol. Therefore, your task is to find matching your Serial Device in UPnP templates. To avoid now reading the huge UPnP folio, I will tell you the main that you must know.

Formal UPnP device has a following hierarchy. Firstly, it is a root device (that can have embedded devices – fortunately for you, this is still not available in this version of CoBox’s firmware). Any devices can have any amount of services. Any services can have any amount of static variables and actions. Any actions can have any amount of input and output arguments. This tree of embedded classes is described formally by some XML-files of fixed structure, beginning from a root device file, whose URL are used for notifying in UPnP.

For you it is important to know that CoBox must have obligatory one file for describing the root device (usually, for CoBox it has name “x.xml”), in what there are some (minimal, one) references to the services description XML-files. Here we must decide how many services we have. Obviously, we can describe two formally independent services: MCI CD Player and Volume Tuning. Would you have some different MCI devices (for example, MP3-Player, FM-Player, etc.) with one Volume Tuning, it would be good idea to extract the Volume service separately. However, in this case it has no sense. Therefore, in according with famous philosophical principle, we will use a minimal amount of essentialities and describe our CD Player with Volume Tuning into framework of one service.

Let us, firstly, consider file “x.xml”. You can see that XML-file is simply structural document where the so-called “tags” (<name>…</name>) enclose some data and can nest each other for forming the definite hierarchy of these data. Marked text (bold-italic) you can change for your device by following “Universal Plug and Play Device Architecture”, Version 1.0, 08 Jun 2000, © 1999-2000 Microsoft Corporation.

<?xml version="1.0"?>

<root xmlns="urn:schemas-upnp-org:device-1-0">

<specVersion>

<major>1</major>

<minor>0</minor>

</specVersion>

<device>

<deviceType>urn:schemas-upnp-org:device:testdevice:1</deviceType>

<friendlyName>LTRX UPNP CD player</friendlyName>

<manufacturer>Lantronix</manufacturer>