Knowledge Base

10 - User-defined hardware devices

10 User-defined hardware devices

user-defined device types

Device types like the PhenoTyper's Top Unit Interface, the Lickometer and the Pellet dispenser are pre-defined in EthoVision XT as default device types, so when you use such devices you do not have to define their properties. In the case you want to use a new device type or a device with parameters different from those set in Noldus devices, you can create a User-defined device type. For example: You want to sample the Lickometer at a rate different from the default one, that is one sample every two seconds. To do so, create a new Lickometer device type, where the only difference between the existing Lickometer and the new device type is the value for the sampling interval. Add a "Trapdoor" device type by duplicating the existing Custom Device, and by replacing the various command- and signal texts. For instance: replace Output 1 High with Door 1 open. This section instructs how to make simple changes to an existing device. For more complex changes, the Noldus HardwareInterface USB-IO box software and maybe even EthoVision XT itself may need to be changed. Contact Noldus Technical support for wishes and ideas. In order to carry out the procedure below, you need some experience with computers and xml language.

in a nutshell

When you install EthoVision XT, the following file: DeviceTypesNoldus.xml is copied to the

following folders (henceforth named ProgramData folder):

C:\ProgramData\Noldus\Components\Ethovision\Noldus HardwareInterface

Iobox{version number} and

C:\ProgramData\Noldus\Components\Ethovision\Noldus HardwareInterface

MiniIobox{version number}

Two files are present in this folder: DeviceTypesNoldusChCh.xml and

DeviceTypesNoldusEnUs.xml. The first is used with the Chinese version of EthoVision XT, the second with the English version. 10 - User-defined hardware devices The XML file contains all the details of the types of hardware devices that you can control with EthoVision XT with the USB-IO box and the Mini USB-IO box. You can edit this file for small changes in the hardware devices, for example if you want to change the frequency a PhenoWheel counter is read out. You can also define custom devices and create a file

DeviceTypesUser.xml. If you do so, make sure the file DeviceTypesUser.xml and

DeviceTypesNoldus[language version].xml do not contain settings for the same device. When you create an experiment, EthoVision XT copies these files to your experiment folder, under Configuration Files\Add-ins\Hardware{dll serial number}. The dll serial number depends on the type of USB-IO box and its version. See in Table 3.1 which serial number belongs to which device and version. tip To find out which version of the driver is installed on your computer, see the Programs and Features list on the Control Panel. Every time that you open the experiment, EthoVision XT reads the files in the experiment folder, not the ones in the ProgramData folder, and does not change them. Therefore: If you edit the files in the ProgramData folder, the new device types will be available to all your new experiments. If you edit the files in a specific experiment folder, the new device types will only be available to that experiment. When you make a backup of the experiment, the device type files are also copied, so the new devices can be recognized on other computers where you restore the experiment from the backup. important Always make a backup of the ProgramData folder before you edit the file DeviceTypesNoldus[language version].xml. Table 3.1 The dll serial numbers for the different versions of the USB-IO box and the Mini USB-IO box.

Serial Number

USB-IO Box

Mini USB-IO Box

{A8DA8F3E-7EA3-4629-8327-9D21C90FB3ED} {0308106B-1EBE-4620-B00D-396ABEBBC219} {33DF79E0-53C2-44C6-BA2F-A24C4C702615} {F9AAD805-B910-4FEC-AC2F-31DED85324B2} {C183DC50-0CAB-4E67-905E-9D45D8213BD2} {B1336ED5-DE91-4C40-A59D-6A2D131C4F9B} 10 - User-defined hardware devices

Undo the changes in the device type files

If you want to undo the changes made and return to the original situation, proceed as follows: 1. Close EthoVision XT. 2. Remove or rename the file DeviceTypesUser.xml in the ProgramData folder. 3. Copy the files from the backup of the ProgramData folder to the ProgramData folder. 4. optional Run installation of EthoVision XT and select Repair. Browse to my.noldus.com if you need to download the EthoVision XT installation files. Any experiments that you have created which refer to the user devices can still be analyzed and continued. To remove every trace of your user devices, you must also delete these experiments (and if you made experiment backups, delete these too) by removing them from the Experiments folder.

define a new device type

important Before making changes to files in the "ProgramData" folder, make a backup of this folder, so you can recover the files if anything goes wrong. The "ProgramData" folder contains other information important to EthoVision XT. If the files in this folder get corrupted or deleted, you can restore EthoVision XT by re-running installation of EthoVision XT and selecting Repair.

To define a new device type

1. Make the necessary changes to the DeviceTypesUser.xml file in the "ProgramData" folder as described below. Use the program XML Notepad that you can download from www.microsoft.com/downloads. to edit a device type file. Other editors could add undesired characters that may not be read in EthoVision XT.

• For changes to standard Noldus device types, edit the file DeviceTypesUser.xml. Note: You can in fact make the changes to the file DeviceTypesNoldus[language version].xml {DF396575-4883-47C4-9124-8DE30AE1E4C6} {2EDFF151-DF50-486E-887F-55AD41457A5B} {83BF6F4E-D35B-489A-9F5E-703C4EE9453B} {93C9527C-8B2F-4530-9370-7CA330856D15} 10 - User-defined hardware devices but these changes will be overwritten when EthoVision XT is subsequently re- installed, repaired or a new version installed.
• For the other types, also edit file DeviceTypesUser.xml.

2. Make sure that the file DeviceTypesUser.xml is stored in the appropriate folder under C:\Program Data\Noldus\Components\EthoVision\Noldus HardwareInterface Iobox\5 or C:\Program Data\Noldus\Components\EthoVision\Noldus HardwareInterface Mini Iobox\5
3. Start EthoVision XT, create a new experiment and test the devices.
4. If EthoVision XT crashes, or does not behave as expected: Delete the created (failed) experiments. Make corrections to the file DeviceTypesUser.xml in the ProgramData folder specified above. Go to step 2.
5. When everything works fine, create a new experiment and use the changed or new device types. note If you use the Quality Assurance module: The change to the device type file is not recorded in the GLP log.

sample file

On the download page of EthoVision XT you can download two sample files. 1. Browse to my.noldus.com (you must log in or register first to access this site). 2. Choose Downloads > EthoVision XT. Download EthoVision XT - Full installation disc [version number]. Unzip the file and locate the folder Drivers ant Tools > IoBox MiniIoBox Devices. There you find the file User defined device types.zip. 3. Unzip the file User defined device types.zip and save the files on your computer. DeviceTypesUser - Example.xml (see below). DeviceTypesUser Pheno Wheel (30).xml (see page 161). 10 - User-defined hardware devices

DeviceTypesUser - Example.xml

The file DeviceTypeUser - Example.xml specifies several devices. Figure 41 Part of the sample file DeviceTypeUser-Example.xml. The top part specifies the PhenoTyper White spot commands. 10 - User-defined hardware devices

DeviceTypesUser - Example.xml (continued)

Figure 42 Part of the sample file DeviceTypeUser - Example.xml. The bottom part specifies the counter of the RunningWheel. 10 - User-defined hardware devices

DeviceTypesUser Pheno Wheel (30).xml

For a running wheel, with reading interval of 30 s instead of 60 s as in the standard Noldus running wheel, you need a file like this: Rename the file to DeviceTypesUser.xml. Figure 43 An XML file that specifies a device type for a running wheel with reading interval of 30 s instead of 60. Note the device type ID (10006), name (PhenoWheel (30)) and the custom sample frequency (30). 10 - User-defined hardware devices When you restart EthoVision XT, the new device types are then shown, for example in the Arena-Hardware Mapping window that you access in the Arena Settings.

predefined ids

For both devices and connectors, IDs must be unique. IDs from 0 to 9999 are for Noldus device (and connector) types. IDs above 10000 are reserved for device (and connector) types that you may want to add. If you create a device type based on a Noldus device type (for example a Lickometer), always use an ID above 10000.

Figure 44 Arena-Hardware Mapping window showing the new device type

PhenoWheel (30) in the first column of the table.

Device type ID

Name

Top Unit (Standard) Top Unit (Neuro-Bsik) Pellet Dispenser (PTPD-001x) Lickometer (PTLM-001x) TTL Port Tester (PTTB-001x) Custom Hardware PhenoWheel 10 - User-defined hardware devices

xml file entries

Not all of the entries below always apply to each signal, command, etc. If you make edits in a device type file, beware that besides editing the data below you might have to change some numbers that the boost::serialize normally creates itself (vector counts, for example).

NCHiIobConnectorTypes

Devices can be connected to the USB IO box (or mini IO box) via a connector. There can be more than one connector type in the setup. Following are the properties of the collection of

connectors (m_vecConnectorType):

Following are properties of each connector:

NCHiIobConnectorType

USB-IO box monitor Beam Controller (PTBC-0010) Activity Wheel Counter (ENV-042) Activity Wheel Brake (ENV-042) Backlight Unit White Light Top Unit Tester (PTTB-002x) Pellet Receptacle (PTPR-001x)

Connector type ID

Connector type name

Top Unit Interface (PTTI-001x). Note that the Top Unit Standard and Special both use this type of connector.

Count

Indicates the number of connectors

Item_version

Indicates the version of the connectors

HiIob::ConnectorTypeId m_iId

Every connector type must have a unique id. g_ConnectorTypeIdInvalid(-1l): invalid value

Item_version

Indicates the version of the connectors

nstring m_strName

name of the connector 10 - User-defined hardware devices

NCHiIobDeviceTypes

Devices can be connected to the USB-IO box directly (e.g., not via a connector). Following are

the properties of the collection of device types (m_vecDeviceType):

Following are properties of each device type:

NCHiIobDeviceType

HiIob::ePortTypes m_ePortType

ePrtUndefined(-1): undefined ePrtSD(0): simple device port ePrtCD(1): complex device port

int m_iNrPorts

number of ports used by the connector

int m_iOffsetPin

pin offset for the device connected via the connector

Count

Indicates the number of device types

Item_version

Indicates the version of the device types

HiIob::DeviceTypeId

m_iDeviceTypeId

Every device type must have a unique id. g_DeviceTypeIdInvalid(-1l): invalid value

nstring m_strDeviceTypeName

name of device type, showing up in the UI of port- device mapping dialog (hwdll) and various places in EthoVision XT (for example: ATC, test dialog, etc).

int m_MaxFrequency

Most device types are read every read cycle and have m_MaxFrequency = 0. So called "slow device types" (e.g., Lickometer) are not read every read cycle but with the slower frequency MaxFrequency (in seconds). Use integer values only.

HiIob::ePortTypes m_ePortType

ePrtUndefined(-1): undefined ePrtSD(0): simple device port ePrtCD(1): complex device port

HiIob::ConnectorTypeId

m_iConnectorTypeId

Every connector type must have a unique id. Most device types do not use a connector and have value. g_ConnectorTypeIdInvalid(-11): invalid value Currently the only connector type is the top unit connector, used with the top unit. 10 - User-defined hardware devices

NCHiIobSignal

Each device type can have more than one signals. Following are the properties of the collection of signals (m_vecSignal): Following are properties of each signal:

Count

Indicates the number of signals

Item_version

Indicates the version of the device type signals

HiIob::SignalId m_iId

Every signal must have a unique (within device type) id. g_SignalIdInvalid(-11): invalid value

nstring m_strName

Name of signal, showing up in the interface of Device configuration window and other places, for example: The test window in Trial Control).

HiIob::eSignalSource

m_eSignalSource

eSrcUndefined(-1): undefined eSrcInput(0): signal comes from the hardware eSrcOutput(1): signal is created in the software and is related to an output state. E.g.: there are outputs "White spot off" and "White spot on", for these outputs "Is white spot on" is a output state that is treated as an (artificial, because not coming from the hardware) input.

HiIob::eSignalHwType

m_eSignalHwType

eShtUndefined(-1): undefined eShtPin(0): uses pins (most device types) eShtBytes(1): uses direct bytes reading (e.g.: lickometer)

long m_iPin

the pin used by the signal. Only relevant if eSignalHwType = eShtPin.

int m_iNrBytes

the number of bytes used for reading the signal. Only relevant if both m_eSignalSource = eSrcInput and eSignalHwType = eShtBytes.

int m_iIndexFirstByte

least significant byte. Only relevant if both m_eSignalSource = eSrcInput and eSignalHwType = eShtBytes.

int m_iIndexLastByte

most significant byte. Only relevant if both m_eSignalSource = eSrcInput and eSignalHwType = eShtBytes. 10 - User-defined hardware devices

HiIob::eStateEventType

m_eStateEventType

eSetUndefined(-1): undefined eSetL(0): signal is based on Low state eSetH(1): signal is based on High state eSetL2H(2): signal is based on transitions from Low to High eSetH2L(3): signal is based on transitions from High to Low Only relevant if eSignalHwType = eShtPin

bool m_bHighInit

initial value for the signal. True if High, false if Low. Only relevant if m_eSignalSource = eSrcInput and eSignalHwType = eShtPin.

bool m_bTotalsSinceLastCall

true if signal returns a value (via the hwdll COM interface) that represents a total since the last call.

EAdinsIdtHiValueType

m_eValueType

The type of the value the signal returns (via the hwdll COM interface) One of the values: eAdinsIdtHiVtUndefined(-1) eAdinsIdtHiVtBool(0) eAdinsIdtHiVtLongLong(1)eAdinsIdtHiVtDouble(2) eAdinsIdtHiVtDuration(3) This value is used by EthoVision XT: Trial Control and logging

bool m_bHasValueDefault

true if the signal has a default value. Indicates how the value of the signal has to be treated by the EXPORTED hardware log in VTS: If true: only the values not equal to the default value are logged If false: only changes in the values are logged (default value is not used)

NCHiIobValue m_valueDefault

Default value for the signal. Only relevant if m_bHasValueDefault = true;

HiIob::eValueType

m_eTypeValueDefault

Default value type for the signal (see m_eValueType) for the values. 10 - User-defined hardware devices

NCHiIobCommand

Each device type can have more than one commands. Following are the properties of the collection of commands (m_vecCommand): Following are properties of each command:

bool m_bValueDefault

Default value for the signal if m_eValueType = eAdinsIdtHiVtBool.

LONGLONG m_lValueDefault

Default value for the signal if m_eValueType = eAdinsIdtHiVtLongLong.

double m_dbValueDefault

Default value for the signal if m_eValueType = eAdinsIdtHiVtDouble.

Count

Indicates the number of commands

Item_version

Indicates the version of the device type commands

HiIob::CommandId m_iId

Every command must have a unique (within device type) id. g_CommandIdInvalid(-11): invalid value

nstring m_strName

name of command, showing up in the UI of port- device mapping dialog (hwdll) and various places in EthoVision XT (for example: Trial Control boxes, test dialog, etc).

bool m_bIsDefaultCommand

true if command is default command. Default commands are called before start sampler (start of a trial) and after stop sampler (end of a trial).

long m_iPin

the pin used by the command (if any).

bool m_bHigh

true if command corresponds to a High bit value, true if command corresponds to a Low bit value

int m_iDuration

duration in milliseconds. After writing this command a new command is scheduled to be written the given duration time later (only if duration > 0). If the original command was High, the scheduled command is Low and vice versa. Used for the pellet feeder to reset.

---

Source: EthoVision XT 17 - Trial and Hardware Control Reference Manual