@science-corporation/synapse 2.0.0 → 2.2.2

package/synapse-api/api/tap.proto

@@ -0,0 +1,35 @@
+syntax = "proto3";
+
+package synapse;
+
+enum TapType {
+    TAP_TYPE_UNSPECIFIED = 0;
+
+    // The tap will be producing data
+    TAP_TYPE_PRODUCER = 1;
+
+    // The tap type will be consuming data
+    TAP_TYPE_CONSUMER = 2; 
+}
+
+message TapConnection {
+    // Unique name id for this tap
+    string name = 1;
+
+    // What is the zmq endpoint to connect to
+    string endpoint = 2;
+
+    // What is the protobuf message to expect over this 
+    string message_type = 3;
+
+    // Is this tap meant to be producing or consuming
+    TapType tap_type = 4;
+}
+
+message ListTapsQuery {
+
+}
+
+message ListTapsResponse {
+    repeated TapConnection taps = 1;
+}

package/synapse-api/api/time.proto

@@ -0,0 +1,53 @@
+syntax = "proto3";
+
+package synapse;
+
+/**
+ * Used for precise time synchronization over UDP between clients and a server
+ * In most cases, the server is the Synapse device.enum
+ * 
+ * How it works:
+ *  1. Client generates a random client_id on first connection
+ *  2. Client increments the sequence number on each packet (to detect drops)
+ *  3. Client records the send time and sends the packet to the server over udp.
+ *    - The server port will be available through the Status message
+ *    - Try to timestamp the packet as close as possible to the send to minimize
+ *      the calculated offset error. Future improvements could support hardware timestamps
+ *  4. Server records the receive time
+ *  5. Server immediately echos it back to the client, recording the send time
+ *  6. Client records the receive time when the packet returns
+ * 
+ * With these times, the client can calculate
+ *  - Round Trip Time: (client_receive_time_ns - client_send_time_ns)
+ *  - Network Latency (assumes symmetric paths): rtt / 2
+ *  - Clock offset: https://en.wikipedia.org/wiki/Network_Time_Protocol#Clock_synchronization_algorithm
+ * 
+ * Implementation notes:
+ *  - All timestamps are monotonic nanoseconds since Unix epoch
+ *  - The server acts as a passive reflector
+ *  - Multiple sync packets (8 or so) should be sent with a short period (200 ms) between
+*/
+message TimeSyncPacket {
+    fixed32 client_id = 1;
+    fixed32 sequence = 2;
+
+    fixed64 client_send_time_ns = 3;
+    fixed64 server_receive_time_ns = 4;
+    fixed64 server_send_time_ns = 5;
+    fixed64 client_receive_time_ns = 6;
+}
+
+// Defines the time synchronization method for device timestamps
+enum TimeSource {
+    TIME_SOURCE_UNKNOWN = 0;
+        
+    // Use std::chrono::steady_clock (monotonic, immune to system time changes)
+    // Note: The epoch is implementation-defined (often system boot time)
+    TIME_SOURCE_STEADY_CLOCK = 1;
+  
+    // Calculate timestamps based on sample counter and sampling rate
+    // counter_diff = (counter - first_counter)
+    // timestamp_ns = (counter_diff * 1e9 / sample_rate) + initial_steady_clock_value
+    // Where initial_steady_clock_value = get_steady_clock_now() at start
+    TIME_SOURCE_SAMPLE_COUNTER = 2;
+}