EMCFANCTL(8) | System Manager's Manual | EMCFANCTL(8)

# NAME

`emcfanctl` — Command line utility to interact with EMC fan controllers

# SYNOPSIS

`emcfanctl` | [`-dhj`] device `info`

`emcfanctl` | [`-dhj`] device `register list`

`emcfanctl` | [`-dhj`] device `register read` start_register [end_register]

`emcfanctl` | [`-dhj`] device `register write` register value

`emcfanctl` | [`-dhj`] device `fan` n `status`

`emcfanctl` | [`-dhj`] device `fan` n `drive read`

`emcfanctl` | [`-dhj`] device `fan` n `drive write value`

`emcfanctl` | [`-dhj`] device `fan` n `divider read`

`emcfanctl` | [`-dhj`] device `fan` n `divider write value`

`emcfanctl` | [`-dhj`] device `fan` n `min_expected_rpm read`

`emcfanctl` | [`-dhj`] device `fan` n `min_expected_rpm write` `500|1000|2000|4000`

`emcfanctl` | [`-dhj`] device `fan` n `edges read`

`emcfanctl` | [`-dhj`] device `fan` n `edges write` `3|5|7|9`

`emcfanctl` | [`-dhj`] device `fan` n `polarity read`

`emcfanctl` | [`-dhj`] device `fan` n `polarity inverted`

`emcfanctl` | [`-dhj`] device `fan` n `polarity non-inverted`

`emcfanctl` | [`-dhj`] device `fan` n `pwm_base_frequency read`

`emcfanctl` | [`-dhj`] device `fan` n `pwm_base_frequency write` `26000|19531|4882|2441`

`emcfanctl` | [`-dhj`] device `fan` n `pwm_output_type read`

`emcfanctl` | [`-dhj`] device `fan` n `pwm_output_type push-pull`

`emcfanctl` | [`-dhj`] device `fan` n `pwm_output_type open-drain`

`emcfanctl` | [`-dhj`] device `apd read`

`emcfanctl` | [`-dhj`] device `apd on`

`emcfanctl` | [`-dhj`] device `apd off`

`emcfanctl` | [`-dhj`] device `smbus_timeout read`

`emcfanctl` | [`-dhj`] device `smbus_timeout on`

`emcfanctl` | [`-dhj`] device `smbus_timeout off`

# DESCRIPTION

The `emcfanctl` utility interacts with a Microchip Technology EMC-210x or EMC-230x fan controller via emcfan(4) driver.

The options are as follows:

`-d`
  Debug mode.
`-h`
  Display help.
`-j`
  For the commands that produce output, output the result in JSON.

The commands are as follows:

`info`
  Print the family, chip id and chip revision for the specific device.
`register list`
  Print the valid registers for the particular chip at the specific device.
`register read` start_register [end_register]
  Print the values present in the range of registers from start_register to end_register. If end_register is missing, just print one register at start_register. It is possible to use the text names given out by the `list` command for start_register or end_register.
`register write` a_register value
  Write value into the register called a_register.

The EMC210X and EMC230X fan controllers have a tremendous number of features and options and can run in number of different modes. What follows are some short cut commands that can be used for some of the more common things one might want to do with a particular controller.

`fan` n `status`
  Print the stall, spin up and drive status for a particular fan. Note that the fan will be marked as stalled if the RPMs are below the minumum expected RPM level.

`fan` n `drive read`
  Print the current value of the drive level for a particular fan.

`fan` n `drive write value`
  Set the drive level for a particular fan to value.

`fan` n `divider read`
  Print the current value of the frequency divider for a particular fan.

`fan` n `drive write value`
  Set the frequency divider for a particular fan to value.

`fan` n `drive min_expected_rpm read`
  Print the current minimum expected RPM that a fan is suppose to run at. If the RPMs are lower than the expected value, the fan will be marked as stalled and the RPM value in envstat(8) will be ‘`N/A`’.

`fan` n `drive min_expected_rpm write` `500|1000|2000|4000`
  Set the minimum expected RPM value for a fan.

`fan` n `drive edges read`
  Print the number of edges that a particular fan has. This value, along with hw.emcfan0.poles, is used in the tachometer algorithm to determine the RPM.

`fan` n `drive edges write` `3|5|7|9`
  Set the number of edges that the fan has.

`fan` n `polarity read`
`fan` n `polarity inverted`
`fan` n `polarity non-inverted`
  Print or set the polarity of the drive level for the fan. When the polarity is inverted a drive level of 0 will be maximum drive, and when the polarity is non-inverted, a drive level of 0 is minimum drive.

`fan` n `drive pwm_base_frequency read`
  Print the number of PWM base frequency for a particular fan.

`fan` n `drive pwm_base_frequency write` `26000|19531|4882|2441`
  Set the base PWM frequency for a particular fan.

`fan` n `pwm_output_type read`
`fan` n `pwm_output_type push-pull`
`fan` n `pwm_output_type open-drain`
  Print or set the PWM output type for a particular fan.

`apd read`
`apd on`
`apd off`
  Print, turn on or turn off the anti-parallel diode mode on the chip. The EMC2103-2/4, EMC2104 and EMC2106 have the ability to connect two temperature sensor diodes together with just two wires. In order to be able to read both diodes, APD needs to be turned on.

`smbus_timeout read`
`smbus_timeout on`
`smbus_timeout off`
  Print, turn on or turn off SMBUS timeout. I2C and SMBUS are very simular, but a difference is that SMBUS clients can trigger a bus timeout if operations are not performed against the chip in a certain amount of time. In order to be completely I2C compliant, the SMBUS timeout should be turned off. Some of the EMC product default this to on and some default it to off.

Not all of the above options apply to all chip types and the `emcfanctl` command will error if the option does not apply to a particular device.

# EXAMPLES

This will print the chip family and product id for a particular device:

    # emcfanctl /dev/emcfan0 info
    Product Family: EMC230x
    Chip name: EMC2301
    Revision: 1

This is the same, except in JSON:

    # emcfanctl -j /dev/emcfan0 info | json_pp
    {
       "chip_name" : "EMC2301",
       "family_name" : "EMC230x",
       "product_family" : 2,
       "product_id" : 55,
       "revision" : 1
    }

This reads a number of registers from the chip and output the result in a JSON array:

    # emcfanctl -j /dev/emcfan0 register read 0x20 0x29 | json_pp
    [
       {
          "register" : 32,
          "register_name" : "configuration",
          "register_value" : 64
       },
       {
          "register" : 36,
          "register_name" : "fan_status",
          "register_value" : 0
       },
       {
          "register" : 37,
          "register_name" : "fan_stall_status",
          "register_value" : 0
       },
       {
          "register" : 38,
          "register_name" : "fan_spin_status",
          "register_value" : 0
       },
       {
          "register" : 39,
          "register_name" : "drive_fail_status",
          "register_value" : 0
       },
       {
          "register" : 41,
          "register_name" : "fan_interrupt_enable_register",
          "register_value" : 0
       }
    ]

You can use names for the registers. The following produces the same result as the previous example, except not in JSON:

    # emcfanctl /dev/emcfan0 register read configuration drive_fail_status
    configuration;32 (0x20);64 (0x40)
    fan_status;36 (0x24);0 (0x00)
    fan_stall_status;37 (0x25);0 (0x00)
    fan_spin_status;38 (0x26);0 (0x00)
    drive_fail_status;39 (0x27);0 (0x00)

This writes a uint8_t value to a particular register:

`# emcfanctl /dev/emcfan0 register write configuration 0xc0`

This read back the 0x20 register, also known as ‘`configuration`’ as a JSON array. Using the jq(1) command the value is extracted.

    # emcfanctl -j /dev/emcfan0 register read 0x20 | jq -r '.[0].register_value'
    192

Read the current drive level for fan #1 on a particular device:

    # emcfanctl /dev/emcfan0 fan 1 drive read
    Drive:96

Change the drive level for fan #1. A number of other variables such as polarity and the PWM divider affect what the drive level means.

    # emcfanctl /dev/emcfan0 fan 1 drive write 0x80
    # emcfanctl /dev/emcfan0 fan 1 drive read
    Drive:128

If the envstat(8) command is used to look at the RPM of a fan, it will produce something like the following:

                        Current  CritMax  WarnMax  WarnMin  CritMin  Unit
    [emcfan0]
               FAN 1:      1159                                       RPM

This is below the minumum expected RPM that the fan is suppose to run at:

    # emcfanctl /dev/emcfan0 fan 1 min_expected_rpm read
    Minumum expected rpm:500

If the minimum expected RPM is changed to be higher than what the fan is able to run at, that will simulate a stalled fan.

`# emcfanctl /dev/emcfan0 fan 1 min_expected rpm write 4000`

Using the envstat(8) command again should produce the following if the fan is not able to run at 4000 RPM:

                        Current  CritMax  WarnMax  WarnMin  CritMin  Unit
    [emcfan0]
               FAN 1:       N/A

The fan will be marked as having stalled:

    # emcfanctl /dev/emcfan0 fan 1 status
    Stalled: Yes
    Spin up failed: No
    Drive failed: No

The minimum expected RPM should be set to just below the lowest value that the fan is expected to run at. The minumum expected RPM effects the accuracy of the tachometers and should be as high as it can be made while still producing usable RPM values.

`# emcfanctl /dev/emcfan0 fan 1 min_expected rpm write 500`

Using the envstat(8) command again:

                        Current  CritMax  WarnMax  WarnMin  CritMin  Unit
    [emcfan0]
               FAN 1:      1176                                       RPM

The fan is not marked as having stalled:

    # emcfanctl /dev/emcfan0 fan 1 status
    Stalled: No
    Spin up failed: No
    Drive failed: No

# SEE ALSO

emcfan(4), iic(4), envstat(8)

# HISTORY

The `emcfanctl` utility first appeared in NetBSD 11.0.

# AUTHORS

The `emcfanctl` utility was written by Brad Spencer <brad@anduin.eldar.org>.

Feburary 20, 2025 | NetBSD 10.99