# Fan Control Configuration File

## Table of Contents

- [Overview](#overview)
- [Data Format](#data-format)
- [System Config Location](#system-config-location)
- [Contents](#contents)
- [Validation](#validation)
- [Firmware Updates](#firmware-updates)
- [Loading and Reloading](#loading-and-reloading)
- [Debug](#debug)

## Overview

The `phosphor-fan-control` application is comprised of as set of configuration
files (config files) that constructs the algorithm in which fans are controlled
within a machine.

## Data Format

The config file is written using the
[JSON (JavaScript Object Notation)](https://www.json.org/) data format and can
be created using a text editor.

## System Config Location

The config file names are:

- `manager.json`
- `profiles.json`
- `fans.json`
- `zones.json`
- `groups.json`
- `events.json`

### Supported Directory

`/usr/share/phosphor-fan-presence/control/`

The supported version of the config files are installed under this read-only
directory location as part of the firmware image install. This is where the
config files will be loaded from when no corresponding override config file
exists.

#### Default Location

Where a single set of config files for 1-or-more system types can be used, the
config files can be located at the base of the supported directory.

i.e.) `/usr/share/phosphor-fan-presence/control/manager.json`
`/usr/share/phosphor-fan-presence/control/profiles.json`
`/usr/share/phosphor-fan-presence/control/fans.json`
`/usr/share/phosphor-fan-presence/control/zones.json`
`/usr/share/phosphor-fan-presence/control/groups.json`
`/usr/share/phosphor-fan-presence/control/events.json`

#### Compatible System Type Location

The config files location can also be based on a system type. This is necessary
where more than one type of machine is supported in a single BMC firmware image
and those system types can not share any one common config file.

A system type sub-directory can be obtained from the
`Inventory.Decorator.Compatible` D-Bus interface's `Names` property. The
property holds a list of one or more compatible system types.

Example:

- `com.ampere.Hardware.Chassis.Model.MtJade`
- `com.ampere.Hardware.Chassis.Model.MtMitchell`

The `phosphor-fan-control` application then traverses the supported directory,
appending each compatible system type entry as a sub-directory on each config
file until it is found.

Example:

1. `/usr/share/phosphor-fan-presence/control/com.ampere.Hardware.Chassis.Model.MtJade/`
   - (directory/config file does not exist)
2. `/usr/share/phosphor-fan-presence/control/com.ampere.Hardware.Chassis.Model.MtMitchell/events.json`
   - (config file found)

If any required config file is not found and the machine is powered on, an error
is logged and `phosphor-fan-control` application terminates preventing the
machine from successfully powering on.

### Override Directory

`/etc/phosphor-fan-presence/control/`

A different version of each of the config files can be loaded by placing it into
this writable directory location. This avoids the need to build and install a
new firmware image on the BMC when changing any part of the configuration, such
as for testing purposes.

The override directory may not exist on the BMC, therefore to be able to use any
number of overriding config files it must be created using the following
command:

`mkdir -p /etc/phosphor-fan-presence/control`

### Search Order

The `phosphor-fan-control` application will search for each config file at the
directory locations in the following order:

1. Override directory
2. Supported directory
   - Default location
   - Compatible System Type location

## Contents

### Structure

#### fans.json

This file consists of an array of fan objects representing the fan FRUs in the
system.

```json
[
    {
        "name": "fan0",
        "zone": "0",
        "sensors": ["fan0_0"],
        "target_interface": "xyz.openbmc_project.Control.FanSpeed"
    }
    ...
]
```

[Syntax](fans.md)

#### zones.json

This file contains parameters specific to the zone.

```json
[
    {
        "name": "0",
        "poweron_target": 18000,
        "default_floor": 18000,
        "increase_delay": 5,
        "decrease_interval": 30
    },
    ...
]
```

[Syntax](zones.md)

#### groups.json

This file defines the groups that events.json will use in its actions. Groups
consist of one or more D-Bus object paths and a name.

```json
[
   {
     "name": "fan inventory",
     "members": [
       "/xyz/openbmc_project/inventory/system/chassis/motherboard/fan0",
       "/xyz/openbmc_project/inventory/system/chassis/motherboard/fan1",
       "/xyz/openbmc_project/inventory/system/chassis/motherboard/fan2",
       "/xyz/openbmc_project/inventory/system/chassis/motherboard/fan3",
       "/xyz/openbmc_project/inventory/system/chassis/motherboard/fan4",
       "/xyz/openbmc_project/inventory/system/chassis/motherboard/fan5"
     ]
   }
 ...
]
```

[Syntax](groups.md)

#### events.json

This file contains the fan control events, where each event can contain groups,
trigger, and actions.

```json
{
  [
    {
      "name": ...
      "groups": [
        {
           ...
        },
        ...
      ],

      "triggers": [
        {
            ...
        },
        ...
      ],

      "actions": [
        {
          ...
        },
        ...
      ],
      ...
    },
    ...
  ]
}
```

[Syntax](events.md)

### Comments

The JSON data format does not support comments. However, the library used by
code to parse the JSON does support '//' as a comment:

```json
// This is a comment.
{
   ...
}
```

Alternatively, a comment attribute can be used:

```json
{
  "comment": "This is a comment."
  ...
}
```

Fans can be queried and controlled manually using the fanctl utility. Full
documentation can be found at
<https://github.com/openbmc/phosphor-fan-presence/blob/master/docs/control/fanctl/README.md>

## Validation

TBD

## Firmware Updates

When a new firmware image is installed on the BMC, it will update the config
file in the standard directory.

The override directory will **not** be modified by a firmware update. If a
config file exists in the override directory, it will continue to be used as the
fan presence configuration instead of the config file located under the
appropriate location within the supported directory.

## Loading and Reloading

The config files are loaded when the `phosphor-fan-control` application starts.

To force the application to reload the config files, use the following command
on the BMC:

`systemctl kill -s HUP phosphor-fan-control@0.service`

To confirm which config files were loaded, use the following command on the BMC:

`journalctl -u phosphor-fan-control@0.service | grep Loading`

## Debug

Fan control maintains internal data structures that can be be dumped at runtime.
[Details](debug.md).