Installations notes of TUC/DTUC

1 ................................................................................................................ 2 OVERALL

2 .................................................................................. 3 WINDOWS INSTALLATIONS

2.1 ........................................................................................................................... 3 Administrator privileges

2.2 ...................................................................................................... 3 Check USB2 functionality of the PC

2.3 .................................. 5 Installation of the USB driver for the IPHC cards (all except Win7 64bits)

2.4 .................................................................................................. 11 Installation of Java Runtime Engine :

2.5 ................................................................. 12 Installation of TUC/DTUC program files and resources

2.6 ............................................................................................................ 12 Windows 7 - 64 bits installation2.6.1 .................................................................................. 14 Authorize the test signing feature of the test driver2.6.2 ........................................................................................ 17 Import the test certificat “IPHC.in2p3.fr(test)”2.6.3 ................................................................... 20 Download & install Java Runtime Environment JRE engine2.6.4 ................................................................................................................. 20 Installation of the signed driver

3 ....................................................................................... 24 LINUX INSTALLATIONS

4 .................................................... 25 SUPPORTED CONFIGURATIONS SUMMARY

5 ...................................................................................... 26 GENERAL TIPS & HINTS

1 Overall Since January 2010 and the TUC 3.43 & DTUC 0.43 versions, TUC and DTUC are now co-bundled and shipped with some scripts which invoques different pieces of software with the rights arguments in order to start TUC, DTUC-server and /or DTUC-GUI. Up to 127 TNT cards can be plugged on the same USB bus controller (PC).

A TUC/DTUC installation is made of these parts:

Software part Notes

Basic OS component

Java Runtime Environnement (JRE) 1.5.0_02 (or greater)

See http://java.sun.com and http://www.oracle.com/technetwork/java/index.html for additional information on this topic.

Windows OS

Drivers files for the IPHC card USB2 peripheral (iphcusbdriver.inf & iphcusbdriver.sys).

a DLL library usbtnt.dll that must be found in the installation directory. This file is an interface between the main TUC/DTUC software and the Windows I/O system API’s which relay communications for IPHC USB2 cards to the attached USB2 driver. IPHC specific

middleware Linux OS The Java API for USB under Unix systems:

JUSB.jar libjusb.so (JNI library) http://jusb.sourceforge.net/ : This file is an

interface between the JUSB part and the Linux I/O system.

TUC/DTUC softwares

Tuc.bat/.sh DTUC-goServer.bat/sh or DTUC-goGUI.bat/sh: Scripts files to use in order to start TUC, DTUC-server or DTUC-GUI.

DTUC.jar: main DTUC program file (for both server and GUI parts) TUC.jar: main TUC java program file which contain all java classes and

resources like images and like ’tuc.properties’ parameter files. TUCHelp.jar: Help file which contain the TUC online informations (2006 version).

jas-plotter.jar: a graphic component used for histogram plotting (energy,

polezero automatic search, ADC data). This component is from a community from High-Energy Physics laboratories and universities.

jhall.jar the JavaHelp system classes. The JavaHelp system is distributed as an standard extension of the Java platform. These classes provides the online help mechanism through the F1 key.

Toolkit.jar some IPHC utility classes. swing-layout-1.0.3.jar: GUI layout manager lablib-checkboxtree-3.1.zip : some checkboxtree used in DTUC’s GUI freehep libraries used for plotting features (11 jar files): see

http://java.freehep.org/

These different files should be placed in this way :

Install directory (ex : D:\TUCs)

«\dist » sub directory

«\dist\lib » sub-sub directory

Tuc.bat/.sh DTUC-goServer.bat/sh

DTUC.jar TUC.jar

usbtnt.dll (Windows) jas-plotter.jar

libjusb.so (Linux) jhall.jar

TUCHelp.jar

jusb.jar(Linux)

Toolkit.jar

swing-layout-1.0.3.jar

lablib-checkboxtree-3.1.zip

aida-3.3.jar, aida-dev-3.3.jar, bcel-5.1.jar, freehep-application-2.0.jar, freehep-export-2.0.1.jar, freehep-graphics2d-1.2.3.jar, freehep-graphicsio-1.2.3.jar, freehep-graphicsio-gif-1.2.3.jar, freehep-jaida-3.3.0-1.jar, freehep-swing-2.0.jar, freehep-util-2.0.jar

2 Windows installations TUC/DTUC can be installed on W2000, XP, Vista (not tested), Seven and Seven-64bits (See 2.6 Windows 7 - 64 bits installation) .

2.1 Administrator privileges Generally, under Windows, in order to install some software (ex : JRE) and peripherals drivers, you must have some specific privileges which are part of the administrator account. So, be sure that you have got a Windows 2000/XP USER or LOGIN with administrator privileges, and, in order to avoid some problems, don’t forget to work only with this LOGIN...

2.2 Check USB2 functionality of the PC The Tnt USB Control software (TUC) has been conceived for USB2 communications but nevertheless it should operate with USB1 in a degraded mode, with very low transfer rates (max 1 MBytes/s). In order to avoid some possible dysfunctions, it is strongly recommended to work with a USB2 bus installed thus having access to USB2 high speed transfers (we obtain peaks at 30 MB/s for one card, while reaching 40MB/S global transfer rates for several cards plugged on the same USB controller, thus obtaining 80 MB/s on a PC with 2 USB2 controller). If your PC mainboard is recent (shipped in/after during 2003), it should have normally a native USB2 controller hardware (check the technical documentation of your PC) but sometimes you will have to install the USB2

controller software/driver, depending of the operating system and/or service pack installed. If your PC is a older one, you must get a USB2 PCI add-on card (but in this case, the basic transfer performances are not so good : 13Mbytes/s on a DELL precision 340).

The simplest way to know if you have some USB2 capability is to look at the ’Device manager screen’ : go to the ’Configuration Panel’, ’System’ icon, choose the ’Hardware’ tab and press the ’Device manager’ button. Expand the ’USB bus controller’ node :

Window with native USB2

PC with a PCI USB2 card

If you see an item / line that contain the ’Enhanced’ or ’USB2’ key words, the you PC has some USB2 ability. If not then you have only the USB 1 feature !

TIP - If you have a TNT2 card at hand, as TUC is also USB1compliant, continue the installation steps and start normally TUC : take a look at the right side of the list box containing all numbers of TNT cards found over USB bus. TUC will show at which USB speed the actual selected is operating, thus giving a hint about USB2 capability of your PC. If you see some blue ’USB 2’ text then your PC is USB2 compliant (motherboard with integrated USB2 or PCI add-on card), it you see only a red ’USB 1’ then the actual card is plugged on a USB 1 port of your PC. Sometimes, may be the bus negotiation between the card and the bus controller was not correctly achieved : unplug & replugg again to re-start this negotiation phase and thus the speed negotiation.

2.3 Installation of the USB driver for the IPHC cards (all except Win7 64bits)

Download from http://www.iphc.cnrs.fr/TUC-Download.html the driver (ex: Windriver.zip) zip bundle.

Unzip the archive file in some installation directory on your local drive:

Search the right drivers version ( XP or Seven 32 bits). The ‘ia64’ compilation is currently not supported (as it could not be tested).

The driver is made of these 2 files iphcusbdriver.sys: main driver file iphcusbdriver.inf : installation file for the main driver file

These files are similar to the General Purpose Driver from Cypress which is shipped with their USB2 development Kit, except that they are attached to the IPHC USB identifiers (VID 0999 & PID=8888). In order to be able to communicate with the driver, some native interface library (compiled C/C++ code) has been made : <usbtnt.dll>. This small DLL simply setup a communication bridge (transtyping) between java world and native world. Caution: in case of a 64 bits installation, it can be necessary to use the 64 bits compiled version of this small DLL interface library. TNT2, PSG and DT5 cards uses the same driver. The driver logical attachment to a plugged card is done via the USB VID/PID notions :

At ‘driver’ side, this information is stored in the INF file At ‘card’ side, this information is stored in the adequate USB VID/PID descriptors within compiled

code for the onboard FX2 USB2 chip (in some I2C EEPROM on board).

Plugg the IPHC card to USB2 port of the PC, you should see :

The windows device installation wizard starts and ask for the driver to use. Don’t let the wizard start to search the driver through the ’Windows Update’ website : choose ’No’ and click on the ’Next’ button.

Choose ’Install from a list or a specific place (advanced users)’ :

Select ’Search best driver at these places’ and check ’Include this place in the search’. Click on the ’Select’ button in order to give to the device installation wizard the path were he could find the specific drivers files you just download on your local disk (’D:\TNT’, for example) and click on the ’Next’ button.

Wait some moment while Windows reads & install the drivers :

At the end of the driver installation process, you will see something like :

Don’t delete the 2 drivers files from you installation directory : if you plug now the card to another USB2 port of the PC, Windows will ask again for the driver : just select again the same installation directory.

You should now distinguish the TNT2 device in the windows ’Configuration Panel’, ’System’, ’Hardware’ tab, ’Devices manager’ button, ’USB Controler’ topic, as ’USB2 Acquisition card-IPHC/CNRS’ :

Device manager with TNT2 card

2.4 Installation of Java Runtime Engine : Download and get on your local drive the Java Runtime Engine (JRE) installation program (exe file). It’s okay if you download the JDK (Java Development Kit) because it contain also the JRE. http://java.sun.com/ or http://java.sun.com/products/archive/ or http://www.oracle.com/technetwork/java/index.html.

Launch the installation program and follow the instructions... If everything has been correctly installed, type ’java -version’ at a prompt window. You should see something like this :

Testing java installation

2.5 Installation of TUC/DTUC program files and resources Download from http://www.iphc.cnrs.fr/TUC-Download.html the TUC/DTUC softwares (ex: tuc3-43_dtuc0-43.zip) zip bundle.

Unzip the archive file in some installation directory on your local drive, like C:\Iphc.

Use (double-click or type name of script file in a command windows / terminal windows) one of these start-up scripts in order to launch:

TUC use Tuc.bat or Tuc.sh

DTUC server use DTUC-goServer.bat or DTUC-goServer.sh

DTUC Gui use DTUC-goGUI.bat or DTUC-goGUI.sh

2.6 Windows 7 - 64 bits installation Windows Seven 64 bits installation has two additional difficulties in regards to other Windows versions (W2000, XP, Vista et Seven 32 bits):

Driver signing with certificates 64 bits compilation

Until now, the driver signing feature was optional: it was possible to install not signed drivers by simply ignoring the warning shown during installation (XP and 32 bits Seven installations).

This is no more possible with a 64 bits Windows 7 installation ! The IPHC driver has been signed with a self made ‘test’ certificate (not approved by Microsoft) and we have to enable test signing on the installation machine before the driver installation can succeed. These actions must be accomplished:

Authorize the test signing feature for drivers at deployment PC Import the certificat used to sign the Iphc driver into Windows certificate store Download & install Java Runtime Environment JRE engine. You have to decide whether to run in

a 32 bits or in a full 64 bits environnement : o 32 bits : install the 32 bits JRE/JVM and use the original <usbtnt.dll> which is a 32 bits

compiled one o 64 bits : install the 64 bits JRE/JVM and use the 64 bits version of the <usbtnt.dll>,

usbtnt.dll.x64. Delete the old 32 bits DLL and replace it with a renamed copy of usbtnt.dll.x64 to ustnt.dll.

Please note that the driver will be the same in both cases.

Plugg one of the IPHC card and install the correct driver ( found in “WindowsDrivers\amd64_7” subdirectory of the driver zip package installation). Please note that the ‘ia64’ compilation is currently not supported (as it could not be tested).

Install TUC/DTUC software. Be sure to use the adequate interface DLL <usbtnt.dll> (32 or 64 bits version depending of the installed java - JVM)

The Java bytecode of the TUC/DTUC is the same regardless of whether it is deployed in a 32 bit or 64 bit JVM. When the JVM runs, the JIT will compile the java application from the bytecode (compiled java source code) to the native environment, which will be 32 bit for one case, and 64 bit for the other. If the second step above (“Import the test certificate used”) is not done, during driver installation, you will see:

Choose « Install this driver anyway » and after some seconds :

The driver has been signed with at his time unknown certificate: it is not fully operational (yellow exclamation mark)!

2.6.1 Authorize the test signing feature of the test driver

When you try to install some device drivers on Windows 7, you might come across a warning message that those drivers should be digitally signed. You can get disable this driver signing warning message in Windows 7 with the help of a workaround.

Go to the Start menu and type cmd.exe in the Search Bar. Right click on cmd.exe and choose Run as Administrator.

If you have the UAC turned on, choose Yes to proceed. Otherwise, you should see the command windows opened already. In the shell window, copy paste the following and hit Enter.

bcdedit.exe -set loadoptions DDISABLE_INTEGRITY_CHECKS bcdedit.exe -set TESTSIGNING ON

You’ll get a confirmation that the operation completed successfully, as you can see below:

Type bcdedit in a command window:

Restart your computer for the changes to take effect.

You’ve just disabled digital driver signing in Windows 7.

After reboot, on the windows desktop you can see in the right corner ‘Test Mode’:

 

2.6.2 Import the test certificat “IPHC.in2p3.fr(test)”

In the “Start menu”

Key ‘Certmgr.msc’

Rigth clic droit ‘run as administrator’

Go to the « Root Autority certification» node and select « All tasks Import… » in the contextual menu.

Select the « IPHC_Certificat.ser » file holding the certificate that was used to sign the driver file <iphcusb.sys>:

2.6.3 Download & install Java Runtime Environment JRE engine

Search, download & install a 32 bits JRE or a 64 bits one : see 2.4Installation of Java Runtime Engine :

2.6.4 Installation of the signed driver

Download from http://www.iphc.cnrs.fr/TUC-Download.html the driver (ex: Windriver.zip) zip bundle.

Unzip the archive file in some installation directory on your local drive:

Search the right drivers version : within “amd64_7” sub directory. The ‘ia64’ compilation is currently not supported (it could not be tested).

The driver is made of these 2 files iphcusbdriver.sys: main driver file

iphcusbdriver.inf : installation file for the main driver file  

Plugg one card on some USB2 port of the PC: the card can appears within « Other peripherals» with a yellow exclamation marks beside meaning it wasn’t correctly installed.

Select ‘Update driver’ in the contextual menu :

Wait some seconds…and then you will see:

Card appears now ‘normaly’ under the ‘USB Bus controler’ :

3 Linux installations There is no particular / specific driver to install. In order to get rid of the low level USB communication details, TUC and DTUC make use of the java JUSB API available at http://jusb.sourceforge.net. Some small native library ‘libjusb.so’ must be compiled and deployed in order to interface JSUB java code with linux kernel commands for the USB2 system. The <libjusb.so> must be put somewhere in the path listed in your LD_LIBRARY_PATH or in the ’/lib/i386’ subdirectory of the JRE installation directory.

Download and install some JRE from http://www.oracle.com/technetwork/java/index.html

Download and unzip the TUC/DTUC zip archive from http://www.iphc.cnrs.fr/TUC-Download.html

(If necessary) JUSB installation from http://www.iphc.cnrs.fr/IMG/jusb-withUSB-Reset.zip and re-compilation.

In order to avoid some problems, it is recommended to work with the ’root’ account. It is not absolutely necessary, but you will need to switch temporary to the root account (’su root’).

Verify that you have the appropriate USB and USB2 modules loaded (use ’lsmod’ and/or ’insmod’) or build in your kernel version. For USB support, you need : ’usbcore.o’, ’usb-uhci.o’ and ’usb-ohci.o’ modules for USB2, you need the ’ehci-hcd.o’ module.

Verify that the USB file system is mounted : Ex : ’mount -t usbdevfs none /proc/bus/usb ’

If you don’t plan to launch TUC as ’root’, you will need to give access for all users to the /proc/bus/usb directory : ’ex:chmod +777 /proc/bus/usb -R’, and this every time you plugg your TNT2 card on the bus !

When unzipping the TUC/DTUC zip archive, there is a compiled version of the JUSB (some java jusb.jar file and the native library ‘libjusb.so’ compiled on a x86 linux machine).

If the ‘libjusb.so’ is not compatible with your PC hardware & software architecture, you will have to download (http://www.iphc.cnrs.fr/IMG/zip/jusbSrc-withUSB-Reset.zip ) the whole API and recompile only the shared library on your system. Verify and use the <compilCC.sh> script by keying path to

linuxCorrected.c source file

usb_linux_DeviceImpl.h and usb_linux_USBException.h header files

jni header file shipped within the JDK installation

Use (double-click or type name of script file in a command windows / terminal windows) one of these start-up scripts in order to launch:

TUC use Tuc.sh

DTUC server use DTUC-goServer.sh

DTUC Gui use DTUC-goGUI.sh

Note : if this kind of error message ’Exception ....java.lang.unsatisfiedLinkError : no jusb in java.library.path’ appears when trying to start TUC/DTUC and the native library file ’libjusb.so’ is not found because the file is not found in the environment variable LD_LIBRARY_PATH. Type ’set’ in order to view all actual defined environment variable and their actual values. You can also put the library file in some general libray directory (ex : /usr/lib).

Note 2: probably due to our poor advanced linux skills, the general raw USB2 transfer rates are somehow not so high as under windows? With exactly the same hardware, we could reach 40 Mbytes/s under XP while reaching only 15 Mbytes/s under linux.

4 Supported configurations summary TUC and DTUC can operate with these different hardware / software configurations:

Note that for Seven 64 bits machine, it is possible to run in 32 bits mode or in 64 bits mode (but nothing specific has been specifically designed in TUC/DTUC in order to gain benefits of 64 bits systems…)

5 General tips & hints  

Take a look on the TNT web site for newer software versions or / and contact our technical team if you have strange behaviours or simple questions, bugs, ...

Ignore card feature : by adding as a command line argument a space separated list of card

numbers (4 digits), TUC will ignore these cards as if they were not plugged. Example:

java ….. ‐cp …… tuc.GUI_Tnt2 1234 7589 4421 

The card n° 1234, 7589 and 4421 will not be found by TUC.

Everytime you launch an acquisition saving the readout data to a file, the program generate automatically a ASCII text containing the parameters values you set for this acquisition. This file is located in the same directory of your data file and is named ’Name of your data file’_log.txt.

The general principle about controlling the board is : — viewing /setting or loading from a file the parameters values — AND THEN starting the acquisition with or without viewing the readout data on screen. If you want to modify some parameter after an acquisition start : stop first the ongoing process, modify whatever you want, and restart again !

Make sure you quit the TUC / DTUC-server software before unplugging IPHC cards !

Data visualisation is beautiful but it has a cost regarding the transfer rate ! So use it only in order to setup correctly the parameters values and deactivate it if you don’t really need it.

The USB identifiers Vendor ID & Product ID which are hard coded in the IPHC card and in the IPHC driver for windows are not registered to the USB organisation. It means that you may encounter some commercial USB peripheral (mouse, camera, scanner,..) which carry the same id’s : in this case, the IPHC driver and the other peripheral driver will conflict about claiming the same id’s, thus disabling both peripherals. If this happens, please contact IPHC TNT team in order to get a new driver with new id’s. VID : 0x0999 PID : 0x8888

The ’tuc.properties’ (which is stored in main jar archive file) contain various parameter values needed for correct execution of the program. Some of them can be adjusted by the user for special needs (in this case you must uncompress the file from the jar archive, modify what ever you want and put it again in the jar) some other are only for very advanced users only ! This file contains also the GUI/screens texts, labels and interactives messages used by TUC, in the default language of TUC, french. It has also some list contents of the GUI (list of analogical inspection lines, list of logical inspection lines and lists of possible data outputs for channel 1 and channel 2) and other parameters. If you want to internationalize the GUI to another language, you will have to construct a new properties file ’’tuc_xx.properties" based on the second half of the default.properties original file (after the ’##### GUI text and labels#######################’ line), with ’xx’= ISO language code for your favorite language. The ’tuc_en.properties’ file contains all informations text and labels that is translated in english. You can freely change the traduction, put the modified file again in the jar file and then restart TUC. The ’api.properties’ parameter file contains some USB specific values.

The ’user.properties’ file : When the user modify in TUC’s screen some basic parameter (ex : data

file name, colors attributes,..) another file will containing the user’s wishes will appears in the installation directory : the ’user.properties’ file.