ovos-PHAL-plugin-dotstar 0.0.3a1__tar.gz

ovos_phal_plugin_dotstar-0.0.3a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 builderjer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ovos_phal_plugin_dotstar-0.0.3a1/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: ovos-PHAL-plugin-dotstar
+Version: 0.0.3a1
+Summary: An OVOS PHAL plugin to control DotStar type LEDs
+Author-email: builderjer <builderjer@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/OpenVoiceOS/ovos-PHAL-plugin-dotstar
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Text Processing :: Linguistic
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: ovos-plugin-manager<3.0.0,>=2.1.0
+Requires-Dist: ovos-lingua-franca>=0.4.8a8
+Requires-Dist: ovos-i2c-detection>=0.0.5
+Requires-Dist: adafruit-circuitpython-dotstar; platform_machine == "aarch64" or platform_machine == "armv7l" or platform_machine == "armv6l"
+Requires-Dist: gpiozero; platform_machine == "aarch64" or platform_machine == "armv7l" or platform_machine == "armv6l"
+Requires-Dist: rpi-lgpio; platform_machine == "aarch64" or platform_machine == "armv7l" or platform_machine == "armv6l"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Dynamic: license-file
+
+# ovos-PHAL-plugin-dotstar
+
+**Compatible with**
+* Respeaker 2/4/6/8 i2c microphone HAT's
+* Adafruit 2 mic VoiceBonnet
+
+# Usage
+
+There are a few ways for this plugin to get enabled.
+
+* Enable manually
+
+Add this to your `~/.config/mycroft/mycroft.conf`
+
+```json
+{
+    "PHAL": {
+        "ovos-PHAL-plugin-dotstar": {
+            "enabled": true
+        }
+    }
+}
+```
+With this configuration, no other validation checks are made.  It is assuming you have a compatible HAT installed.
+
+* Automatically with [ovos-i2csound](https://github.com/OpenVoiceOS/ovos-i2csound)
+
+When `ovos-i2csound` is installed and running, it creates a file at `/etc/OpenVoiceOS/i2c_platform` with the HAT name it detected.  This plugin then checks that file and if a compatible HAT is detected, the plugin is activated.
+
+* Automatically with hardware detection
+
+If the above two options don't work, the plugin tries to detect a compatible HAT using `i2c-detect`.  If a compatible device address is found, the plugin will activate.
+
+From this point, if you are using a ReSpeaker i2c microphone, your LED's should give you prompts of what is going on with your OVOS assistant.
+
+### Adafruit 2mic voicebonnet
+
+The [Adafruit voicebonnet](https://learn.adafruit.com/adafruit-voice-bonnet/overview) can be used with this plugin, but it requires one more step of manual configuration.  While the above detection options will properly enable the plugin, this HAT uses different GPIO pins for it's LED's, therefore cannot be easily distinguished from a ReSpeaker 2mic HAT.
+
+Add the following to your `~/.config/mycroft/mycroft.conf` file
+
+```json
+{
+    "PHAL": {
+        "ovos-PHAL-plugin-dotstar": {
+            "dotstar_hat": "ADAFRUIT2MIC"
+        }
+    }
+}
+```
+
+And restart OVOS
+
+Your LED's on your Adafruit voicebonnet will now show the same prompts as the ReSpeaker devices.
+
+## Custom Configuration
+
+Colors and animations can be configured in `~/.config/mycroft/mycroft.conf`
+
+```json
+{
+    "PHAL": {
+        "ovos-PHAL-plugin-dotstar": {
+            "main_color": "Mycroft blue",
+            "background_color": "OVOS red",
+            "listen_animation": "breath",
+            "talking_animation": "blink"
+        }
+    }
+}
+```
+
+`main_color` -> str:
+```
+    rgb value -> "32, 195, 63"
+    name -> "blue"
+    hex value -> "#22A7F0"
+```
+
+`background_color` -> str
+```
+    rgb value -> "32, 195, 63"
+    name -> "red"
+    hex value -> "#FF1A1A"
+```
+
+`listen_animation` -> str:
+```
+    one of:
+        'breathe'
+        'chase'
+        'fill'
+        'refill'
+        'bounce'
+        'blink'
+        'alternating'
+```
+
+`talking_animation` -> str:
+```
+    one of:
+        'breathe'
+        'chase'
+        'fill'
+        'refill'
+        'bounce'
+        'blink'
+        'alternating'
+```
+## Conflicts With
+
+There are two pre-existing plugins that either need uninstalled with pip, or blacklisted in your `mycroft.conf` file.
+
+[ovos-PHAL-plugin-respeaker2mic](https://github.com/OpenVoiceOS/ovos-PHAL-plugin-respeaker-2mic)
+[ovos-PHAL-plugin-respeaker4mic](https://github.com/OpenVoiceOS/ovos-PHAL-plugin-respeaker-4mic)
+
+### TODO
+
+- [x] Add more animations
+- [x] User configurable colors
+- [ ] Theme support
+- [x] User configurable animations
+- [ ] Add github tests and automation
+
+Please enjoy this plugin and don't be afraid to create an [issue](#) if you run into any problems.

ovos_phal_plugin_dotstar-0.0.3a1/README.md

@@ -0,0 +1,125 @@
+# ovos-PHAL-plugin-dotstar
+
+**Compatible with**
+* Respeaker 2/4/6/8 i2c microphone HAT's
+* Adafruit 2 mic VoiceBonnet
+
+# Usage
+
+There are a few ways for this plugin to get enabled.
+
+* Enable manually
+
+Add this to your `~/.config/mycroft/mycroft.conf`
+
+```json
+{
+    "PHAL": {
+        "ovos-PHAL-plugin-dotstar": {
+            "enabled": true
+        }
+    }
+}
+```
+With this configuration, no other validation checks are made.  It is assuming you have a compatible HAT installed.
+
+* Automatically with [ovos-i2csound](https://github.com/OpenVoiceOS/ovos-i2csound)
+
+When `ovos-i2csound` is installed and running, it creates a file at `/etc/OpenVoiceOS/i2c_platform` with the HAT name it detected.  This plugin then checks that file and if a compatible HAT is detected, the plugin is activated.
+
+* Automatically with hardware detection
+
+If the above two options don't work, the plugin tries to detect a compatible HAT using `i2c-detect`.  If a compatible device address is found, the plugin will activate.
+
+From this point, if you are using a ReSpeaker i2c microphone, your LED's should give you prompts of what is going on with your OVOS assistant.
+
+### Adafruit 2mic voicebonnet
+
+The [Adafruit voicebonnet](https://learn.adafruit.com/adafruit-voice-bonnet/overview) can be used with this plugin, but it requires one more step of manual configuration.  While the above detection options will properly enable the plugin, this HAT uses different GPIO pins for it's LED's, therefore cannot be easily distinguished from a ReSpeaker 2mic HAT.
+
+Add the following to your `~/.config/mycroft/mycroft.conf` file
+
+```json
+{
+    "PHAL": {
+        "ovos-PHAL-plugin-dotstar": {
+            "dotstar_hat": "ADAFRUIT2MIC"
+        }
+    }
+}
+```
+
+And restart OVOS
+
+Your LED's on your Adafruit voicebonnet will now show the same prompts as the ReSpeaker devices.
+
+## Custom Configuration
+
+Colors and animations can be configured in `~/.config/mycroft/mycroft.conf`
+
+```json
+{
+    "PHAL": {
+        "ovos-PHAL-plugin-dotstar": {
+            "main_color": "Mycroft blue",
+            "background_color": "OVOS red",
+            "listen_animation": "breath",
+            "talking_animation": "blink"
+        }
+    }
+}
+```
+
+`main_color` -> str:
+```
+    rgb value -> "32, 195, 63"
+    name -> "blue"
+    hex value -> "#22A7F0"
+```
+
+`background_color` -> str
+```
+    rgb value -> "32, 195, 63"
+    name -> "red"
+    hex value -> "#FF1A1A"
+```
+
+`listen_animation` -> str:
+```
+    one of:
+        'breathe'
+        'chase'
+        'fill'
+        'refill'
+        'bounce'
+        'blink'
+        'alternating'
+```
+
+`talking_animation` -> str:
+```
+    one of:
+        'breathe'
+        'chase'
+        'fill'
+        'refill'
+        'bounce'
+        'blink'
+        'alternating'
+```
+## Conflicts With
+
+There are two pre-existing plugins that either need uninstalled with pip, or blacklisted in your `mycroft.conf` file.
+
+[ovos-PHAL-plugin-respeaker2mic](https://github.com/OpenVoiceOS/ovos-PHAL-plugin-respeaker-2mic)
+[ovos-PHAL-plugin-respeaker4mic](https://github.com/OpenVoiceOS/ovos-PHAL-plugin-respeaker-4mic)
+
+### TODO
+
+- [x] Add more animations
+- [x] User configurable colors
+- [ ] Theme support
+- [x] User configurable animations
+- [ ] Add github tests and automation
+
+Please enjoy this plugin and don't be afraid to create an [issue](#) if you run into any problems.

ovos_phal_plugin_dotstar-0.0.3a1/ovos_PHAL_plugin_dotstar/__init__.py

@@ -0,0 +1,251 @@
+from threading import Event
+
+from os.path import exists, expanduser, join
+from time import sleep
+
+from ovos_bus_client.message import Message
+from ovos_plugin_manager.phal import PHALPlugin
+from ovos_plugin_manager.templates.phal import PHALValidator
+from ovos_utils.log import LOG
+from ovos_config.config import Configuration
+
+from ovos_i2c_detection import is_wm8960, is_respeaker_4mic, is_respeaker_6mic, is_mark_1
+
+from lingua_franca.util.colors import Color
+from lingua_franca.internal import load_language
+
+from ovos_PHAL_plugin_dotstar.leds import DotStarLed
+from ovos_PHAL_plugin_dotstar.animations import animations
+
+# File defined in ovos-i2csound
+# https://github.com/OpenVoiceOS/ovos-i2csound/blob/dev/ovos-i2csound#L76
+I2C_PLATFORM_FILE = "/etc/OpenVoiceOS/i2c_platform"
+
+# Wiring of the supported HATs (clock pin, data pin, number of LEDs). The actual
+# adafruit_dotstar.DotStar objects are built lazily by get_predefined_hat() so
+# the module stays importable on hosts without SPI/LED hardware (e.g. CI).
+PREDEFINED_HAT_PINS = {
+    "WM8960": ("D11", "D10", 3),
+    "RESPEAKER4": ("D11", "D10", 12),
+    "RESPEAKER6": ("D11", "D10", 12),
+    "ADAFRUIT2MIC": ("D6", "D5", 3),
+}
+
+
+def get_predefined_hat(name):
+    """
+    Instantiate the adafruit_dotstar.DotStar strip for a known HAT.
+
+    Hardware libraries (adafruit_dotstar, board) are imported here rather than at
+    module load so the plugin can be imported and unit-tested without LED hardware.
+
+    Parameters:
+        name (str): One of the keys in PREDEFINED_HAT_PINS.
+
+    Returns:
+        adafruit_dotstar.DotStar: configured LED strip.
+    """
+    clock, data, num_led = PREDEFINED_HAT_PINS[name]
+    from adafruit_dotstar import DotStar
+    import board
+    return DotStar(getattr(board, clock), getattr(board, data), num_led,
+                   brightness=0.2)
+
+
+def check_i2c_platform():
+    if exists(I2C_PLATFORM_FILE):
+        with open(I2C_PLATFORM_FILE, "r") as f:
+            platform = f.readline().strip()
+            LOG.debug(f"platform in check_i2c_platform: {platform}")
+            if platform in PREDEFINED_HAT_PINS:
+                LOG.debug(f"detected {platform} in i2c_platform")
+                return platform
+    return None
+
+
+class DotStarLedControlPluginValidator(PHALValidator):
+
+    @staticmethod
+    def validate(config=None):
+        # If the user enabled the plugin no need to go further
+        """
+        Validate the configuration for the DotStar LED control plugin.
+        
+        Determines whether the plugin should be activated based on configuration and hardware detection.
+        
+        Parameters:
+            config (dict, optional): Plugin configuration dictionary. Defaults to None.
+        
+        Returns:
+            bool: True if the plugin should be enabled, False otherwise.
+        
+        Conditions for validation:
+            1. If plugin is explicitly enabled in configuration
+            2. If specific audio hardware is detected (WM8960, ReSpeaker 4-mic, ReSpeaker 6-mic)
+            3. Excludes Mark 1 hardware configuration
+        
+        Logs debug information about validation process.
+        """
+        if config.get("enabled"):
+            LOG.debug("user enabled")
+            return True
+        # Try a direct hardware check
+        if is_wm8960() or is_respeaker_4mic() or is_respeaker_6mic():
+            if is_mark_1():
+                LOG.debug("Mark 1 detected.  Dotstar is not needed")
+                return False
+            LOG.debug("direct hardware check")
+            return True
+        LOG.debug("no validation")
+        return False
+
+
+class DotStarLedControlPlugin(PHALPlugin):
+    validator = DotStarLedControlPluginValidator
+
+    lang = Configuration().get("lang", "en")
+    try:
+        load_language(lang)
+    except Exception as e:
+        LOG.error(f"Could not load language model {e}")
+
+    def __init__(self, bus=None, config=None):
+        super().__init__(bus=bus, name="ovos-PHAL-plugin-dotstar", config=config)
+        self._enable_pin = None
+        self.active_animation = None
+        self.ds = None
+        # Check and see if there is a configuration for a specific board
+        if self.config.get("dotstar_hat"):
+            ds = self.config.get("dotstar_hat")
+            if ds in PREDEFINED_HAT_PINS:
+                LOG.debug(f"loading {ds} from config")
+                try:
+                    self.ds = DotStarLed(get_predefined_hat(ds))
+                except Exception as e:
+                    LOG.error(f"Could not load {ds} from config:  {e}")
+            elif isinstance(self.config.get("dotstar_hat"), dict):
+                try:
+                    from adafruit_dotstar import DotStar
+                    self.ds = DotStar(
+                        ds["clock_pin"], ds["led_pin"], ds["num_led"], brightness=ds.get("brightness", 0.2))
+                    self._enable_pin = ds.get("enable_pin", None)
+                except Exception as e:
+                    LOG.error(f"Could not create led array:  {e}")
+        else:
+            try:
+                self.ds = DotStarLed(get_predefined_hat(check_i2c_platform()))
+            except KeyError as e:
+                LOG.debug(f"check_i2c_platform failed {e}")
+            except Exception as e:
+                LOG.error(e)
+        # No manual configuration and i2csound is not installed or failed
+        if not self.ds:
+            # Direct hardware checks
+            if is_wm8960():
+                self.ds = DotStarLed(get_predefined_hat("WM8960"))
+            elif is_respeaker_4mic():
+                self.ds = DotStarLed(get_predefined_hat("RESPEAKER4"))
+            elif is_respeaker_6mic():
+                self.ds = DotStarLed(get_predefined_hat("RESPEAKER6"))
+            # All else fails, fall back to respeker 4mic
+            else:
+                self.ds = DotStarLed(get_predefined_hat("RESPEAKER4"))
+
+        # Required for ReSpeaker 4/6/8 mic
+        if not is_wm8960():
+            LOG.debug("enable LED's")
+            from gpiozero import LED
+            from RPi.GPIO import cleanup
+            cleanup(5)
+            self._enable_pin = LED(5)
+            self._enable_pin.on()
+
+        self.ds.fill(self.main_color.rgb255)
+        sleep(1.0)
+        self.on_reset()
+
+    @property
+    def main_color(self):
+        color = self.config.get(
+            "main_color", Color.from_description("Mycroft blue"))
+        if isinstance(color, str):
+            try:
+                color = eval(color)
+                color = Color.from_rgb(color[0], color[1], color[2])
+            except Exception as e:
+                LOG.debug(f"Exception caught in eval {e}")
+                try:
+                    LOG.debug(color)
+                    color = Color.from_hex(color)
+                    LOG.debug(color)
+                except Exception as e:
+                    LOG.debug(f"Exception caught in description {e}")
+                    try:
+                        color = Color.from_description(color)
+                    except Exception as e:
+                        LOG.warning(f"could not set color to {color}: {e}")
+                        color = Color.from_description("Mycroft blue")
+        return color
+
+    @property
+    def background_color(self):
+        color = self.config.get(
+            "background_color", Color.from_description("OVOS red"))
+        if isinstance(color, str):
+            try:
+                color = eval(color)
+                color = Color.from_rgb(color[0], color[1], color[2])
+            except Exception as e:
+                LOG.debug(f"Exception caught in eval {e}")
+                try:
+                    color = Color.from_description(color)
+                except Exception as e:
+                    LOG.debug(f"Exception caught in description {e}")
+                    try:
+                        color = Color.from_hex(color)
+                    except Exception as e:
+                        LOG.warning(f"could not set color to {color}: {e}")
+                        color = Color.from_description("OVOS red")
+        return color
+
+    @property
+    def listen_animation(self):
+        return self.config.get("listen_animation", "breathe")
+
+    @property
+    def talking_animation(self):
+        return self.config.get("talking_animation", "blink")
+
+    def on_record_begin(self, message=None):
+        self.active_animation = animations[self.listen_animation](
+            self.ds, self.main_color)
+        self.active_animation.start()
+
+    def on_record_end(self, message=None):
+        self.on_reset()
+
+    def on_audio_output_start(self, message=None):
+        LOG.debug(animations[self.talking_animation])
+        self.active_animation = animations[self.talking_animation](
+            self.ds, self.main_color, repeat=True)
+        LOG.debug(self.active_animation)
+        self.active_animation.start()
+
+    def on_audio_output_end(self, message=None):
+        self.on_reset()
+
+    def on_think(self, message=None):
+        self.on_reset()
+
+    def on_reset(self, message=None):
+        if self.active_animation:
+            self.active_animation.stop()
+            self.active_animation = None
+        self.ds.fill(Color.from_description("black").rgb255)
+
+    def on_system_reset(self, message=None):
+        self.on_reset()
+
+    def shutdown(self):
+        self.reset()
+        super().shutdown()

ovos_phal_plugin_dotstar-0.0.3a1/ovos_PHAL_plugin_dotstar/animations.py

@@ -0,0 +1,308 @@
+from abc import abstractmethod
+from threading import Event
+
+from ovos_utils.log import LOG
+from time import time
+from typing import Optional
+
+from lingua_franca.util.colors import Color
+from lingua_franca.internal import load_language
+
+from ovos_config.config import Configuration
+
+from ovos_PHAL_plugin_dotstar.leds import DotStarLed
+
+
+class LedAnimation:
+    def __init__(self, leds: DotStarLed, **kwargs):
+        self.leds = leds
+        self._delay = Event()
+        # Needed for lingua_franca
+        self._lang = Configuration().get("lang", "en")
+        load_language(self._lang)
+
+    @abstractmethod
+    def start(self, timeout: Optional[int] = None, one_shot: bool = False):
+        """
+        Start the animation.
+        :param timeout: Optional timeout in seconds after which animation stops
+        :param one_shot: if True, run animation once and return
+        """
+
+    @abstractmethod
+    def stop(self):
+        """
+        Stop the animation and reset LEDs to black.
+        """
+
+
+class BreatheLedAnimation(LedAnimation):
+    def __init__(self, leds: DotStarLed, color: Color, **kwargs):
+        """
+        Breathing effect where all LEDs dim up and down until timing out
+        or being stopped. LEDs are turned off after animation.
+        @param leds: LED object to interact with
+        @param color: Base color of LEDs
+        """
+        LedAnimation.__init__(self, leds)
+        self.color = color
+        self.step = 0.1
+        self.step_delay = 0.1
+        self.stopping = Event()
+
+    def start(self, timeout=None, one_shot=False):
+        self.stopping.clear()
+        end_time = time() + timeout if timeout else None
+        brightness = 0
+        step = self.step
+        ending = False
+        while not self.stopping.is_set():
+            if brightness >= 1:  # Going Down
+                step = -1 * self.step
+            elif brightness <= 0:
+                step = self.step
+
+            brightness += step
+            brightness = round(brightness, 1)
+            self.leds.fill(self.color.rgb255 + (brightness,))
+            self._delay.wait(self.step_delay)
+            if one_shot and brightness >= 1:
+                ending = True
+            elif ending and brightness <= 0:
+                self.stopping.set()
+            elif end_time and time() > end_time:
+                self.stopping.set()
+        self.leds.fill(Color.from_description("black".rgb255))
+
+    def stop(self):
+        self.stopping.set()
+
+
+class ChaseLedAnimation(LedAnimation):
+    def __init__(self, leds: DotStarLed, foreground_color: Color,
+                 background_color: Optional[Color] = None, **kwargs):
+        """
+        Chase effect where all LEDs are lit individually in order until timing
+        out or being stopped. LEDs are turned off after animation.
+        @param leds: LED object to interact with
+        @param foreground_color: Color of active LED
+        @param background_color: Color of inactive LEDs
+        """
+        LedAnimation.__init__(self, leds)
+        self.foreground_color = foreground_color
+        self.background_color = background_color or Color.from_description(
+            "black")
+        self.step = 0.05
+        self.step_delay = 0.1
+        self.stopping = Event()
+
+    def start(self, timeout=None, one_shot=False):
+        self.stopping.clear()
+        end_time = time() + timeout if timeout else None
+
+        self.leds.fill(self.background_color.rgb255)
+        while not self.stopping.is_set():
+            for led in range(0, self.leds.num_leds):
+                self.leds.set_led(led, self.foreground_color.rgb255)
+                self._delay.wait(self.step_delay)
+                self.leds.set_led(led, self.background_color.rgb255)
+            if one_shot:
+                self.stopping.set()
+            elif end_time and time() > end_time:
+                self.stopping.set()
+        self.leds.fill(Color.from_description("black").rgb255)
+
+    def stop(self):
+        self.stopping.set()
+
+
+class FillLedAnimation(LedAnimation):
+    def __init__(self, leds: DotStarLed, fill_color: Color,
+                 reverse: bool = False, **kwargs):
+        """
+        Fill effect where LEDs are set to the same color in order. LEDs will
+        remain lit after the animation.
+        @param leds: LED object to interact with
+        @param fill_color: Color to fill LEDs
+        @param reverse: If true, fill in reverse order
+        """
+        LedAnimation.__init__(self, leds)
+        self.fill_color = fill_color
+        self.reverse = reverse
+        self.step_delay = 0.05
+
+    def start(self, timeout=None, one_shot=True):
+        if not one_shot or timeout is not None:
+            LOG.warning("Fill animation does not support persistent animation")
+        leds = list(range(0, self.leds.num_leds))
+        if self.reverse:
+            leds.reverse()
+        for led in leds:
+            self.leds.set_led(led, self.fill_color.rgb255)
+            self._delay.wait(self.step_delay)
+
+    def stop(self):
+        pass
+
+
+class RefillLedAnimation(LedAnimation):
+    def __init__(self, leds: DotStarLed, fill_color: Color,
+                 reverse: bool = False, **kwargs):
+        """
+        Fill effect in the requested color, followed by fill effect in black.
+        Animation repeats until timing out or being stopped. LEDs are turned
+        off after animation.
+        @param leds: LED object to interact with
+        @param fill_color: Color to fill LEDs
+        @param reverse: If true, fill in reverse order
+        """
+        LedAnimation.__init__(self, leds)
+        self.stopping = Event()
+        self.fill_color = fill_color
+        self.fill_animation = FillLedAnimation(leds, fill_color, reverse)
+
+    def start(self, timeout=None, one_shot=False):
+        self.stopping.clear()
+        end_time = time() + timeout if timeout else None
+
+        while not self.stopping.is_set():
+            self.fill_animation.start()
+            self.fill_animation.fill_color = Color.from_description("black")
+            self.fill_animation.start()
+            self.fill_animation.fill_color = self.fill_color
+            if one_shot:
+                self.stopping.set()
+            elif end_time and time() > end_time:
+                self.stopping.set()
+
+    def stop(self):
+        self.stopping.set()
+
+
+class BounceLedAnimation(LedAnimation):
+    def __init__(self, leds: DotStarLed, fill_color: Color,
+                 reverse: bool = False, **kwargs):
+        """
+        Fill effect in the requested color, followed by reversed fill effect
+        in black. Animation repeats until timing out or being stopped.
+        LEDs are turned off after animation.
+        @param leds: LED object to interact with
+        @param fill_color: Color to fill LEDs
+        @param reverse: If true, fill in reverse order
+        """
+        LOG.debug("bouncing")
+        LedAnimation.__init__(self, leds)
+        self.stopping = Event()
+        self.fill_color = fill_color
+        self.fill_animation = FillLedAnimation(leds, fill_color, reverse)
+
+    def start(self, timeout=None, one_shot=False):
+        self.stopping.clear()
+        end_time = time() + timeout if timeout else None
+
+        while not self.stopping.is_set():
+            self.fill_animation.start()
+            self.fill_animation.reverse = not self.fill_animation.reverse
+            self.fill_animation.fill_color = Color.from_description("black")
+            self.fill_animation.start()
+            self.fill_animation.reverse = not self.fill_animation.reverse
+            self.fill_animation.fill_color = self.fill_color
+            if one_shot:
+                self.stopping.set()
+            elif end_time and time() > end_time:
+                self.stopping.set()
+
+    def stop(self):
+        self.stopping.set()
+
+
+class BlinkLedAnimation(LedAnimation):
+    def __init__(self, leds: DotStarLed, color: Color,
+                 num_blinks: int = 2, repeat: bool = False, **kwargs):
+        """
+        Blink LEDs in the requested color, for the requested number of blinks.
+        If repeating, pause and repeat the effect until timeout or stop event.
+        @param leds: LED object to interact with
+        @param color: Color to blink LEDs
+        @param num_blinks: Number of times to blink LEDs
+        @param repeat: If true, repeat animation until timeout or stopped
+        """
+        LedAnimation.__init__(self, leds)
+        self.stopping = Event()
+        self.color = color
+        self.num_blinks = num_blinks
+        self.repeat = repeat
+
+    def start(self, timeout=None, one_shot=False):
+        self.stopping.clear()
+        end_time = time() + timeout if timeout else None
+
+        self.leds.fill(Color.from_description("black").rgb255)
+        self._delay.wait(0.25)
+        while not self.stopping.is_set():
+            for i in range(self.num_blinks):
+                self.leds.fill(self.color.rgb255)
+                self._delay.wait(0.1)
+                self.leds.fill(Color.from_description("black").rgb255)
+                self._delay.wait(0.1)
+            if one_shot:
+                self.stopping.set()
+            elif self.repeat:
+                self._delay.wait(.2)
+            else:
+                self.stopping.set()
+            if end_time and time() > end_time:
+                self.stopping.set()
+
+    def stop(self):
+        self.stopping.set()
+
+
+class AlternatingLedAnimation(LedAnimation):
+    def __init__(self, leds: DotStarLed, color: Color, **kwargs):
+        """
+        Show alternating even/odd LEDs
+        @param leds: LED object to interact with
+        @param color: Color to blink LEDs
+        """
+        LedAnimation.__init__(self, leds)
+        self.stopping = Event()
+        self.color = color
+        self.delay = 0.5
+
+    def start(self, timeout: Optional[int] = None, one_shot: bool = False):
+        evens = True
+        self.leds.fill(Color.from_description("black").rgb255)
+        self.stopping.clear()
+        end_time = time() + timeout if timeout else None
+        while not self.stopping.is_set():
+            for led in range(self.leds.num_leds):
+                if evens and led % 2 == 0:
+                    self.leds.set_led(led, self.color.rgb255, False)
+                elif not evens and led % 2 == 1:
+                    self.leds.set_led(led, self.color.rgb255, False)
+                else:
+                    self.leds.set_led(
+                        led, Color.from_description("black").rgb255, False)
+            # self.leds.show()
+            self._delay.wait(self.delay)
+            evens = not evens
+            if one_shot and evens:  # We did one animation
+                self.stopping.set()
+            elif end_time and time() > end_time:
+                self.stopping.set()
+        self.leds.fill(Color.from_description("black").rgb255)
+
+    def stop(self):
+        self.stopping.set()
+
+
+animations = {
+    'breathe': BreatheLedAnimation,
+    'chase': ChaseLedAnimation,
+    'fill': FillLedAnimation,
+    'refill': RefillLedAnimation,
+    'bounce': BounceLedAnimation,
+    'blink': BlinkLedAnimation,
+    'alternating': AlternatingLedAnimation
+}

ovos_phal_plugin_dotstar-0.0.3a1/ovos_PHAL_plugin_dotstar/leds.py

@@ -0,0 +1,40 @@
+from abc import abstractmethod
+
+from ovos_plugin_manager.hardware.led import AbstractLed
+
+
+class DotStarLed(AbstractLed):
+    def __init__(self, dotstar_led_strip):
+        # dotstar_led_strip is an adafruit_dotstar.DotStar instance; the type is
+        # not imported here so the module is importable without LED hardware.
+        self.dotstar = dotstar_led_strip
+
+    @property
+    def num_leds(self):
+        return self.dotstar.n
+
+    @property
+    def capabilities(self):
+        pass
+
+    def set_led(self, led_idx: int, color: tuple, immediate: bool = True):
+        self.dotstar[led_idx] = color
+
+    def fill(self, color: tuple):
+        self.dotstar.fill(color)
+
+    def show(self):
+        self.dotstar.show()
+
+    def shutdown(self):
+        # TODO: something
+        pass
+
+    def scale_brightness(color_val: int, bright_val: float) -> float:
+        """
+        Scale an individual color value by a specified brightness.
+        :param color_val: 0-255 R, G, or B value
+        :param bright_val: 0.0-1.0 brightness scalar value
+        :returns: Float modified color value to account for brightness
+        """
+        return min(255.0, round(color_val * bright_val))

ovos_phal_plugin_dotstar-0.0.3a1/ovos_PHAL_plugin_dotstar.egg-info/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: ovos-PHAL-plugin-dotstar
+Version: 0.0.3a1
+Summary: An OVOS PHAL plugin to control DotStar type LEDs
+Author-email: builderjer <builderjer@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/OpenVoiceOS/ovos-PHAL-plugin-dotstar
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Text Processing :: Linguistic
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: ovos-plugin-manager<3.0.0,>=2.1.0
+Requires-Dist: ovos-lingua-franca>=0.4.8a8
+Requires-Dist: ovos-i2c-detection>=0.0.5
+Requires-Dist: adafruit-circuitpython-dotstar; platform_machine == "aarch64" or platform_machine == "armv7l" or platform_machine == "armv6l"
+Requires-Dist: gpiozero; platform_machine == "aarch64" or platform_machine == "armv7l" or platform_machine == "armv6l"
+Requires-Dist: rpi-lgpio; platform_machine == "aarch64" or platform_machine == "armv7l" or platform_machine == "armv6l"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Dynamic: license-file
+
+# ovos-PHAL-plugin-dotstar
+
+**Compatible with**
+* Respeaker 2/4/6/8 i2c microphone HAT's
+* Adafruit 2 mic VoiceBonnet
+
+# Usage
+
+There are a few ways for this plugin to get enabled.
+
+* Enable manually
+
+Add this to your `~/.config/mycroft/mycroft.conf`
+
+```json
+{
+    "PHAL": {
+        "ovos-PHAL-plugin-dotstar": {
+            "enabled": true
+        }
+    }
+}
+```
+With this configuration, no other validation checks are made.  It is assuming you have a compatible HAT installed.
+
+* Automatically with [ovos-i2csound](https://github.com/OpenVoiceOS/ovos-i2csound)
+
+When `ovos-i2csound` is installed and running, it creates a file at `/etc/OpenVoiceOS/i2c_platform` with the HAT name it detected.  This plugin then checks that file and if a compatible HAT is detected, the plugin is activated.
+
+* Automatically with hardware detection
+
+If the above two options don't work, the plugin tries to detect a compatible HAT using `i2c-detect`.  If a compatible device address is found, the plugin will activate.
+
+From this point, if you are using a ReSpeaker i2c microphone, your LED's should give you prompts of what is going on with your OVOS assistant.
+
+### Adafruit 2mic voicebonnet
+
+The [Adafruit voicebonnet](https://learn.adafruit.com/adafruit-voice-bonnet/overview) can be used with this plugin, but it requires one more step of manual configuration.  While the above detection options will properly enable the plugin, this HAT uses different GPIO pins for it's LED's, therefore cannot be easily distinguished from a ReSpeaker 2mic HAT.
+
+Add the following to your `~/.config/mycroft/mycroft.conf` file
+
+```json
+{
+    "PHAL": {
+        "ovos-PHAL-plugin-dotstar": {
+            "dotstar_hat": "ADAFRUIT2MIC"
+        }
+    }
+}
+```
+
+And restart OVOS
+
+Your LED's on your Adafruit voicebonnet will now show the same prompts as the ReSpeaker devices.
+
+## Custom Configuration
+
+Colors and animations can be configured in `~/.config/mycroft/mycroft.conf`
+
+```json
+{
+    "PHAL": {
+        "ovos-PHAL-plugin-dotstar": {
+            "main_color": "Mycroft blue",
+            "background_color": "OVOS red",
+            "listen_animation": "breath",
+            "talking_animation": "blink"
+        }
+    }
+}
+```
+
+`main_color` -> str:
+```
+    rgb value -> "32, 195, 63"
+    name -> "blue"
+    hex value -> "#22A7F0"
+```
+
+`background_color` -> str
+```
+    rgb value -> "32, 195, 63"
+    name -> "red"
+    hex value -> "#FF1A1A"
+```
+
+`listen_animation` -> str:
+```
+    one of:
+        'breathe'
+        'chase'
+        'fill'
+        'refill'
+        'bounce'
+        'blink'
+        'alternating'
+```
+
+`talking_animation` -> str:
+```
+    one of:
+        'breathe'
+        'chase'
+        'fill'
+        'refill'
+        'bounce'
+        'blink'
+        'alternating'
+```
+## Conflicts With
+
+There are two pre-existing plugins that either need uninstalled with pip, or blacklisted in your `mycroft.conf` file.
+
+[ovos-PHAL-plugin-respeaker2mic](https://github.com/OpenVoiceOS/ovos-PHAL-plugin-respeaker-2mic)
+[ovos-PHAL-plugin-respeaker4mic](https://github.com/OpenVoiceOS/ovos-PHAL-plugin-respeaker-4mic)
+
+### TODO
+
+- [x] Add more animations
+- [x] User configurable colors
+- [ ] Theme support
+- [x] User configurable animations
+- [ ] Add github tests and automation
+
+Please enjoy this plugin and don't be afraid to create an [issue](#) if you run into any problems.

ovos_phal_plugin_dotstar-0.0.3a1/ovos_PHAL_plugin_dotstar.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+version.py
+ovos_PHAL_plugin_dotstar/__init__.py
+ovos_PHAL_plugin_dotstar/animations.py
+ovos_PHAL_plugin_dotstar/leds.py
+ovos_PHAL_plugin_dotstar.egg-info/PKG-INFO
+ovos_PHAL_plugin_dotstar.egg-info/SOURCES.txt
+ovos_PHAL_plugin_dotstar.egg-info/dependency_links.txt
+ovos_PHAL_plugin_dotstar.egg-info/entry_points.txt
+ovos_PHAL_plugin_dotstar.egg-info/requires.txt
+ovos_PHAL_plugin_dotstar.egg-info/top_level.txt
+test/test_unit.py

ovos_phal_plugin_dotstar-0.0.3a1/ovos_PHAL_plugin_dotstar.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ovos_phal_plugin_dotstar-0.0.3a1/ovos_PHAL_plugin_dotstar.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[opm.phal]
+ovos-PHAL-plugin-dotstar = ovos_PHAL_plugin_dotstar:DotStarLedControlPlugin

ovos_phal_plugin_dotstar-0.0.3a1/ovos_PHAL_plugin_dotstar.egg-info/requires.txt

@@ -0,0 +1,12 @@
+ovos-plugin-manager<3.0.0,>=2.1.0
+ovos-lingua-franca>=0.4.8a8
+ovos-i2c-detection>=0.0.5
+
+[:platform_machine == "aarch64" or platform_machine == "armv7l" or platform_machine == "armv6l"]
+adafruit-circuitpython-dotstar
+gpiozero
+rpi-lgpio
+
+[test]
+pytest
+pytest-cov

ovos_phal_plugin_dotstar-0.0.3a1/ovos_PHAL_plugin_dotstar.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+ovos_PHAL_plugin_dotstar
+version

ovos_phal_plugin_dotstar-0.0.3a1/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ovos-PHAL-plugin-dotstar"
+dynamic = ["version"]
+description = "An OVOS PHAL plugin to control DotStar type LEDs"
+readme = "README.md"
+license = {text = "MIT"}
+authors = [
+    {name = "builderjer", email = "builderjer@gmail.com"}
+]
+requires-python = ">=3.9"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Topic :: Text Processing :: Linguistic",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11"
+]
+dependencies = [
+    "ovos-plugin-manager>=2.1.0,<3.0.0",
+    "ovos-lingua-franca>=0.4.8a8",
+    "ovos-i2c-detection>=0.0.5",
+    # Raspberry Pi LED/GPIO stack. These only build/run on the Pi and pull C
+    # extensions (lgpio) that cannot compile on generic CI runners, so they are
+    # gated to ARM Linux. The plugin imports them lazily at LED init time.
+    "adafruit-circuitpython-dotstar ; platform_machine == 'aarch64' or platform_machine == 'armv7l' or platform_machine == 'armv6l'",
+    "gpiozero ; platform_machine == 'aarch64' or platform_machine == 'armv7l' or platform_machine == 'armv6l'",
+    "rpi-lgpio ; platform_machine == 'aarch64' or platform_machine == 'armv7l' or platform_machine == 'armv6l'",
+]
+
+[project.optional-dependencies]
+test = ["pytest", "pytest-cov"]
+
+[project.urls]
+Homepage = "https://github.com/OpenVoiceOS/ovos-PHAL-plugin-dotstar"
+
+[project.entry-points."opm.phal"]
+"ovos-PHAL-plugin-dotstar" = "ovos_PHAL_plugin_dotstar:DotStarLedControlPlugin"
+
+[tool.setuptools.dynamic]
+version = {attr = "version.__version__"}
+
+[tool.setuptools]
+py-modules = ["version"]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["ovos_PHAL_plugin_dotstar*"]
+
+[tool.setuptools.package-data]
+ovos_PHAL_plugin_dotstar = ["*.json"]

ovos_phal_plugin_dotstar-0.0.3a1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ovos_phal_plugin_dotstar-0.0.3a1/test/test_unit.py

@@ -0,0 +1,167 @@
+"""Unit tests for ovos-PHAL-plugin-dotstar.
+
+These exercise the pure-python logic of the plugin (HAT pin tables, i2c platform
+detection, the DotStarLed wrapper and the LED animations) without requiring any
+real LED/GPIO hardware. The Raspberry Pi hardware libraries (adafruit_dotstar,
+board, gpiozero, RPi.GPIO) are imported lazily inside the plugin, so the package
+imports cleanly here and the LED strip is replaced by a simple in-memory fake.
+"""
+import unittest
+from unittest.mock import patch
+
+import ovos_PHAL_plugin_dotstar as dotstar
+from ovos_PHAL_plugin_dotstar import (
+    PREDEFINED_HAT_PINS,
+    check_i2c_platform,
+    get_predefined_hat,
+)
+from ovos_PHAL_plugin_dotstar.leds import DotStarLed
+from ovos_PHAL_plugin_dotstar.animations import (
+    animations,
+    BlinkLedAnimation,
+    FillLedAnimation,
+)
+
+
+class FakeStrip:
+    """Minimal stand-in for an adafruit_dotstar.DotStar strip."""
+
+    def __init__(self, n=4):
+        self.n = n
+        self.pixels = [(0, 0, 0)] * n
+        self.filled = None
+        self.shown = 0
+
+    def __setitem__(self, idx, color):
+        self.pixels[idx] = color
+
+    def fill(self, color):
+        self.filled = color
+
+    def show(self):
+        self.shown += 1
+
+
+class TestModuleImport(unittest.TestCase):
+    def test_imports_without_hardware(self):
+        # Importing the plugin must not require LED/GPIO hardware libraries.
+        self.assertTrue(hasattr(dotstar, "DotStarLedControlPlugin"))
+        self.assertTrue(hasattr(dotstar, "DotStarLedControlPluginValidator"))
+
+    def test_predefined_hat_pins_known(self):
+        self.assertIn("WM8960", PREDEFINED_HAT_PINS)
+        self.assertIn("RESPEAKER4", PREDEFINED_HAT_PINS)
+        self.assertIn("RESPEAKER6", PREDEFINED_HAT_PINS)
+        self.assertIn("ADAFRUIT2MIC", PREDEFINED_HAT_PINS)
+        for clock, data, num in PREDEFINED_HAT_PINS.values():
+            self.assertIsInstance(clock, str)
+            self.assertIsInstance(data, str)
+            self.assertIsInstance(num, int)
+
+
+class TestGetPredefinedHat(unittest.TestCase):
+    def test_builds_strip_with_board_pins(self):
+        captured = {}
+
+        class FakeBoard:
+            D11 = "PIN_D11"
+            D10 = "PIN_D10"
+
+        def fake_dotstar(clock, data, num_led, brightness=0.2):
+            captured.update(clock=clock, data=data, num_led=num_led,
+                            brightness=brightness)
+            return FakeStrip(num_led)
+
+        import sys
+        import types
+        fake_mod = types.ModuleType("adafruit_dotstar")
+        fake_mod.DotStar = fake_dotstar
+        with patch.dict(sys.modules, {"adafruit_dotstar": fake_mod,
+                                      "board": FakeBoard()}):
+            strip = get_predefined_hat("WM8960")
+        self.assertEqual(captured["clock"], "PIN_D11")
+        self.assertEqual(captured["data"], "PIN_D10")
+        self.assertEqual(captured["num_led"], 3)
+        self.assertIsInstance(strip, FakeStrip)
+
+    def test_unknown_hat_raises(self):
+        with self.assertRaises(KeyError):
+            get_predefined_hat("NOPE")
+
+
+class TestCheckI2cPlatform(unittest.TestCase):
+    def test_missing_file_returns_none(self):
+        with patch("ovos_PHAL_plugin_dotstar.exists", return_value=False):
+            self.assertIsNone(check_i2c_platform())
+
+    def test_known_platform_returned(self):
+        from unittest.mock import mock_open
+        m = mock_open(read_data="WM8960\n")
+        with patch("ovos_PHAL_plugin_dotstar.exists", return_value=True), \
+                patch("builtins.open", m):
+            self.assertEqual(check_i2c_platform(), "WM8960")
+
+    def test_unknown_platform_returns_none(self):
+        from unittest.mock import mock_open
+        m = mock_open(read_data="SOMETHING_ELSE\n")
+        with patch("ovos_PHAL_plugin_dotstar.exists", return_value=True), \
+                patch("builtins.open", m):
+            self.assertIsNone(check_i2c_platform())
+
+
+class TestDotStarLed(unittest.TestCase):
+    def setUp(self):
+        self.strip = FakeStrip(n=4)
+        self.led = DotStarLed(self.strip)
+
+    def test_num_leds(self):
+        self.assertEqual(self.led.num_leds, 4)
+
+    def test_set_led(self):
+        self.led.set_led(2, (1, 2, 3))
+        self.assertEqual(self.strip.pixels[2], (1, 2, 3))
+
+    def test_fill(self):
+        self.led.fill((9, 9, 9))
+        self.assertEqual(self.strip.filled, (9, 9, 9))
+
+    def test_show(self):
+        self.led.show()
+        self.assertEqual(self.strip.shown, 1)
+
+
+class TestAnimationsRegistry(unittest.TestCase):
+    def test_registry_keys(self):
+        for key in ("breathe", "chase", "fill", "refill", "bounce", "blink",
+                    "alternating"):
+            self.assertIn(key, animations)
+
+
+class TestFillAnimation(unittest.TestCase):
+    def test_fill_sets_each_led(self):
+        from lingua_franca.util.colors import Color
+        strip = FakeStrip(n=3)
+        led = DotStarLed(strip)
+        anim = FillLedAnimation(led, Color.from_rgb(10, 20, 30))
+        # patch the internal delay so the test does not sleep
+        anim._delay.set()
+        anim.start()
+        # all three pixels should have been written
+        for px in strip.pixels:
+            self.assertEqual(px, (10, 20, 30))
+
+
+class TestBlinkAnimationOneShot(unittest.TestCase):
+    def test_blink_one_shot_terminates(self):
+        from lingua_franca.util.colors import Color
+        strip = FakeStrip(n=2)
+        led = DotStarLed(strip)
+        anim = BlinkLedAnimation(led, Color.from_rgb(255, 0, 0), num_blinks=1)
+        anim._delay.set()
+        # one_shot must terminate the loop without an explicit stop()
+        anim.start(one_shot=True)
+        self.assertTrue(anim.stopping.is_set())
+
+
+if __name__ == "__main__":
+    unittest.main()

ovos_phal_plugin_dotstar-0.0.3a1/version.py

@@ -0,0 +1,9 @@
+# The following lines are replaced during the release process.
+# START_VERSION_BLOCK
+VERSION_MAJOR = 0
+VERSION_MINOR = 0
+VERSION_BUILD = 3
+VERSION_ALPHA = 1
+# END_VERSION_BLOCK
+
+__version__ = f"{VERSION_MAJOR}.{VERSION_MINOR}.{VERSION_BUILD}" + (f"a{VERSION_ALPHA}" if VERSION_ALPHA else "")