Adds support for eye events (blinks and fixations) in the simple API.

examples/async/stream_eye_events.py

@@ -1,7 +1,12 @@
 import asyncio
 import contextlib
+from datetime import datetime, timezone
 
 from pupil_labs.realtime_api import Device, Network, receive_eye_events_data
+from pupil_labs.realtime_api.streaming.eye_events import (
+    BlinkEventData,
+    FixationEventData,
+)
 
 
 async def main():
@@ -22,7 +27,20 @@ async def main():
         async for eye_event in receive_eye_events_data(
             sensor_eye_events.url, run_loop=restart_on_disconnect
         ):
-            print(eye_event)
+            if isinstance(eye_event, BlinkEventData):
+                time_sec = eye_event.start_time_ns // 1e9
+                blink_time = datetime.fromtimestamp(time_sec, timezone.utc)
+                print(f"[BLINK] blinked at {blink_time.strftime('%H:%M:%S')} UTC")
+
+            elif isinstance(eye_event, FixationEventData) and eye_event.event_type == 0:
+                angle = eye_event.amplitude_angle_deg
+                print(f"[SACCADE] event with {angle:.0f}° amplitude.")
+
+            elif isinstance(eye_event, FixationEventData) and eye_event.event_type == 1:
+                duration = (eye_event.end_time_ns - eye_event.start_time_ns) / 1e9
+                print(f"[FIXATION] event with duration of {duration:.2f} seconds.")
+
+            # print(eye_event) # This will print all the fields of the eye event
 
 
 if __name__ == "__main__":

examples/simple/stream_eye_events.py

@@ -0,0 +1,42 @@
+from datetime import datetime, timezone
+
+from pupil_labs.realtime_api.simple import discover_one_device
+from pupil_labs.realtime_api.streaming.eye_events import (
+    BlinkEventData,
+    FixationEventData,
+)
+
+# Look for devices. Returns as soon as it has found the first device.
+print("Looking for the next best device...")
+device = discover_one_device(max_search_duration_seconds=10)
+if device is None:
+    print("No device found.")
+    raise SystemExit(-1)
+
+# device.streaming_start()  # optional, if not called, stream is started on-demand
+
+try:
+    while True:
+        eye_event = device.receive_eye_events()
+        if isinstance(eye_event, BlinkEventData):
+            time_sec = eye_event.start_time_ns // 1e9
+            blink_time = datetime.fromtimestamp(time_sec, timezone.utc)
+            print(f"[BLINK] blinked at {blink_time.strftime('%H:%M:%S')} UTC")
+
+        elif isinstance(eye_event, FixationEventData) and eye_event.event_type == 0:
+            angle = eye_event.amplitude_angle_deg
+            print(f"[SACCADE] event with {angle:.0f}° amplitude.")
+
+        elif isinstance(eye_event, FixationEventData) and eye_event.event_type == 1:
+            duration = (eye_event.end_time_ns - eye_event.start_time_ns) / 1e9
+            print(f"[FIXATION] event with duration of {duration:.2f} seconds.")
+
+        # print(eye_event) # This will print all the fields of the eye event
+
+except KeyboardInterrupt:
+    pass
+
+finally:
+    print("Stopping...")
+    # device.streaming_stop()  # optional, if not called, stream is stopped on close
+    device.close()  # explicitly stop auto-update

setup.cfg

@@ -28,11 +28,12 @@ install_requires =
     av
     beaupy
     numpy>=1.20
-    pl-neon-recording>=0.1.4
     pydantic>=2
     websockets
     zeroconf
     importlib-metadata;python_version<"3.8"
+    pl-neon-recording==0.1.12;python_version=="3.9"
+    pupil-labs-neon-recording>=1.0.0;python_version>="3.10"
     typing-extensions;python_version<"3.8"
 python_requires = >=3.9
 include_package_data = true

src/pupil_labs/realtime_api/models.py

@@ -8,6 +8,7 @@
 from datetime import datetime
 from functools import partial
 from textwrap import indent
+from typing import Annotated
 from uuid import UUID
 
 from pydantic import (
@@ -22,7 +23,7 @@
     create_model,
 )
 from pydantic.dataclasses import dataclass as dataclass_pydantic
-from typing_extensions import Annotated, Literal
+from typing_extensions import Literal
 
 logger = logging.getLogger(__name__)
 
@@ -179,7 +180,7 @@ def rec_duration_seconds(self) -> float:
 
 
 def _init_cls_with_annotated_fields_only(cls, d: T.Dict[str, T.Any]):
-    return cls(**{attr: d.get(attr, None) for attr in cls.__annotations__})
+    return cls(**{attr: d.get(attr) for attr in cls.__annotations__})
 
 
 class UnknownComponentError(ValueError):
@@ -305,7 +306,8 @@ def direct_eye_events_sensor(self) -> T.Optional[Sensor]:
         return next(
             self.matching_sensors(Sensor.Name.EYE_EVENTS, Sensor.Connection.DIRECT),
             Sensor(
-                sensor=Sensor.Name.EYES.value, conn_type=Sensor.Connection.DIRECT.value
+                sensor=Sensor.Name.EYE_EVENTS.value,
+                conn_type=Sensor.Connection.DIRECT.value,
             ),
         )
 
@@ -390,7 +392,7 @@ def _simple_model_validator(self):
             answer_input_type = conlist(
                 answer_input_type,
                 min_length=1 if self.required else 0,
-                max_length=None if self.widget_type in {"CHECKBOX_LIST"} else 1,
+                max_length=None if self.widget_type == "CHECKBOX_LIST" else 1,
             )
         else:
             if self.required:
@@ -431,7 +433,7 @@ def _api_model_validator(self):
         answer_input_type = conlist(
             answer_input_entry_type,
             min_length=1 if self.required else 0,
-            max_length=None if self.widget_type in {"CHECKBOX_LIST"} else 1,
+            max_length=None if self.widget_type == "CHECKBOX_LIST" else 1,
         )
         return (answer_input_type, field)
 
@@ -462,7 +464,7 @@ def convert_from_simple_to_api_format(self, data: T.Dict[str, T.Any]):
             api_format[question_id] = value
         return api_format
 
-    def convert_from_api_to_simple_format(self, data: T.Dict[str, T.List[str]]):
+    def convert_from_api_to_simple_format(self, data: T.Dict[str, list[str]]):
         simple_format = {}
         for question_id, value in data.items():
             question = self.get_question_by_id(question_id)
@@ -598,9 +600,9 @@ def __str__(self):
             error_lines = []
             for error in self.errors:
                 error_msg = ""
-                error_msg += f'location: {error["loc"]}\n'
-                error_msg += f'  input: {error["input"]}\n'
-                error_msg += f'  message: {error["msg"]}\n'
+                error_msg += f"location: {error['loc']}\n"
+                error_msg += f"  input: {error['input']}\n"
+                error_msg += f"  message: {error['msg']}\n"
                 question = error.get("question")
                 if question:
                     error_msg += (
@@ -618,6 +620,6 @@ def __str__(self):
                 name = self.template.name
             elif isinstance(self.template, TemplateItem):
                 name = self.template.title
-            return f"{name} ({self.template.id}) validation errors:\n" f"{error_lines}"
+            return f"{name} ({self.template.id}) validation errors:\n{error_lines}"
         except Exception as e:
             return f"InvalidTemplateAnswersError.__str__ error: {e}"

src/pupil_labs/realtime_api/simple/_utils.py

@@ -111,8 +111,7 @@ def _start_streaming_task_if_intended(self, sensor):
     def _stop_streaming_task_if_running(self):
         if self._streaming_task is not None:
             logger_receive_data.info(
-                f"Cancelling prior streaming connection to "
-                f"{self._recent_sensor.sensor}"
+                f"Cancelling prior streaming connection to {self._recent_sensor.sensor}"
             )
             self._streaming_task.cancel()
             self._streaming_task = None
@@ -138,7 +137,10 @@ async def append_data_from_sensor_to_queue(self, sensor: Sensor):
                 device._most_recent_item[name].append(item)
                 if name == Sensor.Name.GAZE.value:
                     device._cached_gaze_for_matching.append(
-                        (item.timestamp_unix_seconds, item)
+                        (
+                            item.timestamp_unix_seconds,
+                            item,
+                        )
                     )
                 elif name == Sensor.Name.WORLD.value:
                     # Matching priority
@@ -211,9 +213,15 @@ async def append_data_from_sensor_to_queue(self, sensor: Sensor):
                     )
                 elif name == Sensor.Name.EYES.value:
                     device._cached_eyes_for_matching.append(
-                        (item.timestamp_unix_seconds, item)
+                        (
+                            item.timestamp_unix_seconds,
+                            item,
+                        )
                     )
-                elif name == Sensor.Name.IMU.value:
+                elif (
+                    name == Sensor.Name.IMU.value
+                    or name == Sensor.Name.EYE_EVENTS.value
+                ):
                     pass
                 else:
                     logger.error(f"Unhandled {item} for sensor {name}")