auto-trainer-core 2.0.1.dev349__py3-none-any.whl

autotrainer/core/message/__init__.py

@@ -0,0 +1,26 @@
+import dataclasses
+from typing import Any, Tuple, Dict
+
+
+@dataclasses.dataclass
+class SystemDataArgsKwargs:
+    """A dedicated dataclass to pass data any desired args and/or kwargs as a single value for system commands"""
+
+    def __init__(self, *args, **kwargs):
+        super().__init__()
+        self.args = args
+        self.kwargs = kwargs
+
+    args: Tuple[Any] = ()
+    kwargs: Dict[str, Any] = dataclasses.field(default_factory=dict)
+
+
+from .audio_spectrum_message import AudioSpectrumMessage
+from .measurement_message import MeasurementMessageProtocol
+from .message_handler import MessageHandler
+from .motor_configuration_message import MotorConfigurations, ServoConfigMessage, \
+    StepperConfigMessage, Motor
+from .system_command_kind import SystemCommandKind
+from .system_message_handler import SystemMessageHandler
+from .system_status_message import SystemStatusMessageKind
+

autotrainer/core/message/audio_spectrum_message.py

@@ -0,0 +1,21 @@
+from typing import Protocol, List
+
+
+class AudioSpectrumMessage(Protocol):
+    @property
+    def when(self) -> float:
+        """Value of time.time() or equivalent absolute time provided by the hardware."""
+        pass
+
+    @property
+    def index(self) -> int:
+        """
+        A relative time index in nanoseconds. Provides finer resolution between measurements than absolute time may
+        provide on some platforms.  By default, would be provided by time.perf_counter_ns().
+        """
+        pass
+
+    @property
+    def  magnitudes(self) -> List[float]:
+        """The audio spectrum magnitudes in dB."""
+        pass

autotrainer/core/message/measurement_message.py

@@ -0,0 +1,61 @@
+from typing import Protocol
+
+
+class MeasurementMessageProtocol(Protocol):
+    """
+    MeasurementMessage defines the expected interface for measurement data provided by the hardware.  This is expected
+    object passed as part of a SystemStatusMessageKind.MEASUREMENTS message.
+    """
+
+    @property
+    def when(self) -> float:
+        """Value of time.time() or equivalent absolute time provided by the hardware."""
+        pass
+
+    # Deprecated
+    @property
+    def timestamp(self) -> int:
+        """
+        A relative time index in nanoseconds. Provides finer resolution between measurements than absolute time may
+        provide on some platforms.  By default, would be provided by time.perf_counter_ns().
+        """
+        pass
+
+    @property
+    def index(self) -> int:
+        """
+        A relative time index in nanoseconds. Provides finer resolution between measurements than absolute time may
+        provide on some platforms.  By default, would be provided by time.perf_counter_ns().
+        """
+        pass
+
+    @property
+    def weight(self) -> float:
+        """The load cell value in grams."""
+        pass
+
+    @property
+    def pressure(self) -> float:
+        """The force detector value in the range of [0, 1024]"""
+        pass
+
+    # Deprecated
+    @property
+    def switch(self) -> float:
+        """The head contact DIO value as 0 or 1."""
+        pass
+
+    @property
+    def temperature(self) -> float:
+        """The temperature in Celsius."""
+        pass
+
+    @property
+    def humidity(self) -> float:
+        """The relative humidity (%)."""
+        pass
+
+    @property
+    def head_contact(self) -> bool:
+        """The head contact DIO value state.  True if contact is made, False otherwise."""
+        pass

autotrainer/core/message/message_handler.py

@@ -0,0 +1,158 @@
+import functools
+import logging
+import threading
+import time
+from functools import partial
+from queue import Queue, Empty
+from threading import Thread
+from typing import Callable, Union, Any, Optional
+
+from autotrainer.core.logging import get_verbose_logger
+from ..observable_object import ObservableObject
+
+from .system_status_message import SystemStatusMessageKind
+
+logger = get_verbose_logger(__name__)
+
+TERMINATE = -1001
+
+
+class MessageHandler(ObservableObject):
+    """
+    Base class for handling messages that come from the hardware.  It has two primary purposes.
+
+    The first is to ensure that any middle-management of information or data happens in a separate thread from both the
+    hardware interfacing and any downstream consumers without requiring either the hardware code or the downstream code
+    to know whether that is taken care of or not - other than knowing to call start() on this object when ready to
+    receive messages.
+
+    The second is to insulate downstream consumers from any specifics of the hardware implementation such as how
+    commands are acknowledged, what capabilities different versions of the hardware may have, etc.  Subclasses for
+    elements such as pellet delivery, tunnel behavior, and sensor measurements present properties (with change
+    notification), callbacks, and other means of making the data available in a consistent format that downstream
+    consumers care about rather than as specifically implemented the hardware.
+    """
+    FIRMWARE_VERSION_PROPERTY = "firmware_version"
+
+    HEAD_MAGNET_INTENSITY_PROPERTY = "head_magnet_intensity"
+    HEAD_GATE_PROPERTY = "gate_angle"
+
+    DEVICE_X_PROPERTY = "device_x"
+    DEVICE_Y_PROPERTY = "device_y"
+    DEVICE_Z_PROPERTY = "device_z"
+
+    STEPPER_X_PROPERTY = "stepper_x"
+    STEPPER_Y_PROPERTY = "stepper_y"
+    STEPPER_Z_PROPERTY = "stepper_z"
+
+    LOAD_ARM_ANGLE_PROPERTY = "load_angle"
+    COVER_ARM_ANGLE_PROPERTY = "cover_angle"
+    TUNNEL_FAN_PROPERTY = "tunnel_fan"
+
+    FRONT_DOOR_PROPERTY = "front_door"
+    DRAWER_DOOR_PROPERTY = "drawer_door"
+    SPARE_DOOR_PROPERTY = "spare_door"
+    EXT_BUTTON_PROPERTY = "ext_button"
+
+    STIMULI_PROPERTY = "stimuli"
+    CONFIG_PROPERTY = "config"
+
+    # type hints helper:
+    # dynamic event:
+    ack_received: Callable[[str], None]
+
+    def __init__(self, input_queue: Queue, name: str = "message-handler", event_names=()):
+        super().__init__(event_names=event_names + ("ack_received",))
+        self._input_queue = input_queue
+        self._name = name
+        self._current_thread = None
+
+    def __del__(self):
+        thread = self._current_thread
+        if thread is not None:
+            self.request_terminate()
+
+    @property
+    def input_queue(self) -> Queue:
+        return self._input_queue
+
+    def start(self):
+        if self._current_thread is None or not self._current_thread.is_alive():
+            logger.verbose("Starting system message handler thread")
+            self._current_thread = Thread(
+                target=self.run, name=self.__class__.__name__,
+                daemon=True,  # in case main thread exits: also have the current handler thread to exit
+            )
+            self._current_thread.start()
+
+    def run(self):
+        try:
+            self._run()
+        except Exception as err:
+            logger.exception("Fatal error during run: %s", err)
+
+    def _run(self):
+        logger.debug(f"<{self._name}>: entering message event loop")
+        q_get = self._input_queue.get
+        task_done = self._input_queue.task_done
+        msg_received = self.message_received
+        tot_read_count = 0
+        t_next_check_size = time.perf_counter()
+        while True:
+            msg, data = q_get()
+            if __debug__:
+                tot_read_count += 1
+                t_now = time.perf_counter()
+                if t_now > t_next_check_size:
+                    logger.debug("system message handler input queue: size=%s read=%.1f / s",
+                                 self._input_queue.qsize(), tot_read_count / 60)
+                    t_next_check_size += 60
+                    tot_read_count = 0
+            if msg == TERMINATE:
+                task_done()
+                break
+            elif msg == SystemStatusMessageKind.ACKNOWLEDGE:
+                try:
+                    self.ack_received(data)
+                except Exception as err:
+                    logger.exception("Error during ack_received callback: %s", err)
+            elif msg == SystemStatusMessageKind.FIRMWARE_VERSION:
+                self.property_changed(MessageHandler.FIRMWARE_VERSION_PROPERTY, data, None)
+            else:
+                try:
+                    msg_received(msg, data)
+                except Exception as err:
+                    logger.exception("Error during msg_received callback: msg=%s err=%s ; data=%s",
+                                     msg, err, data)
+            task_done()
+        logger.debug(f"<{self._name}>: exiting message event loop")
+
+    def request_terminate(self):
+        """
+        Sends a termination request to the device reader queue.  The thread may have not yet terminated when this call
+        returns.
+        """
+        if self._input_queue is not None:
+            self._input_queue.put((TERMINATE, None))
+
+    def wait_terminated(self):
+        thread = self._current_thread
+        queue = self._input_queue
+        if thread is not None:
+            self._current_thread = None
+            thread.join(5)
+            if thread.is_alive():
+                logger.warning("message handler thread still alive")
+        if queue is not None:
+            self._input_queue = None
+            while not queue.empty():
+                try:
+                    obj = queue.get_nowait()
+                except Empty:
+                    break
+                logger.warning("drop unhandled %s ; %s", type(obj), obj)
+                queue.task_done()
+            queue.join()
+
+    def message_received(self, msg, _data):
+        pass

autotrainer/core/message/motor_configuration_message.py

@@ -0,0 +1,128 @@
+from typing import Protocol, Tuple
+from enum import IntEnum
+
+
+class Motor(IntEnum):
+    """
+    Identifiers for the different motor types
+    """
+
+    NONE = 0
+    TUNNEL_MAGNET_SERVO = 1
+    PELLET_X_MOTOR = 2
+    PELLET_Y_MOTOR = 3
+    PELLET_Z_MOTOR = 4
+    PELLET_COVER_SERVO = 5
+    PELLET_LOAD_SERVO = 6
+    TUNNEL_GATE_SERVO = 7
+    TUNNEL_FAN_SERVO = 8
+
+
+class StepperConfigMessage(Protocol):
+    """
+    Protocol for the interface for obtaining stepper motor configuration entities
+    """
+
+    @property
+    def motor(self) -> Motor:
+        """Motor associated with the configuration"""
+
+
+    @property
+    def maximum_velocity(self) -> float:
+        """Units: turns/sec"""
+
+    @property
+    def maximum_acceleration(self) -> float:
+        """Units: turns/sec^2"""
+
+    @property
+    def minimum_step_inverted(self) -> int:
+        """Units: 1/min step"""
+
+    @property
+    def steps_per_revolution(self) -> float:
+        """Units: steps/rev"""
+
+    @property
+    def flip_limit_orientation(self) -> int:
+        """
+        0 - Do no invert motor direction
+        1 - Invert motor direction
+        """
+
+
+class ServoConfigMessage(Protocol):
+    """
+    Protocol for the interface for obtaining servo motor configuration entities
+    """
+
+    @property
+    def motor(self) -> Motor:
+        """Motor associated with the configuration"""
+
+    @property
+    def maximum_velocity(self) -> float:
+        """Units: deg/sec"""
+
+    @property
+    def maximum_acceleration(self) -> float:
+        """Units: deg/sec^2"""
+
+    @property
+    def minimum_position(self) -> float:
+        """Units: deg"""
+
+    @property
+    def maximum_position(self) -> float:
+        """Units: deg"""
+
+    @property
+    def min_pwm_duration(self) -> float:
+        """Units: µs"""
+
+    @property
+    def max_pwm_duration(self) -> float:
+        """Units: µs"""
+
+    @property
+    def detach(self) -> bool:
+        """Is attach/detach used"""
+
+
+class MotorConfigurations(Protocol):
+    """
+    Protocol for access to a full set of motor configurations
+    """
+
+    @property
+    def magnet_config(self) -> Tuple[Motor, ServoConfigMessage]:
+        """The magnet config"""
+
+    @property
+    def gate_config(self) -> Tuple[Motor, ServoConfigMessage]:
+        """The gate config"""
+
+    @property
+    def load_config(self) -> Tuple[Motor, ServoConfigMessage]:
+        """The pellet-load config"""
+
+    @property
+    def cover_config(self) -> Tuple[Motor, ServoConfigMessage]:
+        """The pellet-cover config"""
+
+    @property
+    def x_config(self) -> Tuple[Motor, StepperConfigMessage]:
+        """The pellet stepper X motor & config"""
+
+    @property
+    def y_config(self) -> Tuple[Motor, StepperConfigMessage]:
+        """The pellet stepper Y motor & config"""
+
+    @property
+    def z_config(self) -> Tuple[Motor, StepperConfigMessage]:
+        """The pellet stepper Z motor & config"""
+
+    @property
+    def tunnel_fan_config(self) -> Tuple[Motor, ServoConfigMessage]:
+        """The tunnel-fan motor & config"""

autotrainer/core/message/system_command_kind.py

@@ -0,0 +1,74 @@
+from enum import IntEnum
+
+
+class SystemCommandKind(IntEnum):
+    """
+    This class defines the commands supported by the device.  If there is a response beyond acknowledgement, it is
+    defined in SystemStatusMessageKind.
+
+    Commands are sent to the device with optional data and context information.  The data is specific to the command
+    and may not be applicable to all commands.  The context information is provided by the caller and expected back
+    as part of the acknowledgement that the command is complete.  Note that complete may mean that the action is fully
+    executed (e.g., a move has reached its final position), not simply that the command was sent to the device.
+
+    The above is currently implemented and represented by the send_message() method in the DeviceConnection class.
+    """
+
+    # System commands unrelated to actual behavior.
+    REQUEST_VERSION = 1
+
+    # Actions nominally considered part of the tunnel/head fixation unit (magnet module in some nomenclature).
+    MOVE_MAGNET_SERVO = 101
+    UPDATE_SCALE_TARE = 102
+    OPEN_TUNNEL_GATE = 103
+    CLOSE_TUNNEL_GATE = 104
+
+    # Actions nominally considered part of the pellet delivery unit.
+    READ_MOTOR_CONFIGURATION = 201
+    WRITE_MOTOR_CONFIGURATION = 202
+    SET_LOAD_PELLET_PROCEDURE = 203
+    SET_SEND_PELLET_PROCEDURE = 204
+    SET_X = 205  # sets the X position for use by SEND_FIXED_XYZ
+    SET_Y = 206  # sets the Y position for use by SEND_FIXED_XYZ
+    SET_Z = 207  # sets the Z position for use by SEND_FIXED_XYZ
+    MOVE_LOAD_SERVO = 208
+    MOVE_COVER_SERVO = 209
+    SEND_HOME = 210
+    LOAD_PELLET = 211
+    SEND_PELLET = 212
+    RELEASE_PELLET = 213
+    COVER_PELLET = 214
+    SEND_TO_LIMITS = 215
+    SET_COVER_PELLET_PROCEDURE = 216
+    SET_RELEASE_PELLET_PROCEDURE = 217
+    DELAY = 218
+    SEND_FIXED_XYZ = 219
+    MOVE_X = 220  # moves X, only
+    MOVE_Y = 221  # moves Y, only
+    MOVE_Z = 222  # moves Z, only
+    MOVE_GATE_SERVO = 223
+
+    SEND_RETRACT = 224  # make y - 15, or 0 if lower.
+
+    SET_MOTOR_DRIFT = 225
+    SET_AUTO_CORRECT_DRIFT = 226
+
+    SERVO_ATTACH = 227
+    SERVO_DETACH = 228
+
+    TUNNEL_FAN_ON = 229
+    TUNNEL_FAN_OFF = 230
+    TUNNEL_FAN_SET = 231
+
+    # General actions.
+    PLAY_TONE = 301
+    SET_RGB_LED = 302
+    SET_DIGITAL_OUTPUT = 303
+    SET_ANALOG_OUTPUT = 304
+
+    # Not deprecated so long as the original hardware is supported, but a bit esoteric.  It is not necessary for
+    # new hardware to support them or for new application/scripts to support them.
+    RAW_COMMAND = 1001  # TODO only used at command line for original hardware.  Remove eventually.
+    SETTINGS = 1002  # TODO Specific to original hardware head fix unit and not used in user apps.  Remove eventually.
+    STREAM_START = 1003  # TODO n/a new hardware, but required for original.
+    STREAM_STOP = 1004  # TODO n/a new hardware, but required for original.

autotrainer/core/message/system_message_handler.py

@@ -0,0 +1,122 @@
+import functools
+import logging
+import threading
+from queue import Queue
+from typing import Callable, List, Tuple, Optional
+
+from ..analysis.sensor_analysis import SensorAnalysis
+
+from .message_handler import MessageHandler
+from .system_status_message import SystemStatusMessageKind
+
+logger = logging.getLogger(__name__)
+
+
+class SystemMessageHandler(MessageHandler):
+
+    def __init__(self, input_queue: Queue, *, sensor_analysis: Optional[SensorAnalysis] = None):
+        super().__init__(input_queue, name="system-message-handler")
+
+        self._measurement_callback = None
+        self._audio_callback = None
+
+        self._analysis = SensorAnalysis() if sensor_analysis is None else sensor_analysis
+
+    @property
+    def measurement_callback(self):
+        return self._measurement_callback
+
+    @measurement_callback.setter
+    def measurement_callback(self, measurement_callback: Callable[[Tuple], None]) -> None:
+        self._measurement_callback = measurement_callback
+
+    @property
+    def audio_callback(self):
+        return self._audio_callback
+
+    @audio_callback.setter
+    def audio_callback(self, audio_callback: Callable[[List[float]], None]) -> None:
+        prev = self._audio_callback
+        if prev is not None:
+            logger.info("Replacing audio callback %s with %s", prev, audio_callback)
+        self._audio_callback = audio_callback
+
+    @property
+    def analysis(self):
+        return self._analysis
+
+    def message_received(self, msg, data):
+        # TODO: These are treated as if the property has changed.  If the number of event listeners increases or their
+        #  behaviors are complex and do not check for change themselves, this could become a bottleneck.  This could be
+        #  updated to store previous values and only notify listeners on change, like a typical ObservableObject
+        #  implementation.  Keeping things simple for the time being.
+        if msg == SystemStatusMessageKind.MEASUREMENT or msg == SystemStatusMessageKind.MEASUREMENTS:
+            measures = self._analysis.measurements_received(data)
+            if self._measurement_callback is not None and len(measures) > 0:
+                self._measurement_callback(measures)
+
+        elif msg == SystemStatusMessageKind.AUDIO_SPECTRUM:
+            self._analysis.audio_spectrum_received(data)
+            if self._audio_callback is not None:
+                self._audio_callback(data.magnitudes)
+
+        elif msg == SystemStatusMessageKind.PELLET_X:
+            self.property_changed(MessageHandler.DEVICE_X_PROPERTY, data, None)
+
+        elif msg == SystemStatusMessageKind.PELLET_Y:
+            self.property_changed(MessageHandler.DEVICE_Y_PROPERTY, data, None)
+
+        elif msg == SystemStatusMessageKind.PELLET_Z:
+            self.property_changed(MessageHandler.DEVICE_Z_PROPERTY, data, None)
+
+        elif msg == SystemStatusMessageKind.PELLET_MOTOR_X:
+            self.property_changed(MessageHandler.DEVICE_X_PROPERTY, data.position, None)
+            self.property_changed(MessageHandler.STEPPER_X_PROPERTY, data, None)
+
+        elif msg == SystemStatusMessageKind.PELLET_MOTOR_Y:
+            self.property_changed(MessageHandler.DEVICE_Y_PROPERTY, data.position, None)
+            self.property_changed(MessageHandler.STEPPER_Y_PROPERTY, data, None)
+
+        elif msg == SystemStatusMessageKind.PELLET_MOTOR_Z:
+            self.property_changed(MessageHandler.DEVICE_Z_PROPERTY, data.position, None)
+            self.property_changed(MessageHandler.STEPPER_Z_PROPERTY, data, None)
+
+        elif msg == SystemStatusMessageKind.PELLET_LOAD:
+            self.property_changed(MessageHandler.LOAD_ARM_ANGLE_PROPERTY, data, None)
+
+        elif msg == SystemStatusMessageKind.PELLET_COVER:
+            self.property_changed(MessageHandler.COVER_ARM_ANGLE_PROPERTY, data, None)
+
+        elif msg == SystemStatusMessageKind.HEAD_MAGNET:
+            self.property_changed(MessageHandler.HEAD_MAGNET_INTENSITY_PROPERTY, data, None)
+
+        elif msg == SystemStatusMessageKind.TUNNEL_GATE_SERVO:
+            self.property_changed(MessageHandler.HEAD_GATE_PROPERTY, data, None)
+
+        elif msg == SystemStatusMessageKind.TUNNEL_FAN:
+            self.property_changed(MessageHandler.TUNNEL_FAN_PROPERTY, data, None)
+
+        elif msg == SystemStatusMessageKind.FRONT_DOOR:
+            # directly update related monitor, hopefully is very fast
+            self._analysis.external_doors_monitor.update_door_state(msg, data)
+            self.property_changed(MessageHandler.FRONT_DOOR_PROPERTY, data, None)
+
+        elif msg == SystemStatusMessageKind.DRAWER_DOOR:
+            # directly update related monitor, hopefully is very fast
+            self._analysis.external_doors_monitor.update_door_state(msg, data)
+            self.property_changed(MessageHandler.DRAWER_DOOR_PROPERTY, data, None)
+
+        elif msg == SystemStatusMessageKind.SPARE_DOOR:
+            self.property_changed(MessageHandler.SPARE_DOOR_PROPERTY, data, None)
+
+        elif msg == SystemStatusMessageKind.EXT_BUTTON:
+            self.property_changed(MessageHandler.EXT_BUTTON_PROPERTY, data, None)
+
+        elif msg == SystemStatusMessageKind.STIMULUS_INPUTS:
+            self.property_changed(MessageHandler.STIMULI_PROPERTY, data, None)
+
+        elif msg == SystemStatusMessageKind.MOTOR_CONFIGURATION:
+            self._on_property_changed("config", data, None)
+
+        else:
+            logger.warning("unhandled msg %s", msg)