1# Liquid Leak Detection 2 3Author: Jagpal Singh Gill <paligill@gmail.com> 4 5Created: July 26, 2024 6 7## Problem Description 8 9Liquid cooling is becoming a promising alternative to traditional air flow 10cooling for high performance computing in data center environments. However, 11this technique presents its own set of challenges, as liquids can be harmful to 12electronic components. Therefore, it is crucial for any system that uses liquid 13cooling to have a mechanism for detecting and reporting leaks so that 14remediation actions can be taken. Currently, there is no service available in 15openBMC to handle this task. 16 17## Background and References 18 19In this document, a leak is considered to be an entity with digital (present or 20not-present) value. Currently, openBMC has a framework for sensors, but it is 21primarily designed for numerical readings rather than detectors with digital 22values. The 23[phosphor-gpio-monitor](https://github.com/openbmc/phosphor-gpio-monitor) is too 24generic in its design and does not meet most of the requirements. 25 26## Requirements 27 281. Able to identify leak presence for GPIO-based detectors and generate 29 corresponding redfish events. 302. Able to classify leaks events according to their severity levels based on 31 certain attributes. 32 - For example, the physical location of detectors can be used to determine 33 the severity level of a leak. A leak may be considered minor if it is 34 contained within a tray, but its severity level increases as it spreads 35 into a drip pan. 363. Capable of performing actions based on leak classification, which can be 37 optionally delegated to another component. 384. Capable of generating a D-Bus interface that adheres to 39 [Redfish Leak Detection](https://redfish.dmtf.org/schemas/v1/LeakDetection.v1_0_1.json) 40 standards, allowing for the exposure of leak detection status to clients. 41 42## Proposed Design 43 44### Dbus interfaces 45 46The DBus Interface for leak detection will consist of following - 47 48| Interface Name | New/Existing | Purpose/Updates | 49| :------------------------------------------- | :----------: | :----------------------------: | 50| xyz.openbmc_project.State.Leak.DetectorGroup | New | Implements Leak Detector Group | 51| xyz.openbmc_project.State.Leak.Detector | New | Implements Leak Detector | 52 53Refer to 54[patch](https://gerrit.openbmc.org/c/openbmc/phosphor-dbus-interfaces/+/73151) 55for related D-Bus changes. 56 57### BMCWeb 58 59This design involves implementing following Redfish schemas and associated 60properties in BMCWeb. 61 62| Redfish Schema | Properties | 63| :--------------: | :---------------------------------------------------------------------: | 64| ThermalSubsystem | LeakDetection | 65| LeakDetection | Name, Status, LeakDetectors, LeakDetectorGroups | 66| | LeakDetectorGroup: GroupName, Detectors, Detectors\@odata.count, Status | 67| LeakDetector | Name, DetectorState, Status | 68 69NOTE: The ThermalSubsystem is required because it contains the LeakDetection 70endpoint. 71 72### Liquid Leak Detector 73 74```mermaid 75--- 76config: 77 layout: fixed 78--- 79flowchart LR 80 A["EntityManager"] -- Detector Configuration 81(via D-Bus) --> B["Leak Detection Manager"] 82 B -- Creates --> C["Leak Detector Group"] & F["Leak Detectors"] 83 C -- Creates Interface --> E["xyz.openbmc_project.State.Leak.DetectorGroup at /xyz/openbmc_project/state/leak/detectorgroup/<GroupX>"] 84 F -- Creates Interface --> G["xyz.openbmc_project.State.Leak.Detector at /xyz/openbmc_project/state/leak/detector/<DetectorY>"] 85 C -. contains .- F 86 F@{ shape: procs} 87``` 88 89#### Entity Manager Configuration 90 91##### Json Schema 92 93For information on the configuration schema for leak detectors, please 94[refer](https://gerrit.openbmc.org/c/openbmc/entity-manager/+/75734). 95 96##### Configuration Example 97 98An example of entity manager configuration for leak detector is as under - 99 100```json 101"Exposes": [ 102... 103 { 104 "Type": "GPIOLeakDetector", 105 "Name": "ManifoldFrontDetector", 106 "SubType": "LeakSensingCable", 107 "PinName": "DETECTOR1_GPIO", 108 "Polarity": "ActiveLow", 109 "Level": "Critical" 110} 111... 112] 113``` 114 115#### LeakDetection Manager 116 117The LeakDetection Manager is responsible for processing input configuration 118objects from the Entity Manager via DBus. Based on related interface signals, it 119creates or deletes the corresponding detector and detector group D-Bus 120interfaces. Additionally, it monitors detector GPIO events and triggers systemd 121targets based on the leak level if a leak is detected. It also raises or 122resolves the appropriate leak-related alerts. This fulfills requirements# 1 123and 3. 124 125### Error Reporting 126 127A 128[leak detection](https://gerrit.openbmc.org/c/openbmc/phosphor-dbus-interfaces/+/73707) 129definition is proposed for events through Redfish based on 130[event logging design](https://github.com/openbmc/docs/blob/master/designs/event-logging.md). 131 132#### Leak Severity 133 134The entity manager configuration specifies the severity level for a leak 135detector. When the corresponding detector detects a leak, the LeakDetection 136Manager generates an event message with the appropriate severity level as 137defined in the configuration. This fulfills requirement# 2. 138 139## Alternatives Considered 140 141### phosphor-gpio-monitor 142 143The current design of the phosphor-gpio-monitor is too generic and does not meet 144most of the requirements, particularly Requirement #2 and #4. Any changes to the 145phosphor-gpio-monitor to add these requirements would result in a monolithic 146daemon that would need to be extended for every other such feature. Currently, 147the phosphor-gpio-monitor performs generic tasks in a simple manner and does so 148effectively, so it's better suited for that. 149 150## Impacts 151 152### API Impacts 153 154- A new D-Bus interface for leak detection is being proposed as part of this 155 design. This would require implementation in the BMCWeb. 156 157### Performance Impacts 158 159The design may cause a minor reduction in system performance due to the need for 160processing leak detector GPIO events, but the impact is negligible. 161 162### Organizational 163 164- Does this repository require a new repository? No. 165- Who will be the initial maintainer(s) of this repository? NA 166- Which repositories are expected to be modified to execute this design? BMCWeb, 167 dbus-sensors, phosphor-dbus-interfaces 168- Make a list, and add listed repository maintainers to the gerrit review. 169 170## Testing 171 172### Unit Testing 173 174All the functional testing of the reference implementation will be performed 175using GTest. 176 177### Integration Testing 178 179Integration testing for generating Redfish events will be conducted using the 180GPIO sim tool to simulate leak detection GPIOs, which can be triggered as 181needed. 182