Merge pull request #45 from ethz-asl/cleanup/betterDoc

Cleanup/better doc

Author: HannesSommer

cuckoo_time_translator/msg/DeviceTimestamp.msg

@@ -1,7 +1,25 @@
+####
+# This message's purpose is to support the user when tuning device time translation.
+# It collects all the relevant input and output such that a mutual comparison of various configuration (algorithms / parametes) and the current configuration in the driver is possible given a single bag file.
+# It can also be used to inspect the performance of the current configuration.
+####
+
+# The standard header's timestamp should be the device time translated into local / system time, potentially plus an artificial offset (see below)
 Header header
+
+# the device clock stamp of the event in the device (e.g. LIDAR beam fire)
 uint64 event_stamp
+# the device clock stamp of the transmission event (e.g. shortly before the transmission (sending) starts) if available separately. Otherwise equal to event_stamp.
 uint64 transmit_stamp
+
+# the local / system clock time of when the device's message was received.
 time receive_time
+
+# the artifical offeset in seconds that was added to the header's timestamp after translating the hardware time (e.g. to correct an known transport delay (would be negative then))
 float32 offset_secs
+
+# correction_secs := receiveTime - translatedTime in seconds (without the offset above)
 float32 correction_secs
+
+# the algorithm employed to compute the timestamp in the header
 uint8 filter_algorithm

cuckoo_time_translator/package.xml

@@ -2,7 +2,12 @@
 <package format="2">
   <name>cuckoo_time_translator</name>
   <version>0.0.0</version>
-  <description>cuckoo_time_translator</description>
+  <description>This library intends to do most of the dirty work required within a device driver that emoploys one way device time translation.
+  This includes:
+  * handling the one way translator
+  * sending special timing messages (DeviceTimestamp) for debugging and evaluation (e.g. with ctt_introspect in the cuckoo_time_translator_python package)
+  * provide dynamic confiugration for the one way translation algorithm
+   </description>
 
   <author email="hannes.sommer@mavt.ethz.ch">Hannes Sommer</author>
   <maintainer email="hannes.sommer@mavt.ethz.ch">Hannes Sommer</maintainer>

cuckoo_time_translator_algorithms/package.xml

@@ -3,7 +3,7 @@
   <name>cuckoo_time_translator_algorithms</name>
   <version>0.0.1</version>
   <description>
-    Algorithms for translating times emitted by other (cheap) clocks into local system time.
+    Algorithms for translating times emitted by remote (cheap) clocks into local system time.
     The dominant application is translating hardware timestamps of a sensor into the system time of a receiving computer system.
   </description>
 

cuckoo_time_translator_python/package.xml

@@ -1,8 +1,11 @@
 <?xml version="1.0"?>
 <package format="2">
   <name>cuckoo_time_translator_python</name>
-  <version>0.0.0</version>
-  <description>cuckoo_time_translator_python</description>
+  <version>0.0.1</version>
+  <description>Export of some of the cuckoo_time_translator_algorithms functionality to python.
+  In particular the one way translators.
+  Additionally, there is the ctt_introspect.py scipt, that can help debugging and evaluating one way translators running in a hardware driver using cuckoo_time_translator.
+  </description>
 
   <author email="hannes.sommer@mavt.ethz.ch">Hannes Sommer</author>
   <maintainer email="hannes.sommer@mavt.ethz.ch">Hannes Sommer</maintainer>

cuckoo_time_translator_python/scripts/ctt_introspect.py

@@ -19,9 +19,9 @@
   parser.add_argument('bag', nargs=1, help='The path to the bag file containing the DeviceTimestamp messages')
   parser.add_argument('-t,--topic', dest='topic', nargs='+', help='The path to the bag file containing the DeviceTimestamp messages')
   parser.add_argument('-v,--verbose', dest='verbose', action='count', help='Increase verbosity (counted)')
-  parser.add_argument('-o,--output', dest='output', help='Output file to plot to (PDF)')
+  parser.add_argument('-o,--output', dest='output', help='Output file to plot to (PDF format)')
   parser.add_argument('-b,--baseLine', dest='baseLine', default="LeastSquares", help='Use this batch-method as base line; LeastSquare, ConvexHull, Index')
-  parser.add_argument('-f,--owts', dest='owts', default=OwtsDefault, help='Additional owts to compare with. Default: ' + OwtsDefault)
+  parser.add_argument('-f,--owts', dest='owts', default=OwtsDefault, help='Additional OWTs (one way translators) to compare with. Default: ' + OwtsDefault)
   parser.add_argument('--dontPlotReceiveTimes', action='store_true', help='don\'t plot receive timestamps')
   parser.add_argument('--dontPlotPreTranslated', action='store_true', help='don\'t plot pre-translated timestamps, i.e., translated in the device driver')
   parser.add_argument('--invalidate', action='store_true', help='invalidate any possibly existing cache')