manual_time_adjustment_window

  1"""
  2This module defines the ManualTimeAdjustment class, a Tkinter Toplevel window
  3responsible for allowing users to view, modify, and save valve open duration
  4timings used by the Arduino controller.
  5
  6It provides an interface to load different timing profiles (default, last used,
  7archived), edit individual valve timings (in microseconds), and save the
  8updated configuration, which also involves archiving the previously active
  9timings. It relies on configuration loaded via `system_config` and interacts
 10with an `models.arduino_data` object so that the Arduino can 'remember' durations
 11over many experiments.
 12"""
 13
 14import tkinter as tk
 15from tkinter import ttk
 16import numpy as np
 17import toml
 18from models.arduino_data import ArduinoData
 19import system_config
 20import logging
 21
 22from views.gui_common import GUIUtils
 23
 24###TYPE HINTS###
 25import numpy.typing as npt
 26import datetime
 27###TYPE HINTS###
 28
 29logger = logging.getLogger()
 30
 31rig_config = system_config.get_rig_config()
 32
 33with open(rig_config, "r") as f:
 34    VALVE_CONFIG = toml.load(f)["valve_config"]
 35
 36# pull total valves constant from toml config
 37TOTAL_VALVES = VALVE_CONFIG["TOTAL_CURRENT_VALVES"]
 38
 39VALVES_PER_SIDE = TOTAL_VALVES // 2
 40
 41
 42class ManualTimeAdjustment(tk.Toplevel):
 43    """
 44    Implements a Tkinter Toplevel window for manually adjusting valve open durations.
 45
 46    This window allows users to:
 47    - Select and load different valve timing profiles (Default, Last Used, Archives).
 48    - View and edit the open duration (in microseconds) for each valve.
 49    - Save the modified timings, which automatically archives the previously
 50      'selected' timings and sets the new ones as 'selected'.
 51
 52    It interacts with `models.arduino_data` object (passed during initialization)
 53    to load and persist timing configurations. Uses `views.gui_common.GUIUtils` for standard
 54    widget creation and layout.
 55
 56    Attributes
 57    ----------
 58    - **arduino_data** (*ArduinoData*): This is a reference to the program instance of `models.arduino_data` ArduinoData. It allows access to this
 59    class and its methods which allows for the loading of data stored there such as valve duration times and schedule indicies.
 60    - **`tk_vars`** (*dict[str, tk.IntVar]*): Dictionary mapping valve names (e.g., "Valve 1") to Tkinter IntVars holding their durations.
 61    - **`labelled_entries`** (*list[tuple OR None]*): List storing tuples of (Frame, Label, Entry) widgets for each valve timing input. Stored to make possible later
 62    modification of the widgets.
 63    - **`dropdown`** (*ttk.Combobox*): Widget for selecting the duration profile to load/view.
 64    - **`date_used_label`** (*tk.Label*): Label displaying the timestamp of the currently loaded profile.
 65    - **`timing_frame`** (*tk.Frame*): Frame containing the grid of labeled entries for valve timings.
 66    - **`save_changes_bttn`** (*tk.Button*): Button to trigger the save operation.
 67    - **`duration_types`** (*dict[str, str]*): Maps user friendly display names in the dropdown to internal keys used for loading profiles.
 68
 69    Methods
 70    -------
 71    - `show`()
 72        Updates the interface with the latest data and makes the window visible.
 73    - `update_interface`(...)
 74        Callback for dropdown selection; loads and displays the chosen timing profile.
 75    - `create_dropdown`()
 76        Creates and configures the Combobox for selecting duration profiles.
 77    - `create_interface`(...)
 78        Constructs the main GUI layout, including labels, dropdown, entry fields, and buttons.
 79    - `fill_tk_vars`(...)
 80        Populates `self.tk_vars` with Tkinter variables based on loaded duration arrays.
 81    - `write_timing_changes`()
 82        Handles archiving old timings, validating user input, and saving new timings in 'selected' profile.
 83    """
 84
 85    def __init__(self, arduino_data: ArduinoData):
 86        """
 87        Initializes the ManualTimeAdjustment Toplevel window.
 88
 89        Parameters
 90        ----------
 91        - **arduino_data** (*ArduinoData*): Reference to program instance of `models.arduino_data.ArduinoData`, used for loading and saving valve durations.
 92
 93        Raises
 94        ------
 95        - Propagates exceptions from `GUIUtils` methods during icon setting.
 96        - Propagates exceptions from `arduino_data.load_durations()`.
 97        """
 98        super().__init__()
 99
100        self.arduino_data = arduino_data
101
102        self.title("Manual Valve Timing Adjustment")
103        self.bind("<Control-w>", lambda event: self.withdraw())
104
105        self.resizable(False, False)
106
107        self.tk_vars: dict[str, tk.IntVar] = {}
108        self.labelled_entries: list[tuple | None] = [None] * TOTAL_VALVES
109
110        # load default 'selected' dur profile
111        side_one, side_two, date_used = self.arduino_data.load_durations()
112
113        self.fill_tk_vars(side_one, side_two)
114        self.create_interface(date_used)
115
116        window_icon_path = GUIUtils.get_window_icon_path()
117        GUIUtils.set_program_icon(self, icon_path=window_icon_path)
118
119    def show(self):
120        """
121        Updates the interface with either default 'Last Used' profile data or selected profile from dropdown and makes the window visible.
122        """
123        self.update_interface(event=None)
124        self.deiconify()
125
126    def update_interface(self, event: tk.Event | None):
127        """
128        Loads and displays the valve timings based on the selected profile from the dropdown.
129
130        If `event` is None (e.g., called from `show`), it loads the 'Last Used'
131        profile. Otherwise, it uses the profile selected in the dropdown. Updates
132        the *tk.IntVar* variables, which refreshes the Entry widgets, and updates
133        the 'date last used' label.
134
135        Parameters
136        ----------
137        - **event** (*tk.Event | None*): The Combobox selection event, or None to default
138          to loading the 'Last Used' profile.
139
140        Raises
141        ------
142        - Propagates exceptions from `arduino_data.load_durations()`.
143        """
144
145        # event is the selection event of the self.combobox. using .get gets the self.duration_type dict key
146        load_durations_key = None
147        if event is None:
148            load_durations_key = self.duration_types["Last Used"]
149        else:
150            load_durations_key = self.duration_types[f"{event.widget.get()}"]
151
152        side_one, side_two, _ = self.arduino_data.load_durations(load_durations_key)
153
154        # set default durations for side one
155        for i, duration in enumerate(side_one):
156            self.tk_vars[f"Valve {i + 1}"].set(duration)
157        # set default durations for side two
158        for i, duration in enumerate(side_two):
159            self.tk_vars[f"Valve {i + 8 + 1}"].set(duration)
160
161    def create_dropdown(self):
162        """
163        Creates the `ttk.Combobox` widget for selecting duration profiles.
164
165        Populates the dropdown with user-friendly names for duration profiles and maps them to keys in
166        `self.duration_types` dict, sets the default selection to 'Last Used',
167        and binds the selection event to `self.update_interface`.
168        """
169        self.duration_types = {
170            "Default": "default_durations",
171            "Last Used": "selected_durations",
172            "(most recent) Archive 1": "archive_1",
173            "Archive 2": "archive_2",
174            "(oldest) Archive 3": "archive_3",
175        }
176        self.dropdown = ttk.Combobox(self, values=list(self.duration_types.keys()))
177        self.dropdown.current(1)
178        self.dropdown.grid(row=1, column=0, sticky="e", padx=10)
179        self.dropdown.bind("<<ComboboxSelected>>", lambda e: self.update_interface(e))
180
181    def create_interface(self, date_used: datetime.datetime):
182        """
183        Constructs the main GUI elements within the Toplevel window.
184
185        Creates labels, the duration profile dropdown, the grid of labeled
186        entries for valve timings, and the save button. Uses `views.gui_common.GUIUtils` for
187        widget creation.
188
189        Parameters
190        ----------
191        - **date_used** (*datetime.datetime*): The timestamp for date selected profile was created,
192          used to populate the date label.
193
194        Raises
195        ------
196        - Propagates exceptions from `GUIUtils` methods during widget creation.
197        """
198        warning = tk.Label(
199            self,
200            text="ALL TIMINGS IN MICROSECONDS (e.g 24125 equivalent to 24.125 ms)",
201            bg="white",
202            fg="black",
203            font=("Helvetica", 15),
204            highlightthickness=1,
205            highlightbackground="black",
206        )
207
208        warning.grid(row=0, column=0, sticky="nsew", pady=10, padx=10)
209
210        self.create_dropdown()
211
212        formatted_date = date_used.strftime("%B/%d/%Y")
213        formatted_time = date_used.strftime("%I:%M %p")
214        self.date_used_label = tk.Label(
215            self,
216            text=f"Timing profile created on: {formatted_date} at {formatted_time}",
217            bg="white",
218            fg="black",
219            font=("Helvetica", 15),
220            highlightthickness=1,
221            highlightbackground="black",
222        )
223        self.date_used_label.grid(row=1, column=0, sticky="w", padx=10)
224
225        self.timing_frame = tk.Frame(
226            self, highlightbackground="black", highlightthickness=1
227        )
228
229        self.timing_frame.grid(row=2, column=0, pady=10, padx=10, sticky="nsew")
230        self.timing_frame.grid_columnconfigure(0, weight=1)
231
232        for i in range(VALVES_PER_SIDE):
233            # GUIUtils.create_button returns both the buttons frame and button object in a tuple. using [1] on the
234            # return item yields the button object.
235
236            self.labelled_entries[i] = GUIUtils.create_labeled_entry(
237                self.timing_frame,
238                f"Valve {i + 1} Open Time",
239                self.tk_vars[f"Valve {i + 1}"],
240                i,
241                0,
242            )
243
244            self.labelled_entries[i] = GUIUtils.create_labeled_entry(
245                self.timing_frame,
246                f"Valve {i + (VALVES_PER_SIDE) + 1} Open Time",
247                self.tk_vars[f"Valve {i + (TOTAL_VALVES) + 1}"],
248                i,
249                1,
250            )
251
252        warning = tk.Label(
253            self,
254            text="This action will archive the current timing configuration into assets/valve_durations.toml\n and set these new timings to selected timings",
255            bg="white",
256            fg="black",
257            font=("Helvetica", 15),
258            highlightthickness=1,
259            highlightbackground="black",
260        )
261
262        warning.grid(row=3, column=0, padx=10)
263        self.save_changes_bttn = GUIUtils.create_button(
264            self,
265            "Write Timing Changes",
266            lambda: self.write_timing_changes(),
267            bg="green",
268            row=4,
269            column=0,
270        )[1]
271
272    def fill_tk_vars(
273        self, side_one: npt.NDArray[np.int32], side_two: npt.NDArray[np.int32]
274    ):
275        """
276        Populates the `self.tk_vars` dictionary with *tk.IntVar* objects.
277
278        Initializes each *tk.IntVar* with the corresponding duration value
279        loaded from the provided numpy arrays (`side_one`, `side_two`). These
280        variables are then linked to the Entry widgets in the UI.
281
282        Parameters
283        ----------
284        - **side_one** (*np.ndarray*): Numpy array of np.int32 durations for the first side of valves.
285        - **side_two** (*np.ndarray*): Numpy array of np.int32 durations for the second side of valves.
286        """
287
288        for i, duration in enumerate(side_one):
289            self.tk_vars[f"Valve {i + 1}"] = tk.IntVar(value=duration)
290        for i, duration in enumerate(side_two):
291            self.tk_vars[f"Valve {i + 9}"] = tk.IntVar(value=duration)
292
293    def write_timing_changes(self):
294        """
295        Archives the current 'selected' timings, validates the user-entered
296        timings, and saves the new timings as the 'selected' profile.
297
298        Retrieves values from the Entry widgets via their linked *tk.IntVar*s.
299        Performs basic validation (checks for empty fields). If valid, it
300        instructs `models.arduino_data` to archive the old 'selected' profile and
301        save the new profile as 'selected'. Displays error messages on failure.
302
303        Raises
304        ------
305        - Propagates exceptions from `arduino_data.load_durations()` or
306          `arduino_data.save_durations()`.
307        """
308        side_one, side_two, _ = self.arduino_data.load_durations()
309
310        ## save durations in the oldest valve duration archival location
311        self.arduino_data.save_durations(side_one, side_two, "archive")
312
313        timings = [GUIUtils.safe_tkinter_get(value) for value in self.tk_vars.values()]
314
315        # check if one of the fields are empty
316        if None in timings:
317            msg = "ONE OR MORE FIELDS ARE EMPTY, FILL BEFORE TRYING ANOTHER ADJUSTMENT"
318            logger.error(msg)
319            GUIUtils.display_error("FIELD ERROR", msg)
320            return
321
322        # using total possible valves per side here (maximum of 16 valves) for future proofing
323        side_one_new = np.full(8, np.int32(0))
324        side_two_new = np.full(8, np.int32(0))
325
326        for i in range(len(timings) // 2):
327            side_one_new[i] = timings[i]
328            side_two_new[i] = timings[i + 8]
329
330        # save new durations in the selected slot of the configuration file
331        self.arduino_data.save_durations(side_one_new, side_two_new, "selected")