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, build time YAML configuration file(s) are used for each
20application. The use of YAML configuration file(s) has been deprecated in favor
21of using runtime JSON configuration file(s). Support for the use of YAML based
22configuration files will be removed once all applications completely support
23getting their configuration from JSON file(s) at runtime.
24
25The following applications are built by default:
26* [Fan Control](#fan-control)
27  * To disable from building, provide the `--disable-control` flag at
28  *configure* time:
29  ```
30  ./configure ${CONFIGURE_FLAGS} --disable-control
31  ```
32* [Fan Presence Detection](#fan-presence-detection)
33  * To disable from building, provide the `--disable-presence` flag at
34  *configure* time:
35  ```
36  ./configure ${CONFIGURE_FLAGS} --disable-presence
37  ```
38* [Fan Monitoring](#fan-monitoring)
39  * To disable from building, provide the `--disable-monitor` flag at
40  *configure* time:
41  ```
42  ./configure ${CONFIGURE_FLAGS} --disable-monitor
43  ```
44* [Cooling Type](#cooling-type)
45  * To disable from building, provide the `--disable-cooling-type` flag at
46  *configure* time:
47  ```
48  ./configure ${CONFIGURE_FLAGS} --disable-cooling-type
49  ```
50
51The following applications must be enabled at *configure* time to be built:
52* [Sensor Monitoring](#sensor-monitoring)
53  * To enable building this, provide the `--enable-sensor-monitor` flag at
54  *configure* time:
55  ```
56  ./configure ${CONFIGURE_FLAGS} --enable-sensor-monitor
57  ```
58
59To clean the repository run `./bootstrap.sh clean`.
60
61### YAML (Deprecated)
62The location of the YAML configuration file(s) are provided at
63*configure* time to each application thru environment variables. The default
64YAML configuration file(s) used are the examples found within each
65application's example directory. See each application below
66([Contents](#contents)) for more information on how to set their specific
67*configure* time options, including the location of the YAML configuration
68file(s).
69
70To simply build this package to use YAML, without changing the configurations
71of each application for a specific system, do the following steps:
72```
73    1. ./bootstrap.sh
74    2. ./configure ${CONFIGURE_FLAGS}
75    3. make
76```
77
78### JSON
79See each application below ([Contents](#contents)) for more information on how
80to set their specific *configure* time options and details on how to configure
81each using JSON.
82
83To build this package to use JSON based runtime configuration for all
84applications, follow these steps and provide the `--enable-json` flag at
85*configure* time:
86```
87    1. ./bootstrap.sh
88    2. ./configure ${CONFIGURE_FLAGS} --enable-json
89    3. make
90```
91**Note: Features/Restrictions of applications in this package that are only
92supported using the JSON based configuration are listed below:**
93#### Features
94* [Fan Presence Detection](#fan-presence-detection)
95  * Error logging for missing fans
96* [Fan Monitoring](#fan-monitoring)
97  * Error logging for nonfunctional fans
98  * System power off due to missing or nonfunctional fans
99* [Sensor Monitoring](#sensor-monitoring) - Only supports JSON
100
101#### Restrictions
102* [Fan Control](#fan-control)
103  * Currently only supports setting fans to the configured `full_speed`.
104  If you require more than just setting fans to the configured `full_speed`, it
105  is recommended to continue using YAML based configurations by providing the
106  `--disable-json-control` flag at *configure* time.
107
108
109## Contents
110
111### Fan Control
112Controls the fans based on a set of events that are configured using a group of
113D-Bus objects and one-or-more triggers that run a configured set of actions.
114These events are meant to be configured to handle all aspects of controlling
115the fans within a system. Fans are added to zones that then have events
116configured against the zone to control the fans based on the state of any sized
117group of D-Bus objects.
118
119* *Configure* time environment variables:
120  * `CONTROL_BUSNAME` - Application's D-Bus busname to own
121    * Default = 'xyz.openbmc_project.Control.Thermal'
122  * `CONTROL_OBJPATH` - Application's root D-Bus object path
123    * Default = '/xyz/openbmc_project/control/thermal'
124  * `CONTROL_PERSIST_ROOT_PATH` - Base location to persist zone property states
125  on the BMC
126    * Default = '/var/lib/phosphor-fan-presence/control'
127
128#### YAML (Deprecated)
129* *Configure* time environment variables:
130  * `FAN_DEF_YAML_FILE` - Build time fan configuration file
131    * Default = ['control/example/fans.yaml'](control/example/fans.yaml)
132  * `FAN_ZONE_YAML_FILE` - Build time zone configuration file
133    * Default = ['control/example/zones.yaml'](control/example/zones.yaml)
134  * `ZONE_EVENTS_YAML_FILE` - Build time events configuration file
135    * Default = ['control/example/events.yaml'](control/example/events.yaml)
136  * `ZONE_CONDITIONS_YAML_FILE` Build time zone conditions configuration file
137    * Default = ['control/example/zone_conditions.yaml'](control/example/zone_conditions.yaml)
138
139[Example](control/example/)
140
141#### JSON
142[README](docs/control/README.md)
143
144---
145
146### Fan Presence Detection
147Monitors the presence state of fans using GPIOs, nonzero tach feedbacks, or a
148combination of both. This updates a configured location of a fan D-Bus object's
149`Present` property according to the state of the methods used to detect the
150fan's presence.
151
152* *Configure* time environment variables:
153  * `NUM_PRESENCE_LOG_ENTRIES` - Maximum number of entries in the message log
154    * Default = 50
155
156#### YAML (Deprecated)
157* *Configure* time environment variables:
158  * `PRESENCE_CONFIG` - Location of the config file
159    * Default = ['presence/example/example.yaml'](presence/example/example.yaml)
160
161Example: [example.yaml](presence/example/example.yaml)
162
163#### JSON
164[README](docs/presence/README.md)
165
166---
167
168### Fan Monitoring
169Monitors the functional state of fans by comparing the fan feedback speed
170against the current target, applying any configured adjustments to the target
171due to fan hardware properties. In addition to updating the configured location
172of a fan D-Bus object's `Functional` property in inventory, actions can be
173configured* to be taken based on the state of fans, i.e.) creating event logs or
174powering off the system.
175
176Another feature that can be configured is the ability to cancel the monitoring
177of a set of fans that may be necessary to workaround designs of the fan
178hardware and/or controller used.
179
180**Actions to be taken based on the state of fans is only available using a JSON
181 based configuration*
182
183* *Configure* time environment variables:
184  * `NUM_MONITOR_LOG_ENTRIES` - Maximum number of entries in the message log
185    * Default = 75
186  * `THERMAL_ALERT_BUSNAME` - Application's D-Bus busname to own
187    * Default = 'xyz.openbmc_project.Thermal.Alert'
188  * `THERMAL_ALERT_OBJPATH` - Application's root D-Bus object path
189    * Default = '/xyz/openbmc_project/alerts/thermal_fault_alert'
190
191#### YAML (Deprecated)
192* *Configure* time environment variables:
193  * `FAN_MONITOR_YAML_FILE` - Location of the config file
194    * Default = ['monitor/example/monitor.yaml'](monitor/example/monitor.yaml)
195
196Example: [monitor.yaml](monitor/example/monitor.yaml)
197
198#### JSON
199[README](docs/monitor/README.md)
200
201---
202
203### Cooling Type
204Sets the `AirCooled` and `WaterCooled` property on the
205`xyz.openbmc_project.Inventory.Decorator.CoolingType` interface in inventory
206based on a given GPIO. No configuration files are used with this application as
207it is command line driven.
208
209---
210
211### Sensor Monitoring
212Takes actions, such as powering off the system, based on sensor thresholds and
213values.
214
215* *Configure* time environment variables:
216  * `SENSOR_MONITOR_PERSIST_ROOT_PATH` - Base location to persist sensor
217  monitoring data
218    * Default = '/var/lib/phosphor-fan-presence/sensor-monitor'
219  * `SHUTDOWN_ALARM_HARD_SHUTDOWN_DELAY_MS` - Milliseconds to delay the alarm
220  hard shutdown
221    * Default = 23000
222  * `SHUTDOWN_ALARM_SOFT_SHUTDOWN_DELAY_MS` - Milliseconds to delay the alarm
223  soft shutdown
224    * Default = 900000
225
226[README](docs/sensor-monitor/README.md)
227
228---
229