piLagTesterPRO user's Guide/manual for measuring monitor Lag, response time

The piLagTesterPRO is a cheap addon to the Raspberry Pi for measuring monitor input lag and response time. Using it requires minimal Linux knowledge, most of which this page will teach you, such as: you hit enter after typing a command (most commands are just a single word). For instance to start the lag tester you type lt and then hit enter.

This is an owner's guide to using the software; this other page explains how to set up the hardware. 

In order to get good timing resolution the software needs to be run from the command line, which is how the provided OS image is configured to boot. Once powered up fully you will be automatically logged into root with no password required. The default password is the letter t. Yes, I'm not expecting you to run this on public a network. You won't break anything if you change the password, however, other than my heart.

The lag test is started by typing lt at the prompt. If you want to save the results of your test to disk, try giving a filename (no spaces allowed) like this: lt sonyxbr4  

This is what you should see:

(If you need a reminder of what the graph shows read this). From this screen you have two main options: press escape to quit, or space to start recording and averaging the currently measured lag. Press escape when you have recorded enough measurements (I recommend at least 7).

Sensor placement

Before you start recording position the light sensor over the target rectangle (top, middle, or bottom) and make sure you are getting enough light for a consistent measurement, but not so much that you are getting clipping (the yellow part of the graph should show some variation, not just a flat rectangle). 

The light sensor is somewhat directional so changing the angle between it and the display will give you some control over the light levels. The sensor works over a wide range of intensities, however, so that shouldn't be necessary. I've found TVs don't vary enough that I need to mess with adjusting anything unless I'm trying a new mounting method. Keep in mind the wires can't be bent an infinite number of times, so adjust the angle with the tape. 

If you are testing a TN display keep in mind that the angle to the screen can impact the response time (pointing the sensor up at a significant angle gives the same input lag, but a slower response time). This a real property of TN displays but you don't notice it with the naked eye because we are talking about 10-15ms slower response time. 

If testing a CRT: there are two things to keep in mind. First, CRTs produce an incredible amount of electronic and magnetic noise, and can make the sensor malfunction for some period of time if it physically touches the tube. Best to hold it with your hand at least an inch away from the screen to avoid this problem. Consider sliding the sensor into a plastic hose/black straw/etc. so you can limit its field of view while maintaining your distance from the surface of the screen. Second, because many/most CRTs have significant overscan it's best to measure the center of the middle bar on the screen. You can calculate the lag at the top of the screen from this measurement by subtracting half a refresh cycle (eg at 60hz you would subtract 8.3ms). On most CRTs you should find the estimated lag  at the top of the screen is no more than 1ms, which includes some time for your HDMI to VGA adapter and also a little time for the phosphor to get bright after being struck by the electron beam. However a couple late model CRT HDTVs actually deinterlace 480i content before displaying it, adding significant lag.

Advanced options

By default the target rectangles are wide enough that you can find a single position to measure both 480p/i (4:3) and wide screen modes (720p, etc). The bars blink on and off completely, changing the local light levels, so TVs with dynamic contrast may adjust the backlighting level between frames. This can confuse  response time measurements. The alternative is to use smaller target rectangles which shift back and forth, keeping the local light levels constant. While the lag tester is running type D to toggle this alternative mode on. In this mode place the sensor over the target when it is in the left-most position.

There are a few other options you can adjust from this screen. You can increase and decrease the scale of the graph with the 1 and 2 keys. P takes a screenshot. Q and W adjust the brightness threshold used for detecting input lag (aka 1st response). A and S do the same thing but for measuring the full response. 

Interpreting measurements 

You'll notice that the lag fluctuates. The pi lag tester itself is consistent to 0.2 milliseconds or better, but the signal it measures varies by much more than that, due to the flickering backlight used on most displays. Rather than leaving the backlight on all the time, TV's pulse it on and off, perhaps to reduce motion blur, or as a way to change the brightness level. Either way, you can't see pixels changing when there's no backlight, and backlight flicker never seems to be synchronized with the frame rate (this may be done to reduce perceived flicker, I'm not sure).

Occasionally you will find a TV where the lag doesn't just fluctuate, but drifts by a millisecond or more with each measurement, and wraps around after drifting consistently for 16ms. This is the sign of a TV that has uses a fixed refresh rate of 59.94HZ even when the Pi is outputting 60HZ (or vs versa). On such a TV it's possible that even when you set the refresh rate on the pi to match the TV, the TV still won't sync with the input signal, and will maintain fixed extra lag of  up to 16ms. Each time you turn the TV back on the lag should change in this scenario. This is not a bug with the piLagTester(pro). Other lag testers will show the same thing. I include software to test for this, called vsyncTest. You can also test if the drift is permanent or if the display eventually settles on the lowest value using the command drift. You will also see drifting lag on TVs that advertise refresh rates that are significantly higher than they actually support, such as 75hz on a 60hz display  .

Summarizing results 

After running several tests you might want to see a summary of the results so far. try

cat log.txt

If you start the lag tester with the optional <name> argument (e.g. lt sonya7) it will be listed in the summary, along with the average lag and response time for that session. Furthermore, the raw brightness values for each recording trial are saved in the <name>.datr file, and the calculated input lag and response times for each trial in the <name>.datx file.  These files are stored in the current directory, which is /root when you first turn on the pi. You can type ls to see all the files there, and you can move them to your desktop using SSH (I use winSCP for this). Alternatively, you can save the files to the FAT32 partition of the SD Card, which is readable on windows etc. with no extra drivers. To do this just type "cd /boot" once when you first power on the pi. But be aware, the raw recordings take up a lot of space and the FAT32 partition doesn't have a lot of extra space so I prefer the SSH option.

To get rid of all recordings safely (important as root) don't use rm but instead use del:

del *.dat*

emptyTrash

emptyTrash is required to actually free up space, del just moves the files to a "trash can". 

Measuring input lag for interlaced modes or different resolutions and refresh rates

The easiest option: tvmenu lets you interactively select the resolution and refresh rates from among the set of modes that the monitor has told the Pi it supports. Note there are often other modes that the monitor can display properly but which it doesn't advertise. There are some additional scripts that force modes even if the monitor does not report supporting them. Retro gamers will be particularly interested in input lag for 480i and 480p signals. I've included several mode settings scripts which include these and other popular resolutions:

tv1080p  

tv1080i

tv480i  

tv480p 

tv720p  

tv4k

Here's an example of testing 480i:

tv480i

lt

By default these scripts run at 60hz, but you can switch to NTSC (59.94hz) by adding -t, like this: tv480p -t . The pi is happy to do 240p over HDMI as well, but most TVs don't like 240p over HDMI; you'll probably need to plug the pi into a cheap HDMI->component/composite adapter first.

If you want to test modes outside of that list, that's also possible, although the pi0 and pi4 versions use different methods for selecting them.  With the pi4 it's even possible to create modes from scratch, using either modeline which allow very precise control, or using the "CVT" algorithm which only requires the width, height, and refresh rate. The details to these commands are explained each time you turn on the pi0/pi4.

Testing multiple resolutions / automation

If you are testing more than one display you might be interested in some scripts that automate switching resolutions and generate intuitive file names too. There are several to choose among:

testAll 

will load each of the popular modes and wait for you to press spacebar to start recording. Once you have taken enough samples (7 or more!) press escape and it will advance to the next mode. Halfway though you are expected to move the sensor from the top to the bottom of the screen. You can also do testAllByRes that has you moving the sensor more often.

The syntax is testAll tvNameOrSomething (no spaces!).

If you want truly hands free testing, you can also use the autoTest script, which runs through a range of resolutions with zero keyboard interaction from you. Of course if your sensor is in the wrong place you'll get junk data. The syntax is autoTest tvname locationOrNote <samples>. For instance:

autoTest LG top 15

autoTest LG mid 15

This pair of commands would save 15 samples each, starting the moment you press enter at the command line. 

If you want to edit the list of resolutions tested, type nano /x/autoTest but I'll leave the full details to advanced users who can extrapolate from examples.

Real pros will also want to try out the responseTime and vsyncTest scripts both of which print a short summary of their syntax if you execute them with no arguments. 

Advanced command line options

lt -h lists the options, but here they are in detail:

-a<number> causes the program to start recording automatically. It  skips the first 3 measurements firsts, so that the screen is in a steady state. when <number> is reached it will quit automatically as well.

-x turns off recording to the .datx file. 

-r turns off recording  to the .datr file

-l sets the name of the log file (normally log.txt).

-p <0..255>: brightness of test probe (255=default)

-b <0...255>: brightness before/after test probe (0=default)

 -u ultra-wide bars (good for testing cracked screens)

You can set defaults by editing the lt script in /x, like this: nano /x/lt

Here's an example invocation, which automatically records 5 trials, doesn't save the raw brightness data, writes the trial by trial input lag and response time to xbr_resolution_top.datx, and appends the average input lag and response time to sonysummary.txt

lt -a5 -r -lsonysummary.txt xbr4 top

Publication quality figures

If you want to make figures for web/print you have two options. You can export individual trials into a simple text file that Excel or any other plot package or website can read. Then you can design any kind of plot you want given enough clicking around. Or there's the option of using the custom plot code I've written that auto-generates pretty nice figures but without the ease of modification that Excel would offer. 

For those autogenerated figures you'll need to roll up your sleeves and install some software on your desktop (Windows, Mac, or Linux) called octave. It's a full programing environment, but the sample script I wrote for it does not require any programming experience, you just double click my script and press F5 to run it; it will ask for the location of the  .datr file you transferred from the pi, and then will plot each trial, one after another. Full instructions are given at the top of my script so I won't duplicate them here. The script is downloadable the same place as the SD card image are stored:

https://1drv.ms/f/s!Ahb4rgU6L_z9gxV287CTdwmz8mvh (link not clickable to avoid extra traffic).

Either way you'll need to copy your data off the pi and onto your desktop. Use a SCP client to connect to the pi if it's on a network; by default all the raw .datr files are in the folder called /root. I use winscp for this. Or if it's not on a network you can copy the files from the SD card directly. Unless you have a linux desktop you'll need to move the files to where they can be accessed by windows or the mac first.  One way to do this would be to log in to the pi and type mv *.datr  /boot which will move the files to the easily readable fat32 boot partition on the SD card. Be sure to turn off the pi (halt) before removing the SD card.

Display characterization

To tell how pixel perfect your TV is, try out these programs that provide useful test images: 

dots

lines

bouncing

pixelart