SUMMARY OF WHISKER COMMANDS

The heart of the Whisker control system is the exchange of messages between Whisker server and those clients to which it is connected. First, the scope of Whisker will be outlined by listing the purpose of all the commands you can send to it. After that, the communications system will be described in detail, and in Part 2, each command and message will be described in full.

In the text, messages sent by the server will be blue and the commands sent by the client will be red.

Messages from the Server

These messages are sent down the main communication channel. They are unpredictable in that they may be sent at any time. The arrival of these should cause the client to deal with them 'as soon as possible': this is handled for you in most event-driven programming environments (such as Visual Basic and Visual C++).

When the server detects an event that the client has expressed an interest in, such as a digital line changing state, a timer triggering, or a picture being touched, it sends an Event: message to the client.

Info: messages are sent to inform a client about the completion of commands issued by that client.

If a command cannot be completed, an Error: message will be sent.

If a command is unrecognised, or malformed, a SyntaxError: message will be sent.

If a client allows, the server may pass on a ClientMessage: from one client to another (typically a 'remote-control' message).

If a client attached to a multimedia edition of Whisker has asked for keyboard notification for a display which has the input focus on the server, that client may receive KeyEvent: messages when a key is pressed on the keyboard.

Commands to the Server

Clients may issue a variety of commands to the server. These commands can be grouped into device commands - which control or interrogate the hardware managed by the server, and general commands - for example, those to alter the way in which the server communicates with the client. Devices which can be controlled by a client are timers, digital I/O lines, and (for multimedia editions of Whisker only) video display devices and audio output channels.

Timer Devices

Timers are simple software devices which are used to generate events after pre-specified intervals.

Creates a timer.

Cancels (kills) a timer.

Cancels (kills) all timers.

Line Devices

Takes control of a digital input or output line.

Gives the line one or more alternative names.

Gives up control of claimed lines.

Sets the state of an output line (or lines).

Reads the state of a line (be it an input or an output line).

Causes Whisker to generate an event when the state of the line changes in a specified way.

Clears a specific event associated with a line.

Clears all events associated with a line.

Clears all events on all line devices.

Protects critical devices (such as intravenous infusion pumps) by specifying that the line should return to a safe state after a certain time.

Clears a safety timer.

Audio Devices (Multimedia Edition only)

Takes control of an audio output device.

Gives an audio device an alternative name.

Relinquishes control of all audio devices.

Plays a WAV (waveformat) file directly.

Loads a WAV file, attaching it to a specified audio device.

Creates simple sounds without the need for a WAV file.

Plays a sound that has been loaded with AudioLoadSound or AudioLoadTone.

Sets playback volume for the device.

Stops playback, keeping the sound in memory.

Unloads the specified sound, freeing the memory it occupied.

Stops playback of all sounds currently playing on the specified device.

Unloads all sounds from the device.

Display Devices (Multimedia Edition only)

To display things using Whisker, you place objects into documents and show those documents on display devices. A document's content may be altered whether or not it is being displayed.

Takes control of a 'physical' display (usually a dedicated monitor on a multimonitor computer).

Gives a display an alternative name.

Releases all display devices.

Creates a 'virtual' device (usually a new window on the Windows desktop).

Deletes a virtual device created with DisplayCreateDevice.

Finds out how big a display device is.

Causes the display to respond to keypresses (only applicable when your display has the Windows input focus but useful if you want to use the keyboard as an input device in your testing). Keyboard events are sent to the client with a special KeyEvent: message.

Creates a document.

Places a document on a display device.

Removes a document from a display device.

Deletes a document.

Sets the background colour for a document.

Adds an object to a document. (Objects can be of many types.)

Brings an object to the front of a document.

Sends an object to the back of a document.

Removes an object from a document.

Makes an object respond to being touched or clicked with the mouse.

Clears an event created with DisplaySetEvent.

Determines whether objects behind the specified object are also allowed to respond to touches or mouse clicks.

Obtain high-precision information about the location of touches and mouse clicks.

Although Whisker will display documents sensibly, you can gain extra control over the way your documents are scaled (if need be, adopting your own coordinate system to scale documents for different monitor sizes) using DisplayScaleCoordinates and DisplaySetDocumentSize.

Sets the logical size of the document (for use with DisplayScaleCoordinates).

Claiming groups of devices

You may claim digital I/O lines, displays, and audio devices by device number, or by using names that you define to the server using a device definition file. This allows you to define groups of devices (e.g. all those that correspond to a single operant chamber) and claim them all at once using ClaimGroup.

Timing of events

Determines whether the server appends a time-stamp to all messages it sends to the client. This facility can be used to record accurate timing information.

Resets the timestamp clock to zero.

Requests the time as judged by the timestamp clock (in milliseconds).

Communications management

These commands control the exchange of messages with the server.

Closes all communications with the server, freeing all claimed resources in the process.

Informs the client which TCP port number to use in order to establish a second communication channel with the server. (The second channel is called the "immediate" socket, as opposed to the "main" socket that is established when the client first connects to the server).

Informs the client of the code to use when using the Link command.

Informs the server that a particular "immediate" socket is to be functionally linked to a particular "main" socket because both are owned by the same client.

Tests the speed of the network connecting the client and the server.

Status reporting and miscellany

Detects the server's version information.

Reports the client's name to the server.

Reports the client's current status to the server.

Sends a comment to the server (primarily for debugging).

Requests information about the clients connected to the server, and their current status. (Used to monitor the Whisker system as a whole.)

Audio and display devices may use multimedia resource files such as wave-format (WAV) sound files and bitmap (BMP) pictures. These must be stored on the WhiskerServer machine. Tell the server where to find them with SetMediaDirectory. If a file cannot be found here, the server will try its own resource directory before trying the raw filename.

Client–client communication

The server assists clients to communicate with each other directly, if so desired.

Sends a message to another client. (If the server and recipient permit the message, the recipient will receive the message in a ClientMessage: message from the server; q.v.).

Tells the server whether the client will permit incoming messages from other clients.

Video commands

Video objects are controlled using these conventional object-manipulation commands:

... and these video-specific commands: