1 /** 2 * Copyright © 2022 IBM Corporation 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 #pragma once 17 18 #include "../zone.hpp" 19 #include "action.hpp" 20 #include "group.hpp" 21 22 #include <nlohmann/json.hpp> 23 24 namespace phosphor::fan::control::json 25 { 26 27 using json = nlohmann::json; 28 29 /** 30 * @class MappedFloor - Action to set a fan floor based on ranges of 31 * multiple sensor values. 32 * For example, consider the following config: 33 * 34 * { 35 * "name": "mapped_floor", 36 * "key_group": "ambient_temp", 37 * "default_floor": 2000, 38 * "fan_floors": [ 39 * { 40 * "key": 27, 41 * "floor_offset_parameter": "floor_27_offset", 42 * "default_floor": 3000, 43 * "floors": [ 44 * { 45 * "group": "altitude", 46 * "floors": [ 47 * { 48 * "value": 5000, 49 * "floor": 4500 50 * } 51 * ] 52 * }, 53 * { 54 * "group": "power_mode", 55 * "floors": [ 56 * { 57 * "value": "MaximumPerformance", 58 * "floor": 5000 59 * } 60 * ] 61 * } 62 * ] 63 * } 64 * ] 65 * } 66 * 67 * When it runs, it will: 68 * 69 * 1. Evaluate the key_group 70 * - Find the max D-Bus property value (if numeric) of the member properties 71 * in this group. 72 * - Check it against each 'key' value in the fan_floor entries until 73 * the key_group property value < key value, so: 74 * max ambient temp < 27. 75 * - If the above check passes, the rest of that entry will be evaluated 76 * and then the action will be done. 77 * 78 * 2. Evaluate the group values in each floors array entry for this key value. 79 * - Find the max D-Bus property value (if numeric) of the member properties 80 * of this group - in this case 'altitude'. 81 * - Depending on the data type of that group, compare to the 'value' entry: 82 * - If numeric, check if the group's value is <= the 'value' one 83 * - Otherwise, check if it is == 84 * - If that passes, save the value from the 'floor' entry and continue to 85 * the next entry in the floors array, which, if present, would specify 86 * another group to check. In this case, 'power_mode'. Repeat the above 87 * step. 88 * - After all the group compares are done, choose the largest floor value 89 * to set the fan floor to, but first apply the floor offset provided 90 * by the parameter in the 'floor_offset_parameter' field, if it present. 91 * - If any group check results doesn't end in a match being found, then 92 * the default floor will be set. 93 * 94 * There are up to 3 default value values that may be used when a regular 95 * floor value can't be calculated: 96 * 1. Optional default floor at the key group level 97 * - Chosen when a floor wasn't found in any floor groups 98 * 2. Optional default floor at the action level 99 * - Chosen when there isn't a key table found for the key value, 100 * or 1. above occurred but that default floor wasn't supplied. 101 * 3. The default floor in the zone config 102 * - Chosen when when 2. would be used, but it wasn't supplied 103 * 104 * Other notes: 105 * - If a group has multiple members, they must be numeric or else 106 * the code will throw an exception. 107 * 108 * - The group inside the floors array can also be a Manager parameter, so that 109 * this action can operate on a parameter value set by another action. 110 * 111 * So instead of 112 * "group": "altitude", 113 * it can be: 114 * "parameter": "some_parameter" 115 */ 116 117 class MappedFloor : public ActionBase, public ActionRegister<MappedFloor> 118 { 119 public: 120 /* Name of this action */ 121 static constexpr auto name = "mapped_floor"; 122 123 MappedFloor() = delete; 124 MappedFloor(const MappedFloor&) = delete; 125 MappedFloor(MappedFloor&&) = delete; 126 MappedFloor& operator=(const MappedFloor&) = delete; 127 MappedFloor& operator=(MappedFloor&&) = delete; 128 ~MappedFloor() = default; 129 130 /** 131 * @brief Parse the JSON to set the members 132 * 133 * @param[in] jsonObj - JSON configuration of this action 134 * @param[in] groups - Groups of dbus objects the action uses 135 */ 136 MappedFloor(const json& jsonObj, const std::vector<Group>& groups); 137 138 /** 139 * @brief Run the action. See description above. 140 * 141 * @param[in] zone - Zone to run the action on 142 */ 143 void run(Zone& zone) override; 144 145 private: 146 /** 147 * @brief Parse and set the key group 148 * 149 * @param[in] jsonObj - JSON object for the action 150 */ 151 void setKeyGroup(const json& jsonObj); 152 153 /** 154 * @brief Parse and set the default floor value 155 * 156 * @param[in] jsonObj - JSON object for the action 157 */ 158 void setDefaultFloor(const json& jsonObj); 159 160 /** 161 * @brief Parses and sets the floor group data members 162 * 163 * @param[in] jsonObj - JSON object for the action 164 */ 165 void setFloorTable(const json& jsonObj); 166 167 /** 168 * @brief Applies the offset in offsetParameter to the 169 * value passed in. 170 * 171 * If offsetParameter is empty then no offset will be 172 * applied. 173 * 174 * Note: The offset may be negative. 175 * 176 * @param[in] floor - The floor to apply offset to 177 * @param[in] offsetParameter - The floor offset parameter 178 * 179 * @return uint64_t - The new floor value 180 */ 181 uint64_t applyFloorOffset(uint64_t floor, 182 const std::string& offsetParameter) const; 183 184 /** 185 * @brief Determines the maximum value of the property specified 186 * for the group of all members in the group. 187 * 188 * If not numeric, and more than one member, will throw an exception. 189 * Converts numeric values to doubles so they can be compared later. 190 * 191 * If cannot get at least one valid value, returns std::nullopt. 192 * 193 * @param[in] group - The group to get the max value of 194 * 195 * @return optional<PropertyVariantType> - The value, or std::nullopt 196 */ 197 std::optional<PropertyVariantType> getMaxGroupValue(const Group& group); 198 199 /** 200 * @brief Returns a pointer to the group object specified 201 * 202 * Throws ActionParseError if no group found 203 * 204 * @param[in] name - The group name 205 * 206 * @return const Group* - Pointer to the group 207 */ 208 const Group* getGroup(const std::string& name); 209 210 /* Key group pointer */ 211 const Group* _keyGroup; 212 213 /* Optional default floor value for the action */ 214 std::optional<uint64_t> _defaultFloor; 215 216 using FloorEntry = std::tuple<PropertyVariantType, uint64_t>; 217 218 struct FloorGroup 219 { 220 std::variant<const Group*, std::string> groupOrParameter; 221 std::vector<FloorEntry> floorEntries; 222 }; 223 224 struct FanFloors 225 { 226 PropertyVariantType keyValue; 227 std::string offsetParameter; 228 std::optional<uint64_t> defaultFloor; 229 std::vector<FloorGroup> floorGroups; 230 }; 231 232 /* The fan floors action data, loaded from JSON */ 233 std::vector<FanFloors> _fanFloors; 234 }; 235 236 } // namespace phosphor::fan::control::json 237