1# Repository Details
2
3## Table of Contents
4* [Overview](#overview)
5* [Building](#building)
6* [Contents](#contents)
7
8## Overview
9The phosphor-fan-presence repository provides a set of thermal related
10applications that control and monitor the cooling of a system using fans. Each
11application independently controls or monitors an area related to the thermal
12status of a system that uses fans as its primary cooling mechanism. Since each
13application independent in its functionality, they can individually be included
14in a BMC image at *configure* time to provide only the functionality needed by
15a user's machine.
16
17
18## Building
19By default, runtime JSON configuration file(s) are used for each application.
20The use of YAML configuration file(s) has been deprecated in favor of the JSON
21method.  Support for the use of YAML based configuration files may be removed
22once all applications completely support getting their configuration from JSON
23file(s) at runtime.
24
25The following applications are built by default:
26* [Fan Control](#fan-control)
27  * To disable from building, use the `-Dcontrol-service=disabled` meson option:
28  ```
29  meson build -Dcontrol-service=disabled
30  ```
31* [Fan Presence Detection](#fan-presence-detection)
32  * To disable from building, use the `-Dpresence-service=disabled` meson
33    option:
34  ```
35  meson build -Dpresence-service=disabled
36  ```
37* [Fan Monitoring](#fan-monitoring)
38  * To disable from building, use the `-Dmonitor-service=disabled` meson
39    option:
40  ```
41  meson build -Dmonitor-service=disabled
42  ```
43* [Sensor Monitoring](#sensor-monitoring)
44  * To disable from building, use the `-Dsensor-monitor-service=disabled` meson
45    option:
46  ```
47  meson build -Dsensor-monitor-service=disabled
48  ```
49
50The following applications must be enabled at *configure* time to be built:
51* [Cooling Type](#cooling-type)
52  * To enable building this, set the `-Dcooling-type-service=enable` meson
53    option:
54  ```
55  meson build -Dcooling-type-service=enabled
56  ```
57
58### YAML (Deprecated)
59The location of the YAML configuration file(s) are provided at
60*configure* time to each application thru environment variables. The default
61YAML configuration file(s) used are the examples found within each
62application's example directory. See each application below
63([Contents](#contents)) for more information on how to set their specific
64*configure* time options, including the location of the YAML configuration
65file(s).
66
67Meson defaults to JSON based runtime configuration, so to select the YAML
68configuration use the '-Djson-config=disabled' option when building:
69```
70    1. meson build -Djson-config=disabled
71    2. ninja -C build
72```
73
74### JSON
75See each application below ([Contents](#contents)) for more information on how
76to set their specific *configure* time options and details on how to configure
77each using JSON.
78
79As JSON based runtime configuration is the default option, no extra options
80are required to build:
81```
82    1. meson build
83    2. ninja -C build
84```
85**Note: Features/Restrictions of applications in this package that are only
86supported using the JSON based configuration are listed below:**
87#### Features
88* [Fan Presence Detection](#fan-presence-detection)
89  * Error logging for missing fans
90* [Fan Monitoring](#fan-monitoring)
91  * Error logging for nonfunctional fans
92  * System power off due to missing or nonfunctional fans
93* [Sensor Monitoring](#sensor-monitoring) - Only supports JSON
94
95
96## Contents
97
98### Fan Control
99Controls the fans based on a set of events that are configured using a group of
100D-Bus objects and one-or-more triggers that run a configured set of actions.
101These events are meant to be configured to handle all aspects of controlling
102the fans within a system. Fans are added to zones that then have events
103configured against the zone to control the fans based on the state of any sized
104group of D-Bus objects.
105
106* Available meson options:
107  * `control-persist-root-path` - Base location to persist zone property states
108  on the BMC
109    * Default = '/var/lib/phosphor-fan-presence/control'
110
111#### YAML (Deprecated)
112* Available meson options:
113  * `fan-def-yaml-file` - Build time fan configuration file
114    * Default = ['control/example/fans.yaml'](control/example/fans.yaml)
115  * `fan-zone-yaml-file` - Build time zone configuration file
116    * Default = ['control/example/zones.yaml'](control/example/zones.yaml)
117  * `fan-events-yaml-file` - Build time events configuration file
118    * Default = ['control/example/events.yaml'](control/example/events.yaml)
119  * `zone-conditions-yaml-file` Build time zone conditions configuration file
120    * Default = ['control/example/zone_conditions.yaml'](control/example/zone_conditions.yaml)
121
122[Example](control/example/)
123
124#### JSON
125[README](docs/control/README.md)
126
127---
128
129### Fan Presence Detection
130Monitors the presence state of fans using GPIOs, nonzero tach feedbacks, or a
131combination of both. This updates a configured location of a fan D-Bus object's
132`Present` property according to the state of the methods used to detect the
133fan's presence.
134
135* Available meson options:
136  * `num-presence-log-entries` - Maximum number of entries in the message log
137    * Default = 50
138
139#### YAML (Deprecated)
140* Available meson options:
141  * `presence-config` - Location of the config file
142    * Default = ['presence/example/example.yaml'](presence/example/example.yaml)
143
144Example: [example.yaml](presence/example/example.yaml)
145
146#### JSON
147[README](docs/presence/README.md)
148
149---
150
151### Fan Monitoring
152Monitors the functional state of fans by comparing the fan feedback speed
153against the current target, applying any configured adjustments to the target
154due to fan hardware properties. In addition to updating the configured location
155of a fan D-Bus object's `Functional` property in inventory, actions can be
156configured* to be taken based on the state of fans, i.e.) creating event logs or
157powering off the system.
158
159Another feature that can be configured is the ability to cancel the monitoring
160of a set of fans that may be necessary to workaround designs of the fan
161hardware and/or controller used.
162
163**Actions to be taken based on the state of fans is only available using a JSON
164 based configuration*
165
166* Available meson options:
167  * `num-monitor-log-entries` - Maximum number of entries in the message log
168    * Default = 75
169
170#### YAML (Deprecated)
171* Available meson options:
172  * `fan-monitor-yaml-file` - Location of the config file
173    * Default = ['monitor/example/monitor.yaml'](monitor/example/monitor.yaml)
174
175Example: [monitor.yaml](monitor/example/monitor.yaml)
176
177#### JSON
178[README](docs/monitor/README.md)
179
180---
181
182### Cooling Type
183Sets the `AirCooled` and `WaterCooled` property on the
184`xyz.openbmc_project.Inventory.Decorator.CoolingType` interface in inventory
185based on a given GPIO. No configuration files are used with this application as
186it is command line driven.
187
188---
189
190### Sensor Monitoring
191Takes actions, such as powering off the system, based on sensor thresholds and
192values.
193
194* Available meson options:
195  * `sensor-monitor-persist-root-path` - Base location to persist sensor
196  monitoring data
197    * Default = '/var/lib/phosphor-fan-presence/sensor-monitor'
198  * `sensor-monitor-hard-shutdown-delay` - Milliseconds to delay the alarm
199  hard shutdown
200    * Default = 23000
201  * `sensor-monitor-soft-shutdown-delay` - Milliseconds to delay the alarm
202  soft shutdown
203    * Default = 900000
204  * `use-host-power-state` - Use the host state for the power state as
205  opposed to the PGOOD state.
206
207[README](docs/sensor-monitor/README.md)
208
209---
210