The Scrambler Server Documentation (Updated November 5, 2003)


The Scrambler is a very simple message server that can be used to connect the
work of different artists. It broadcasts data from various sensors and other
inputs to anyone who wants to receive and decode the data stream. The server
supports 2 methods for sending and receiving data. The first is an ASCII text
interface. The second is messages from Cycling 74's Max programming language.

The server has a protocol that allows artists to put data into the system. Each
artist is given a username and password. To send data into the Scrambler, connect
to the server and use the PUT message:

PUT [username] [password]

Once the server has checked the password, it opens a connection to receive data.
Messages are then sent as 2 symbols - an identifier and the data associated with
it. For example:

temperature 90

This message is interpreted with "temperature" as the identifier and "90" as the
data.

People on the system will then receive this message as 3 symbols:

[username] temperature 90

In this case, the username is the one that you logged in with using the PUT
message.


To receive data from the Scrambler, anyone can connect to the server and send the
GET message. There are 3 forms of this message:

GET ALL GET [username] GET [number]

The receiver has the choice of getting all data as it comes through the server or
filtering the data in one of two ways. The "GET [username]" message asks the
server to only give you data from a particular user. The "GET [number]" message
asks the server to give you a certain number of data messages and then stop
sending. For example:

GET 3

This tells the server to send you 3 messages and then stop sending. This is
useful if you have a slow speed connection and can only handle a few messages at
a time.

There is one more message that can be sent to the server:

STOP

This closes the GET connection so that you don't receive any more data.


CONNECTING TO THE SCRAMBLER

The Scrambler server can be accessed at:

IP address: 207.34.141.42 (or URL scrambled.aaeol.ca) port number: 8200


USING AN ASCII CONNECTION

The ASCII connection can be accessed through telnet for simple testing. The
commands, identifiers, and data are separated by whitespace (tab, space, newline,
return). A whitespace character is required at the end of each command. For
example:

PUT [username] [password]

This command requires a return or other whitespace character at the end.



USING A MAX CONNECTION

The Max connections uses Norman Jaffe's
(http://www.opendragon.com/Pages/MaxObjects.shtml) TCP Client object for cycling
74's (http://www.cycling74.com/products/maxmsp.html) Max programming language. An
example Max patch to help you get started will be available on this web-site as
of Nov 5/2003. Norm Jaffe's Help file is also a useful tool for figuring out how
the TCP Client object works.



REFERENCE DOCS FOR THE COMMAND MESSAGES

1. PUT command.

PUT [username] [password]

Used to log into the system. This tells the server who you are and that you want
to send data into the system. If you don't have a username and password, you can
e-mail media@front.bc.ca to get more information and become part of this project.
To try out the system you can use:

PUT bite test

2. Sending data.

[identifier] [data]

Used to send a single item of data. The identifier is intended to describe the
data in a simple way, using one word. The data can be a number or text (also one
word).

3. GET command.

GET ALL | [username] | [number]

ALL refers to all usernames and tells the server to send you all the messages
that come through the system.

[username] refers to a particular user. If a username is specified you will
receive messages from that user AND server messages that are identified as user
"scrambled".

The "GET [number]" message only receives messages from the user specified in the
last "GET [username]" or "GET ALL" for all usernames. The first get connection
that you make with the server assumes that you want all messages. For example, if
you connect to the server and want to get 1 message, then:

GET 1

This will assume that you want 1 message from ALL users. To get 1 from a
particular user do this:

GET [username] GET 1

Subsequent "GET 1" message will still receive messages from the given username.

4. STOP command.

STOP

This command stops the server from sending messages to you. It is used to close a
GET connection.

QUESTIONS and CONTRIBUTIONS

You can e-mail questions, bugs, example code, suggested corrections or
clarifications to this documentation to media@front.bc.ca. Please include
"scrambled bites" or "sb" in the subject line (I get a lot of junk mail).

(Peter Courtemanche, November 2003)