Merge branch 'watcher' into tools

I created a service handler in pyzmq and memory tested and it was in the MegaBytes, comparable to direct Params access, fudge that.

selfdrive/ui/layouts/settings/developer.py

@@ -1,4 +1,3 @@
-from openpilot.common.params import Params
 from openpilot.selfdrive.ui.widgets.ssh_key import ssh_key_item
 from openpilot.selfdrive.ui.ui_state import ui_state
 from openpilot.system.ui.widgets import Widget
@@ -35,7 +34,7 @@ DESCRIPTIONS = {
 class DeveloperLayout(Widget):
   def __init__(self):
     super().__init__()
-    self._params = Params()
+    self._params = ui_state.params
     self._is_release = self._params.get_bool("IsReleaseBranch")
 
     # Build items and keep references for callbacks/state updates

selfdrive/ui/layouts/settings/device.py

@@ -3,7 +3,6 @@ import math
 
 from cereal import messaging, log
 from openpilot.common.basedir import BASEDIR
-from openpilot.common.params import Params
 from openpilot.common.swaglog import cloudlog
 from openpilot.selfdrive.ui.onroad.driver_camera_dialog import DriverCameraDialog
 from openpilot.selfdrive.ui.ui_state import ui_state
@@ -35,7 +34,7 @@ class DeviceLayout(Widget):
   def __init__(self):
     super().__init__()
 
-    self._params = Params()
+    self._params = ui_state.params
     self._select_language_dialog: MultiOptionDialog | None = None
     self._driver_camera: DriverCameraDialog | None = None
     self._pair_device_dialog: PairingDialog | None = None

selfdrive/ui/layouts/settings/toggles.py

@@ -1,5 +1,5 @@
 from cereal import log
-from openpilot.common.params import Params, UnknownKeyName
+from openpilot.common.params import UnknownKeyName
 from openpilot.system.ui.widgets import Widget
 from openpilot.system.ui.widgets.list_view import multiple_button_item, toggle_item
 from openpilot.system.ui.widgets.scroller_tici import Scroller
@@ -41,7 +41,7 @@ DESCRIPTIONS = {
 class TogglesLayout(Widget):
   def __init__(self):
     super().__init__()
-    self._params = Params()
+    self._params = ui_state.params
     self._is_release = self._params.get_bool("IsReleaseBranch")
 
     # param, title, desc, icon, needs_restart
@@ -198,11 +198,6 @@ class TogglesLayout(Widget):
 
     self._update_experimental_mode_icon()
 
-    # TODO: make a param control list item so we don't need to manage internal state as much here
-    # refresh toggles from params to mirror external changes
-    for param in self._toggle_defs:
-      self._toggles[param].action_item.set_state(self._params.get_bool(param))
-
     # these toggles need restart, block while engaged
     for toggle_def in self._toggle_defs:
       if self._toggle_defs[toggle_def][3] and toggle_def not in self._locked_toggles:

selfdrive/ui/sunnypilot/layouts/settings/models.py

@@ -230,9 +230,7 @@ class ModelsLayout(Widget):
     turn_desire: bool = ui_state.params.get_bool("LaneTurnDesire")
     live_delay: bool = ui_state.params.get_bool("LagdToggle")
 
-    self.lane_turn_desire_toggle.action_item.set_state(turn_desire)
     self.lane_turn_value_control.set_visible(turn_desire and advanced_controls)
-    self.lagd_toggle.action_item.set_state(live_delay)
     self.delay_control.set_visible(not live_delay and advanced_controls)
     new_step = int(round(100 / CV.MPH_TO_KPH)) if ui_state.is_metric else 100
     if self.lane_turn_value_control.action_item.value_change_step != new_step:

selfdrive/ui/sunnypilot/layouts/settings/settings.py

@@ -31,6 +31,7 @@ from openpilot.selfdrive.ui.sunnypilot.layouts.settings.steering import Steering
 from openpilot.selfdrive.ui.sunnypilot.layouts.settings.cruise import CruiseLayout
 from openpilot.selfdrive.ui.sunnypilot.layouts.settings.visuals import VisualsLayout
 from openpilot.selfdrive.ui.sunnypilot.layouts.settings.display import DisplayLayout
+from openpilot.selfdrive.ui.ui_state import ui_state
 
 # from openpilot.selfdrive.ui.sunnypilot.layouts.settings.navigation import NavigationLayout
 
@@ -196,6 +197,10 @@ class SettingsLayoutSP(OP.SettingsLayout):
 
     return False
 
+  def set_current_panel(self, panel_type: OP.PanelType):
+    super().set_current_panel(panel_type)
+    ui_state.set_active_layout(self._panels[self._current_panel].instance)
+
   def show_event(self):
     super().show_event()
     self._panels[self._current_panel].instance.show_event()

selfdrive/ui/sunnypilot/layouts/settings/sunnylink.py

@@ -320,7 +320,6 @@ class SunnylinkLayout(Widget):
     self._sunnylink_enabled = ui_state.params.get_bool("SunnylinkEnabled")
     self._sunnylink_toggle.set_right_value(tr("Dongle ID") + ": " + self._get_sunnylink_dongle_id())
     self._sunnylink_toggle.action_item.set_enabled(not ui_state.is_onroad())
-    self._sunnylink_toggle.action_item.set_state(self._sunnylink_enabled)
     self._sunnylink_uploader_toggle.action_item.set_enabled(self._sunnylink_enabled)
     self.handle_backup_restore_progress()
 

selfdrive/ui/sunnypilot/layouts/settings/vehicle/brands/hyundai.py

@@ -55,5 +55,4 @@ class HyundaiSettings(BrandSettings):
     self.longitudinal_tuning_item.action_item.set_enabled(not longitudinal_tuning_disabled)
     self.longitudinal_tuning_item.set_description(long_tuning_desc)
     self.longitudinal_tuning_item.show_description(True)
-    self.longitudinal_tuning_item.action_item.set_selected_button(tuning_param)
     self.longitudinal_tuning_item.set_visible(self.alpha_long_available)

selfdrive/ui/sunnypilot/ui_helpers.py

@@ -0,0 +1,41 @@
+"""
+Copyright (c) 2021-, Haibin Wen, sunnypilot, and a number of other contributors.
+
+This file is part of sunnypilot and is licensed under the MIT License.
+See the LICENSE.md file in the root directory for more details.
+"""
+
+
+def update_item_from_param(item, key, params):
+  if not (action := getattr(item, 'action_item', None)):
+    return
+
+  if hasattr(action, 'set_state'):
+    action.set_state(params.get_bool(key))
+  elif hasattr(action, 'set_value'):
+    action.set_value(params.get(key, return_default=True))
+  else:
+    try:
+      val = int(params.get(key, return_default=True))
+      if hasattr(action, 'selected_button'):
+        action.selected_button = val
+      if hasattr(action, 'current_value'):
+        action.current_value = val
+    except (ValueError, TypeError):
+      pass
+
+
+def sync_layout_params(layout, param_name, params):
+  targets = []
+  if toggles := getattr(layout, '_toggles', None):
+    targets.extend([(item, k) for k, item in toggles.items()])
+
+  items = getattr(layout, 'items', []) or getattr(getattr(layout, '_scroller', None), '_items', [])
+  for item in items:
+    action = getattr(item, 'action_item', None)
+    if key := getattr(action, 'param_key', None) or getattr(getattr(action, 'toggle', None), 'param_key', None):
+      targets.append((item, key))
+
+  for item, key in targets:
+    if param_name is None or key == param_name:
+      update_item_from_param(item, key, params)

selfdrive/ui/sunnypilot/ui_state.py

@@ -5,23 +5,49 @@ This file is part of sunnypilot and is licensed under the MIT License.
 See the LICENSE.md file in the root directory for more details.
 """
 from cereal import messaging, custom
-from openpilot.common.params import Params
+from openpilot.common.swaglog import cloudlog
+
+from openpilot.sunnypilot.common.params import Params
 from openpilot.sunnypilot.sunnylink.sunnylink_state import SunnylinkState
+from openpilot.selfdrive.ui.sunnypilot.ui_helpers import sync_layout_params
 
 
 class UIStateSP:
   def __init__(self):
     self.params = Params()
+    self.params.add_watcher(self.on_param_change)
+    self.params.start()
     self.sm_services_ext = [
       "modelManagerSP", "selfdriveStateSP", "longitudinalPlanSP", "backupManagerSP",
       "gpsLocation", "liveTorqueParameters", "carStateSP", "liveMapDataSP", "carParamsSP", "liveDelay"
     ]
 
     self.sunnylink_state = SunnylinkState()
+    self.active_layout = None
+    self.changed_params = set()
+
+  def set_active_layout(self, layout):
+    self.active_layout = layout
+    if layout:
+      sync_layout_params(layout, None, self.params)
+
+  def on_param_change(self, param_name):
+    self.changed_params.add(param_name)
 
   def update(self) -> None:
     self.sunnylink_state.start()
 
+    if not self.params.is_watching():
+      cloudlog.warning("ParamWatcher thread died, restarting...")
+      self.params.start()
+
+    if self.changed_params:
+      while self.changed_params:
+        self.changed_params.pop()
+
+      if self.active_layout:
+        sync_layout_params(self.active_layout, None, self.params)
+
   def update_params(self) -> None:
     CP_SP_bytes = self.params.get("CarParamsSPPersistent")
     if CP_SP_bytes is not None:

selfdrive/ui/ui_state.py

@@ -6,7 +6,6 @@ from collections.abc import Callable
 from enum import Enum
 from cereal import messaging, car, log
 from openpilot.common.filter_simple import FirstOrderFilter
-from openpilot.common.params import Params
 from openpilot.common.swaglog import cloudlog
 from openpilot.selfdrive.ui.lib.prime_state import PrimeState
 from openpilot.system.ui.lib.application import gui_app
@@ -34,7 +33,6 @@ class UIState(UIStateSP):
 
   def _initialize(self):
     UIStateSP.__init__(self)
-    self.params = Params()
     self.sm = messaging.SubMaster(
       [
         "modelV2",

sunnypilot/common/README.md

@@ -0,0 +1,133 @@
+# Comparative Analysis of Parameter Access Methods: `Params::get` vs. `ParamWatcher`
+
+## Inefficiencies in Standard Parameter Access
+The standard `Params::get()` method executes a full file I/O lifecycle—opening, allocating, reading, and closing—for every function call. This approach results in significant CPU overhead and memory churn due to the frequency of these operations in the user interface loop.
+
+### System Overhead Analysis
+*   **System Call Overhead**: Every read operation requires context switches into kernel mode. The `Params::get` function calls `util::read_file` (sunnypilot, 2025), which subsequently invokes `std::ifstream` (sunnypilot, 2025).
+*   **Impact**: Frequent context switching degrades performance (Linux man-pages, 2025 -a; Linux man-pages, 2025 -b).
+*   **C++ Stream Overhead**: The use of `std::ifstream` introduces additional overhead for maintaining stream state and buffering compared to raw file descriptors (cppreference.com, n.d.-a; Codezup, 2025).
+*   **Memory Churn**: The instantiation of `std::string result(size, '\0');` forces heap allocation and deallocation during every call (sunnypilot, 2025). This stresses the memory allocator and can lead to fragmentation (cppreference.com, n.d.).
+
+## The ParamWatcher Optimization
+The `ParamWatcher` implementation utilizes OS-level file system events, such as `inotify` on Linux or `FSEvents` on macOS, to maintain a Random Access Memory (RAM) cache. This architecture eliminates the need for continuous polling.
+
+### Performance Comparison
+| Feature | Standard `Params::get` | Optimized `ParamWatcher` |
+| :--- | :--- | :--- |
+| **Workflow** | `open` → `malloc` → `read` → `close` | `dict.get()` (RAM lookup) |
+| **Complexity** | **O(N * F)** (Linear to toggles & FPS) | **O(1)** (Constant time) |
+| **Disk I/O** | ~1,000 reads/sec (50 toggles @ 20FPS) | **0 reads/sec** (Steady state) |
+| **Memory** | New string object per call (High GC pressure) | Returns reference (Zero GC pressure) |
+
+## Architectural Mismatch of Standard Modules
+Standard C++ modules like `std::ifstream` are optimized for **throughput**—reading large files sequentially—rather than **latency** required for polling small files frequently.
+
+*   **The I/O Trap**: Even when a file resides in the OS page cache (RAM), invoking `open()` and `read()` forces a CPU mode switch (User → Kernel → User). Executing this sequence 1,000 times per second consumes CPU cycles merely to verify state constancy.
+*   **The Memory Trap**: The `std::string` class allocates memory on the heap. Repeated allocation creates short-lived objects, which in C++ fragments memory. In Python (which wraps this), it triggers the Garbage Collector, pausing the UI.
+*   **The Query Mismatch**: `Params::get` queries the current value every frame, whereas `ParamWatcher` waits for a notification of change, serving cached values in the interim.
+
+## Implementation Analysis
+The `ParamWatcher` class provides a cross-platform solution for monitoring file system changes, specifically targeting the parameter files used in Openpilot. The implementation leverages the `ctypes` library to interface directly with operating system kernels, bypassing higher-level abstractions for maximum performance.
+
+### Linux Implementation (`_run_linux`)
+The Linux implementation interacts directly with the kernel's `inotify` subsystem (Linux man-pages, 2025 -c).
+
+*   **Library Loading**: `libc = ctypes.CDLL('libc.so.6')` loads the standard C library to access system calls.
+*   **Initialization**: `inotify_init()` is called to create a new inotify instance, returning a file descriptor.
+*   **Watch Setup**: `inotify_add_watch(fd, path, mask)` registers the parameters directory. The mask includes `IN_MODIFY | IN_CREATE | IN_DELETE | IN_MOVED_TO | IN_CLOSE_WRITE` (Linux Kernel Organization, 2005) to capture all relevant file changes.
+*   **Event Loop**:
+    *   **Polling**: `select.epoll()` is used to efficiently wait for activity on the file descriptor without busy-waiting.
+    *   **Reading**: When events occur, `os.read(fd, 1024)` retrieves the raw binary event data.
+    *   **Parsing**: The code uses Python's `struct` module (`struct.unpack_from("iIII", ...)`) to parse the C-style `inotify_event` structures directly from the buffer, avoiding the overhead of defining `ctypes` structures.
+    *   **Handling**: Extracted filenames are passed to `_trigger_callbacks`, which invalidates the specific cache entry (`self._cache.pop(path, None)`), forcing a fresh read on the next access.
+
+### macOS Implementation (`_run_darwin`)
+The macOS implementation uses the `FSEvents` API from the `CoreServices` framework (Apple Inc., n.d.-a), which is more efficient than `kqueue` for directory monitoring.
+
+*   **Framework Loading**: `ctypes.cdll.LoadLibrary` loads `CoreServices` and `CoreFoundation`.
+*   **Callback Definition**: `CFUNCTYPE` is used to define a C-compatible callback function. This function is invoked by the OS whenever a change occurs in the watched directory.
+*   **Stream Creation**: `FSEventStreamCreate` creates a stream for the target directory. The `kFSEventStreamCreateFlagFileEvents` flag is used to request file-level granularity where available.
+*   **Event Filtering**: The callback filters events using flags such as `kFSEventStreamEventFlagItemCreated` and `kFSEventStreamEventFlagItemModified` to ensure only relevant file changes trigger updates (Apple Inc., n.d.-c).
+*   **Scheduling**: `FSEventStreamScheduleWithRunLoop` attaches the stream to the current thread's run loop (Apple Inc., n.d.-b).
+*   **Execution**: `CFRunLoopRun()` starts the event loop. This passes control to the OS, which wakes the thread only when necessary.
+*   **Handling**: Inside the callback, the code iterates through the changed paths provided by the OS. It extracts the filename and calls `_trigger_callbacks` to invalidate the cache for that specific parameter.
+
+### Python ctypes Integration
+The use of `ctypes` (Python Software Foundation, 2025) is a strategic choice. It allows the Python interpreter to load shared libraries (`libc.so.6` on Linux, `CoreServices` on macOS) and call C functions directly. This approach avoids the overhead of spawning subprocesses or compiling external C extensions, keeping the codebase pure Python while achieving C-level system integration.
+
+### Memory Impact Analysis
+ With 232 defined parameters in `param_keys.h`, the maximum static RAM footprint of `ParamWatcher` is estimated to be **less than 250 KB**. Even if every single parameter were cached simultaneously, this static usage is negligible. Importantly, this stable footprint is likely more probable to maintain no trend of memory increase, whenc compared to the standard `Params::get` approach, which generates **megabytes** of short-lived "garbage" allocations per second, forcing the Python Garbage Collector to pause execution repeatedly.
+
+## Architectural Integration: The Process-Local Singleton Pattern
+To ensure resource efficiency within openpilot's multi-process architecture (e.g., `ui`, `controlsd`, `modeld`), `ParamWatcher` implements the Singleton design pattern (Gamma et al., 1994) using the Python `__new__` allocator.
+
+### Process Isolation and Concurrency
+In the context of Python's memory model, a Singleton ensures a single instance exists *per process*. This behavior aligns with openpilot's multiprocess design:
+
+*   **Intra-Process Efficiency**: Within a single heavy process like `ui`, multiple sub-components (e.g., `UIState`, `SunnylinkState`) import and use `Params`. The Singleton pattern ensures they share a single `inotify` thread and a unified RAM cache. This prevents the proliferation of redundant watcher threads, which would otherwise compete for the Global Interpreter Lock (GIL).
+*   **Inter-Process Safety**: Distinct processes (e.g., `modeld` vs. `ui`) maintain completely isolated `ParamWatcher` instances. This isolation eliminates the need for complex Inter-Process Communication (IPC) locking mechanisms for the cache, as each process synchronizes its independent state via the OS file system events.
+
+### Empirical Verification
+Runtime analysis demonstrates that multiple instantiation attempts result in a shared object reference, minimizing memory footprint.
+
+*   **Test Case**: Instantiating `ParamWatcher` in `UIStateSP` and subsequently in a standalone script within the same process.
+*   **Result**: Both instances report the exact same memory address (`4814358960`) and share the same background thread ID (`6114635776`).
+*   **Impact**: The system incurs the overhead of the watcher thread (measured at < 0.1% CPU idle usage) only once per active process, regardless of import frequency. The average CPU usage across one minute was 0.002%.
+
+## Limitations and Trade-offs
+While `ParamWatcher` offers superior performance for UI rendering, it presents specific trade-offs:
+
+*   **Static RAM Usage**: `ParamWatcher` maintains a persistent dictionary cache of all accessed parameters (~50KB), whereas `Params::get` uses zero static RAM but incurs high dynamic memory access.
+*   **Event Latency**: In high-load scenarios, `inotify` events may experience slight delays or coalescing compared to direct reads. However, for user interface applications, this latency (<10ms) is imperceptible.
+*   **Complexity**: The solution (the process singleton approach) requires managing a background thread and OS-specific event loops, increasing code complexity compared to the synchronous `Params::get` function.
+
+## Alternative Architecture Considered: ZeroMQ Service (ZMQ)
+During the development of `ParamWatcher`, a Client-Server architecture using ZMQ was evaluated. In this architecture, a single background service process would monitor file system events and publish changes over a ZMQ PUB socket to multiple client processes (SUB).
+
+### Trade-off Analysis
+| Metric | In-Process (Current) | ZMQ Service (Rejected)                                |
+| :--- | :--- |:------------------------------------------------------|
+| **Memory Usage** | Low (1 thread/process) | High (1 full Python process + ZMQ buffers per client) |
+| **CPU Usage** | Low (Direct callback) | High (Serialization + TCP Stack + Deserialization)    |
+| **Latency** | Instant (<0.1ms) | Variable (TCP Loopback overhead)                      |
+| **Scalability** | Limited by OS file handles | Limited by TCP ports/buffers                          |
+| **Robustness** | Process-isolated failure | Single point of failure (Service crash affects all)   |
+
+### Decision Rationale
+While the ZMQ approach offers better isolation and reduces the total number of OS file watchers (1 vs N), the overhead of inter-process communication (IPC) proved excessive for this use case.
+*   **Efficiency**: Even with 50+ processes, the memory footprint of 50 simple threads is significantly lower than the overhead of a dedicated Python service process plus the ZMQ context in every client.
+*   **Complexity**: The ZMQ architecture introduced synchronization challenges (e.g., service startup race conditions, "Address already in use" errors) that outweighed its benefits.
+*   **Performance**: The latency of serializing messages and passing them through the TCP stack is orders of magnitude higher than a direct function call within the same process memory space.
+
+## Conclusion
+Replacing polling mechanisms with event-driven caching shifts the computational load from kernel space (syscalls) to user space (RAM). This transition eliminates I/O overhead and UI stutters caused by garbage collection, resulting in a more responsive user experience. The In-Process Singleton approach was selected as the optimal balance between performance, complexity, and resource efficiency.
+
+## References
+Apple Inc. (n.d.-a). *File System Events*. Retrieved from https://developer.apple.com/documentation/coreservices/file_system_events
+
+Apple Inc. (n.d.-b). *CFRunLoop*. Retrieved from https://developer.apple.com/documentation/corefoundation/cfrunloop
+
+Apple Inc. (n.d.-c). *FSEventStreamEventFlags*. Retrieved from https://developer.apple.com/documentation/coreservices/1455361-fseventstreameventflags
+
+Codezup. (2025). *Efficient File I/O in C++*. Retrieved from https://codezup.com/efficient-file-io-cpp-best-practices/
+
+cppreference.com. (n.d.-a). *std::basic_ifstream*. Retrieved from https://en.cppreference.com/w/cpp/io/basic_ifstream
+
+cppreference.com. (n.d.-b). *std::basic_string*. Retrieved from https://en.cppreference.com/w/cpp/string/basic_string/basic_string
+
+Linux man-pages. (2025 -a). *open(2)*. Retrieved from https://man7.org/linux/man-pages/man2/open.2.html
+
+Linux man-pages. (2025-b). *read(2)*. Retrieved from https://man7.org/linux/man-pages/man2/read.2.html
+
+Linux man-pages. (2025 -c). *inotify(7)*. Retrieved from https://man7.org/linux/man-pages/man7/inotify.7.html
+
+Linux Kernel Organization. (2005). *include/uapi/linux/inotify.h*. Retrieved from https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/inotify.h
+
+Python Software Foundation. (2025). *ctypes — A foreign function library for Python*. Retrieved from https://docs.python.org/3/library/ctypes.html
+
+Gamma, E., Helm, R., Johnson, R., & Vlissides, J. (1994). *Design Patterns: Elements of Reusable Object-Oriented Software*. Addison-Wesley.
+
+sunnypilot. (2025). *common/params.cc* [Source code]. GitHub. https://github.com/sunnypilot/sunnypilot/blob/master/common/params.cc#L180C1-L206C2
+
+sunnypilot. (2025). *common/util.cc* [Source code]. GitHub. https://github.com/sunnypilot/sunnypilot/blob/master/common/util.cc#L79C1-L117C2

sunnypilot/common/param_watcher.py

@@ -0,0 +1,193 @@
+"""
+Copyright (c) 2021-, Haibin Wen, sunnypilot, and a number of other contributors.
+
+This file is part of sunnypilot and is licensed under the MIT License.
+See the LICENSE.md file in the root directory for more details.
+"""
+import os
+import platform
+import struct
+import select
+import threading
+import time
+import ctypes
+import ctypes.util
+import traceback
+from ctypes import c_void_p, c_size_t, POINTER, c_uint32, c_uint64
+
+from openpilot.common.params import Params
+from openpilot.common.swaglog import cloudlog
+from openpilot.system.hardware.hw import Paths
+
+IN_MODIFY = 0x00000002
+IN_CREATE = 0x00000100
+IN_DELETE = 0x00000200
+IN_MOVED_TO = 0x00000080
+IN_CLOSE_WRITE = 0x00000008
+
+
+class ParamWatcher(Params):
+  _instance = None
+
+  def __new__(cls):
+    if cls._instance is None:
+      cls._instance = super().__new__(cls)
+      cls._instance._initialized = False
+    return cls._instance
+
+  def __init__(self):
+    if self._initialized:
+      return
+    super().__init__()
+    cloudlog.warning("ParamWatcher initialized")
+    self._cache = {}
+    self._last_trigger = {}
+    self._version = {}
+    self._lock = threading.Lock()
+    self._callbacks = []
+    self.last_accessed_param = None
+    self._initialized = True
+    self.start()
+
+  def start(self):
+    if getattr(self, '_thread', None) and self._thread.is_alive():
+      return
+    self._thread = threading.Thread(target=self._run_watcher, daemon=True)
+    self._thread.start()
+
+  def is_watching(self):
+    return getattr(self, '_thread', None) and self._thread.is_alive()
+
+  def add_watcher(self, callback):
+    if callback not in self._callbacks:
+      self._callbacks.append(callback)
+
+  def _trigger_callbacks(self, path):
+    with self._lock:
+      if (now := time.monotonic()) - self._last_trigger.get(path, 0) < 0.1:
+        return
+      self._last_trigger[path] = now
+      self._version[path] = self._version.get(path, 0) + 1
+      self._cache.pop(path, None)
+
+    for callback in self._callbacks:
+      try:
+        callback(path)
+      except Exception:
+        cloudlog.exception("Param watcher callback failed")
+
+  def _get_cached(self, key, getter, sig):
+    k = str(key)
+    with self._lock:
+      bucket = self._cache.get(k)
+      if bucket and sig in bucket:
+        if bucket[sig][0] == self._version.get(k, 0):
+          return bucket[sig][1]
+
+    start_ver = self._version.get(k, 0)
+    val = getter()
+    with self._lock:
+      if self._version.get(k, 0) != start_ver:
+        val = getter()
+      self._cache.setdefault(k, {})[sig] = (self._version.get(k, 0), val)
+    return val
+
+  def get(self, key, block=False, return_default=False):
+    self.last_accessed_param = key
+    if block:
+      return super().get(key, block, return_default)
+    fetcher = super().get
+    return self._get_cached(key, lambda: fetcher(key, block, return_default), (block, return_default))
+
+  def get_bool(self, key, block=False):
+    self.last_accessed_param = key
+    if block:
+      return super().get_bool(key, block)
+    fetcher = super().get_bool
+    return self._get_cached(key, lambda: fetcher(key, block), ("bool", block))
+
+  def _run_watcher(self):
+    system = platform.system()
+    while True:
+      try:
+        if system == "Linux":
+          self._run_linux()
+        elif system == "Darwin":
+          self._run_darwin()
+      except Exception:
+        cloudlog.exception("Param watcher crashed")
+        time.sleep(2)
+
+  def _run_linux(self):
+    path = Paths.params_root()
+    libc = ctypes.CDLL('libc.so.6')
+    fd = libc.inotify_init()
+    libc.inotify_add_watch(fd, path.encode(), IN_MODIFY | IN_CREATE | IN_DELETE | IN_MOVED_TO | IN_CLOSE_WRITE)
+
+    try:
+      poll = select.epoll()
+      poll.register(fd, select.EPOLLIN)
+      while True:
+        for fileno, _ in poll.poll():
+          if fileno == fd:
+            buffer = os.read(fd, 2048)
+            i = 0
+            while i + 16 <= len(buffer):
+              _, mask, _, name_len = struct.unpack_from("iIII", buffer, i)
+              if mask & (IN_MODIFY | IN_CREATE | IN_DELETE | IN_MOVED_TO | IN_CLOSE_WRITE):
+                name = buffer[i+16:i+16+name_len].rstrip(b"\0").decode()
+                if not name.startswith("."):
+                  self._trigger_callbacks(name)
+              i += 16 + name_len
+    finally:
+      if 'poll' in locals():
+        poll.unregister(fd)
+        poll.close()
+      os.close(fd)
+
+  def _run_darwin(self):
+    CS = ctypes.cdll.LoadLibrary(ctypes.util.find_library("CoreServices"))
+    CF = ctypes.cdll.LoadLibrary(ctypes.util.find_library("CoreFoundation"))
+
+    kCFAllocatorDefault = c_void_p(0)
+    kCFStringEncodingUTF8 = 0x08000100
+    kFSEventStreamCreateFlagFileEvents = 0x00000010
+    kFSEventStreamEventFlagItemCreated = 0x00000100
+    kFSEventStreamEventFlagItemRemoved = 0x00000200
+    kFSEventStreamEventFlagItemRenamed = 0x00000800
+    kFSEventStreamEventFlagItemModified = 0x00001000
+
+    CF.CFStringCreateWithCString.restype = c_void_p
+    CF.CFStringCreateWithCString.argtypes = [c_void_p, ctypes.c_char_p, c_uint32]
+    CF.CFArrayCreate.restype = c_void_p
+    CF.CFArrayCreate.argtypes = [c_void_p, POINTER(c_void_p), c_size_t, c_void_p]
+    CS.FSEventStreamCreate.restype = c_void_p
+    CS.FSEventStreamCreate.argtypes = [c_void_p, c_void_p, c_void_p, c_void_p, c_uint64, ctypes.c_double, c_uint32]
+    CS.FSEventStreamScheduleWithRunLoop.argtypes = [c_void_p, c_void_p, c_void_p]
+    CS.FSEventStreamStart.argtypes = [c_void_p]
+    CF.CFRunLoopGetCurrent.restype = c_void_p
+
+    def _cb(stream, ctx, num, paths, flags, ids):
+      try:
+        paths_arr = ctypes.cast(paths, POINTER(c_void_p))
+        flags_arr = ctypes.cast(flags, POINTER(c_uint32))
+        for i in range(num):
+          path = ctypes.cast(paths_arr[i], ctypes.c_char_p).value
+          if path and (flags_arr[i] & (kFSEventStreamEventFlagItemCreated | kFSEventStreamEventFlagItemRemoved |
+                                       kFSEventStreamEventFlagItemRenamed | kFSEventStreamEventFlagItemModified)):
+            self._trigger_callbacks(os.path.basename(path.decode('utf-8').rstrip('/')))
+      except Exception:
+        traceback.print_exc()
+
+    self._darwin_cb = ctypes.CFUNCTYPE(None, c_void_p, c_void_p, c_size_t, c_void_p, POINTER(c_uint32), POINTER(c_uint64))(_cb)
+
+    path_str = Paths.params_root().encode('utf-8')
+    cf_path = CF.CFStringCreateWithCString(kCFAllocatorDefault, path_str, kCFStringEncodingUTF8)
+    cf_paths = CF.CFArrayCreate(kCFAllocatorDefault, (c_void_p * 1)(cf_path), 1, None)
+    stream = CS.FSEventStreamCreate(kCFAllocatorDefault, self._darwin_cb, None, cf_paths, -1, 0.05, kFSEventStreamCreateFlagFileEvents)
+
+    run_loop = CF.CFRunLoopGetCurrent()
+    kDefaultMode = CF.CFStringCreateWithCString(kCFAllocatorDefault, b"kCFRunLoopDefaultMode", kCFStringEncodingUTF8)
+    CS.FSEventStreamScheduleWithRunLoop(stream, run_loop, kDefaultMode)
+    CS.FSEventStreamStart(stream)
+    CF.CFRunLoopRun()

sunnypilot/common/params.py

@@ -0,0 +1,4 @@
+from openpilot.common.params_pyx import ParamKeyFlag, ParamKeyType, UnknownKeyName
+from openpilot.sunnypilot.common.param_watcher import ParamWatcher as Params
+
+__all__ = ["Params", "ParamKeyFlag", "ParamKeyType", "UnknownKeyName"]

sunnypilot/common/tests/test_param_watcher.py

@@ -0,0 +1,94 @@
+import time
+import pytest
+import threading
+import tracemalloc
+
+from openpilot.common.params import Params
+from openpilot.common.params_pyx import UnknownKeyName
+
+from openpilot.sunnypilot.common.param_watcher import ParamWatcher
+
+
+class TestParamWatcher:
+  BYTES_KEYS = ["LocationFilterInitialState", "UpdaterCurrentReleaseNotes", "UpdaterNewReleaseNotes"]
+  BOOL_KEYS = [
+    "IsMetric", "AdbEnabled", "AlwaysOnDM", "ExperimentalMode",
+    "ExperimentalModeConfirmed", "DisengageOnAccelerator",
+    "OpenpilotEnabledToggle", "RecordAudio", "RecordFront"
+  ]
+  _key_counter = 0
+
+  @pytest.fixture(autouse=True)
+  def setup_method(self):
+    self.params = Params()
+    self.key_index = TestParamWatcher._key_counter
+    TestParamWatcher._key_counter += 1
+    self.bytes_key = self.BYTES_KEYS[self.key_index % len(self.BYTES_KEYS)]
+    self.bool_key = self.BOOL_KEYS[self.key_index % len(self.BOOL_KEYS)]
+
+  @pytest.fixture
+  def param_watcher(self):
+    ParamWatcher._instance = None
+    param_watch = ParamWatcher()
+    param_watch.start()
+    assert param_watch.is_watching(), "ParamWatcher thread died"
+    return param_watch
+
+  def teardown_method(self):
+    for key in (self.bytes_key, self.bool_key):
+      try:
+        self.params.remove(key)
+      except UnknownKeyName:
+        pass
+
+  def test_watcher_detects_change(self, param_watcher):
+    val = b"123"
+    self.params.put(self.bytes_key, val)
+    assert param_watcher.get(self.bytes_key) == val
+
+  def test_watcher_get_bool(self, param_watcher):
+    self.params.put_bool(self.bool_key, True)
+    assert param_watcher.get_bool(self.bool_key) is True  # First read should populate internal cache
+
+  def test_performance_comparison(self, param_watcher):
+    plain_params = self.params
+
+    for key in self.BYTES_KEYS:
+      plain_params.put(key, b"x" * 10000)
+      param_watcher.get(key)
+    for key in self.BOOL_KEYS:
+      plain_params.put_bool(key, True)
+      param_watcher.get_bool(key)
+
+    def bench(get_bytes, get_bool):
+      tracemalloc.start()
+      start_time = time.process_time()
+      for _ in range(1000):
+        for key in self.BYTES_KEYS:
+          get_bytes(key)
+        for key in self.BOOL_KEYS:
+          get_bool(key)
+      duration = time.process_time() - start_time
+      _, memory = tracemalloc.get_traced_memory()
+      tracemalloc.stop()
+      return duration, memory
+
+    plain_cpu, plain_memory = bench(plain_params.get, plain_params.get_bool)
+    watcher_cpu, watcher_memory = bench(param_watcher.get, param_watcher.get_bool)
+
+    # ParamWatcher *should* be significantly faster and use less memory than Params()
+    assert watcher_cpu < plain_cpu * 0.6, f"PW CPU ({watcher_cpu:.4f}s) should be < 60% of Param call ({plain_cpu:.4f}s)"
+    assert watcher_memory < plain_memory * 0.5, f"PW Memory ({watcher_memory}B) should be < 50% of Param call ({plain_memory}B)"
+
+  def test_cache_invalidation_simulation(self, param_watcher):
+    self.params.put(self.bytes_key, b"old")
+    assert param_watcher.get(self.bytes_key) == b"old"
+    time.sleep(0.2)
+
+    event = threading.Event()
+    param_watcher.add_watcher(lambda key: event.set())
+    param_watcher._trigger_callbacks(self.bytes_key)
+    assert event.wait(timeout=2), "Callback not triggered"
+
+    self.params.put(self.bytes_key, b"new")
+    assert param_watcher.get(self.bytes_key) == b"new"

sunnypilot/tools/profile_params.py

@@ -0,0 +1,171 @@
+#!/usr/bin/env python3
+import argparse
+import ctypes
+import csv
+import os
+import platform
+import random
+import select
+import struct
+import sys
+import time
+import matplotlib.pyplot as plt
+import matplotlib.ticker as ticker
+from collections import defaultdict
+
+from openpilot.system.hardware.hw import Paths
+
+from openpilot.sunnypilot.common.param_watcher import ParamWatcher, IN_CLOSE_WRITE, IN_MOVED_TO
+
+IN_ACCESS = 0x00000001
+
+
+def get_linux_monitor(params_path, reads, writes):
+  libc = ctypes.CDLL('libc.so.6')
+  fd = libc.inotify_init()
+  if fd < 0:
+    return None
+
+  mask = IN_ACCESS | IN_MOVED_TO | IN_CLOSE_WRITE
+  if libc.inotify_add_watch(fd, params_path.encode(), mask) < 0:
+    return None
+
+  poll_obj = select.epoll()
+  poll_obj.register(fd, select.EPOLLIN)
+
+  def monitor():
+    for fileno, _ in poll_obj.poll(0.1):
+      if fileno == fd:
+        buffer = os.read(fd, 2048)
+        i = 0
+        while i + 16 <= len(buffer):
+          wd, mask, cookie, name_len = struct.unpack_from("iIII", buffer, i)
+          name = buffer[i+16:i+16+name_len].rstrip(b"\0").decode('utf-8', 'ignore')
+          if name and not name.startswith("."):
+            if mask & IN_ACCESS:
+              reads[name] += 1
+            elif mask & (IN_MOVED_TO | IN_CLOSE_WRITE):
+              writes[name] += 1
+          i += 16 + name_len
+
+  def cleanup():
+    os.close(fd)
+  return monitor, cleanup
+
+def get_darwin_monitor(params_path, reads, writes):
+  print("WARNING: macOS only reports WRITES.")
+
+  def callback(name):
+    writes[name] += 1
+
+  watcher = ParamWatcher()
+  watcher.add_watcher(callback)
+
+  def monitor():
+    time.sleep(0.1)
+
+  def cleanup():
+    if callback in watcher._callbacks:
+      watcher._callbacks.remove(callback)
+  return monitor, cleanup
+
+def profile_params():
+  parser = argparse.ArgumentParser(description="Profile Params I/O")
+  parser.add_argument("--timeout", type=int, default=30, help="Timeout in minutes (default: 30 mins)")
+  default_out = os.path.join(os.path.dirname(os.path.abspath(__file__)), f"params_profile_{random.randrange(99999)}.csv")
+  parser.add_argument("--out", type=str, default=default_out, help="Output CSV file")
+  args = parser.parse_args()
+
+  path = Paths.params_root()
+  if not os.path.exists(path):
+    return print(f"Error: {path} not found")
+
+  print(f"Profiling Params I/O at: {path}\nPress CTRL+C to stop.")
+  reads, writes = defaultdict(int), defaultdict(int)
+
+  setup = get_linux_monitor if platform.system() == "Linux" else \
+          get_darwin_monitor if platform.system() == "Darwin" else None
+
+  if not setup:
+    return print("Unsupported platform")
+  monitor, cleanup = setup(path, reads, writes) or (None, None)
+
+  if not monitor:
+    return print("Failed to initialize monitor")
+
+  start_time = time.monotonic()
+  timeout_seconds = args.timeout * 60
+  last_print = start_time
+
+  try:
+    while True:
+      monitor()
+      if time.monotonic() - last_print > 1.0:
+        sys.stdout.write(".")
+        sys.stdout.flush()
+        last_print = time.monotonic()
+
+      if args.timeout > 0 and (time.monotonic() - start_time) > timeout_seconds:
+        print("\nTimeout reached.")
+        break
+  except KeyboardInterrupt:
+    print("\n\nStopping...")
+  finally:
+    cleanup()
+
+  duration = time.monotonic() - start_time
+
+
+  with open(args.out, 'w', newline='') as csvfile:
+    writer = csv.writer(csvfile)
+    writer.writerow(['Param Name', 'Reads/sec', 'Writes/sec', 'Total Reads', 'Total Writes'])
+    for k in sorted(set(reads) | set(writes), key=lambda k: reads[k] + writes[k], reverse=True):
+      writer.writerow([k, f"{reads[k]/duration:.1f}", f"{writes[k]/duration:.1f}", reads[k], writes[k]])
+  print(f"CSV report saved to {args.out}")
+
+
+  data = []
+  for k in sorted(set(reads) | set(writes), key=lambda k: reads[k] + writes[k], reverse=True):
+    data.append((k, reads[k]/duration, writes[k]/duration))
+
+  if data:
+    data = data[:10]
+    names = [x[0] for x in data]
+    read_rates = [x[1] for x in data]
+    write_rates = [x[2] for x in data]
+
+    bar_height = 0.35
+    plt.figure(figsize=(12, len(names) * 0.5 + 2), dpi=150)
+    y_pos = range(len(names))
+
+    y_pos_reads = [y - bar_height/2 for y in y_pos]
+    y_pos_writes = [y + bar_height/2 for y in y_pos]
+
+    plt.barh(y_pos_reads, read_rates, height=bar_height, align='center', color='dodgerblue', alpha=0.8, label='Reads/sec')
+    plt.barh(y_pos_writes, write_rates, height=bar_height, align='center', color='red', alpha=0.8, label='Writes/sec')
+
+    for i, (r_rate, w_rate) in enumerate(zip(read_rates, write_rates, strict=False)):
+      if r_rate > 0:
+        plt.text(r_rate, y_pos_reads[i], f"{r_rate:.2f}", va='center', fontsize=8, color='#005a9e', fontweight='bold')
+      if w_rate > 0:
+        plt.text(w_rate, y_pos_writes[i], f"{w_rate:.2f}", va='center', fontsize=8, color='#a30000', fontweight='bold')
+
+    max_val = max(max(read_rates), max(write_rates)) if read_rates else 0
+
+    plt.xlim(0, max_val * 1.15)
+    plt.yticks(y_pos, names)
+    plt.xlabel('Rate (Hz)')
+    plt.title('Top 10 Params I/O Profile')
+    plt.legend()
+    plt.grid(axis='x', linestyle='--', alpha=0.5)
+    plt.gca().xaxis.set_major_locator(ticker.MaxNLocator(integer=True, nbins='auto'))
+    plt.tight_layout()
+    plt.gca().invert_yaxis()
+
+    plot_filename = os.path.splitext(args.out)[0] + ".png"
+    plt.savefig(plot_filename)
+    print(f"Plot saved to {plot_filename}")
+
+
+if __name__ == "__main__":
+  profile_params()

system/hardware/hw.py

@@ -95,3 +95,10 @@ class Paths:
       return str(Path(Paths.comma_home()) / "media" / "0" / "osm")
     else:
       return "/data/media/0/osm"
+
+  @staticmethod
+  def params_root() -> str:
+    if PC:
+      return str(Path(Paths.comma_home()) / "params" / "d")
+    else:
+      return "/data/params/d"

system/ui/sunnypilot/widgets/list_view.py

@@ -16,6 +16,7 @@ from openpilot.system.ui.widgets.list_view import ListItem, ToggleAction, ItemAc
                                                   _resolve_value, BUTTON_WIDTH, BUTTON_HEIGHT, TEXT_PADDING
 from openpilot.system.ui.sunnypilot.lib.styles import style
 from openpilot.system.ui.sunnypilot.widgets.option_control import OptionControlSP, LABEL_WIDTH
+from openpilot.selfdrive.ui.ui_state import ui_state
 
 
 class ToggleActionSP(ToggleAction):
@@ -247,6 +248,9 @@ class ListItemSP(ListItem):
 
 def toggle_item_sp(title: str | Callable[[], str], description: str | Callable[[], str] | None = None, initial_state: bool = False,
                    callback: Callable | None = None, icon: str = "", enabled: bool | Callable[[], bool] = True, param: str | None = None) -> ListItemSP:
+  if param is None and hasattr(ui_state.params, 'last_accessed_param') and ui_state.params.last_accessed_param:
+    param = ui_state.params.last_accessed_param
+    ui_state.params.last_accessed_param = None
   action = ToggleActionSP(initial_state=initial_state, enabled=enabled, callback=callback, param=param)
   return ListItemSP(title=title, description=description, action_item=action, icon=icon, callback=callback)
 
@@ -254,6 +258,9 @@ def toggle_item_sp(title: str | Callable[[], str], description: str | Callable[[
 def multiple_button_item_sp(title: str | Callable[[], str], description: str | Callable[[], str], buttons: list[str | Callable[[], str]],
                             selected_index: int = 0, button_width: int = style.BUTTON_WIDTH, callback: Callable = None,
                             icon: str = "", param: str | None = None, inline: bool = False) -> ListItemSP:
+  if param is None and hasattr(ui_state.params, 'last_accessed_param') and ui_state.params.last_accessed_param:
+    param = ui_state.params.last_accessed_param
+    ui_state.params.last_accessed_param = None
   action = MultipleButtonActionSP(buttons, button_width, selected_index, callback=callback, param=param)
   return ListItemSP(title=title, description=description, icon=icon, action_item=action, inline=inline)
 

tools/profile_params.py

@@ -0,0 +1,109 @@
+#!/usr/bin/env python3
+import os
+import sys
+import platform
+import struct
+import select
+import time
+import ctypes
+from collections import defaultdict
+
+from openpilot.system.hardware.hw import Paths
+
+from sunnypilot.common.param_watcher import ParamWatcher, IN_CLOSE_WRITE, IN_MOVED_TO
+
+IN_ACCESS = 0x00000001
+
+
+def get_linux_monitor(params_path, reads, writes):
+  libc = ctypes.CDLL('libc.so.6')
+  fd = libc.inotify_init()
+  if fd < 0:
+    return None
+
+  mask = IN_ACCESS | IN_MOVED_TO | IN_CLOSE_WRITE
+  if libc.inotify_add_watch(fd, params_path.encode(), mask) < 0:
+    return None
+
+  poll_obj = select.epoll()
+  poll_obj.register(fd, select.EPOLLIN)
+
+  def monitor():
+    for fileno, _ in poll_obj.poll(0.1):
+      if fileno == fd:
+        buffer = os.read(fd, 4096)
+        i = 0
+        while i + 16 <= len(buffer):
+          wd, mask, cookie, name_len = struct.unpack_from("iIII", buffer, i)
+          name = buffer[i+16:i+16+name_len].rstrip(b"\0").decode('utf-8', 'ignore')
+          if name and not name.startswith("."):
+            if mask & IN_ACCESS:
+              reads[name] += 1
+            elif mask & (IN_MOVED_TO | IN_CLOSE_WRITE):
+              writes[name] += 1
+          i += 16 + name_len
+
+  def cleanup():
+    os.close(fd)
+  return monitor, cleanup
+
+def get_darwin_monitor(params_path, reads, writes):
+  print("WARNING: macOS only reports WRITES.")
+
+  def callback(name):
+    writes[name] += 1
+
+  watcher = ParamWatcher()
+  watcher.add_watcher(callback)
+
+  def monitor():
+    time.sleep(0.1)
+
+  def cleanup():
+    if callback in watcher._callbacks:
+      watcher._callbacks.remove(callback)
+  return monitor, cleanup
+
+def profile_params():
+  path = Paths.params_root()
+  if not os.path.exists(path):
+    return print(f"Error: {path} not found")
+
+  print(f"Profiling Params I/O at: {path}\nPress CTRL+C to stop.")
+  reads, writes = defaultdict(int), defaultdict(int)
+
+  setup = get_linux_monitor if platform.system() == "Linux" else \
+          get_darwin_monitor if platform.system() == "Darwin" else None
+
+  if not setup:
+    return print("Unsupported platform")
+  monitor, cleanup = setup(path, reads, writes) or (None, None)
+
+  if not monitor:
+    return print("Failed to initialize monitor")
+
+  start_time = time.monotonic()
+  last_print = start_time
+
+  try:
+    while True:
+      monitor()
+      if time.monotonic() - last_print > 1.0:
+        sys.stdout.write(".")
+        sys.stdout.flush()
+        last_print = time.monotonic()
+  except KeyboardInterrupt:
+    print("\n\nStopping...")
+  finally:
+    cleanup()
+
+  duration = time.monotonic() - start_time
+  print(f"\n\n=== Params I/O Profile Report ({duration:.1f}s) ===")
+  print(f"{'Param Name':<40} | {'Reads/sec':<10} | {'Writes/sec':<10} | {'Total Reads':<12} | {'Total Writes':<12}")
+  print("-" * 95)
+
+  for k in sorted(set(reads) | set(writes), key=lambda k: reads[k] + writes[k], reverse=True):
+    print(f"{k:<40} | {reads[k]/duration:<10.1f} | {writes[k]/duration:<10.1f} | {reads[k]:<12} | {writes[k]:<12}")
+
+if __name__ == "__main__":
+  profile_params()