Skip to content

Commit ac1d166

Browse files
bcantrillbcantrill
authored
"humility lpc55gpio" should be better documented (#389)
1 parent eb1b0a3 commit ac1d166

2 files changed

Lines changed: 195 additions & 5 deletions

File tree

‎README.md‎

Lines changed: 96 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1079,7 +1079,102 @@ normal, or `--start`/`-s` to run it once but catch the next fault.
10791079

10801080
### `humility lpc55gpio`
10811081

1082-
The LPC55-equivalent of `humility gpio`.
1082+
The LPC55-equivalent of `humility gpio`, allowing for GPIO pins to
1083+
be set, reset, queried or configured on LPC55 targets. Commands:
1084+
1085+
- `--set` (`-s`): Sets a pin (sets it high)
1086+
- `--reset` (`-r`): Resets a pin (sets it low)
1087+
- `--toggle` (`-t`): Toggles a pin (sets it high if low, low if high)
1088+
- `--input` (`-i`): Queries the state of a pin (or all pins if no pin
1089+
is specified)
1090+
- `--configure` (`-c`): Configures a pin
1091+
- `--direction` (`-d`): Configure the direction of a pin
1092+
1093+
#### Set, reset, toggle
1094+
1095+
To change the state of a pin (or pins), specify the pin (or pins) and
1096+
the desired command. For example, to toggle the state on pin PIO0_17:
1097+
1098+
```console
1099+
$ humility lpc55gpio --toggle --pins PIO0_17
1100+
humility: attached via CMSIS-DAP
1101+
[Ok([])]
1102+
```
1103+
1104+
To set pins PIO0_15, PIO0_16 and PIO0_17:
1105+
1106+
```console
1107+
$ humility lpc55gpio --set --pins PIO0_15,PIO0_16,PIO0_17
1108+
humility: attached via CMSIS-DAP
1109+
[Ok([]), Ok([]), Ok([])]
1110+
```
1111+
1112+
To reset pin PIO0_17:
1113+
1114+
```console
1115+
$ humility lpc55gpio --reset --pins PIO0_17
1116+
humility: attached via CMSIS-DAP
1117+
[Ok([])]
1118+
```
1119+
1120+
#### Input
1121+
1122+
To get input values for a particular pin:
1123+
1124+
```console
1125+
$ humility lpc55gpio --input --pins PIO0_10,PIO0_11,PIO1_0
1126+
humility: attached via CMSIS-DAP
1127+
PIO0_10 = 0
1128+
PIO0_11 = 1
1129+
PIO1_0 = 0
1130+
```
1131+
1132+
To get input values for all pins, leave the pin unspecified:
1133+
1134+
```console
1135+
$ humility lpc55gpio --input
1136+
humility: attached via ST-Link V3
1137+
humility: attached to 1fc9:0143:12UNOSLDXOK51 via CMSIS-DAP
1138+
PIO0_0 = 0
1139+
PIO0_1 = 0
1140+
PIO0_2 = 0
1141+
PIO0_3 = 0
1142+
PIO0_4 = 0
1143+
PIO0_5 = 1
1144+
PIO0_6 = 0
1145+
PIO0_7 = 0
1146+
PIO0_8 = 0
1147+
PIO0_9 = 1
1148+
PIO0_10 = 0
1149+
PIO0_11 = 1
1150+
PIO0_13 = 0
1151+
...
1152+
```
1153+
1154+
#### Configure, direction
1155+
1156+
To configure a pin, the configuration should be specified as a
1157+
colon-delimited 6-tuple consisting of:
1158+
1159+
- Alternate function: one of `Alt0` through `Alt9`
1160+
- Mode: `NoPull`, `PullDown`, `PullUp`, or `Repeater`
1161+
- Slew: `Standard` or `Fast`
1162+
- Invert: `Disable`, or `Enabled`
1163+
- Digital mode: `Analog` or `Digital`
1164+
- Open drain: `Normal` or `OpenDrain`
1165+
1166+
Note that the direction of the pin should also likely be configured;
1167+
this is done via the `--direction` option, specifying either `Input` or
1168+
`Output`. For example, to configure pin PIO0_17 to be an output:
1169+
1170+
```console
1171+
$ humility lpc55gpio -c Alt0:NoPull:Standard:Disable:Digital:Normal -p PIO0_17
1172+
humility: attached via CMSIS-DAP
1173+
[Ok([])]
1174+
$ humility lpc55gpio -p PIO0_17 --direction Output
1175+
humility: attached via CMSIS-DAP
1176+
[Ok([])]
1177+
```
10831178

10841179

10851180

‎cmd/lpc55gpio/src/lib.rs‎

Lines changed: 99 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,102 @@
44

55
//! ## `humility lpc55gpio`
66
//!
7-
//! The LPC55-equivalent of `humility gpio`.
7+
//! The LPC55-equivalent of `humility gpio`, allowing for GPIO pins to
8+
//! be set, reset, queried or configured on LPC55 targets. Commands:
9+
//!
10+
//! - `--set` (`-s`): Sets a pin (sets it high)
11+
//! - `--reset` (`-r`): Resets a pin (sets it low)
12+
//! - `--toggle` (`-t`): Toggles a pin (sets it high if low, low if high)
13+
//! - `--input` (`-i`): Queries the state of a pin (or all pins if no pin
14+
//! is specified)
15+
//! - `--configure` (`-c`): Configures a pin
16+
//! - `--direction` (`-d`): Configure the direction of a pin
17+
//!
18+
//! ### Set, reset, toggle
19+
//!
20+
//! To change the state of a pin (or pins), specify the pin (or pins) and
21+
//! the desired command. For example, to toggle the state on pin PIO0_17:
22+
//!
23+
//! ```console
24+
//! $ humility lpc55gpio --toggle --pins PIO0_17
25+
//! humility: attached via CMSIS-DAP
26+
//! [Ok([])]
27+
//! ```
28+
//!
29+
//! To set pins PIO0_15, PIO0_16 and PIO0_17:
30+
//!
31+
//! ```console
32+
//! $ humility lpc55gpio --set --pins PIO0_15,PIO0_16,PIO0_17
33+
//! humility: attached via CMSIS-DAP
34+
//! [Ok([]), Ok([]), Ok([])]
35+
//! ```
36+
//!
37+
//! To reset pin PIO0_17:
38+
//!
39+
//! ```console
40+
//! $ humility lpc55gpio --reset --pins PIO0_17
41+
//! humility: attached via CMSIS-DAP
42+
//! [Ok([])]
43+
//! ```
44+
//!
45+
//! ### Input
46+
//!
47+
//! To get input values for a particular pin:
48+
//!
49+
//! ```console
50+
//! $ humility lpc55gpio --input --pins PIO0_10,PIO0_11,PIO1_0
51+
//! humility: attached via CMSIS-DAP
52+
//! PIO0_10 = 0
53+
//! PIO0_11 = 1
54+
//! PIO1_0 = 0
55+
//! ```
56+
//!
57+
//! To get input values for all pins, leave the pin unspecified:
58+
//!
59+
//! ```console
60+
//! $ humility lpc55gpio --input
61+
//! humility: attached via ST-Link V3
62+
//! humility: attached to 1fc9:0143:12UNOSLDXOK51 via CMSIS-DAP
63+
//! PIO0_0 = 0
64+
//! PIO0_1 = 0
65+
//! PIO0_2 = 0
66+
//! PIO0_3 = 0
67+
//! PIO0_4 = 0
68+
//! PIO0_5 = 1
69+
//! PIO0_6 = 0
70+
//! PIO0_7 = 0
71+
//! PIO0_8 = 0
72+
//! PIO0_9 = 1
73+
//! PIO0_10 = 0
74+
//! PIO0_11 = 1
75+
//! PIO0_13 = 0
76+
//! ...
77+
//! ```
78+
//!
79+
//! ### Configure, direction
80+
//!
81+
//! To configure a pin, the configuration should be specified as a
82+
//! colon-delimited 6-tuple consisting of:
83+
//!
84+
//! - Alternate function: one of `Alt0` through `Alt9`
85+
//! - Mode: `NoPull`, `PullDown`, `PullUp`, or `Repeater`
86+
//! - Slew: `Standard` or `Fast`
87+
//! - Invert: `Disable`, or `Enabled`
88+
//! - Digital mode: `Analog` or `Digital`
89+
//! - Open drain: `Normal` or `OpenDrain`
90+
//!
91+
//! Note that the direction of the pin should also likely be configured;
92+
//! this is done via the `--direction` option, specifying either `Input` or
93+
//! `Output`. For example, to configure pin PIO0_17 to be an output:
94+
//!
95+
//! ```console
96+
//! $ humility lpc55gpio -c Alt0:NoPull:Standard:Disable:Digital:Normal -p PIO0_17
97+
//! humility: attached via CMSIS-DAP
98+
//! [Ok([])]
99+
//! $ humility lpc55gpio -p PIO0_17 --direction Output
100+
//! humility: attached via CMSIS-DAP
101+
//! [Ok([])]
102+
//! ```
8103
//!
9104
10105
use humility_cli::{ExecutionContext, Subcommand};
@@ -64,7 +159,7 @@ struct GpioArgs {
64159
direction: Option<String>,
65160

66161
/// specifies GPIO pins on which to operate
67-
#[clap(long, short, value_name = "pins")]
162+
#[clap(long, short, value_name = "pins", use_value_delimiter = true)]
68163
pins: Option<Vec<String>>,
69164
}
70165

@@ -137,9 +232,9 @@ fn gpio(context: &mut ExecutionContext) -> Result<()> {
137232

138233
if let Some(ref pins) = subargs.pins {
139234
for pin in pins {
140-
let pin = gpio_toggle.lookup_argument(hubris, "pin", 0, pin)?;
235+
let p = gpio_toggle.lookup_argument(hubris, "pin", 0, pin)?;
141236

142-
args.push((pin, pin.to_string()));
237+
args.push((p, pin.to_string()));
143238
}
144239
}
145240

0 commit comments

Comments
 (0)