1# pmbus_read_sensor 2 3## Description 4Reads one sensor for a PMBus regulator rail. Communicates with the device 5directly using the [I2C interface](i2c_interface.md). 6 7This action should be executed during [sensor_monitoring](sensor_monitoring.md) 8for the rail. 9 10### Sensor Value Type 11Currently the following sensor value types are supported: 12 13| Type | Description | 14| :--- | :---------- | 15| iout | Output current | 16| iout_peak | Highest output current | 17| iout_valley | Lowest output current | 18| pout | Output power | 19| temperature | Temperature | 20| temperature_peak | Highest temperature | 21| vout | Output voltage | 22| vout_peak | Highest output voltage | 23| vout_valley | Lowest output voltage | 24 25Notes: 26* Some regulators only support a subset of these sensor value types. 27* Some of these sensor value types are not part of the PMBus specification and 28 must be obtained by reading from manufacturer-specific commands. 29 30### Data Format 31Currently the following PMBus data formats are supported: 32 33| Format | Description | 34| :----- | :---------- | 35| linear_11 | Linear data format used for values not related to voltage output, such as output current, input voltage, and temperature. Two byte value with an 11-bit, two's complement mantissa and a 5-bit, two's complement exponent. | 36| linear_16 | Linear data format used for values related to voltage output. Two byte (16-bit), unsigned integer that is raised to the power of an exponent. The exponent is not stored within the two bytes. | 37 38### Exponent For "linear_16" Data Format 39The "linear_16" data format requires an exponent value. 40 41If the device supports the PMBus VOUT_MODE command, the exponent value can be 42read from the device. 43 44If VOUT_MODE is not supported by the device, the exponent value must be 45specified using the "exponent" property. The exponent value can normally be 46found in the device documentation (data sheet). 47 48### D-Bus Sensor 49A [D-Bus sensor 50object](https://github.com/openbmc/docs/blob/master/architecture/sensor-architecture.md) 51will be created on the BMC to store the sensor value. This makes the sensor 52available to external interfaces like Redfish. 53 54D-Bus sensors have an object path with the following format: 55``` 56/xyz/openbmc_project/sensors/<type>/<label> 57``` 58 59The D-Bus `<type>` is the hwmon class name. The following table shows how the 60sensor value type is mapped to a D-Bus `<type>`. 61 62| Sensor Value Type | D-Bus `<type>` | 63| :---------------- | :------------- | 64| iout | current | 65| iout_peak | current | 66| iout_valley | current | 67| pout | power | 68| temperature | temperature | 69| temperature_peak | temperature | 70| vout | voltage | 71| vout_peak | voltage | 72| vout_valley | voltage | 73 74The D-Bus `<label>` is the sensor name. It must be unique within the entire 75system. The `<label>` will be set to the following: 76``` 77<rail_id>_<sensor_value_type> 78``` 79For example, if sensor monitoring for rail "vdd0" reads a "vout_peak" sensor, 80the resulting D-Bus `<label>` will be "vdd0_vout_peak". 81 82## Properties 83| Name | Required | Type | Description | 84| :--- | :------: | :--- | :---------- | 85| type | yes | string | Sensor value type. Specify one of the following: "iout", "iout_peak", "iout_valley", "pout", "temperature", "temperature_peak", "vout", "vout_peak", "vout_valley". | 86| command | yes | string | PMBus command code expressed in hexadecimal. Must be prefixed with 0x and surrounded by double quotes. | 87| format | yes | string | Data format of the sensor value returned by the device. Specify one of the following: "linear_11", "linear_16". 88| exponent | no | number | Exponent value for "linear_16" data format. Can be positive or negative. If not specified, the exponent value will be read from VOUT_MODE. | 89 90## Return Value 91true 92 93## Examples 94``` 95{ 96 "comments": [ "Read output current from READ_IOUT." ], 97 "pmbus_read_sensor": { 98 "type": "iout", 99 "command": "0x8C", 100 "format": "linear_11" 101 } 102} 103 104{ 105 "comments": [ "Read output voltage from READ_VOUT. Specify exponent." ], 106 "pmbus_read_sensor": { 107 "type": "vout", 108 "command": "0x8B", 109 "format": "linear_16", 110 "exponent": -8 111 } 112} 113``` 114