From f6637983f54e41a9a330b7b003cc951af40d8c0b Mon Sep 17 00:00:00 2001
From: Dmitri Gavrilov <gavrilov.dvs@gmail.com>
Date: Sun, 10 Mar 2024 15:25:11 -0400
Subject: [PATCH] Documentation on abs.timestamps

---
 docs/user/tutorials/commandline-hdf.rst | 59 +++++++++++++++++++++++++
 tests/test_cli.py                       | 11 +++--
 2 files changed, 66 insertions(+), 4 deletions(-)

diff --git a/docs/user/tutorials/commandline-hdf.rst b/docs/user/tutorials/commandline-hdf.rst
index 28b5f0cec..51bb5881a 100644
--- a/docs/user/tutorials/commandline-hdf.rst
+++ b/docs/user/tutorials/commandline-hdf.rst
@@ -74,6 +74,65 @@ If you have h5diff you can check the contents are the same::
     $ h5diff /tmp/panda-capture-1.h5 /tmp/panda-capture-2.h5
     $ h5diff /tmp/panda-capture-1.h5 /tmp/panda-capture-3.h5
 
+Absolute timestamps
+-------------------
+
+Starting with v3.0, PandABox firmware supports absolute timestamping of
+the collected data. PandA still collects relative timestamps for
+individual data points that are saved as arrays to HDF5 file. In addition,
+the absolute timestamp for the start of the measurement is saved to HDF5
+file and can be used to convert relative timestamps to absolute timestamps
+
+The absolute timestamp is saved as a set of attributes of the root group of
+the HDF5 file and includes the following parameters:
+
+- ``arm_time`` - the time when the Panda (PCAP block) was armed, saved as
+  a string in the ISO 8601 UTC format. Empty string if the absolute timestamps
+  were not is received from Panda. This parameter is mostly used for debugging.
+
+- ``start_time`` - the start time (PCAP block is armed and enabled) of
+  the measurement in seconds since the epoch, saved as a string in the
+  ISO 8601 UTC format. Empty string if the absolute timestamps were not is
+  received from Panda.
+
+- ``hw_time_offset_ns`` - the offset in nanoseconds (*int64*) that should be added to
+  to ``start_time`` to get accurate absolute timestamps. The parameter is
+  used only if Panda is configured to use hardware-based absolute timestamps
+  (PTP or MRF), otherwise it set to ``0``. The parameter is set to ``-1`` in
+  case IOC failed to interpret the parameter as *int64*.
+
+The following code may be used to read the absolute timestamp from the HDF5 file.
+Use ``pandas.Timestamp`` object if nanosecond accuracy is required (standard
+``dataframe`` object is limited to microsecond precision). ::
+
+    import h5py
+    import pandas as pd
+
+    with h5py.File('data/panda_rbdata_20240305_152712.h5', 'r') as f:
+        arm_time = f.attrs['arm_time']
+        start_time = f.attrs['start_time']
+        hw_time_offset_ns = f.attrs['hw_time_offset_ns']
+
+        print(f'Arm time: {arm_time!r}')
+        print(f'Start time: {start_time!r}')
+        print(f'Hardware time offset: {hw_time_offset_ns!r} ns')
+
+        if start_time:
+            # Compute and print the start time that includes the offset
+            ts_start = pd.Timestamp(start_time)
+            if hw_time_offset_ns > 0:
+                ts_start += pd.Timedelta(nanoseconds=hw_time_offset_ns)
+            print(f'Start TS including the offset: {ts_start}')
+
+
+    Output:
+
+    Arm time: '2024-03-05T20:27:12.607841574Z'
+    Start time: '2024-03-05T20:27:12.605729480Z'
+    Hardware time offset: 2155797 ns
+    Start TS including the offset: 2024-03-05T20:27:08.605729480Z
+
+
 Collecting more data faster
 ---------------------------
 
diff --git a/tests/test_cli.py b/tests/test_cli.py
index 21c2bf390..e8559b464 100644
--- a/tests/test_cli.py
+++ b/tests/test_cli.py
@@ -7,10 +7,13 @@
 from click.testing import CliRunner
 
 from pandablocks import cli
-from pandablocks.hdf import (GATE_DURATION_FIELD, SAMPLES_FIELD,
-                             HDFDataOverrunException)
-from tests.conftest import (STATE_RESPONSES, STATE_SAVEFILE, DummyServer,
-                            assert_all_data_in_hdf_file)
+from pandablocks.hdf import GATE_DURATION_FIELD, SAMPLES_FIELD, HDFDataOverrunException
+from tests.conftest import (
+    STATE_RESPONSES,
+    STATE_SAVEFILE,
+    DummyServer,
+    assert_all_data_in_hdf_file,
+)
 
 
 @pytest.mark.parametrize("samples_name", [GATE_DURATION_FIELD, SAMPLES_FIELD])