1# pmbus_write_vout_command
2
3## Description
4
5Writes the value of VOUT_COMMAND to set the output voltage of a PMBus regulator
6rail. Communicates with the device directly using the
7[I2C interface](i2c_interface.md).
8
9This action should be executed during [configuration](configuration.md) for the
10rail.
11
12### Data Format
13
14The PMBus specification defines four modes/formats for the value of
15VOUT_COMMAND:
16
17- Linear
18- VID
19- Direct
20- IEEE Half-Precision Floating Point
21
22Currently only the linear format is supported. The decimal value of the "volts"
23property is converted into linear format before being written.
24
25### Exponent For Linear Data Format
26
27The linear data format requires an exponent value.
28
29If the device supports the PMBus VOUT_MODE command, the exponent value can be
30read from the device.
31
32If VOUT_MODE is not supported by the device, the exponent value must be
33specified using the "exponent" property. The exponent value can normally be
34found in the device documentation (data sheet).
35
36### Write Verification
37
38If you wish to verify that the specified volts value was successfully written to
39VOUT_COMMAND, specify the "is_verified" property with a value of true.
40
41The value of VOUT_COMMAND will be read from the device after it is written to
42ensure that it contains the expected value. If VOUT_COMMAND contains an
43unexpected value, an error will be logged and no further configuration will be
44performed for this regulator rail.
45
46To perform verification, the device must return all 16 bits of voltage data that
47were written to VOUT_COMMAND. The PMBus specification permits a device to have
48less than 16 bit internal data resolution, resulting in some low order bits
49being zero when read back. However, verification is not supported on devices
50that provide less than 16 bit internal data resolution.
51
52## Properties
53
54| Name        | Required | Type                    | Description                                                                                                                                          |
55| :---------- | :------: | :---------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------- |
56| volts       |    no    | number                  | Volts value to write, expressed as a decimal number. If not specified, the "volts" property from the [configuration](configuration.md) will be used. |
57| format      |   yes    | string                  | Data format of the value written to VOUT_COMMAND. Currently the only supported format is "linear".                                                   |
58| exponent    |    no    | number                  | Exponent value for linear data format. Can be positive or negative. If not specified, the exponent value will be read from VOUT_MODE.                |
59| is_verified |    no    | boolean (true or false) | If true, the updated value of VOUT_COMMAND is verified by reading it from the device. If false or not specified, the updated value is not verified.  |
60
61## Return Value
62
63true
64
65## Examples
66
67```json
68{
69  "comments": [
70    "Set output voltage.  Get volts value from configuration.",
71    "Get exponent from VOUT_MODE."
72  ],
73  "pmbus_write_vout_command": {
74    "format": "linear"
75  }
76}
77```
78
79```json
80{
81  "comments": [
82    "Set output voltage.  Explicitly specify volts and exponent.",
83    "Verify value was successfully written to VOUT_COMMAND."
84  ],
85  "pmbus_write_vout_command": {
86    "volts": 1.03,
87    "format": "linear",
88    "exponent": -8,
89    "is_verified": true
90  }
91}
92```
93