Embed Size (px)
Citation preview
LabControl© A software to control computers in a lab for behavioral experiments. Version 2.6
Adrian Etter University of Zurich Department of Economics Winterthurerstrasse 30 CH-‐8006 Zurich E-‐Mail: [email protected] URL: http://www.econ.uzh.ch/faculty/etter.html
20 September 2013
20.09.13 2
Abstract
This is the manual for the LabControl. LabControl is a program to control computers in a laboratory for behavioral
experiments. The program was designed, developed and deployed to improve the workflow in the laboratory for behavioral experiments at the Department of Economics of the University of Zurich. It allows to simply configuring a set of computers with a given program and its parameters from another computer. The main functionality was adapted to the needs of the laboratories where it is mainly deployed. The standard workflow is the following:
1. Select the program to conduct the experiment with 2. Select the computers to run 3. Wake up the selected computers by pressing the wake up button 4. Conduct the experiment 5. Shutdown the computers
Copyright Copyright © 2007-‐2013 Adrian Etter. All rights reserved.
This document may be copied, modified, reproduced and redistributed for educational and personal use as long as the original author is mentioned and cited.
MATLAB® is a registered Trademark of MathWorks, Inc.™ (http://www.mathworks.com). Processing is an open project initiated by Ben Fry and Casey Reas. (http://www.processing.org) z-‐Tree is a Program to conduct experiments, programmed and developed at the University of Zurich. Urs Fischbacher (2007): z-‐Tree: Zurich Toolbox for Ready-‐made Economic Experiments, Experimental Economics 10(2), 171-‐178. QT is a registered Trademark by Digia Oyj (http://qt-‐project.org/). Windows® is a registered Trademark by Microsoft® (http://www.microsoft.com)
20.09.13 3
Table of contents: Abstract ....................................................................................... 2
Terms and Conditions ................................................................. 4 Acknowledgment .................................................................................................................... 4 License .................................................................................................................................... 4
Installation .................................................................................. 5 Requirements .......................................................................................................................... 5 Files needed ............................................................................................................................ 5 Windows modifications .......................................................................................................... 5 Changes on the control computer ....................................................................................... 5 Changes on the Client Computers ........................................................................................ 7
How to run LabControl .............................................................. 10 Manage Computers ............................................................................................................... 10 Edit ini-‐File directly or how to add multiple computers at the same time ........................... 11 Wake up Computers ............................................................................................................. 13 Wake up configuration .......................................................................................................... 14 The different configurations in detail – Configuration of the batch snippets .................... 15
Shutdown / Restart ............................................................................................................... 16
Acknowledgment ...................................................................... 17
References ................................................................................ 17
20.09.13 4
Terms and Conditions Acknowledgment You are allowed to use this software for free, but please acknowledge if you are using this software to perform
your experiment with the following statement: This experiment was performed with the help of LabControl. LabControl is a tool to control a laboratory for behavioral experiments. LabControl was designed and developed by Adrian Etter at the University of Zurich.
License LabControl is licensed under the BSD 2 License. Copyright Copyright (c) 2013, Adrian Etter
All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. Neither the name of the UNIVERSITY OF ZURICH nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
20.09.13 5
Installation Requirements
LabControl runs on Windows. It was successfully tested on Windows XP, Windows Vista, Windows 7 and Windows 8. Please be aware that you have to make some changes on your operating system to benefit from the full advantages of Lab Control. These modifications can increase the risk of becoming a victim of cyber-‐attacks! The author is not responsible for any occurring security incident provided by this product.
Files needed
Extract the files somewhere on your computer and make a link to the LabControl.exe at a place you will mostly find it again. The files needed to run LabControl are the following: D3DCompiler_43.dll icudt49.dll icuin49.dll icuuc49.dll LabControl.exe libEGL.dll libGLESv2.dll msvcp100.dll msvcr100.dll Qt5Core.dll Qt5Gui.dll Qt5Network.dll Qt5Widgets.dll And in the subfolder “platforms” the following two files: qminimal.dll qwindows.dll Most of these files are QT libraries as it is the under laying framework. Additionally the Microsoft Compiler redistribution libraries are needed. But all these files should be in the original Package you downloaded.
Windows modifications
To benefit from all advantages provided by LabControl you have to do the following modifications to your computers.
Changes on the control computer
Wakeup If the Control Computer is on two different networks, LabControl cannot distinguish where to send the wakeup package. To assure that the wakeup mechanism works reliably, please make the following change to your network interface: Go to the Windows “Control PanelàNetwork and InternetàNetwork and Sharing CenteràChange adapter settings”
20.09.13 6
Fig. 1 Network and Sharing Center
Click on “Change adapter settings”
Fig. 2 Ethernet Properties
Mostly there will be two or more Ethernet adapters in a behavioral experiment laboratory. Repeat this procedure for both or all adapters. Right click on the Ethernet adapter you want to change, select “Properties” from the context menu. Scroll down and highlight “Internet Protocol Version 4 (TCP/IPv4)” and click on Properties.
Fig. 3 Metric change
20.09.13 7
In the “General”-‐Tab click on “Advanced …”. On the new dialog at the bottom unselect the “Automatic metric”-‐selection box and insert in the “Interface Metric” a numeric value between 1 and 1000. The value indicates the cost of using that interface. This means the lower the value, the cheaper it is to use that interface. For instance, to prioritize the network, where the wakeup package should be delivered, enter a low metric, e.g. 1 in to the field “Interface Metric”. All the other interfaces should have a higher value, e.g. 100.
Changes on the Client Computers
These changes must be applied to all client computers:
Wakeup – Bios setting To allow wake up over LAN, the “Wake from LAN on S5” needs to be enabled in the BIOS. Please refer to your
BIOS Manual on how to enable this feature. è Some mainboards do not allow wake on LAN after a complete power loss.
Such computers need to be started manually after they lost power.
Fig. 4 BIOS Enable Wake from S5
Wakeup – NIC Setting Moreover the wake on LAN has to be enabled in the network controller as well. Go to the Windows “Control
PanelàNetwork and InternetàNetwork and Sharing CenteràChange adapter settings”. See Fig. 1 Right click on the Ethernet adapter you want to change, select “Properties” from the context menu.
Fig. 5 Configure NIC
Click on “Configure…”
20.09.13 8
Fig. 6 Enable Wake on LAN
In the Nic Controller Properties on the “Advanced”-‐Tab scroll down until you find two entries: • “Wake on Magic Packet” • “Wake on pattern match”
Set both entries to enabled. Sometimes there is a global “Allow”, “Disable” – Wake on Lan. Check for this property in the above list and select the apropriate value.
To enable and allow remote shutdown on the client computers, there are 3 necessary steps to be followed.
Add Control User on Client Step 1:
On all the client computers there has to be an account with the same Username and Password as on the control computer. The clients don’t have to run on this account, but a control computer must have valid credentials on the client computer to execute the shutdown command remotely. This account has to be the account where LabControl is running on the Control Computer. E.g. The control computer is logged in as user “Experimenter” with the password “SecretPassword”. Then all clients must have an account with the username “Experimenter” and the password “SecretPassword”. But the actual experiment may happen on the account e.g. “Subject” with the password e.g. “SubjectPassword”.
Give Remote Shutdown Privilege
Step 2: Enable remote shutdown privilege. Press “Windows Key + R”, enter in the Run-‐Dialog Field“gpedit.msc” and click on “OK”. Navigate to “Local Computer Policy” à “Computer Configuration” à “Windows Settings” à “Security Settings” à “Local Policies” à User Rights Assignment”. Scroll down to “Force shutdown from a remote system” doubleclick and add the user created in step 1.
20.09.13 9
Fig. 7 Add user privilege to allow remote shutdown
Enable Admin Share Step 3:
Note: Remote shutdown will work only if the admin share is enabled. Again, press “Windows Key + R”, enter in the Run-‐Dialog Field“regedit” and click on “OK”. Navigate to “HKEY_LOCAL_MACHINE” à “Software” à “Microsoft” à “Windows” à “CurrentVersion” à “Policies” à “System” Add the following REG_DWORD: “LocalAccountTokenFilterPolicy” and give it the value 1.
Hive: HKEY_LOCAL_MACHINE Key: Software\Microsoft\Windows\CurrentVersion\Policies\System Name: LocalAccountTokenFilterPolicy Data Type: REG_DWORD Value: 1
Auto Login With the above Steps LabControl is now running. For conveniency, it is recommended to enable “auto login” to the subject account on the client computer. There are a lot of guides in the internet on “How to enable auto login for Windows” for each version of Windows. Please use an internet search engine to get help on this topic or ask your local computer expert.
Add batch file to start up Add a batch file to the startup folder on the client computer. Best practice is to create a batch file that opens the
batch file on the shared drive written by LabControl. Sometimes it happens that the startup script is executed before all network drives are connected. Be aware: the network drive may not be ready immediately after login, therefor the script fails to run correctly if the startup script just is a shortcut to the real startup script on the server.
Ping / IMCP To see in LabControl whether a Client Computer is online or not, IMCP must be enabled on the client computer. There exist several Step by Step guides on the internet on how to enable IMCP. Just type into your prefered search engine: “How to enable ping echo on windows” –followed by the windows version number!
20.09.13 10
How to run LabControl To run LabControl just double click on the LabControl.exe
Fig. 8 Opened LabControl
Manage Computers
To manage computers click on the “Manage Computers” button. The view will be extended by a list of computers. Within LabControl the list of computers can be managed. If the list is empty, there is no computer added yet. A green highlighted computer indicates a running computer; a red highlighted computer indicates that it is not running. Note: This is only working if Ping/IMCP is enabled on the clients! See Chapterà Changes on the Client Computers.
Fig. 9 Manage Computer view -‐ green: online computer -‐ red: offline computer
Add Computer To add a computer click on the green plus. A new window will be opened to enter the name, the IP and the MAC address of the client computer. Add all clients needed to be controlled by LabControl. See how to edit the ini-‐File directly to add multiple Computers at the same time.
Fig. 10 Add/edit computer
20.09.13 11
Three necessary values All three values are needed.
The Computer Name is needed for the batch file generation. The IP is needed for shutdown and online / offline check. The MAC-‐Address is needed for the wake on LAN mechanism.
Edit ini-‐File directly or how to add multiple computers at the same time WARNING: This chapter is only intended for the computer experts who manage/install/maintain LabControl. It is not the purpose that a LabControl user changes default values in the ini. This could be very confusing for other researchers.
Location of the ini-‐File Instead of manually adding and editing all the computers within LabControl, the ini-‐File can be edited directly with
a text editor. The ini-‐File is located on “%AppData% \SNS-‐Lab\Behavioral Lab Control.ini”. Enter “%AppData% \SNS-‐Lab\” in the windows explorer navigation list to access the folder directly. Be aware to change the size to the number of triple rows added.
Editing the ini-‐File If you change the ini-‐File by hand, be aware to follow the escape character rule for special characters, e.g. to
make backslashes used by a path, it needs two: “\” à “\\”, as well e.g. highcommas need to be preceded by a backslash, and so on. If there aren’t any entries in the ini-‐File, open LabControl, navigate to “Wake up Lab” à “View/Change configurations” open the dialog and click on save. The ini-‐File will be extended with all the default configurations.
ini-‐File The ini-‐File could look like this: [Computers] size=7 1\LABEL=Client_01 1\IP=10.0.0.1 1\MAC=00:0C:29:21:4E:01 2\LABEL=Client_02 2\IP=10.0.0.2 2\MAC=00:0C:29:21:4E:02 3\LABEL=Client_03 3\IP=10.0.0.3 3\MAC=00:0C:29:21:4E:03 4\LABEL=Client_04 4\IP=10.0.0.4 4\MAC=00:0C:29:21:4E:04 5\LABEL=Client_05 5\IP=10.0.0.6 5\MAC=00:0C:29:21:4E:05 6\LABEL=Client_06 6\IP=10.0.0.6 6\MAC=00:0C:29:21:4E:06 7\LABEL=Client_07 7\IP=10.0.0.7 7\MAC=00:0C:29:21:4E:07 [Startup_Params] zLeave1=start /D\"N:\\zleaf1\\\" zleaf.exe /fontsize 14 /channel 1\n WebExp=start /D\"%PROGRAMFILES%\\Mozilla Firefox\\\" firefox.exe /no-‐remote /P proxy\n Matlab="matlab -‐r \"addpath('N:\\Matlab\\');runMatlabExp\"" Processing=C:\\ExpFiles\\processing_app.exe custom2="start /D\"N:\\zleaf1\\\" zleaf.exe /fontsize 14 /channel 1 /name wuerfelclient /size 640x480 /position 40,40" CopySource=N:\\ExpData\\copy_to_client CopyDestination=C:\\ExpFiles\\ zLeave2=start /D\"N:\\zleaf2\\\" zleaf.exe /fontsize 14 /channel 2\n custom1=start /D\"N:\\zleaf1\\\" zleaf.exe /fontsize 14 /channel 1\n Header=@@ECHO off\n\n\ntimeout /T 30 /NOBREAK>nul\n [Startup_File]
20.09.13 12
StartUpFile=N:\\Batch\\start_experiment.bat [Lab_Settings] Rows=5
Location of the ini-‐File
Fig. 11 To navigate to the ini-‐File enter “%AppData%” in the Explorer
20.09.13 13
Wake up Computers Startup! To wake up computers, click on “Wake up Lab”. A new window appears where it is possible to select all
computers at the same time or to create individual configurations for each computer. The icons in the top list indicates the program to be started up after the client computer logs in. Select the program that should be started after login and click on “Startup!”
Fig. 12 Wake up all computers the same way
Copy Files If there are files needed to copy to each client computer before running the program, click on “Copy Files from Server to Client?” before hitting the “Startup!”-‐Button.
Write Batch only! Instead of restarting a computer with the desired configuration it is also possible to just write the batch file and
then manually execute it on the client computer to start the desired configuration.
Individual startup To startup every computer with an individual configuration click on “Selected”. The window will expand and show
all computers that were added to LabControl. In the top list select the configuration to startup and click on the “Wake Up?”-‐Button of the computer that is supposed to run that configuration. Click on another configuration and then on another computer to run the other configuration.
Fig. 13 Individual Wakeup Screen
20.09.13 14
Fig. 14 Individual Wakeup -‐ Configuration was set
Online -‐ restart In the selected wakeup each client can be configured seperately. Even the files to copy can be activated for each client individualy. If a computer was already running, it has to be selected to restart first, before the configuration can be set.
Fig. 15 Click on online to flag the computer for restart
Wake up configuration
The wake up configuration can be edited in the wake up dialog on the top right button “View/Change configurations”. Only the custom fields can be edited. Best practice is to copy from the program configurations above and extend it to the required setup. To avoid misconfigurations the other fields are blocked for editing. If there is a need to change the default configuration, it can be edited in the ini-‐File. See chapter: Edit ini-‐File directly or how to add multiple computers at the same time
20.09.13 15
Fig. 16 The Batch snippets configurations
The different configurations in detail – Configuration of the batch snippets
See: Edit ini-‐File directly or how to add multiple computers at the same time
z-‐Leave There are two default z-‐Leave configurations. To change the default configuration, edit the line in the ini-‐File that starts with “zLeave1=” respectively “zLeave2”.
Web Experiment This is default batch script for a web experiment. To change the default configuration, edit the line in the ini-‐File that starts with “WebExp=”.
MATLAB The default Maltab configuration add a path on the network to a shared network script, which can be configured there. Find an example runMatlabExp.m in the package folder. To change the default configuration, edit the line in the ini-‐File that starts with “Matlab=”.
Processing This is the default Processing configuration. To change the default configuration, edit the line in the ini-‐File that starts with “Processing =”.
Custom Configuration A custom configuration can be created in the custom confgiuration field. If the setup e.g. should be that MATLAB
starts first followed by a z-‐Leave, just copy the default configurations of the first to start in that field followed by the copy of the default configuration of the next program to start.
Copy Source Path The copy source path defines the folder where the files are copied from when the “Copy Files”-‐Button is active. It
normaly is a folder on the network path and can be edited in the ini-‐File on the line starting with “CopySource=” Copy Destination Path The copy destination path is the folder where the files form the Copy Source Path are copied to. This should be a
local path on the client computer. To change the default configuration, edit the line in the ini-‐File that starts with “CopyDestination=”.
Startup Batch Name and Path The startup Batch Name and Path indicates where LabControl writes the Batch file to. This is Batch file which the
client computers are reading after login. To change this, open the ini-‐File and edit the line starting with “StartUpFile=”.
Rows of computers displayed
To change on how many rows the computers are displayed in the “Wakeup/Restart/Shutdown – Selected”-‐View, move the slider to the desired position.
Header (hidden) The ini-‐File has a hidden entry, which cannot be edited within LabControl. The line starts with “Header=” and is to add a custom line on top of the Batch file, e.g. for Windows 7 “Header=@@ECHO off\n\n\ntimeout /T 30 /NOBREAK>nul\n”. This example command makes the client wait for 30 sec before processing the rest of the batch file – this gives the user time to abort if necessary (ctrl + C)! The header can be used to add other special commands, welcome text etc. on top of every batch file.
20.09.13 16
Shutdown / Restart To shutdown or restart the clients, click on “Shutdown” or “Restart”. Again there is the possiblity to shutdown /
restart all or selected computers. Be aware that LabControl can only restart / shutdown computers that are recognized by LabControl as running. Running computers are highlighted with green in the “Manage Computers”-‐list.
Fig. 17 Only running computers are displayed
Fig. 18 For Restart a Restart Button is displayed
Fig. 19 Select the desired timeout before shutdown / restart
After clicking “Shutdown!” / “Restart!” another small dialog will pop up to enter the desired timeout. When clicking on “OK” the computers are shutted down or restarted after the previoulsy entered timeout. The only thing to abort shutdown / restart would be to enter on every selected computer in the console the command “shutdown -‐a”. Note: Always be careful deciding when to shutdown the computers. The computers will shutdown after the indicated time even if the experiment still is running.
20.09.13 17
Acknowledgment Many thanks to Stefan Schmid for revising, spotting typos and for contributing with helpful hints.
Many thanks to Michael Hohl for providing necessary information about the required modifications needed to run LabControl successfully on Windows 7 and Windows 8.
References
