README for WhiskerServer ======================== WhiskerServer is now installed. The server can now be launched from the start menu (Start > Whisker > WhiskerServer), or by holding down Ctrl + Alt and pressing 'S'. The edition of the server that you have is displayed on the server's main page. -------------------------------------------------------------- Configuring WhiskerServer -------------------------------------------------------------- Remember, you must do the following manually: - Configure digital I/O hardware (*) - Configure debugging (fake) digital IO lines, if required - Configure audio devices (#) - Configure display devices (#) - Configure touchscreens (*) (#) Note: if you use touchscreens, they must be configured by means of the UPDD (Universal Pointer Device Driver) from Touch-Base Ltd. - If you are using UPDD v4.1 (*) (#), you must modify the PATH environment variable so that WhiskerServer can find TBAPI.DLL. Typically, UPDD installs itself to C:\Program Files\UPDD. So you would do this (on a Windows 2000/XP box): Start > Settings > Control Panel > System > Advanced > Environment Variables > find "PATH" under "System Variables" > click "Edit" > add a semicolon and then type C:\Program Files\UPDD > OK > OK > log off and on. If you don't do this, WhiskerServer will not run and will complain about not being able to find TBAPI.DLL. - Create a Device Definition File - Select the Device Definition File, so the server knows where it is. (*) Not applicable to WhiskerServer Programmer's Edition. (#) Not applicable to WhiskerServer Standard Edition. -------------------------------------------------------------- Running WhiskerServer on Windows Vista/Windows 7 -------------------------------------------------------------- Special considerations apply to Windows Vista and higher, as follows. - INSTALLATION. Ensure you run the installer as an administrator (or it will be unable to intsall to \Program Files). - ALLOWING WHISKER THROUGH THE WINDOWS FIREWALL. When you run WhiskerServer, for the first time, you will see the following message: Windows Security Alert Windows Firewall has blocked some features of this program --------------- Windows Firewall has blocked this program from accepting incoming network connections. If you unblock this program, it will be unblocked on all private networks that you connect to. What are the risks of unblocking a program? Name: WhiskerServer Publisher: Unknown Path: C:\Program Files\WhiskerControl\WhiskerServer.exe Network location: Private network Choose "Unblock" (rather than "Keep blocking"). If you get this wrong the first time, you can redo this using: Start > Settings > Control Panel > Windows Firewall > Allow a program through Windows Firewall. You can then choose either "Add program" (and select whiskerserver.exe, usually in C:\Program Files\WhiskerControl) or "Add port" (and choose port 3233 of type TCP, giving it an appropriate name such as "Whisker main port"). Explanation: WhiskerServer is a server program that must accept network connections to it, on port 3233 and other ephemeral ports. You do not have to let other computers have access to it, but you must at least allow clients on the same computer to have access. - CHANGES TO DEFAULT NETWORK BEHAVIOUR: INTERNET PROTOCOL VERSION 6. Note that Windows Vista by default accepts "localhost" to mean "this computer" for network connections. The old "loopback" is not accepted. Furthermore, Windows Vista runs IPv6. By default, "localhost" refers to the IPv6 local address of ::1, rather than the older IPv4 local address of 127.0.0.1. (This behaviour is all configurable by editing C:\Windows\System32\Drivers\etc\hosts if you wish to do so.) As of January 2009, Whisker clients supplied via www.whiskercontrol.com default to "localhost". If you are using an older client, simply enter "localhost" or "127.0.0.1" instead of the old "loopback". Because of IPv6 implementation problems (as of 6 Feb 2009), we suggest you continue to use IPv4. To specify IPv4 manually, use "127.0.0.1". To make "localhost" refer to this automatically, edit C:\Windows\System32\Drivers\etc\hosts from 127.0.0.1 localhost ::1 localhost to 127.0.0.1 localhost # ::1 localhost - FEATURES OF WHISKERSERVER THAT REQUIRE IT TO RUN WITH ADMINISTRATOR PRIVILEGES. If you do not run WhiskerServer.exe as an administrator, Windows refuses to let it run as a real-time process; Windows silently fails (i.e. doesn't tell WhiskerServer that it won't allow this) and changes the real-time request to "High". Furthermore, it is unable to write to the hardware configuration section of the registry (see the Help section on Whisker's use of the registry). Therefore, *WhiskerServer should be run with administrator privileges.* To configure WhiskerServer to run as an administrator, this is the easiest way: - left-click Start > Whisker - right-click WhiskerServer - left-click Properties > Advanced > tick "Run as administrator" > OK > OK Windows will say: Access denied You will need to provide administrator privileges to changes these settings. Click continue to complete this operation Click "Continue". Windows will say: User Account Control Windows needs your permission to continue If you started the action, continue. Save Shortcut Properties Microsoft Windows Click "Continue". Now the usual WhiskerServer menu shortcut (and the Ctrl-Alt-S keyboard shortcut) will run WhiskerServer as an administrator. However, whenever you do this, a message will pop up saying: User Account Control An unidentified program wants access to your computer Don't run the program unless you know where it's from or you've used it before. WhiskerServer.exe Unidentified Publisher > Cancel - I don't know where the program is from or what it's for. > Allow - I trust the program. I know where it's from or I've used it before. Click "Allow" or press Alt-A. So your quickest shortcut to starting WhiskerServer is now Ctrl-Alt-S > Alt-A. If you wish, you can DISABLE USER ACCOUNT CONTROL entirely (via the Control Panel), and the confirmation message will not appear. However, Windows Vista will moan about this periodically, and it's up to you whether you want the protection against malicious software that User Account Control is meant to add. -------------------------------------------------------------- Programming for Whisker -------------------------------------------------------------- Install the SDK on this machine before running any SDK-based clients (unless these clients install SDK components directly). -------------------------------------------------------------- Using the WebStatus client (*) -------------------------------------------------------------- (*) Not applicable to WhiskerServer Programmer's Edition. If you opted to install and configure Xitami, then the status of the server should be accessible by a web browser (with Java Enabled). The URL will be 'http://servername.domain/' e.g. http://WhiskerPC.psychol.cam.ac.uk/, NOT http://www.WhiskerPC.psychol.cam.ac.uk/