Chamelium automates external display testing across VGA, HDMI, and DisplayPort (DP), helping to identify graphics bugs and regressions in a reliable and scalable way. It can emulate user behavior across a wide range of scenarios, such as plugging in (or unplugging) an external monitor before or after suspending, waking, or rebooting a device. It also allows us to simulate all types of displays on the market, at various resolutions and refresh rates, including non-standard or flaky behavior.
Chamelium is the public name of the internal Google project Chameleon (similar to Chromium and Chrome). You may see references to the original codename throughout the documentation linked below.
Chamelium consists of 3 primary components:
a hardware board which acts as an external display emulator, simulating output over VGA, HDMI, and DP. You can either ask a hardware manufacturer to build these for you, or contact email@example.com to request a few units.
an off-the-shelf FPGA board (SoCKit) to capture the output frames, with a micro-SD card that provides the Linux image and FPGA configuration. This can be purchased from distributors like Arrow or Terasic.
source code for the underlying test infrastructure and logic
Please direct any questions about Chamelium to firstname.lastname@example.org.
Setting up Chamelium
(Front side of the external display emulator board. On the left side there is one HDMI, two DP, and one VGA connector. On the right side there is the HSMC connector.)
(Back side of the external display emulator board)
You will need the following equipment to set up all the individual components in Chamelium:
1 external display emulator board (described above)
1 FPGA board (described above). Included in the box should be:
1 micro-SD card with at least 1GB of storage
1 micro-SD card reader
1 HSMC flex cable
Depending on what you’d like to test, one of each of the following cables: HDMI, VGA, and DP
1 Linux host (workstation or laptop)
1 USB drive with at least 4GB of storage
The following equipment is optional:
4 M3 screws (6mm in length)
4 M3 nuts (15mm in length)
4 M3 nuts (6mm in length)
1 additional VGA cable and 1 external monitor for debugging, if you’d like to see the display output as well
Configure the FPGA board
Image the SD card
Download tio.image.gz, gunzip it, and dd tio.image onto the micro-SD card from your Linux host.
# sudo dd if=tio.image of=/dev/sdx
Now insert the micro-SD card into the FPGA board.
Configure the external display emulator board
First, attach the HSMC flex cable to connect the two boards.
Optionally, if you’d like a more compact setup, you can stack the FPGA on top of the external display emulator board and secure them into place per the diagram below:
Note that the longer nuts should be placed in between the two boards, with the shorter nuts on the bottom.
Attach all cables
Attach the power and HDMI, DP, and/or VGA cables (depending on what interface you’d like to test), per the diagram below.
Connect the other end of the HDMI, DP, and/or VGA cable to the device under test (DUT) - the device you’d like to run the tests against.
Then connect the mini-USB port in the diagram below to your Linux host.
The additional VGA port next to the ethernet port is optional (it’s for debugging purposes only) and should be connected to an external monitor if you decide to use it.
Running the tests
Verify your network setup
# minicom -D /dev/ttyUSB0 -o -w -s
Select Serial port setup
Set the terminal to be 115200 8N1, and the Hardware Flow Control to No
Select Save setup as dfl to save these changes as the default
Restart the FPGA board
Once the FPGA is done booting, login as root
Make sure you can ping the FPGA board from your Linux host, and the Linux host from your FPGA. You may need to setup a DHCP server on your Linux host.
Switch your DUT into developer mode
Finally, make sure you can ping the DUT from your Linux host.
The IP address will change at each reboot, as the MAC address of the board is not fixed. You can fix it by running the following commands in uboot (change XX to hex numbers of your choice):
> setenv ethaddr 0A:XX:XX:XX:XX:XX
Setup your Linux host, DUT and the FPGA
# export BOARD=[name of your DUT’s board, viewable at chrome://version]
# ./setup_board --board $BOARD
# ./build_packages --board=$BOARD
# ./build_image --board=$BOARD test
Run the command displayed in the output in the terminal, under the section, “To copy the image to a USB key, use…”
# cros flash usb:// ../build/images/[...]/chromiumos_test_image.bin
Now, boot your DUT from the USB drive (with the test image) - you’ll need to enter vt2, login as root, and run enable_dev_usb_boot. Then, connect your USB drive to your DUT and restart - you’ll need to enter [Ctrl]-[u] at the developer mode boot screen.
After the DUT has booted, switch to vt2, login as root (the password on the test image is test0000) and run chromeos-install .
# cd ~/trunk/src/scripts
# ./setup_board --board arm-generic
# export CHAMELIUM_IP=[IP address of the FPGA board]
# export DUT_IP=[IP address of the DUT]
# cd ~/trunk/src/platform/chameleon
# make remote-install CHAMELEON_HOST=$CHAMELIUM_IP
Setup root password and SSH key
- There is no password by default. For security concern, we should set the password.
- Set the password on FPGA
# ssh root@$CHAMELEON_IP mkdir -p .ssh
- In Chromium OS chroot, copy the public key to FPGA and check it works.
# cat ~/trunk/chromite/ssh_keys/testing_rsa.pub | ssh root@$CHAMELEON_IP 'cat >> .ssh/authorized_keys'
# ssh $CHAMELEON_IP
Run the tests
# export TEST_NAME=[name of the test you’d like to run]
Alternatively, you can run an entire test suite by setting $TEST_NAME to either of these values, below. Each suite consists of a combination of the individual tests listed above.
Run a test using test_that!
# cd ~/trunk/src/scripts
# test_that --board=$BOARD --args "chameleon_host=$CHAMELIUM_IP" $DUT_IP $TEST_NAME
For additional instructions on how to modify tests or the FPGA image, please refer to the documentation below.