nct66xx-tools

nct66xx-tools is a Linux command-line toolkit for Nuvoton NCT66xx Super-I/O and embedded-controller hardware. It can monitor sensors, inspect and control fans on a verified board, dump controller firmware, and analyze saved firmware images.

The register maps and protocols used by this project were obtained through reverse engineering and validation on real hardware. The hardware-facing tools access the Super-I/O and EC directly through Linux /dev/port. They do not use lm-sensors, the hwmon sysfs interface, or the in-kernel nct6683 driver as their data source. A loaded kernel driver does not need to be removed for normal monitoring or fan control. The firmware dumper temporarily pauses and restores the bound nct6683 device while it owns the controller interface.

Warning

Direct hardware access can return incorrect data or damage hardware when a register map does not match the board. Development and complete testing were performed only on MSI MAG X870E TOMAHAWK WIFI (MS-7E59) with NCT6687D/DR. Other boards may or may not work. Use these tools at your own risk.

Tools

Tool	Purpose	Hardware writes	Root
nct66xx-monitor	Live sensors and controller diagnostics	No sensor, PWM, or fan-register writes	Yes
nct66xx-fan-control	Fan status, curves, manual duty, and automatic restore	Yes	Yes
nct66xx-dump-firmware	Save external SPI firmware to a file	EC mailbox control only; SPI flash remains read-only	Yes
nct66xx-firmware-analyzer	Analyze or compare saved firmware files	No hardware access	No

Hardware support

Function	Tested	Expected but untested
Monitoring	MS-7E59, NCT6687D/DR (0xD592, HWM 0x0A20)	Generic read-only monitoring on recognized NCT6683D, NCT6686D, and NCT6687D/DR controllers with the same HWM layout
Fan control	MS-7E59 with NCT6687D/DR	None; the tool rejects every other board and controller family
Firmware dump	NCT6687D/DR on MS-7E59	Other NCT6687D/DR boards using the same ISP mailbox layout
Firmware analysis	Known 256-KiB capture and arbitrary-file basic analysis	Board-specific metadata may not be recognized in other images

The monitor enables verified sensor labels and voltage-divider scales only when the DMI board name contains MS-7E59. All other recognized controllers use generic TEMP, Fan, PWM, and unscaled IN labels so board wiring is not presented as fact.

nct66xx-monitor

Reads temperatures, fan RPM, PWM duty, voltage ADCs, and controller diagnostics directly from the NCT66xx hardware-monitor registers. Normal live output keeps current, minimum, maximum, and average values since startup. The monitor never changes fan settings or EC data registers.

sudo ./nct66xx-monitor [FLAGS] [INTERVAL_MS]

Flag	What it does
--once	Print one sample and exit.
--hide-zero	Hide current zero-valued channels; also applies to --json.
--raw	Append raw sensor, fan, and PWM configuration.
--identity	Print SIO chip ID, revision, and HWM base.
--sio-report	Print the Super-I/O logical-device report.
--ec-info	Print selected EC/HWM state and metadata.
--firmware-info	Print direct firmware metadata.
--frozen-state	Print EC protection state.
--fan-routing	Print raw Tach/PWM pin routing.
--topology	Print discovered sensor source slots.
--adc	Print raw voltage ADC values and active scale.
--json	Print one JSON snapshot and exit.
-h, --help	Print help.
INTERVAL_MS	Refresh interval; default 1000, minimum 10.

Diagnostic flags that describe a static controller state exit after printing their report. --identity can also be combined with live-monitoring flags.

Monitor example

sudo ./nct66xx-monitor --once --hide-zero

NCT6687D/DR hardware monitor / MS-7E59 board profile
direct NCT66xx EC reads | interval 1000 ms | runtime 0s | samples 1

SENSOR                 CURRENT          MIN          MAX          AVG

TEMPERATURES
CPU (AMD TSI)           51.0 C         51.0 C         51.0 C         51.0 C  
System diode            45.5 C         45.5 C         45.5 C         45.5 C  
VRM MOS                 45.0 C         45.0 C         45.0 C         45.0 C  
Chipset                 48.0 C         48.0 C         48.0 C         48.0 C  
CPU socket              46.5 C         46.5 C         46.5 C         46.5 C  
Aux thermistor          48.5 C         48.5 C         48.5 C         48.5 C  

FANS
CPU fan                  643 rpm        643 rpm        643 rpm        643 rpm
Pump fan                2955 rpm       2955 rpm       2955 rpm       2955 rpm
System fan 1             623 rpm        623 rpm        623 rpm        623 rpm
System fan 4             669 rpm        669 rpm        669 rpm        669 rpm
System fan 6             601 rpm        601 rpm        601 rpm        601 rpm

PWM
CPU fan PWM             34.1 %         34.1 %         34.1 %         34.1 %  
Pump PWM                77.3 %         77.3 %         77.3 %         77.3 %  
EZ-Conn. PWM            64.7 %         64.7 %         64.7 %         64.7 %  
System fan 1 PWM        39.2 %         39.2 %         39.2 %         39.2 %  
System fan 2 PWM        64.7 %         64.7 %         64.7 %         64.7 %  
System fan 3 PWM        36.9 %         36.9 %         36.9 %         36.9 %  
System fan 4 PWM        64.7 %         64.7 %         64.7 %         64.7 %  
System fan 5 PWM        64.7 %         64.7 %         64.7 %         64.7 %  
System fan 6 PWM        40.8 %         40.8 %         40.8 %         40.8 %  

VOLTAGES
+12V                  11.904 V       11.904 V       11.904 V       11.904 V  
+5V                    5.040 V        5.040 V        5.040 V        5.040 V  
CPU SoC                1.072 V        1.072 V        1.072 V        1.072 V  
DIMM                   1.216 V        1.216 V        1.216 V        1.216 V  
Vcore sense            0.560 V        0.560 V        0.560 V        0.560 V  
Chipset V              0.640 V        0.640 V        0.640 V        0.640 V  
CPU SA                 0.624 V        0.624 V        0.624 V        0.624 V  
VIN7                   1.520 V        1.520 V        1.520 V        1.520 V  
+3.3V                  3.280 V        3.280 V        3.280 V        3.280 V  
VSB                    3.328 V        3.328 V        3.328 V        3.328 V  
AVSB                   3.328 V        3.328 V        3.328 V        3.328 V  
VTT                    2.032 V        2.032 V        2.032 V        2.032 V  
CMOS battery           3.216 V        3.216 V        3.216 V        3.216 V  
VREF                   1.840 V        1.840 V        1.840 V        1.840 V  

nct66xx-fan-control

Board-specific fan tool for the verified MS-7E59 mapping. Status and curve commands inspect the controller. --set and --set-all write real fan-control registers.

sudo ./nct66xx-fan-control COMMAND

Command	What it does
--status	Show RPM, PWM, and automatic/manual mode for all channels.
--curve CHANNEL	Show one channel's target or curve.
--curves	Show all configured targets and curves.
--set CHANNEL PERCENT	Set channel 1..8 to 0..100 percent.
--set CHANNEL auto	Restore one channel to firmware automatic control. AUTO is also accepted.
--set-all auto	Restore all channels to firmware automatic control. AUTO is also accepted.
-h, --help	Print help.

Channel map: 1 CPU, 2 Pump, 3..8 System Fan 1..6. 0% can stop a fan. Before the first manual change, the original target is saved under /var/lib/nct66xx-fan-control/. Restoring auto reapplies the saved target and then returns control to the firmware. If no saved state exists, only the manual mode bit is cleared.

For CPU and Pump, --curve shows the exposed direct PWM command target; their complete BIOS curve is handled internally and has not been located in the identified registers. System Fan 1 through 6 expose seven target points.

Fan-control example

sudo ./nct66xx-fan-control --status

MSI MS-7E59 NCT6687DR fan map (read-only status)
1 CPU fan       rpm=645 pwm= 88 ( 34.5%) mode=auto
2 Pump fan      rpm=2962 pwm=199 ( 78.0%) mode=auto
3 System fan 1  rpm=601 pwm=100 ( 39.2%) mode=auto
4 System fan 2  rpm=0 pwm=168 ( 65.9%) mode=auto
5 System fan 3  rpm=669 pwm= 94 ( 36.9%) mode=auto
6 System fan 4  rpm=0 pwm=168 ( 65.9%) mode=auto
7 System fan 5  rpm=0 pwm=168 ( 65.9%) mode=auto
8 System fan 6  rpm=623 pwm=104 ( 40.8%) mode=auto

nct66xx-dump-firmware

Reads the controller's external SPI firmware through the verified NCT6687D/DR ISP transport. The tool writes EC mailbox and transport-control values required to enter and leave ISP read mode, but sends only JEDEC-ID, status-read, and SPI READ commands to the flash. It does not send flash write-enable, program, erase, or status-register-write commands.

sudo ./nct66xx-dump-firmware [--output FILE] [--offset BYTES] [--size BYTES]

Flag	What it does
--output FILE	Output file; default nct66xx-flash.bin. Existing files are replaced.
--offset BYTES	Start address; default 0, maximum 0xFFFFFF. Decimal and 0x hexadecimal are accepted.
--size BYTES	Bytes to read; default detected capacity or 262144, maximum 0x1000000. Decimal and 0x hexadecimal are accepted.
-h, --help	Print help.

Firmware-dumper example

sudo ./nct66xx-dump-firmware

WARNING: After dumping the firmware, some hardware-monitor sensor values may be incorrect.
Reboot to restore correct readings; suspend or hibernate may not be enough.

[sio] NCT6687D/DR family: chip ID 0xD592, revision 0xBC, HWM base 0x0A20
[isolation] kernel hwmon access paused (driver nct6683, HWM 0x0A20)
[start] NCT6687 ISP firmware dump: offset 0x0, requested 262144 bytes -> nct66xx-flash.bin
[isp] SPI JEDEC ID: EF 30 12 (Winbond)
[isp] JEDEC-derived capacity: 262144 bytes (0.2 MiB)
[progress] 262144 / 262144 bytes  100.0%
[done] 262144 bytes read; EC returned to user mode.
[isolation] kernel hwmon access restored

Reboot after every dump before trusting hardware-monitor readings again. Suspend and hibernate may not restore correct values. Do not run the monitor, sensors, or another hardware-monitoring tool while dumping.

nct66xx-firmware-analyzer

Offline file analysis. No root and no hardware access required.

./nct66xx-firmware-analyzer FIRMWARE.bin
./nct66xx-firmware-analyzer --diff OLD.bin NEW.bin

The normal mode reports file size, SHA-256, data statistics, readable strings, and recognized metadata. --diff also reports changed bytes and up to 32 changed regions. There is no --help flag.

Firmware-analyzer example

./nct66xx-firmware-analyzer nct66xx-flash.bin

NCT6687 firmware analysis

File:        nct66xx-flash.bin
Size:        262144 bytes (0x40000)
SHA-256:     4f54ff685ca83ea860260ef269d2fc1aa24390fe1f641f4330e076a544178b81

Recognized metadata layout: MSI eSIO/NCT6687 capture
Manufacturer: MSI (layout/profile match; not a signed vendor field)
Chip ID:      0xD592 (NCT6687 family)
Board ID:     0x020D
Build date:   2024-11-13

Build

Requirements

• Linux on x86 hardware that exposes /dev/port
• A C11 compiler such as GCC or Clang
• GNU Make
• Root privileges for direct hardware tools

git clone https://github.com/tpoechtrager/nct66xx-tools.git
cd nct66xx-tools
make

The four binaries are created in the project root. There is currently no install target.

make clean

Project layout

Path	Content
src/nct66xx-monitor.c	Live monitor and read-only diagnostics
src/nct66xx-fan-control.c	Board-guarded fan control
src/nct66xx-dump-firmware.c	Read-only firmware dumper
src/nct66xx-firmware-analyzer.c	Offline analyzer and image comparison
src/nct66xx-common.c, .h	Shared direct-I/O, identity, board guard, and acknowledgement code
src/nct66xx-common-flash.c, .h	Disabled and untested flash-writing reference code

First hardware access

Direct tools require sudo. On first use, enter YES once; it is stored in /var/lib/nct66xx-tools/acknowledged. Set NCT66XX_ACK_FILE to use a different acknowledgement path.

Safety

• The monitor is read-only.
• The analyzer is offline and never accesses hardware.
• The dumper reads SPI flash only, but changes the EC transport state while it runs and requires a reboot afterwards.
• Fan control writes real hardware registers and deliberately rejects hardware other than MS-7E59 with the expected NCT6687D/DR identity and HWM base.
• A failed or interrupted firmware dump still requires a reboot.
• Suspend and hibernate are not substitutes for that reboot.

Inactive flash-writing reference code

src/nct66xx-common-flash.c and src/nct66xx-common-flash.h contain reverse-engineered reference implementations for two firmware-writing paths: an NCT6687 ISP erase/program sequence for a host-provided image and the /MAF handoff for an image already supplied by the system firmware. /MAF is the observed mode name; no public expansion of the acronym is known.

This code has never been tested and is not part of a normal build. It is guarded by NCT66XX_ENABLE_UNTESTED_FLASH, which normal builds do not define. No command-line tool calls it, and there is no supported option to enable firmware writing. It exists only as documented reference code for future review. The firmware dumper remains read-only and does not use these functions.

Technical findings

Controller and hardware-monitor interface

The tested controller identifies itself through the Super-I/O configuration interface as NCT6687D/DR family, chip ID 0xD592, revision 0xBC. Its hardware-monitor logical device is at I/O base 0x0A20:

Port	Purpose
0x0A20	Page selector
0x0A21	Register index
0x0A22	Register data

The monitor discovers the base through SIO before reading values. Confirmed HWM ranges on the tested controller are:

Register range	Content
0x0100..	Temperature, fan, and voltage sample data
0x0140..	16 fan tachometer inputs
0x0160..	8 primary PWM duty registers
0x0174..	Monitor and fan status
0x01A0..0x01BF	32 monitor-source selectors
0x01C0..	Fan input configuration
0x01D0..	PWM output configuration

On MS-7E59, the verified named voltage rails use monitor slots MON16 through MON29. The external voltage dividers are x12 for +12V, x5 for +5V, and x2 for DIMM; all other named rails use x1. Other boards deliberately use unscaled raw IN values because their physical rail wiring is unknown.

Fan mapping on MS-7E59

The tested fan-control mapping is CPU fan, Pump fan, and System Fan 1 through 6. CPU and Pump use direct targets. System Fan 1 through 6 use seven curve points each. This mapping and its configuration handshake are board-specific; they are the reason that nct66xx-fan-control rejects other boards.

Firmware and ISP read path

The controller reads a 256-KiB external SPI flash. The tested chip reports JEDEC ID EF 30 12 (Winbond). Confirmed ISP mailbox locations are:

EC address	Purpose
0x0EEC	ISP task A control block
0x0EF4	ISP task B control block
0x0EFC	ISP exit/user-mode handoff
0x0EFD	ISP state
0x0EFE	ISP entry mailbox
0x1E00	Task A data buffer
0x1F00	Task B data buffer

The dumper uses only JEDEC-ID, SPI status-read, and SPI READ commands. It discovers the HWM base instead of assuming 0x0A20, so it should work on other NCT6687D/DR boards that use this same ISP mailbox layout and read protocol. That compatibility is expected, but has not been tested on another board. It does not claim support for NCT6683D or NCT6686D firmware dumping.

Captured firmware layout

The verified 256-KiB image contains 8051-family controller machine code and board-specific data. The recognized metadata block starts at 0x7100. In the tested capture it reports chip ID 0xD592, board ID 0x020D, and build date 2024-11-13.

Sixteen default fan-curve records start at 0x7600. Each captured record uses temperature points 10, 20, 30, 40, 50, 60, 70 C and PWM points 40, 50, 60, 70, 80, 90, 100 %. These are defaults stored in the firmware image, not necessarily the live curves currently selected by the BIOS.

License

This project is licensed under the GNU General Public License version 2. See LICENSE.