/
README
254 lines (205 loc) · 11.3 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
README
ssterm - Version 1.6 - 02/11/2013
Vanya A. Sergeev - vsergeev at gmail
================================================================================
Table of Contents
1. ABOUT ssterm
2. INSTALLING
3. USAGE
4. LICENSE
5. USING ssterm
6. Example Usage
================================================================================
1. ABOUT ssterm
================================================================================
ssterm is a console-based simple serial port terminal. It features painless
serial port configuration, no dependencies outside of a standard Python 2
installation, is contained in a single file, and provides a variety of useful
input/output features:
- plain ASCII representation
- split hexadecimal/ASCII representation
- pure hexadecimal representation with optional newline interpretation
- color coding bytes in all three ASCII, split, and hexadecimal modes
- raw terminal with control character forwarding
- transmit newline character remapping (e.g. LF -> CRLF)
- receive newline character remapping (e.g. CR -> LF)
- local character echo
ssterm was written in Python 2, and should work on most *nix platforms. It
works with both CPython and pypy implementations of Python. Feel free to send
any bugs, ideas, or suggestions to vsergeev at gmail dot com.
2. INSTALLING
================================================================================
Install ssterm to /usr/local/bin (requires root):
# make install
Remove ssterm from /usr/local/bin (requires root):
# make uninstall
Install ssterm to an alternate prefix, such as /usr:
# make install PREFIX=/usr
3. USAGE
================================================================================
Usage: ssterm [options] <serial port device>
ssterm - simple serial-port terminal
Written by Vanya A. Sergeev - <vsergeev@gmail.com>.
Serial Port Options:
-b, --baudrate <rate> Specify baudrate
-d, --databits <number> Specify number of data bits [5,6,7,8]
-p, --parity <type> Specify parity [none, odd, even]
-t, --stopbits <number> Specify number of stop bits [1,2]
-f, --flow-control <type> Specify flow-control [none, rtscts, xonxoff]
Formatting Options:
-s, --split Split hexadecimal/ASCII mode
--split-full Split hexadecimal/ASCII mode with full lines
(good for piping)
-x, --hex Pure hexadecimal mode
--hex-nl Print newlines in pure hexadecimal mode
-c, --color <list> Specify comma-delimited list of characters in
ASCII or hex to color code: A,$,0x0d,0x0a,...
--tx-nl <substitution> Specify the transmit newline substitution
[raw, none, cr, lf, crlf]
--rx-nl <match> Specify the receive newline match
[raw, cr, lf, crlf, crorlf]
-e, --echo Turn on local character echo
-h, --help Display this usage/help
-v, --version Display the program's version
Quit Escape Character: Ctrl-]
Color Code Sequence (fg/bg):
Black/Red, Black/Green, Black/Yellow, White/Blue, White/Magenta,
Black/Cyan, Black/White
Default Options:
baudrate: 9600 | databits: 8 | parity: none | stopbits: 1 | flow ctrl: none
tx newline: raw | rx newline: raw | local echo: off
split mode: off | hex mode: off | color code: off
4. LICENSE
================================================================================
ssterm is released under the GNU General Public License Version 3.
You should have received a copy of the GNU General Public License
along with this program; see the file "COPYING". If not, see
<http://www.gnu.org/licenses/>.
5. USING ssterm
================================================================================
By default, ssterm will open the specified serial port with 9600 baudrate, 8
data bits, no parity, 1 stop bit, and no flow control. These settings can be
adjusted with the -b / --baudrate, -d / --databits, -p / --parity, -t /
--stopbits, and -f / --flow-control options (see usage below).
ssterm opens the input terminal in raw mode, so all characters and control
signals are passed through transparently to the serial port. This enables
interacting with terminal interfaces over the serial port that interpret
control characters, such as a *nix termios on an embedded system. The only
exception is Ctrl-], which serves as ssterm's quit escape character.
ssterm can display output in split hexadecimal/ASCII mode, with the -s or
--split option. This mode will format data in the split mode as it is received,
updating the hexadecimal and ASCII columns by clearing and re-drawing the line
until it is full width. For a split hexadecimal/ASCII representation suitable
for piping to another program or file, --split-full should be used, to limit
printing to full column lines.
ssterm can color code particular characters, specified by a comma-delimited
list with the -c or --color option. The list can contain ASCII entries (e.g.
a,_,A,...), as well as hexadecimal entries (e.g. 0x0a,0xff,...). There is
currently a maximum of seven distinct colors, assigned sequentially to the
specified characters in the following order (foreground/background): Black/Red,
Black/Green, Black/Yellow, White/Blue, White/Magenta, Black/Cyan, Black/White.
ssterm can also display output in pure hexadecimal mode, with the -x or --hex
option, and interpret newlines in this mode with the --hex-nl option.
Plain ASCII representation mode is default.
The newline characters can be remapped upon transmission and remapped upon
reception. These mappings are specified with the --tx-nl and --rx-nl options.
These options were created to accommodate working with the serial port on LF
based systems, but the functionality should extend to CR and CRLF based systems
as well. The substitution and matching can be disabled by selecting 'raw' mode
for both --tx-nl and --rx-nl options.
The following receive newline character remappings are available:
* raw - no remapping of received newline characters
* cr - map received CR to platform newline
* lf - map received LF to platform newline
* crlf - map received CRLF to platform newline
* crorlf - map any received CR or LF to platform newline
The following transmit newline character remappings are available:
* raw - no remapping of transmit newline characters
* none - omit newline characters on transmit
* cr - map platform newline to CR on transmit
* lf - map platform newline to LF on transmit
* crlf - map platform newline to CRLF on transmit
The default receive newline character mapping (--rx-nl option) is raw.
The default transmit newline character mapping (--rx-nl option) is raw.
Other options include local character echo, which is off by default.
6. Example Usage
================================================================================
Typical usage with defaults (9600 8N1, no flow control):
$ ssterm /dev/ttyUSB0
Logging some data:
$ ssterm /dev/ttyUSB0 > nmea_data.txt
Viewing and logging some data, with the help of tee:
$ ssterm /dev/ttyUSB0 | tee nmea_data.txt
Specific serial port settings (115200 baudrate, odd parity, 2 stop bits), and
the default 8 data bits:
$ ssterm -b 115200 -p odd -t 2 /dev/ttyUSB0
CRLF for transmitted newlines, but LF for received newlines:
$ ssterm --tx-nl crlf --rx-nl lf /dev/ttyUSB0
Split representation mode:
$ ssterm -s /dev/ttyUSB0
4c 6f 72 65 6d 20 69 70 73 75 6d 20 64 6f 6c 6f |Lorem ipsum dolo|
72 20 73 69 74 20 61 6d 65 74 2c 20 63 6f 6e 73 |r sit amet, cons|
65 63 74 65 74 75 72 20 61 64 69 70 69 73 69 63 |ectetur adipisic|
69 6e 67 20 65 6c 69 74 2c 20 73 65 64 20 64 6f |ing elit, sed do|
20 65 69 75 73 6d 6f 64 20 74 65 6d 70 6f 72 20 | eiusmod tempor |
69 6e 63 69 64 69 64 75 6e 74 20 75 74 20 6c 61 |incididunt ut la|
62 6f 72 65 20 65 74 20 64 6f 6c 6f 72 65 20 6d |bore et dolore m|
61 67 6e 61 20 61 6c 69 71 75 61 2e 0a 55 74 20 |agna aliqua..Ut |
65 6e 69 6d 20 61 64 20 6d 69 6e 69 6d 20 76 65 |enim ad minim ve|
6e 69 61 6d 2c 20 71 75 69 73 20 6e 6f 73 74 72 |niam, quis nostr|
75 64 20 65 78 65 72 63 69 74 61 74 69 6f 6e 20 |ud exercitation |
75 6c 6c 61 6d 63 6f 20 6c 61 62 6f 72 69 73 20 |ullamco laboris |
6e 69 73 69 20 75 74 20 61 6c 69 71 75 69 70 20 |nisi ut aliquip |
65 78 20 65 61 20 63 6f 6d 6d 6f 64 6f 20 63 6f |ex ea commodo co|
6e 73 65 71 75 61 74 2e 0a 44 75 69 73 20 61 75 |nsequat..Duis au|
74 65 20 69 72 75 72 65 20 64 6f 6c 6f 72 20 69 |te irure dolor i|
6e 20 72 65 70 72 65 68 65 6e 64 65 72 69 74 20 |n reprehenderit |
69 6e 20 76 6f 6c 75 70 74 61 74 65 20 76 65 6c |in voluptate vel|
69 74 20 65 73 73 65 20 63 69 6c 6c 75 6d 20 64 |it esse cillum d|
6f 6c 6f 72 65 20 65 75 20 66 75 67 69 61 74 20 |olore eu fugiat |
6e 75 6c 6c 61 20 70 61 72 69 61 74 75 72 2e 0a |nulla pariatur..|
45 78 63 65 70 74 65 75 72 20 73 69 6e 74 20 6f |Excepteur sint o|
63 63 61 65 63 61 74 20 63 75 70 69 64 61 74 61 |ccaecat cupidata|
74 20 6e 6f 6e 20 70 72 6f 69 64 65 6e 74 2c 20 |t non proident, |
73 75 6e 74 20 69 6e 20 63 75 6c 70 61 20 71 75 |sunt in culpa qu|
69 20 6f 66 66 69 63 69 61 20 64 65 73 65 72 75 |i officia deseru|
6e 74 20 6d 6f 6c 6c 69 74 20 61 6e 69 6d 20 69 |nt mollit anim i|
64 20 65 73 74 20 6c 61 62 6f 72 75 6d 2e 0a 00 |d est laborum...|
01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 10 |................|
11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 20 |............... |
21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f 30 |!"#$%&'()*+,-./0|
31 32 33 34 35 36 37 38 39 3a 3b 3c 3d 3e 3f 40 |123456789:;<=>?@|
41 42 43 44 45 46 47 48 49 4a 4b 4c 4d 4e 4f 50 |ABCDEFGHIJKLMNOP|
51 52 53 54 55 56 57 58 59 5a 5b 5c 5d 5e 5f 60 |QRSTUVWXYZ[\]^_`|
61 62 63 64 65 66 67 68 69 6a 6b 6c 6d 6e 6f 70 |abcdefghijklmnop|
71 72 73 74 75 76 77 78 79 7a 7b 7c 7d 7e 7f 80 |qrstuvwxyz{|}~..|
81 82 83 84 85 86 87 88 89 8a 8b 8c 8d 8e 8f 90 |................|
91 92 93 94 95 96 97 98 99 9a 9b 9c 9d 9e 9f a0 |................|
a1 a2 a3 a4 a5 a6 a7 a8 a9 aa ab ac ad ae af b0 |................|
b1 b2 b3 b4 b5 b6 b7 b8 b9 ba bb bc bd be bf c0 |................|
c1 c2 c3 c4 c5 c6 c7 c8 c9 ca cb cc cd ce cf d0 |................|
d1 d2 d3 d4 d5 d6 d7 d8 d9 da db dc dd de df e0 |................|
e1 e2 e3 e4 e5 e6 e7 e8 e9 ea eb ec ed ee ef f0 |................|
f1 f2 f3 f4 f5 f6 f7 f8 f9 fa fb fc fd fe ff |...............|
Split representation mode with color coding:
$ ssterm -s -c 0x0A,{,g,0xAE /dev/ttyUSB0
Hexadecimal representation mode:
$ ssterm -x /dev/ttyUSB0
24 47 50 47 47 41 2c 30 38 32 38 33 30 2e 38 32
31 2c 2c 2c 2c 2c 30 2c 30 30 2c 2c 2c 4d 2c 30
2e 30 2c 4d 2c 2c 30 30 30 30 2a 35 43 0d 0a 24
47 50 47 53 41 2c 41 2c 31 2c 2c 2c 2c 2c 2c 2c
2c 2c 2c 2c 2c 2c 2c 2c 2a 31 45 0d 0a 24 47 50
52 4d 43 2c 30 38 32 38 33 30 2e 38 32 31 2c 56
2c 2c 2c 2c 2c 2c 2c 32 36 31 30 30 39 2c 2c 2a
32 39 0d 0a 24 47 50 47 47 41 2c 30 38 32 38 33
31 2e 38 31 34 2c 2c 2c 2c 2c 30 2c 30 30 2c 2c
2c 4d 2c 30 2e 30 2c 4d 2c 2c 30 30 30 30 2a 35
42 0d 0a 24 47 50 47 53 41 2c 41 2c 31 2c 2c 2c
2c 2c 2c 2c 2c 2c 2c 2c 2c 2c 2c 2c 2a 31 45 0d
0a 24 47 50 52 4d 43 2c 30 38 32 38 33 31 2e 38
31 34 2c 56 2c 2c 2c 2c 2c 2c 2c 32 36 31 30 30
39 2c 2c 2a 32 45 0d 0a 24 47 50 47 47 41 2c 30
38
Hexadecimal representation mode, with newline interpretation and color coding:
$ ssterm -x --hex-nl -c $,0x0a,0x0d /dev/ttyUSB0