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