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 7 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,10 +67,70 @@ As soon as the prompt reappears after running `write`, the changes have been
67 67
 stored to flash, which can be verified with `get_cfg`.  The Sink may be safely
68 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 129
 ## Commands
71 130
 
72 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 135
 The command buffer can be cleared by sending ^D (a `\x04` character).  It is
76 136
 recommended to do this at the start of programmatic communications to ensure
@@ -161,7 +221,8 @@ Prints the contents of the configuration buffer.
161 221
 
162 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 227
 #### toggle_giveback
167 228
 
@@ -172,6 +233,14 @@ power supply to temporarily remove power from the Sink's output if another
172 233
 device needs more power.  Recommended if the Sink is being used to charge a
173 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 244
 #### set_v
176 245
 
177 246
 Usage: `set_v voltage_in_mV`
@@ -179,18 +248,55 @@ Usage: `set_v voltage_in_mV`
179 248
 Sets the voltage of the configuration buffer, in millivolts.  Prints no output
180 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 271
 #### set_i
186 272
 
187 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 301
 ### Power Delivery
196 302
 
@@ -248,19 +354,52 @@ this configuration object:
248 354
 
249 355
 * `GiveBack`: allows the power supply to temporarily reduce power to the device
250 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 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 380
 The field's value is a floating-point decimal number, followed by a space and a
256 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 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 388
 The field's value is a floating-point decimal number, followed by a space and a
262 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 403
 ## PDO Format
265 404
 
266 405
 When a list of PDOs is printed, each PDO is numbered with a line as follows:

Loading…
Cancel
Save