docs/designs/external-sensor.md

1 # ExternalSensor in dbus-sensors
11 In OpenBMC, the _dbus-sensors_[^2] package contains a suite of sensor daemons.
18 There are 10 existing sensor daemons in _dbus-sensors_. Why add another sensor
21 - Most of the existing sensor daemons are tied to one particular physical
22   quantity they are measuring, such as temperature, and are hardcoded as such.
23   An externally-updated sensor has no such limitation, and should be flexible
26 - Essentially all of the existing sensor daemons obtain the sensor values they
27   publish to D-Bus by reading from local hardware (typically by reading from
30   pushed in from an external source. Although there is some debugging
31   functionality to add this feature to other sensor daemons[^25], it is not the
34 - Even if the debugging functionality of an existing daemon were to be used, the
35   daemon would still need a valid configuration tied to recognized hardware, as
36   detected by _entity-manager_[^4], in order for the daemon to properly
39 - For the same reason it is desirable for existing sensor daemons to detect and
40   properly indicate failures of their underlying hardware, it is desirable for
42   from their external source. This is a new feature, and does not cleanly fit
43   into the architecture of any existing sensor daemon, thus a new daemon is the
46 For these reasons, _ExternalSensor_ has been added[^5], as the eleventh sensor
47 daemon in _dbus-sensors_.
51 After some discussion, a proof-of-concept _HostSensor_[^6] was published. This
55 the simplest existing sensor daemons, _HwmonTempSensor_[^7], as references to
58 As written, after validating parameters during initialization, there is
59 essentially no work for _ExternalSensor_ to do. The main loop is mostly idle,
60 remaining blocked in the Boost ASIO[^8] library, handling D-Bus requests as they
62 which already contains the D-Bus hooks necessary to receive values from the
65 An example external source is the IPMI service[^10], receiving values from the
66 host via the IPMI "Set Sensor Reading" command[^11]. _ExternalSensor_ is
67 intended to be source-agnostic, so it does not matter if this is IPMI or
68 Redfish[^12] or something else in the future, as long as they are received
69 similarly over D-Bus.
73 The timeout feature is the primary feature which distinguishes _ExternalSensor_
75 external source is expected to continue to provide timely updates. Each update
76 will be properly published onto D-Bus, in the usual way done by all sensor
77 daemons, as a floating-point value.
79 A timer is used, the same Boost ASIO[^13] timer mechanism used by other sensor
80 daemons to poll their hardware, but in this case, is used to manage how long it
82 sensor value will be deemed stale, and will be replaced with floating-point
87 The advantage of floating-point _NaN_ is that it is a drop-in replacement for
88 the valid floating-point value of the sensor. A subtle difference of the earlier
89 OpenBMC sensor "Value" schema change, from integer to floating-point, is that
90 the field is essentially now nullable. Instead of having to arbitrarily choose
91 an arbitrary integer value to indicate "not valid", such as -1 or 9999 or
92 whatever, floating-point explicitly has _NaN_ to indicate this. So, there is no
93 possibility of confusion that this will be mistaken for a valid sensor value, as
94 _NaN_ is literally _not a number_, and thus can not be misparsed as a valid
101 more, adding a second field might require a second D-Bus message to update, and
102 D-Bus messages are computationally expensive[^17] and should be used sparingly.
104 to frequent D-Bus traffic and thus should be kept as minimal as practical. And
107 scope of what is needed for _ExternalSensor_.
112 way[^18] that is done for use with other sensor daemons, namely, a JSON
113 dictionary that is an element of the "Exposes" array within a JSON configuration
114 file to be read by _entity-manager_. In that JSON dictionary, the valid names
115 are listed below. All of these are mandatory parameters, unless mentioned as
116 optional. For fields listed as "Numeric" below, this means that it can be either
117 integer or valid floating-point.
119 - "Name": String. The sensor name, which this sensor will be known as. A
120   mandatory component of the `entity-manager` configuration, and the resulting
121   D-Bus object path.
123 - "Units": String. This parameter is unique to _ExternalSensor_. As
124   _ExternalSensor_ is not tied to any particular physical hardware, it can
127   mandatory component of the D-Bus object path.
129 - "MinValue": Numeric. The minimum valid value for this sensor. Although not
130   used by _ExternalSensor_ directly, it is a valuable hint for services such as
132   to scale their reporting range accurately. As _ExternalSensor_ is not tied to
133   one particular physical quantity, there is no suitable default value for
134   minimum and maximum. Thus, unlike other sensor daemons where this parameter is
135   optional, in _ExternalSensor_ it is mandatory.
137 - "MaxValue": Numeric. The maximum valid value for this sensor. It is treated
140 - "Timeout": Numeric. This parameter is unique to _ExternalSensor_. It is the
142   received over D-Bus from the external source, this sensor will be deemed
143   stale. The value of this sensor will be replaced with floating-point _NaN_, as
144   described above. This field is optional. If not given, the timeout feature
147 - "Type": String. Must be exactly "ExternalSensor". This string is used by
148   _ExternalSensor_ to obtain configuration information from _entity-manager_
149   during initialization. This string is what differentiates JSON stanzas
151   _dbus-sensors_ sensor daemons.
153 - "Thresholds": JSON dictionary. This field is optional. It is passed through to
155   daemons. Other than that, it is not used by _ExternalSensor_.
157 - "PowerState": String. This field is optional. Similarly to "Thresholds", it is
160 Here is an example. The sensor created by this stanza will form this object
167             "MinValue": -16.0,
174 There can be multiple _ExternalSensor_ sensors in the configuration. There is no
175 set limit on the number of sensors, except what is supported by a service such
176 as IPMI.
180 As it stands now, _ExternalSensor_ is up and running[^20]. However, the timeout
185 IPMI sensors, however, expected usage of almost all external sensor updates is a
186 one-shot adjustment (for example, somebody wishes to change a voltage regulator
193 not dependent on IPMI as the only source of external updates.
197 D-Bus setter hook to be customized. This feature was straightforward to
200 _ExternalSensor_, we want to recognize all updates received, even duplicates, as
202 timeout feature. However, it is still important to avoid needlessly sending the
203 D-Bus _PropertiesChanged_ event for duplicate readings.
205 The timeout value was originally a compiled-in constant. If _ExternalSensor_ is
206 to succeed as a general-purpose tool, this must be configurable. It was
208 timeout value, as shown in "Parameters" above.
217 [^2]: https://github.com/openbmc/dbus-sensors/blob/master/README.md
221 [^4]: https://github.com/openbmc/entity-manager/blob/master/README.md
223 [^5]: https://gerrit.openbmc.org/c/openbmc/dbus-sensors/+/36206
225 [^6]: https://gerrit.openbmc.org/c/openbmc/dbus-sensors/+/35476
227 [^7]: https://github.com/openbmc/dbus-sensors/blob/master/src/HwmonTempMain.cpp
229 [^8]: https://think-async.com/Asio/
231 [^9]: https://github.com/openbmc/dbus-sensors/blob/master/include/sensor.hpp
234     https://github.com/openbmc/docs/blob/master/architecture/ipmi-architecture.md
237 …w.intel.com/content/www/us/en/servers/ipmi/ipmi-intelligent-platform-mgt-interface-spec-2nd-gen-v2…
244 [^14]: https://anniecherkaev.com/the-secret-life-of-nan
247 …https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Sensor/Va…
254     https://github.com/openbmc/entity-manager/blob/master/docs/my_first_sensors.md
256 [^19]: https://github.com/openbmc/dbus-sensors/blob/master/src/SensorPaths.cpp
258 [^20]: https://gerrit.openbmc.org/c/openbmc/dbus-sensors/+/36206
260 [^21]: https://gerrit.openbmc.org/c/openbmc/dbus-sensors/+/41398
262 [^22]: https://gerrit.openbmc.org/c/openbmc/dbus-sensors/+/39294
264 [^23]: https://gerrit.openbmc.org/c/openbmc/dbus-sensors/+/41394
266 [^24]: https://gerrit.openbmc.org/c/openbmc/entity-manager/+/41397
268 [^25]: https://gerrit.openbmc.org/c/openbmc/dbus-sensors/+/16177