EthoVision XT 19 - User-defined Hardware and Analysis
Last updated: Jul 26, 2026
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 at every new experiment. 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}
- 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.
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 Table 3.1 for 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: DLL Serial Numbers for USB-IO Box and Mini USB-IO Box Versions
| Serial Number | USB-IO Box | Mini USB-IO Box |
|---|---|---|
| {A8DA8F3E-7EA3-4629-8327-9D21C90FB3ED} | 5 | |
| {0308106B-1EBE-4620-B00D-396ABEBBC219} | 5 | |
| {33DF79E0-53C2-44C6-BA2F-A24C4C702615} | 4 | |
| {F9AAD805-B910-4FEC-AC2F-31DED85324B2} | 4 | |
| {C183DC50-0CAB-4E67-905E-9D45D8213BD2} | 3 | |
| {B1336ED5-DE91-4C40-A59D-6A2D131C4F9B} | 3 | |
| {DF396575-4883-47C4-9124-8DE30AE1E4C6} | 2 | |
| {2EDFF151-DF50-486E-887F-55AD41457A5B} | 2 | |
| {83BF6F4E-D35B-489A-9F5E-703C4EE9453B} | 1 | |
| {93C9527C-8B2F-4530-9370-7CA330856D15} | 1 |
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:
- Close EthoVision XT.
- Remove or rename the file DeviceTypesUser.xml in the ProgramData folder.
- Copy the files from the backup of the ProgramData folder to the ProgramData folder.
- 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
- 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 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.
- Make sure that the file DeviceTypesUser.xml is stored in the appropriate folder under:
- C:\ProgramData\Noldus\Components\EthoVision\Noldus HardwareInterface Iobox\5
- C:\ProgramData\Noldus\Components\EthoVision\Noldus HardwareInterface Mini Iobox\5
- Start EthoVision XT, create a new experiment and test the devices.
- 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.
- 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.
- Browse to my.noldus.com (you must log in or register first to access this site).
- Choose Downloads > EthoVision XT. Download EthoVision XT - Full installation disc [version number]. Unzip the file and locate the folder Drivers and Tools > IoBox MiniIoBox Devices. There you find the file User defined device types.zip.
- Unzip the file User defined device types.zip and save the files on your computer:
- DeviceTypesUser - Example.xml
- DeviceTypesUser Pheno Wheel (30).xml
DeviceTypesUser - Example.xml
The file DeviceTypeUser - Example.xml specifies several devices. The top part specifies the PhenoTyper White spot commands. The bottom part specifies the counter of the Running wheel.
DeviceTypesUser Pheno Wheel (30).xml
For a running wheel, with reading interval of 30 s instead of 60 s as in the standard Noldus PhenoWheel, you need a file like this. Rename the file to DeviceTypesUser.xml.
The XML file 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).
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.
| Device Type ID | Name |
|---|---|
| 0 | Top Unit (Standard) |
| 1 | Top Unit (Neuro-Bsik) |
| 2 | Pellet Dispenser (PTPD-001x) |
| 3 | Lickometer (PTLM-001x) |
| 4 | TTL Port Tester (PTTB-001x) |
| 5 | Custom Hardware |
| 6 | PhenoWheel |
| 7 | USB-IO box monitor |
| 8 | Beam Controller (PTBC-0010) |
| 9 | Med Associates Activity Wheel Counter (ENV-042) |
| 10 | Med Associates Activity Wheel Brake (ENV-042) |
| 11 | Backlight Unit White Light |
| 12 | Top Unit Tester (PTTB-002x) |
| 13 | Pellet Receptacle (PTPR-001x) |
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):
| Connector Type ID | Connector Type Name |
|---|---|
| 0 | Top Unit Interface (PTTI-001x). Note that the Top Unit Standard and Special both use this type of connector. |
| Property | Description |
|---|---|
| Count | Indicates the number of connectors |
| Item_version | Indicates the version of the connectors |
Following are properties of each connector (NCHiIobConnectorType):
| Property | Description |
|---|---|
| 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 |
| 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 |
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):
| Property | Description |
|---|---|
| Count | Indicates the number of device types |
| Item_version | Indicates the version of the device types |
Following are properties of each device type (NCHiIobDeviceType):
| Property | Description |
|---|---|
| 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. |
NCHiIobSignal
Each device type can have more than one signal. Following are the properties of the collection of signals (m_vecSignal):
| Property | Description |
|---|---|
| Count | Indicates the number of signals |
| Item_version | Indicates the version of the device type signals |
Following are properties of each signal:
| Property | Description |
|---|---|
| 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 an 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. |
| 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). |
| 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. |
NCHiIobCommand
Each device type can have more than one command. Following are the properties of the collection of commands (m_vecCommand):
| Property | Description |
|---|---|
| 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 the command |
Source: EthoVision XT 19 - Trial and Hardware Control Reference Manual