Controlling EIZO displays

This document is a collection of cleaned up personal notes. Feel free to contact me if you’re interested in continuing the efforts.

Overview

Goals

To be able to change the brightness and signal input of an EIZO ColorEdge display simply and quickly from all of Linux/Windows/macOS, but primarily Linux, which is my daily driver OS. Note that EIZO monitors are exceptional in that they do not support DDC/CI, for which I already have a solution.

I haven’t paid this much money for gatekeeping, and changing those settings on CG2700S has become even more annoying than on a CS2730.

What’s particularly insulting is that EIZO does provide such software for their cheap FlexScan series (called Screen InStyle), and that it could be rather easily adjusted to do ColorEdge as well, with an unimportant caveat.

Concrete goals

Tools and also targets

Previous works

I have found the successful approaches too late, read on for further explanations:


Reverse engineering

It took me way too much time to find out that my goals are actually technically possible at all. I had been a suffering customer for naught.

Targets

Trivia

Frontends

Tools

Target platforms

It was the most convenient for me to primarily use a MacBook throughout. That said, the decompiling tools do not care about what you load in them.

Target binaries

Windows

The Screen InStyle .Net executable perhaps provides the cleanest information on the use of libemc, to the extent that it actually uses it. Note that some of the functions are missing from macOS/Linux libemc. The application hardcodes some monitor data on its own, e.g., FlexScan ports. (The ports list for most EIZO monitors is also hardcoded into the libemc library but I haven’t figured out how to access it through its API.)

EIZO installers can be unpacked on Linux/macOS with innoextract—​unzip and 7za don’t work, although there are clearly some ZIP entries within.

macOS

macOS packages can be unpacked without installing them by using bsdtar recursively, just mind that the paths below don’t strictly apply.

/Library/Application Support/EIZO/ColorNavigator 7/tools/CN7ResetTool/*

ColorNavigator 7’s bundled reset tool is a good minimal example of how libemc should be used, and it comes with its own library bundle. The library versions here might be older, though.

/Library/Application Support/EIZO/ColorNavigator 7/plugins/exports/mac/{libimpronta2,libetk}.dylib

This is a logging library loaded on runtime that might provide a few runtime hints, but it seems like a hassle to get working.

/Library/Application Support/EIZO/ColorNavigator 7/plugins/…​/libcn7*.dylib

ColorNavigator 7’s own various libraries decompile very well, and they generally show how individual libemc functions are supposed to be used.

  • The cn7::monitor namespace is seemingly statically linked to all of them.

  • com.eizo.cn7.core/mac/libcnCore.dylib is about as good as any other.

/Library/Application Support/EIZO/ColorNavigator 7/plugins/com.eizo.framework.salt/mac/libsalt.dylib
  • The "bagel" namespace seems interesting.

  • bagel::emerror_string() is an odd one, though it pertains directly to libemc rather than to the wire protocol.

/Applications/Screen InStyle.app/Contents/Resources/Libs/*.dylib

Screen InStyle is a bit more involved for reuse:

fixup() (install_name_tool \
  -change @executable_path/../Resources/Libs/$1 @rpath/$1 $2)
fixup libmptag.dylib libemc.dylib
fixup libHIDmctrl.dylib libemc.dylib
fixup libcolour.dylib libemc.dylib
fixup libmctrl.dylib libHIDmctrl.dylib
/Library/Application Support/EIZO/QuickColorMatch/plugins/exports/mac/*.dylib

Quick Color Match is similar, libraries need patching up.

libfwu.dylib
libfwupdate.dylib

Firmware updaters include an interesting library that names more HID usages, which aren’t actually even used by libemc. This is of interest for implementing custom interfaces.

Firmware files are encrypted, and decryption code is obfuscated. But you can still figure it out:

  • .efw Blowfish ECB key: 7F3B1965-5184-4289-A8B8-EC8808E08B37\0

  • .efw2 AES-256-CBC key: 85eb3db17c514317b2256f13269e158651797624d31d40d69007b2c604982167

The .efw2 header contains version fields, and an IV which is further XORed based on that version:

  • 2.0: 61e899ec5899443d9af818c502f61e9e

  • 2.1: 05e606d92454401ca5108267db3880cb

  • 2.2: 53f68f111fee5a6eadc1107637ab9171

Linux

Ask your local EIZO support for a Linux package of ColorNavigator 7, then locate and extract the libraries. For reuse, they need some fixing up:

for i in lib*.so.?.*.*; do mv "$i" "${i%.*.*}"; done
for i in lib*.so.?; do ln -s "$i" "${i%.?}"; done
patchelf --set-rpath '$ORIGIN' lib*.so.?

Library notes


Library reuse

Use EmCtrlFind(NULL, 0) with EmCtrlGetSerialProduct() to initialise the library and retrieve monitor ID pairs, then you can just try to use any libemc function you have a prototype of. A Screen InStyle decompile should get you far.

Linking

To cross-compile Windows utilities, you will need gendef to create a .a file for linking with MinGW:

In Makefile terms:

%.def: %.dll
        gendef - $< > $@
%.a: %.def
        dlltool --input-def $< --output-lib $@

To make executables look at their own directory for the reused libraries:


Software for debugging

macOS

Linux

It should be possible to generate reverse-engineered debugging symbols, and then use any capable GDB UI, although I haven’t tried doing so. These projects are incidentally ELF-only: ghidra2dwarf, ghidra-ExportDwarfELFSymbols.

You should also be able to actually use both Ghidra’s and Binary Ninja’s debugger modes.


USB packet capture setup

Wireshark’s USBHID filter/dissector (Analyze → Enabled Protocols…​) sucks in that while it makes a few fields immediately readable, you also stop being able to select report data. With it disabled, remember that bRequests 1 and 9 are Get_Report and Set_Report respectively, and a wValue of 0x03XX is a Feature request concerning Report ID XX.

macOS

Windows

Linux


Tracing and USB packet format

The monitor kind-of follows USB HID. However, it doesn’t use something standard like MCCS over USB, but rather a custom, evolving, complicated protocol. Report IDs are always included at the beginning of report data as usual.

How libemc behaves on the CS2730

 - Initialization: EmCtrlFind

      EIZOMonitor::FindAllMonitor -> EIZOMonitor::FindAllHIDMonitor
       -> EmHIDFind -> EmFind -> EmFindEx
           -> CHIDDevice::FindDevices
               -> CHIDDevice::open -> CHHIDDeviceImplLeopard::open
                   -> CHHidDeviceImplLeopard::getCommandElements
               -> CHIDDevice::payoutPINCode
                   -> CHIDDevice::getFixedData
                       -> CHIDDeviceImplLeopard::getFixedData
                   -> CHIDDevice::getFeatureValue
                       -> CHIDDeviceImplLeopard::getFeatureValue

    - Read descriptor:    bRequest 1, wValue 0x0306, wIndex 0, wLength 3

               -> CHIDDevice::loadReportDescriptor
                   -> CHIDDevice::getFixedData
                       -> CHIDDeviceImplLeopard::getFixedData
                   -> CHIDDevice::setFeatureArray
                       -> CHIDDeviceImplLeopard::setFeatureArray

    - Write request type: bRequest 9, wValue 0x0301, wIndex 0, wLength 517

                   -> CHIDDevice::getFeatureArray
                       -> CHIDDeviceImplLeopard::getFeatureArray

    - Read response:      bRequest 1, wValue 0x0301, wIndex 0, wLength 517
      <repeats until the data is complete>

               -> CHIDDeviceImplLeopard::setProperty
           -> CHIDDevice::GetAllDevices
           -> CountDevices
               -> CHIDDevice{,ImplLeopard}::getProperty
               -> CHIDDevice::GetProductGroup
       -> EmHIDRetrieve -> EmRetrieve -> EmRetrieveEx
       -> EmHIDGetFixedData -> EmGetFixedData -> EmGetFixedDataRaw
       -> EmHIDGetData
           -> EmGetFixedDataEx, EmGetFeatureArray

    - Read serial product bRequest 1, wValue 0x0308, wIndex 0, wLength 25

           -> EmCheckResult
      EIZOMonitor:EmParseMonitorProfile
       -> EIZOMonitorInterface::GetFixedDataMonitorProfile
           -> EmHIDGetFixedData -> EmGetFixedData -> EmGetFixedDataRaw
       -> EIZOMonitorInterface::GetMonitorprofile
           -> EmHIDGetData
               -> EmGetFixedDataEx, EmGetFeatureArray

    - Read response:      bRequest 1, wValue 0x0309, wIndex 0, wLength 112

           -> EmCheckResult
       -> EIZOMonitorInterface::Supported3DLUT
           -> EmHIDGetFixedData -> EmGetFixedData
       -> EIZOMonitorProfile::EIZOMonitorProfile
           -> EmpTagParse, EmpGetTagDataSize, EmpGetTagData, Emp*...
      EIZOMonitor::EmParseModeProfile
       -> EmHIDGetFixedData -> EmGetFixedData
       -> EmHIDGetData
           -> EmGetFixedDataEx, EmGetFeatureArray, EmIsExclusiveMode

    - Write request type: bRequest 9, wValue 0x0305, wIndex 0, wLength 529
    - Read response:      bRequest 1, wValue 0x0305, wIndex 0, wLength 529

           -> EmCheckResult

    - Read result:        bRequest 1, wValue 0x0307, wIndex 0, wLength 8

       -> EIZOModeProfile::EIZOModeProfile
           -> EIZOModeProfile::parseProfileData -> Emp*...

 - Read brightness: EmCtrlGetBrightnessForPercentage

      EIZOMonitor::EmGetBrightness
       -> EIZOMonitorInterface::GetBrightness
           -> EIZOHIDMonitor::GetBrightness
               -> EmHIDGetFixedData -> EmGetFixedData
               -> EmHIDGetValue
                   -> EmGetFixedDataEx, EmGetFeatureValue
                       -> EmIsExclusiveMode
                       -> CHIDDeviceImplLeopard::setFeature*

    - Write request type: bRequest 9, wValue 0x0303, wIndex 0, wLength 39

                       -> CHIDDeviceImplLeopard::getFeatureArray

    - Read response:      bRequest 1, wValue 0x0303, wIndex 0, wLength 39

                   -> EmCheckResult

    - Read result:        bRequest 1, wValue 0x0307, wIndex 0, wLength 8

 - Write brightness: EmCtrlSetBrightnessForPercentage

    - Write request type: bRequest 9, wValue 0x0302, wIndex 0, wLength 39
    - Read result:        bRequest 1, wValue 0x0307, wIndex 0, wLength 8

I stopped bothering to check code paths near the end, it’s actually fairly straightforward once you realise how the USB interface is structured.

Dumping report descriptors

Linux makes looking at HID report descriptors the easiest, though the following won’t get you the interesting one:

# uniq -c /sys/kernel/debug/hid/*:056D:*/rdesc
$ hexdump /sys/bus/hid/devices/*:056D:*/report_descriptor

HID reports

Reports 1, 3, 5, 12, 14 use an odd scheme for retrieval where you first set Feature reports before you get them back with their values. Note that these reports all use the 0xff30 Usage Page:

1: [Receive] legacy report descriptor (Feature)

The monitor adds a layer to the HID protocol, in that this Feature report returns another HID report descriptor that describes data contained within reports 2—​5, 11—​14.

The data start with two 16-bit fields denoting the starting offset, and the total size of data.

2: Send small data (Feature)
4: Send large data (Feature)

These two differ by report size. If it’s more than 32 bytes, use the larger report.

The data consist of: 16-bit HID Usage Page, 16-bit HID Usage ID, 16-bit PIN code, and finally the subreport, without its Report ID.

3: Receive small data (Feature, Input)
5: Receive large data (Feature, Input)

Analogical to setting features, but mind the set/get oddity.

6: [Get] PIN code (Feature)

This returns a linearly increasing 16-bit field that presumably serves to help resolve race conditions.

7: [Receive] last command result (Feature)

Used to check whether the last operation has been successful.

The data consist of: 16-bit HID Usage Page, 16-bit HID Usage ID, 16-bit PIN code, and an 8-bit result code that should not be negative.

8: [Receive] serial number [and] model name (Feature)

The serial number is always 8 characters long, the rest of the data will be the model name, padded with spaces.

9: [Receive] monitor profile (Feature)

Key-value database of: 8-bit key, 8-bit length, data. See the EIZOMonitorProfile class.

10: Enter/exit critical section (Feature)

This has been added in later models, such as the CG2700S.

The data is a 16-bit number, which you can both get and set. libemc sets it either to zero, or to its PIN code.

11, 12, 13, 14: Send/receive small/large data (Feature)

Like 2, 3, 4, 5, but for critical sections.

The data is additionally prepended by the 16-bit critical section number.

Input reports

Button presses alone generate at least 4 Input reports, so the monitor is rather talkative. That said, not all possible changes are reported.

Monitor profile contents

Presence of keys differs by monitor. For me, the important ones were:

Other databases

The monitor maintains a "filesystem" where files have names in the scheme of ABC123. Filenames do not make a lot of sense. VER (firmware version?), EFW (more firmware information?), AIC (ASIC/FPGA data?), PRM (parameters?), EEP (EEPROM?), FLA (flash?), SYS (system?), INP (input?), LUT (look-up table?), MON (mode name?), INI (initial parameters?), BAK, BKL, MET, MOD, TMP…​

"prg000", "inp027", "aic653" have been seen used for firmware uploads.


Firmware decoding

I have captured a firmware update of my CS2730. This is the easiest way to decrypt at least parts of it—​the .efw was over 2 MiB, the monitor received 1 MiB. There’s half of my plaintext!

$ tshark -r cs2730-fw-update.pcapng.gz -l -T ek --disable-protocol usbhid \
  | NO_COLOR=1 go run eizo-pcap-decode.go \
  | awk '$2 == "OUT" && $3 == "<>" && $4 == "ff0200fe" && $7 ~ /^prg000/ {
      print substr($6, 21) }' \
  | xxd -r -p > cs2730-fw-update.bin

The main microprocessor uses the Thumb-2 instruction set in little-endian. And there are symbols in the form of name references to the current function. It’s just not clear how to pair them automatically. Making sense of the code is still a difficult undertaking.

I have also captured a firmware update of my CG2700S, but it’s missing the symbols. The MCU identifies as Renesas Synergy. Then there’s also an MStar unit.


Reimplementing libemc


Display notes

EIZO is overpriced. I went for a second one because I wanted a mostly uniform display, and after the backlight of my former BenQ PD3220U failed just out of warranty, the second deciding factor was a decent warranty period.

My experiences say that with EIZO, you pay for properties rather than durability. LCDs suck.

CS2730 woes

CG2700S woes

CS2731 woes

Comments

Use e-mail, webchat, or the form below. I'll also pick up on new HN, Lobsters, and Reddit posts.