Browse Source

Added more documentation for the config console

Now there's a docs/ directory for storing our documentation in!
Clara Hobbs 6 years ago
parent
commit
9bc66a8537
2 changed files with 154 additions and 0 deletions
  1. 3
    0
      README.md
  2. 151
    0
      docs/console_config.md

+ 3
- 0
README.md View File

@@ -101,6 +101,9 @@ commands:
101 101
 When `write` is run, the chosen settings are written to flash.  You can then
102 102
 simply disconnect the Sink from your computer.
103 103
 
104
+For more information about the serial console configuration interface, see
105
+`docs/console_config.md`.
106
+
104 107
 [GNU Screen]: https://www.gnu.org/software/screen/
105 108
 [Minicom]: https://alioth.debian.org/projects/minicom
106 109
 [PuTTY]: http://www.chiark.greenend.org.uk/~sgtatham/putty/

+ 151
- 0
docs/console_config.md View File

@@ -0,0 +1,151 @@
1
+# PD Buddy Sink Serial Console Configuration Interface
2
+
3
+The PD Buddy Sink can be put into setup mode by holding the Setup button while
4
+plugging it into a computer.  In this mode, the device does not perform any USB
5
+Power Delivery communications, instead running a configuration console over a
6
+USB CDC-ACM virtual serial port.  This allows the user to change the voltage
7
+and current the Sink requests, as well as other settings related to the
8
+device's operation.
9
+
10
+## Quick Start
11
+
12
+### Connecting to the Configuration Console
13
+
14
+Connect to the PD Buddy Sink with your favorite serial console program, such as
15
+[GNU Screen][], [Minicom][], or [PuTTY][].  On Linux, the device file will
16
+probably be something like `/dev/ttyACM0`.  Any baud rate will work, as USB
17
+CDC-ACM doesn't care what it's set to.  After connecting, press Enter and you
18
+should be greeted with a `PDBS)` prompt.
19
+
20
+[GNU Screen]: https://www.gnu.org/software/screen/
21
+[Minicom]: https://alioth.debian.org/projects/minicom
22
+[PuTTY]: http://www.chiark.greenend.org.uk/~sgtatham/putty/
23
+
24
+### View the Saved Configuration
25
+
26
+To see the configuration the device already has, run `get_cfg`:
27
+
28
+    PDBS) get_cfg
29
+    status: valid
30
+    flags: (none)
31
+    v: 9.00 V
32
+    i: 3.00 A
33
+
34
+If the Sink has no configuration, this will simply print `No configuration`.
35
+
36
+### Setting Voltage and Current
37
+
38
+The `set_v` and `set_i` commands allow you to set the voltage and current the
39
+Sink will request.  The units used are millivolts and milliamperes.  For
40
+example, to configure the device to request 2.25 A at 20 V, run the following
41
+commands:
42
+
43
+    PDBS) set_v 20000
44
+    PDBS) set_i 2250
45
+
46
+### Reviewing Configuration Changes
47
+
48
+The changes made so far are held temporarily in RAM.  To review the temporary
49
+configuration buffer, run `get_tmpcfg`:
50
+
51
+    PDBS) get_tmpcfg
52
+    status: valid
53
+    flags: (none)
54
+    v: 20.00 V
55
+    i: 2.25 A
56
+
57
+### Saving Configuration
58
+
59
+The configuration buffer must be written to flash for the device to actually
60
+request the selected voltage and current.  To do this, run:
61
+
62
+    PDBS) write
63
+
64
+As soon as the prompt reappears after running `write`, the changes have been
65
+stored to flash, which can be verified with `get_cfg`.  The Sink may be safely
66
+unplugged at any time.
67
+
68
+## Commands
69
+
70
+### help
71
+
72
+Usage: `help`
73
+
74
+Prints short help messages about all available commands.
75
+
76
+### license
77
+
78
+Usage: `license`
79
+
80
+Prints licensing information for the firmware.
81
+
82
+### erase
83
+
84
+Usage: `erase`
85
+
86
+Erases all stored configuration from flash.  This can be used to restore a
87
+device to its default state.
88
+
89
+Note: The `erase` command is mainly intended for development and testing.
90
+Stored configuration is automatically erased if necessary when `write` is run,
91
+and wear leveling is performed as well.  Unless you really know what you're
92
+doing, there should be no reason to ever run `erase`.
93
+
94
+### write
95
+
96
+Usage: `write`
97
+
98
+Writes the contents of the configuration buffer to flash.  Wear leveling is
99
+done to ensure long flash life, and the flash sector is automatically erased if
100
+necessary.
101
+
102
+### load
103
+
104
+Usage: `load`
105
+
106
+Loads the current configuration from flash into the buffer.  Useful if you want
107
+to change some settings while leaving others alone.
108
+
109
+### get_cfg
110
+
111
+Usage: `get_cfg [index]`
112
+
113
+If no index is provided, prints the current configuration from flash.  If there
114
+is no configuration, `No configuration` is printed instead.
115
+
116
+For developers, if an index is provided, prints a particular location in the
117
+configuration flash sector.
118
+
119
+### get_tmpcfg
120
+
121
+Usage: `get_tmpcfg`
122
+
123
+Prints the contents of the configuration buffer.
124
+
125
+### toggle_giveback
126
+
127
+Usage: `toggle_giveback`
128
+
129
+Toggles the GiveBack flag in the configuration buffer.  GiveBack allows the
130
+power supply to temporarily remove power from the Sink's output if another
131
+device needs more power.  Recommended if the Sink is being used to charge a
132
+battery.
133
+
134
+### set_v
135
+
136
+Usage: `set_v voltage_in_mV`
137
+
138
+Sets the voltage of the configuration buffer, in millivolts.
139
+
140
+### set_i
141
+
142
+Usage: `set_i current_in_mA`
143
+
144
+Sets the current of the configuration buffer, in milliamperes.
145
+
146
+### identify
147
+
148
+Usage: `identify`
149
+
150
+Blinks the LED quickly.  Useful for identifying which device you're connected
151
+to if several are plugged in to your computer at once.

Loading…
Cancel
Save