# openbmc/phosphor-fan-presence architecture

> Architecture diagram of the GitHub repository openbmc/phosphor-fan-presence, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openbmc/phosphor-fan-presence
- Repository: https://github.com/openbmc/phosphor-fan-presence

## Overview

This repository packages independent BMC thermal applications, not one shared runtime. The principal control workflow loads JSON configuration, evaluates D-Bus-backed groups and triggers, runs actions on fan zones, and drives fan targets. Separate applications detect fan presence, monitor fan function (including trust and power-off policies), monitor sensor alarms, and set inventory cooling type. Relationships not shown in sampled source are included only where the README documents them; other implementation details remain summarized at subsystem level.

Main entry points: [`monitor/fan.cpp`](https://github.com/openbmc/phosphor-fan-presence/blob/master/monitor/fan.cpp) (Fan function monitor), [`control/json/manager.cpp`](https://github.com/openbmc/phosphor-fan-presence/blob/master/control/json/manager.cpp) (Control manager), [`control/json/group.hpp`](https://github.com/openbmc/phosphor-fan-presence/blob/master/control/json/group.hpp) (D-Bus groups), [`control/json/event.hpp`](https://github.com/openbmc/phosphor-fan-presence/blob/master/control/json/event.hpp) (Triggers and events)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Fan control"]
  node_json_config["JSON config loader<br/>[json_config.hpp]"]
  node_control_manager["Control manager<br/>[manager.cpp]"]
  node_groups["D-Bus groups<br/>[group.hpp]"]
  node_triggers["Triggers and events<br/>[event.hpp]"]
  node_actions["Control actions<br/>[action.hpp]"]
  node_zones["Fan zones<br/>[zone.hpp]"]
  node_fan_targets["Fan targets<br/>[fan.hpp]"]
end

subgraph group_presence["Presence detection"]
  node_presence_detection["Presence detection<br/>[json_parser.cpp]"]
  node_presence_inputs["GPIO and tach inputs"]
  node_presence_updates["Presence property updates<br/>[fan.hpp]"]
end

subgraph group_monitor["Fan monitoring"]
  node_monitor_config["Monitor configuration<br/>[json_parser.cpp]"]
  node_fan_monitor["Fan function monitor<br/>[fan.cpp]"]
  node_tach_sensors["Tach sensors<br/>[tach_sensor.hpp]"]
  node_trust_groups["Sensor trust groups<br/>[trust_group.hpp]"]
  node_monitor_actions["Monitor actions"]
end

subgraph group_sensor["Sensor monitoring"]
  node_sensor_thresholds["Threshold alarm logger"]
  node_shutdown_monitor["Shutdown alarm monitor"]
end

subgraph group_cooling["Cooling type"]
  node_cooling_type["Cooling type setter<br/>[cooling_type.cpp]"]
end

node_operator(("Machine configuration"))
node_dbus["OpenBMC D-Bus"]

node_operator -->|"provides config"| node_json_config
node_json_config -->|"loads config"| node_control_manager
node_dbus -->|"supplies object state"| node_groups
node_control_manager -->|"uses groups"| node_groups
node_control_manager -->|"configures events"| node_triggers
node_groups -->|"selects events"| node_triggers
node_triggers -->|"runs actions"| node_actions
node_actions -->|"acts on zones"| node_zones
node_zones -->|"controls fans"| node_fan_targets
node_dbus -->|"updates inventory"| node_presence_detection
node_presence_inputs -->|"detects presence"| node_presence_detection
node_presence_detection -->|"sets Present"| node_presence_updates
node_operator -->|"provides config"| node_monitor_config
node_monitor_config -->|"configures monitoring"| node_fan_monitor
node_fan_monitor -->|"checks feedback"| node_tach_sensors
node_fan_monitor -->|"applies trust"| node_trust_groups
node_fan_monitor -->|"takes configured actions"| node_monitor_actions
node_dbus -->|"reads targets and state"| node_fan_monitor
node_dbus -->|"provides sensor values"| node_sensor_thresholds
node_sensor_thresholds -.->|"can trigger shutdown"| node_shutdown_monitor
node_dbus -->|"reads GPIO state"| node_cooling_type
node_cooling_type -->|"sets inventory properties"| node_dbus

click node_json_config "https://github.com/openbmc/phosphor-fan-presence/blob/master/json_config.hpp"
click node_control_manager "https://github.com/openbmc/phosphor-fan-presence/blob/master/control/json/manager.cpp"
click node_groups "https://github.com/openbmc/phosphor-fan-presence/blob/master/control/json/group.hpp"
click node_triggers "https://github.com/openbmc/phosphor-fan-presence/blob/master/control/json/event.hpp"
click node_actions "https://github.com/openbmc/phosphor-fan-presence/blob/master/control/json/actions/action.hpp"
click node_zones "https://github.com/openbmc/phosphor-fan-presence/blob/master/control/json/zone.hpp"
click node_fan_targets "https://github.com/openbmc/phosphor-fan-presence/blob/master/control/json/fan.hpp"
click node_presence_detection "https://github.com/openbmc/phosphor-fan-presence/blob/master/presence/json_parser.cpp"
click node_presence_inputs "https://github.com/openbmc/phosphor-fan-presence/tree/master/presence"
click node_presence_updates "https://github.com/openbmc/phosphor-fan-presence/blob/master/presence/fan.hpp"
click node_monitor_config "https://github.com/openbmc/phosphor-fan-presence/blob/master/monitor/json_parser.cpp"
click node_fan_monitor "https://github.com/openbmc/phosphor-fan-presence/blob/master/monitor/fan.cpp"
click node_tach_sensors "https://github.com/openbmc/phosphor-fan-presence/blob/master/monitor/tach_sensor.hpp"
click node_trust_groups "https://github.com/openbmc/phosphor-fan-presence/blob/master/monitor/trust_group.hpp"
click node_monitor_actions "https://github.com/openbmc/phosphor-fan-presence/blob/master/monitor/power_off_action.hpp"
click node_sensor_thresholds "https://github.com/openbmc/phosphor-fan-presence/blob/master/sensor-monitor/threshold_alarm_logger.cpp"
click node_shutdown_monitor "https://github.com/openbmc/phosphor-fan-presence/blob/master/sensor-monitor/shutdown_alarm_monitor.cpp"
click node_cooling_type "https://github.com/openbmc/phosphor-fan-presence/blob/master/cooling-type/cooling_type.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_json_config,node_control_manager,node_groups,node_triggers,node_actions,node_zones,node_fan_targets toneBlue
class node_presence_detection,node_presence_inputs,node_presence_updates toneAmber
class node_monitor_config,node_fan_monitor,node_tach_sensors,node_trust_groups,node_monitor_actions toneMint
class node_sensor_thresholds,node_shutdown_monitor toneRose
class node_cooling_type,node_operator,node_dbus toneIndigo
```

## Components

### Fan control

- [JSON config loader](https://github.com/openbmc/phosphor-fan-presence/blob/master/json_config.hpp): `json_config.hpp`
- [Control manager](https://github.com/openbmc/phosphor-fan-presence/blob/master/control/json/manager.cpp): `control/json/manager.cpp`
- [D-Bus groups](https://github.com/openbmc/phosphor-fan-presence/blob/master/control/json/group.hpp): `control/json/group.hpp`
- [Triggers and events](https://github.com/openbmc/phosphor-fan-presence/blob/master/control/json/event.hpp): `control/json/event.hpp`
- [Control actions](https://github.com/openbmc/phosphor-fan-presence/blob/master/control/json/actions/action.hpp): `control/json/actions/action.hpp`
- [Fan zones](https://github.com/openbmc/phosphor-fan-presence/blob/master/control/json/zone.hpp): `control/json/zone.hpp`
- [Fan targets](https://github.com/openbmc/phosphor-fan-presence/blob/master/control/json/fan.hpp): `control/json/fan.hpp`

### Presence detection

- [Presence detection](https://github.com/openbmc/phosphor-fan-presence/blob/master/presence/json_parser.cpp): `presence/json_parser.cpp`
- [GPIO and tach inputs](https://github.com/openbmc/phosphor-fan-presence/tree/master/presence): `presence`
- [Presence property updates](https://github.com/openbmc/phosphor-fan-presence/blob/master/presence/fan.hpp): `presence/fan.hpp`

### Fan monitoring

- [Monitor configuration](https://github.com/openbmc/phosphor-fan-presence/blob/master/monitor/json_parser.cpp): `monitor/json_parser.cpp`
- [Fan function monitor](https://github.com/openbmc/phosphor-fan-presence/blob/master/monitor/fan.cpp): `monitor/fan.cpp`
- [Tach sensors](https://github.com/openbmc/phosphor-fan-presence/blob/master/monitor/tach_sensor.hpp): `monitor/tach_sensor.hpp`
- [Sensor trust groups](https://github.com/openbmc/phosphor-fan-presence/blob/master/monitor/trust_group.hpp): `monitor/trust_group.hpp`
- [Monitor actions](https://github.com/openbmc/phosphor-fan-presence/blob/master/monitor/power_off_action.hpp): `monitor/power_off_action.hpp`

### Sensor monitoring

- [Threshold alarm logger](https://github.com/openbmc/phosphor-fan-presence/blob/master/sensor-monitor/threshold_alarm_logger.cpp): `sensor-monitor/threshold_alarm_logger.cpp`
- [Shutdown alarm monitor](https://github.com/openbmc/phosphor-fan-presence/blob/master/sensor-monitor/shutdown_alarm_monitor.cpp): `sensor-monitor/shutdown_alarm_monitor.cpp`

### Cooling type

- [Cooling type setter](https://github.com/openbmc/phosphor-fan-presence/blob/master/cooling-type/cooling_type.cpp): `cooling-type/cooling_type.cpp`

### Other components

- **Machine configuration**
- **OpenBMC D-Bus**

## Connections

- Machine configuration → JSON config loader: provides config
- JSON config loader → Control manager: loads config (evidence: `control/json/manager.cpp`)
- OpenBMC D-Bus → D-Bus groups: supplies object state
- Control manager → D-Bus groups: uses groups (evidence: `control/json/manager.cpp`)
- Control manager → Triggers and events: configures events (evidence: `control/json/manager.cpp`)
- D-Bus groups → Triggers and events: selects events (evidence: `control/json/group.hpp`)
- Triggers and events → Control actions: runs actions (evidence: `control/json/manager.cpp`)
- Control actions → Fan zones: acts on zones (evidence: `control/json/actions/action.hpp`)
- Fan zones → Fan targets: controls fans (evidence: `control/json/zone.hpp`)
- OpenBMC D-Bus → Presence detection: updates inventory
- GPIO and tach inputs → Presence detection: detects presence (evidence: `presence/json_parser.cpp`)
- Presence detection → Presence property updates: sets Present
- Machine configuration → Monitor configuration: provides config
- Monitor configuration → Fan function monitor: configures monitoring (evidence: `monitor/json_parser.cpp`)
- Fan function monitor → Tach sensors: checks feedback
- Fan function monitor → Sensor trust groups: applies trust
- Fan function monitor → Monitor actions: takes configured actions
- OpenBMC D-Bus → Fan function monitor: reads targets and state
- OpenBMC D-Bus → Threshold alarm logger: provides sensor values
- Threshold alarm logger → Shutdown alarm monitor: can trigger shutdown
- OpenBMC D-Bus → Cooling type setter: reads GPIO state
- Cooling type setter → OpenBMC D-Bus: sets inventory properties
