1JPNEVULATOR(1)                   User Commands                  JPNEVULATOR(1)
2
3
4

NAME

6       jpnevulator - Just another serial sniffer
7

SYNOPSIS

9       jpnevulator [OPTION]... <FILE>
10

DESCRIPTION

12       jpnevulator is a handy serial sniffer. You can use it to send data on a
13       serial device too. You can read or write from/to  one  or  more  serial
14       devices at the same time.
15
16       In write (--write) mode data to be sent on the serial device(s) is read
17       from a file or stdin in base (--base) defined notation. Data is sent on
18       the serial device(s) line by line.
19
20       In  read  (--read)  mode  data  to be read from the serial device(s) is
21       written to a file or stdout in base  (--base)  defined  notation.  Skim
22       through  the  options for several enhancements in the output. It's even
23       possible to  pass(--pass)  on  the  data  between  the  several  serial
24       devices.
25
26       Mandatory  arguments  to  long  options are mandatory for short options
27       too.
28
29       Generic options:
30
31       -B, --base=BASE
32              Specify the  base  unit  of  read/write  bytes.  Currently  only
33              2=binary and 16=hexadecimal are supported. The default base unit
34              is hexadecimal.
35
36              Selecting hexadecimal as the base unit, the input format  is  FD
37              or 0xFD. Of course all input is treated case-insensitive. Spaces
38              may or may not be included in the input. So DEADBEEF is  exactly
39              the same as DE AD   BE  EF.
40
41              Selecting binary as the base unit, the input format is 01000010.
42              Spaces may or may not be included in the input.  So  01000010111
43              is  exactely  the  same as 01000010 111. Yes, that's right! It's
44              perfectly fine to write less than 8 bits, excluding the  leading
45              zeros. Please understand if doing so, spaces are needed to sepa‐
46              rate the individual bytes in this case, but that's  obvious.  If
47              no  spaces are used, the parses reads the first 8 bits before it
48              continues with the next, as shown in the example above.
49
50       -l, --alias-separator
51              Use the given string as the alias separator. See --tty for  more
52              information.
53
54       -f, --file=NAME
55              In  write mode read the contents of the file given and send them
56              on the serial device(s) and in read mode write the  contents  of
57              the serial device(s) to the file given.
58
59       -h, --help
60              Shows a brief list of options.
61
62       -o, --count=BYTES
63              Exit after reading / writing the given amount of bytes.
64
65       -r, --read
66              Put  the  program  in read mode. This way you read the data from
67              the given serial device(s) and write it to  the  file  given  or
68              stdout  if  none  given.   See the read options section for more
69              read specific options.
70
71       -t, --tty=NAME:ALIAS
72              The serial device to read from or write to. Use  multiple  times
73              to  read/write from/to more than one serial device(s). For handy
74              reference you can also separate an alias from the tty name  with
75              a  collon  ':'.  If  a collon is for some strange reason part of
76              your device name, you can use the  --alias-separator  option  to
77              specify  another separation string. If an alias is given it will
78              be used as the name of the serial device.
79
80       -v, --version
81              Output the version information, a small GPL notice and exit.
82
83       -w, --write
84              Put the program in write mode. This way you  read  data  from  a
85              given  file  or  stdin  if none given and write it to the serial
86              device(s) given. See the write options section  for  more  write
87              specific options.
88
89       Read options:
90
91       -a, --ascii
92              Besides  the  normal  output  of the data, also display an extra
93              column with the data in the ASCII representation. Non  printable
94              characters  are  displayed as a dot '.'.  The ASCII data is dis‐
95              played after the normal data.
96
97       -b, --byte-count
98              Besides the normal output also display an extra column with  the
99              current  index  number  of the byte in the output. These numbers
100              are displayed in front of the normal output.  When  readin  from
101              multiple  serial  devices at the same time the index number will
102              increase per serial device.
103
104       -C, --control
105              Monitor modem control bits (line enable,  data  terminal  ready,
106              request  to  send,  secondary TXD, secondary RXD, clear to send,
107              carrier detect, ring and data set ready) too and notify changes.
108              Use  the  --control-poll option to specify how often to poll for
109              the bits.
110
111       -D, --control-poll=MICROSECONDS
112              The control poll is  the  amount  of  microseconds  to  wait  in
113              between  two checks of the modem control bits if nothing else is
114              happening.
115
116       -P, --pass
117              This one passes all the data between the serial  devices.  Handy
118              if  you  want  to  put your serial sniffer in between the serial
119              devices you want to sniff.
120
121       -q, --pty=:ALIAS
122              The pseudo-terminal device to read from. Use multiple  times  to
123              read  from  more  than  one pseudo-terminal device(s). For handy
124              reference you can also use an alias to name the pty.  Make  sure
125              it starts with a collon ':'. Use the --alias-separator option if
126              you for some reason don't like to use a collon.  If an alias  is
127              given it will be used as the name of the pseudo-terminal device.
128
129       -e, --timing-delta=MICROSECONDS
130              The timing delta is the amount of microseconds between two bytes
131              that the latter is considered to be part of a new  package.  The
132              default  is 100 miliseconds. Use this option in conjunction with
133              the --timing-print option.
134
135       -g, --timing-print
136              Print a line of timing information before every continues stream
137              of  bytes. When multiple serial devices are given also print the
138              name or alias of the device where the data is coming from.
139
140       -i, --width=WIDTH
141              The number of bytes to display on one line. The default is 16.
142
143       -A, --append
144              Append to the output file instead of overwriting. The default is
145              to overwrite.
146
147       -S, --append-separator
148              Use the given string as the append separator. The string is pro‐
149              cessed and the '\n' sequence transforms into a real newline.  So
150              far  no  other  sequences  do anything special. The default is a
151              single newline character.
152
153       Write options:
154
155       -c, --checksum
156              Append a single checksum byte to the line of data written to the
157              serial  device(s)  chosen.  This checksum is a simple modulo 256
158              addition of all input bytes on a line.
159
160       -z, --crc8=POLY
161              Append a crc8 checksum to the line of data written to the serial
162              device(s)  chosen.  Use the optionally given poly as the polyno‐
163              mial. Specify the polynomial as hexadecimal value,  as  in  0x07
164              (the default).
165
166       -y, --crc16=POLY
167              Append  a  crc16  checksum  to  the  line of data written to the
168              serial device(s) chosen.  Use the optionally given poly  as  the
169              polynomial.  Specify  the polynomial as hexadecimal value, as in
170              0xA001 (the default).
171
172       -k, --delay-byte=MICROSECONDS
173              This delay is an optional amount  of  microseconds  to  wait  in
174              between every input byte is sent on the serial device(s).
175
176       -d, --delay-line=MICROSECONDS
177              This  delay  is  an  optional  amount of microseconds to wait in
178              between every input line is sent on the serial device(s).
179
180       -j, --fuck-up
181              This is the special fuck up option. When the  calculation  of  a
182              checksum  is  chosen (see checksum and crc* options) the checkum
183              will be crippled on purpose. Carefully named after  the  special
184              Jan Arie de Bruin 'fuck up crc' button.
185
186       -n, --no-send
187              Do  not  actually send the bytes on the serial device(s). Rather
188              pointless, but seemed one day long ago to be a rather handy fea‐
189              ture.
190
191       -p, --print
192              Besided  sending the data on the serial device(s) also write the
193              data to stdout.
194
195       -s, --size=SIZE
196              The maximum number of bytes per  line  to  send  on  the  serial
197              device(s). The default is 22, coming from back in the Cham2 days
198              of the program.
199

DIAGNOSTICS

201       Normally, exit status is 0 if the program did run with no problem what‐
202       soever.  If  the  exit  status  is  not  equal to 0 an error message is
203       printed on stderr which should help you solve the problem.
204

BUGS

206       Order of bytes broke when reading several tty devices at once
207
208       The display of incoming bytes can be broke  if  you  use  multiple  tty
209       devices  to  read from. At the moment I do not have a solution for this
210       problem. Since I use select() to watch  the  several  tty  devices  and
211       after  the  select()  I  have to read() them one by one, I can not com‐
212       pletely 100% display which bytes came  after  which  on  different  tty
213       devices. Take the example below:
214
215              $ jpnevulator --ascii --timing-print --tty /dev/ttyS0 --tty /dev/ttyUSB0 --read
216              2006-05-30 13:23:49.461075: /dev/ttyS0
217              00 00 05 3B 0D 00 00 05                         ...;....
218              2006-05-30 13:23:49.461113: /dev/ttyUSB0
219              00 05 3B 0D 00 00 05 3B 0D                      ..;....;.
220              2006-05-30 13:23:49.473074: /dev/ttyS0
221              3B 0D 00 00 05 3B 0D                            ;....;.
222              2006-05-30 13:23:49.473105: /dev/ttyUSB0
223              00 12 05 06 39 00 12 05 06 39 1F 00 22 80 00 0E ....9....9.."...
224              $
225
226       And now see the order in which things really got sent on the line:
227
228              /dev/ttyS0:
229              00 00 05 3B 0D
230              /dev/ttyUSB0:
231              00 00 05 3B 0D
232              /dev/ttyS0:
233              00 00 05 3B 0D
234              /dev/ttyUSB0:
235              00 00 05 3B 0D
236              /dev/ttyS0:
237              00 00 05 3B 0D
238              /dev/ttyUSB0:
239              00 00 05 3B 0D 00 12 05 06 39 00 12 05 06 39 ...
240
241       As  you  can  see  /dev/ttyUSB0 receives the echo of all things sent by
242       /dev/ttyS0.  This is exactly what happens. But since there does exist a
243       small  time  between  the select() who is happy expressing something is
244       available and the read() who does get the available  data,  some  extra
245       data will be available. I have no idea on how I can use high level sys‐
246       tem call like select() and read() and be still able to put the bytes in
247       the correct order. Anyone an idea?
248

AUTHOR

250       Written by Freddy Spierenburg.
251

REPORTING BUGS

253       Report bugs to <freddy@snarl.nl>.
254
256       Copyright © 2006-2020 Freddy Spierenburg
257
258
259
260jpnevulator 2.3.5                  May 2020                     JPNEVULATOR(1)
Impressum