Siteplayer

The following is a guide to understanding the basics of siteplayer use. There is more comprehensive treatment in siteplayer's documentation.

See Steve Sprouse's Siteplayer FAQ also.

Definition file

The definition file (SPD file) is the guts of a siteplayer program, in that it defines the siteplayer's initial conditions, and where everything goes. It has three parts: the definition section, the object section, and the export section.

Definition section

The definition section sets values for the siteplayer's operating environment. It tells the siteplayer how to operate, and it tells the SiteLinker program where to find the files it needs to make a siteplayer program. It looks something like this:

 ;$devicename sets the name or description of the device
 $devicename "Tom's Siteplayer"

;$DHCP on tells Siteplayer to find its IP address from a DHCP server
 $DHCP on

;$DownloadPassword sets password for downloading web pages
 $DownloadPassword "password"

;$SitePassword sets password for browsing web pages
 $SitePassword ""

;$InitialIP sets Siteplayer's IP address to use
 $InitialIP "128.122.151.62"

;$Sitefile sets the binary image filename that will be created
 $sitefile "C:\Program Files\Siteplayer\myFile.spb"

;$Sitepath sets the root path of the web pages for this project
 $sitepath "C:\Program Files\Siteplayer\SP_Root"

;$Include sets the name of a file to include during make process
 $Include "C:\Program Files\Siteplayer\pcadef.inc" 

note: comments are preceded by a semicolon in the definition file. The parameters are all explained in depth in the siteplayer software manual.

Object section

This section of the definition file defines the variables, or objects, available in the siteplayer's memory.

Siteplayer's variables are called objects. Objects can be several sizes, depending on how you define them. Objects are defined in the definition file, and used in the HTML and SPI files.

• DBit defines a bit-sized object
• DB defines a byte (8 bits)
• DW defines a word (16 bits)
• DD defines a double word (32 bits)
• DS defines space for a variable without placing a value in it. This is similar to indirection in the C language; the variable defined using DS is a pointer.

Before assigning any variable, you define an origin address in the siteplayer's memory using the keyword ORG. Any variable defined after an ORG command will start at the address given by the ORG command. Addresses are usually given in hexadecimal notation, so the letter h is added after the address. For example:

org 0h
byteVar dB 2 ;a byte variable with the initial value 2   
fooVar dB 0 ;a byte variable with the initial value 0
bigVar dw 921 ;a word variable with the initial value 921


org 0FF15h ; switching to another section of memory
anotherVar dB 1
lastVar dB 3 

In the above example, the variable byteVar is at memory address 0h; fooVar is at memory address 8h (follows right after byteVar); and bigVar is at 10h (follows on from fooVar). anotherVar is at 0FF15h (follows from the next ORG statement); and lastVar is at 0FF1Dh (follows on from anotherVar).

In practice, it's easiest to just start your variables at address 0h, and not worry about other addresses unless you're addressing the special function registers, like the com port or the UDP send and receive objects (more on those later).

The I/O pins are bits located at a special address in memory, starting with 0FF11h. To use them and give them names, define spaces at their addresses, like so:

org 0FF1h

pin1 ds 1
pin2 ds 2
pin3 ds 3
pin4 ds 4
pin5 ds 5
pin6 ds 6
pin7 ds 7
pin8 ds 8

(tip: the pcadef.inc file in the main siteplayer directory includes definitions for all the pins. Include it in your definition section and you can use its names for the pins, IO0 through IO7)

If all this addressing makes you crazy, take out a piece of graph paper, treat each square as a bit, and map out the variables on paper. Count the squares and use a decimal-to-hex calculator like the one built into siteLinker to get the right values.

Export Section

The Export section of the definition file allows you to export your siteplayer code as HTML files, Visual Basic files, and so forth. For simple projects, it's not needed, so we won't go into it here. For more on it, see the software manual.

HTML File

Siteplayer's HTML files are normal HTML files. To include the variables in your HTML files, you use special symbols. For example, to include the variable myVar in a file, type a caret character (^), then the name of the variable, like so:

The value of myVar is ^myVar

The value of the variable will replace the caret and the variable name. Variable names can thus be used to show the value of a variable, to make links to other pages in the siteplayer (A HREF="page^myVar.html"), and much more. There are modifiers that allow you to add to a variable's value, get a specific bit or digit of a variable, perform logic operations like AND, OR, and XOR on a variable, and so forth. Consult the manual for the full range of possibilities.

"When designing your web site, keep in mind that Siteplayer has a 48K limit. The size is displayed by SiteLinker after it makes the SPB binary image file. Every character, space, linefeed, carriage return, and filename will make a difference towards that total."
-wise words from the software manual

SPI File

The SPI file allows you to input data to the siteplayer from a browser using the GET method, much like a CGI script on a regular server. The SPI file can return perform any function in the HTTP 1.0 specification. Most commonly, it's used to redirect the browser to a new page after a form has been completed. It's possible to use objects in the SPI file to direct the browser to different pages depending on the value of a variable.

For example, let's assume there are three pages, file1.html, file2.html, and file3.html, which the user might see after picking a number from a popup menu on an initial page, index.html. The form on the index page would assign a value to the variable myVar, and the SPI file would use that value to redirect the browser as follows:

HTTP/1.0 302 Found
Location: /file^myVar.html

The HTTP message 302 tells the browser that the server got the response, and the location line tells the browser where to go.

If you don't want to use a form, you can write a simple link to an SPI file to send in variables, using the ? operator used to address a CGI form, as follows:

 <a href="myFile.spi?myVar=12">set the variable to 12</a>

You can string several variables in using the & operator, like this:

 <a href="myFile.spi?myVar=12&fooVar=0">set lots</a>

SPI files offer considerable possibilities for input to a siteplayer. Since they simply respond to HTTP requests, anything that can make such a request could then get information from a siteplayer. For example, a Director movie that calls getNetText using the SPI file as its source could continually poll the siteplayer for information. Instead of using the 302 redirect command, an SPI file could simply return a 200 OK command, followed by text, like this:

HTTP/1.0 200 OK
myVar = ^myVar
fooVar = ^fooVar

The getNetText would then get nothing but a string including the variables and their names, along with a header which could be discarded. This allows you to send information from the siteplayer to a Director movie without having to go through a web page.

Once the files are made

Once you've made your SPD, SPI, and HTML files, you use the siteLinker program to compile them into a siteplayer binary file (.spb) and download them to the siteplayer.

Before you download, however, you need to make sure you have the IP address set correctly. Open the Serial Tester program, and connect your siteplayer to the serial port of your PC. Click "GET IP" to see the siteplayer's IP address. If it's a new siteplayer, it will have the default IP address, 192.168.1.250. Set it to whatever address you plan to use and click "SET IP".

Note that when you load a new .spd file into the siteplayer, you're actually doing it through the ethernet connection. So if you don't have a good ethernet link, you won't be able to download. If you're working on a network where others might be using a siteplayer, make sure you have the right address. If you set the wrong address, someone might download to your siteplayer inadvertently. If you are working with others who have similar IP addresses, it's a good idea to set your download password to something unique, and use it for all of your programs, so that no one downloads to you my mistake.

Once you've set the IP address, you're ready to compile and download. If you've downloaded once already, make sure you've got the right password. Then choose "Compile and download" from the sitelinker program, and your program will download to your siteplayer.

Sometimes it takes a few tries to get the siteLinker to download, but once you get it going, there's not much to it. The siteplayerPC program is an emulator that will let you test your siteplayer files on the PC without an actual module. Useful if you've ordered one and are waiting for it to arrive.