py_tsip_proxy : a simple proxy for a Trimble Thunderbolt GPS

py_tsip_proxy is a proxy for the Trimble Standard Interface Protocol (TSIP).
It allows several clients to connect to one single TSIP capable device.
Assuming the TSIP capable device is a GPS controlled clock (e.g. timing
standard, GPSDO (GPS disciplined oscillator), a logfile can be written to disk
for monitoring purposes. This software lives at https://github.com/vogelchr/py_tsip_proxy
and has been tested with a Trimbe Thunderbolt http://www.leapsecond.com/tbolt-faq.htm.

*** Usage ***

: usage: py_tsip_proxy.py [-h] [-d] [-t PORT] [-b BAUD] [-l PORT] [-m PORT]
:                         [-o BASE] [-f]
:                         TTY|HOST
:
: optional arguments:
:   -h, --help            show this help message and exit
:   -d, --debug           Write packets sent/received by each client. (def:
:                         don't)
:
: Serial or Network Connection to GPS Device:
:   -t PORT, --tcp PORT   Use TCP connection and specify port number. (def: use
:                         serial)
:   -b BAUD, --baud BAUD  Baudrate to use on serial device (def: 9600)
:   TTY|HOST              Serial device or hostname when using TCP connection.
:
: Listening Sockets:
:   -l PORT, --listen PORT
:                         Listen for local connections on tcp port whose packets
:                         will be forwarded to the device (def: 4321).
:   -m PORT, --listen-mute PORT
:                         Listen for local connections on tcp port whose packets
:                         will not be forwarded to the device (def: None).
:
: Logging to ASCII Files:
:   -o BASE, --logfile BASE
:                         Write GPS stats (primary and supplemental timing
:                         information and GPS satellite data) to logfile, files
:                         will be named BASE_YYYYmmdd.txt and reopened at
:                         midnight local time. (def: no logfile)
:   -f, --flush           Flush logfiles after each line. Useful if you are
:                         watching with "tail -f", but wears out storage faster
:                         as the file will fsync() after every single line.
:                         (def: no flush)

*** Prerequisites ***

This program requires pyserial-asyncio. You can get it here:

	https://pypi.python.org/pypi/pyserial-asyncio

Install via...
  $ pip install pyserial-asyncio
(maybe use pip install --user, or use a virtualenv).

*** Running the Program ***

Run on the device connected to your GPS' serial port as such:

   ./py_tsip_proxy.py -b 9600 /dev/ttyUSB0 

...or, when the GPS is connected to a terminal server, at the given
address and port (in this example: host 192.168.2.134, port 4001):

   ./py_tsip_proxy.py -t 4001 192.168.2.134

Then you can connect to the local machine running the proxy at port 4321.
This port can be changed using the "-l PORT" option.

*** Muted Clients ***

If you want to allow some software to receive TSIP packets, but not be able to
send them to the thunderbolt, then use the "-m PORT" option to start up
a second port whose sent data will be thrown away.

*** Logfiles ***

Logfiles will be written when giving the "-o" option. With a option of
"-o logfile", filenames will be logfile_20170903.txt (yyyymmdd: four digit
year, two digit month, two digit day) and re-created daily.

Contents of the logfile is:

!                 --GPS--
!  Timestamp    TOW    week tfl  r d critic minor  dec  a offs   dac      temp
!-------------:-------:----:----:-:-:------:------:----:-:------:--------:------
1504389595.191  597613  940 0x00 7 0 0x0000 0x0000 0x00 0 -1.901 +0.07811 40.215
1504389596.191  597614  940 0x00 7 0 0x0000 0x0000 0x00 0 -2.038 +0.07811 40.215
1504389597.191  597615  940 0x00 7 0 0x0000 0x0000 0x00 0 -2.162 +0.07811 40.215
1504389598.191  597616  940 0x00 7 0 0x0000 0x0000 0x00 0 -2.243 +0.07811 40.215
!    prn signal cphase doppler signal az    elo 
!----:--:-----:-------:-------:-----:-----:-----
# SAT 32 37.70  4008.8  2148.6 37.70 117.1  34.3
# SAT 08 42.10 15654.4  -530.3 42.10 214.5  75.2
# SAT 10 43.90 13059.7 -2264.0 43.90  58.4  46.5
# SAT 11 36.30  7917.7  2659.9 36.30 289.3  44.7
# SAT 27 38.30 14732.4 -2783.8 38.30 154.0  45.6

  tfl: Timing Flags, r: receiver mode, d: disciplining mode,
  critic: critical alarms, minor: minor alarms, dec: GPS decoding status,
  a: disciplining activity, offs: PPS offset (ns), dac: DAC output (volt),
  temp: temperature (degrees celsius)

  prn/signal/cphase/doppler : from Raw Data Measurement Data
  prn/signal/az/elo         : From Satellite Tracking Status

  signal : signal level
  cphase : Code Phase
  doppler : signal doppler
  az/elo: azimuth/elongation

The flags are explained in the manual you can find with a web search:
 Trimble Thunderbolt E GPS Disciplined Clock User Guide Appendix A
See the sections on
 Report Packet 0x8F-AB Primary Timing Packet
and
 Report Packet 0x8F-AC Supplemental Timing Packet.

If you specify the "--flush"/"-f" option, then the file will be synced
to disk after every single line. So every line will be visible when
doing a "tail -f", but it will also wear out your storage, e.g. sd-cards,
much faster.

*** Debug ***

With the "-d" flag, all packets received from each client will be printed
in an abbreviated form:

timestamp               receiving connection            packet len payload
-----------------------:----------------------------:--:-----:----:----------------------
2017-09-03 11:35:17,045 Master 192.168.178.59/4001   << 8f-ab (18) 8fab000086e703ad0012..
2017-09-03 11:35:17,110 Master 192.168.178.59/4001   << 6d-5d (23) 6d5d0000000000000000..
2017-09-03 11:35:17,113 Slave  127.0.0.1/32842       << 1f    (01) 1f
2017-09-03 11:35:17,133 Slave  127.0.0.1/32842       << 8e-41 (02) 8e41
2017-09-03 11:35:17,153 Slave  127.0.0.1/32842       << 8e-42 (02) 8e42
2017-09-03 11:35:17,173 Slave  127.0.0.1/32842       << 1c-01 (02) 1c01
2017-09-03 11:35:17,194 Slave  127.0.0.1/32842       << 1c-03 (02) 1c03
2017-09-03 11:35:17,214 Slave  127.0.0.1/32842       << 3c-46 (02) 3c46
2017-09-03 11:35:17,220 Master 192.168.178.59/4001   << 8f-ac (69) 8fac070001000000f000..

"packet" is just the first two bytes of the payload. Payload is just a hexdump.

*** Typical Usage ***

	[thinkstation /home/chris/py_tsip_proxy (master)]
	$ ./py_tsip_proxy.py -o logfile -m 4322 -t 4001 192.168.178.59 
	2017-09-03 11:36:39,567 Master 192.168.178.59/4001   Connection made.
	2017-09-03 11:36:39,568 Master 192.168.178.59/4001   new slave Logger
	2017-09-03 11:36:40,221 Logger: appending to logfile logfile_20170903.txt.
	(...)

Then, you can start "Lady Heather" (the most famous monitoring tool) with
the following command line:

	wine ./heather.exe /ip=127.0.0.1:4321 /vx /ta /wa=tbolt.log /tw=100

The proxy will then output a few "received junk" lines as heather tries to
probe several different types of GPS receivers:

	(...)
	2017-09-03 11:41:26,138 Slave  127.0.0.1/46904       Connection made.
	2017-09-03 11:41:26,138 Master 192.168.178.59/4001   new slave Slave  127.0.0.1/46904      
	2017-09-03 11:41:26,557 Slave  127.0.0.1/46904       received junk byte 3f
	2017-09-03 11:41:26,557 Slave  127.0.0.1/46904       received junk byte 57
	2017-09-03 11:41:26,557 Slave  127.0.0.1/46904       received junk byte 41

You can run the Thunderbolt Monitor also via wine, but you have to redirect
the COM port.

	# Workaround: wine seems to re-create the links in ~/.wine/dosdevices
	# upon first start, so first run a dummy application and leave it
	# running until tboltmon has opened its com port.

	wine notepad.exe

	cd ~/.wine/dosdevices
	socat pty,link=./com1,raw,echo=0 tcp:localhost:4321 &
	cd ~/.wine/drive_c/Tboltmon/
	wine ./tboltmon.exe
	  -> choose com1