Browse Source

Add specs for the new configuration for 1.2.0

This adds specifications for the new configuration interface features
planned in this article:
https://hackaday.io/project/20424-pd-buddy-sink/log/68316-new-configuration-for-firmware-120
Clara Hobbs 6 years ago
parent
commit
8ea76e4126
1 changed files with 149 additions and 10 deletions
  1. 149
    10
      docs/console_config.md

+ 149
- 10
docs/console_config.md View File

67
 stored to flash, which can be verified with `get_cfg`.  The Sink may be safely
67
 stored to flash, which can be verified with `get_cfg`.  The Sink may be safely
68
 unplugged at any time.
68
 unplugged at any time.
69
 
69
 
70
+### Voltage Ranges
71
+
72
+The preferred voltage may be set to any value for programmable power supplies.
73
+This means uncommon voltages may be set, e.g. 13.8 V.  Few non-programmable
74
+power supplies offer such a voltage.  To ensure a Sink configured this way can
75
+still work with as many power supplies as possible, it is possible to configure
76
+a closed range of acceptable voltages:
77
+
78
+    PDBS) set_v 13800
79
+    PDBS) set_vmin 11000
80
+    PDBS) set_vmax 16000
81
+    PDBS) get_cfg
82
+    status: valid
83
+    flags: (none)
84
+    v: 13.80 V
85
+    vmin: 11.00 V
86
+    vmax: 16.00 V
87
+    i: 2.25 A
88
+
89
+If 12 V and 15 V are available from a power supply, the Sink would request 12 V
90
+given this configuration.  If higher voltages from the range are preferred over
91
+lower ones, it is possible to set this as well:
92
+
93
+    PDBS) toggle_hv_preferred
94
+    PDBS) get_cfg
95
+    status: valid
96
+    flags: HV_Preferred
97
+    v: 13.80 V
98
+    vmin: 11.00 V
99
+    vmax: 16.00 V
100
+    i: 2.25 A
101
+
102
+To remove a configured voltage range, returning to a single desired voltage,
103
+simply set the top and bottom of the range to 0 V.
104
+
105
+### Alternate Configuration Types
106
+
107
+While configuring a current to be requested at any voltage works well for some
108
+use cases (e.g. linear regulators), for others, it may make more sense to set
109
+the power required, or even the resistance of a resistive load.  As of firmware
110
+version 1.2.0, the PD Buddy Sink supports setting these directly:
111
+
112
+    PDBS) set_p 45000
113
+    PDBS) get_tmpcfg
114
+    status: valid
115
+    flags: (none)
116
+    v: 20.00 V
117
+    p: 45.00 W
118
+    PDBS) set_r 8889
119
+    PDBS) get_tmpcfg
120
+    status: valid
121
+    flags: (none)
122
+    v: 20.00 V
123
+    r: 8.88 Ω
124
+
125
+In either case, the device will set the current it requests according to the
126
+configured value.  The value is kept constant across the entire configured
127
+voltage range, allowing the current to vary accordingly.
128
+
70
 ## Commands
129
 ## Commands
71
 
130
 
72
 Commands are echoed on the terminal as characters are received.  Lines are
131
 Commands are echoed on the terminal as characters are received.  Lines are
73
-separated by `\r\n` and a command's output ends with the `PDBS) ` prompt.
132
+separated by `\r\n` and a command's output ends with the `PDBS) ` prompt.  The
133
+character encoding used for text is UTF-8.
74
 
134
 
75
 The command buffer can be cleared by sending ^D (a `\x04` character).  It is
135
 The command buffer can be cleared by sending ^D (a `\x04` character).  It is
76
 recommended to do this at the start of programmatic communications to ensure
136
 recommended to do this at the start of programmatic communications to ensure
161
 
221
 
162
 Usage: `clear_flags`
222
 Usage: `clear_flags`
163
 
223
 
164
-Clears all the flags in the configuration buffer.
224
+Clears the configuration buffer flags that can be toggled with `toggle_*`
225
+commands.
165
 
226
 
166
 #### toggle_giveback
227
 #### toggle_giveback
167
 
228
 
172
 device needs more power.  Recommended if the Sink is being used to charge a
233
 device needs more power.  Recommended if the Sink is being used to charge a
173
 battery.
234
 battery.
174
 
235
 
236
+#### toggle_hv_preferred
237
+
238
+Usage: `toggle_hv_preferred`
239
+
240
+Toggles the HV_Preferred flag in the configuration buffer.  When enabled,
241
+preference is given to higher voltages in the range.  When disabled, preference
242
+is given to lower voltages.
243
+
175
 #### set_v
244
 #### set_v
176
 
245
 
177
 Usage: `set_v voltage_in_mV`
246
 Usage: `set_v voltage_in_mV`
179
 Sets the voltage of the configuration buffer, in millivolts.  Prints no output
248
 Sets the voltage of the configuration buffer, in millivolts.  Prints no output
180
 on success, an error message on failure.
249
 on success, an error message on failure.
181
 
250
 
182
-Note: values are rounded down to the nearest Power Delivery voltage unit
183
-(50 mV).
251
+Note: values are rounded down to the nearest 10 mV.
252
+
253
+#### set_vmin
254
+
255
+Usage: `set_vmin voltage_in_mV`
256
+
257
+Sets the minimum voltage of the configuration buffer, in millivolts.  Prints no
258
+message on success, an error message on failure.
259
+
260
+Note: values are rounded down to the nearest 10 mV.
261
+
262
+#### set_vmax
263
+
264
+Usage: `set_vmax voltage_in_mV`
265
+
266
+Sets the maximum voltage of the configuration buffer, in millivolts.  Prints no
267
+message on success, an error message on failure.
268
+
269
+Note: values are rounded down to the nearest 10 mV.
184
 
270
 
185
 #### set_i
271
 #### set_i
186
 
272
 
187
 Usage: `set_i current_in_mA`
273
 Usage: `set_i current_in_mA`
188
 
274
 
189
-Sets the current of the configuration buffer, in milliamperes.  Prints no
190
-output on success, an error message on failure.
275
+Sets the current of the configuration buffer, in milliamperes, overriding any
276
+power or resistance configured.  Prints no output on success, an error message
277
+on failure.
278
+
279
+Note: values are rounded down to the nearest 10 mA.
280
+
281
+#### set_p
191
 
282
 
192
-Note: values are rounded down to the nearest Power Delivery current unit
193
-(10 mA).
283
+Usage: `set_p power_in_mW`
284
+
285
+Sets the power of the configuration buffer, in milliwatts, overriding any
286
+current or resistance configured.  Prints no output on success, an error
287
+message on failure.
288
+
289
+Note: values are rounded down to the nearest 10 mW.
290
+
291
+#### set_r
292
+
293
+Usage: `set_r resistance_in_mΩ`
294
+
295
+Sets the resistance of the configuration buffer, in milliohms, overriding any
296
+current or power configured.  Prints no output on success, an error message on
297
+failure.
298
+
299
+Note: values are rounded down to the nearest 10 mΩ.
194
 
300
 
195
 ### Power Delivery
301
 ### Power Delivery
196
 
302
 
248
 
354
 
249
 * `GiveBack`: allows the power supply to temporarily reduce power to the device
355
 * `GiveBack`: allows the power supply to temporarily reduce power to the device
250
   if necessary.
356
   if necessary.
357
+* `HV_Preferred`: precedence is given to higher voltages when selecting from
358
+  the range (lower voltages take precedence when the flag is disabled).
251
 
359
 
252
 ### v
360
 ### v
253
 
361
 
254
-The `v` field holds the fixed voltage of the configuration object, in volts.
362
+The `v` field holds the preferred voltage of the configuration object, in
363
+volts.
364
+The field's value is a floating-point decimal number, followed by a space and a
365
+capital V.  For example: `20.00 V`.
366
+
367
+### vmin
368
+
369
+The `vmin` field holds the lower end of the configuration object's voltage
370
+range, in volts.
371
+The field's value is a floating-point decimal number, followed by a space and a
372
+capital V.  For example: `20.00 V`.
373
+
374
+When absent, this field's value may be assumed to be `0 V`.
375
+
376
+### vmax
377
+
378
+The `vmax` field holds the upper end of the configuration object's voltage
379
+range, in volts.
255
 The field's value is a floating-point decimal number, followed by a space and a
380
 The field's value is a floating-point decimal number, followed by a space and a
256
 capital V.  For example: `20.00 V`.
381
 capital V.  For example: `20.00 V`.
257
 
382
 
383
+When absent, this field's value may be assumed to be `0 V`.
384
+
258
 ### i
385
 ### i
259
 
386
 
260
-The `i` field holds the fixed current of the configuration object, in amperes.
387
+The `i` field holds the current of the configuration object, in amperes.
261
 The field's value is a floating-point decimal number, followed by a space and a
388
 The field's value is a floating-point decimal number, followed by a space and a
262
 capital A.  For example: `2.25 A`.
389
 capital A.  For example: `2.25 A`.
263
 
390
 
391
+### p
392
+
393
+The `p` field holds the power of the configuration object, in watts.
394
+The field's value is a floating-point decimal number, followed by a space and a
395
+capital W.  For example: `2.25 W`.
396
+
397
+### r
398
+
399
+The `r` field holds the resistance of the configuration object, in ohms.
400
+The field's value is a floating-point decimal number, followed by a space and a
401
+capital Ω.  For example: `2.25 Ω`.
402
+
264
 ## PDO Format
403
 ## PDO Format
265
 
404
 
266
 When a list of PDOs is printed, each PDO is numbered with a line as follows:
405
 When a list of PDOs is printed, each PDO is numbered with a line as follows:

Loading…
Cancel
Save