hackerbot 0.5.0__tar.gz → 0.6.0__tar.gz

hackerbot-0.6.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: hackerbot
+Version: 0.6.0
+Summary: This module contains the setup for the hackerbot python package.
+Author-email: Allen Chien <allen@hackerbot.co>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/hackerbotindustries/hackerbot-python-package
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyserial
+Requires-Dist: pytest
+Requires-Dist: piper-tts
+Requires-Dist: sounddevice
+Requires-Dist: pyaudio
+Requires-Dist: huggingface_hub
+Requires-Dist: requests
+Dynamic: license-file
+
+![HackerBot](images/transparent_hb_horizontal_industries_.png)
+# Hackerbot Python Package
+
+The `hackerbot` Python package provides modules for controlling and managing the Hackerbot robotics system.
+
+## Installation
+
+You can now install the package directly from PyPI:
+
+```bash
+pip install hackerbot
+```
+
+This will automatically install all required dependencies and make the `hackerbot` package available in your Python environment.
+
+### (Optional) Installing from Source
+
+If you prefer to install from source for development purposes:
+
+1. **Clone the Repository**
+
+   ```bash
+   git clone https://github.com/hackerbotindustries/hackerbot-python-package.git
+   cd hackerbot-python-package/
+   ```
+
+2. **Install Locally**
+
+   ```bash
+   pip install .
+   ```
+
+## Quick Start
+
+SSH into the Raspberry Pi or open a VNC viewer, then install the official Python package:
+
+```bash
+pip install hackerbot
+```
+
+Or upgrade the existing package:
+
+```bash
+pip install --upgrade hackerbot
+```
+
+Then, run `python3` to open up the Python interactive shell and copy and paste the following:
+
+```python
+from hackerbot import Hackerbot
+
+bot = Hackerbot()
+
+bot.base.drive(0, 65)
+bot.base.drive(200, 0)
+```
+
+You should see your Hackerbot leave the charger and move in the opposite direction.
+
+```python
+bot.head.look(180, 250, 70)
+```
+
+Now your robot should move its head and look up at you!
+
+```python
+bot.arm.move_joints(0, 0, 0, 0, 0, 0, 10)
+```
+
+You should see your elephant arm moving to a straight-up position.
+
+```python
+bot.base.destroy(auto_dock=True)
+```
+
+Safely clean up, and your Hackerbot will return to the charger. Once `destroy` is called, you need to create a new Hackerbot instance to perform new actions.
+
+## Usage
+
+After installation, you can import and use the package in your Python scripts:
+
+```python
+import hackerbot
+```
+
+## Testing
+
+To run the unit tests:
+
+```bash
+cd tests/unit_tests
+pytest
+```
+
+## Troubleshooting
+
+If you run into issues during installation or usage, try the following:
+
+* Use a virtual environment:
+
+  ```bash
+  python3 -m venv venv
+  source venv/bin/activate
+  ```
+
+* Upgrade `pip`:
+
+  ```bash
+  pip install --upgrade pip
+  ```

hackerbot-0.6.0/README.md

@@ -0,0 +1,110 @@
+![HackerBot](images/transparent_hb_horizontal_industries_.png)
+# Hackerbot Python Package
+
+The `hackerbot` Python package provides modules for controlling and managing the Hackerbot robotics system.
+
+## Installation
+
+You can now install the package directly from PyPI:
+
+```bash
+pip install hackerbot
+```
+
+This will automatically install all required dependencies and make the `hackerbot` package available in your Python environment.
+
+### (Optional) Installing from Source
+
+If you prefer to install from source for development purposes:
+
+1. **Clone the Repository**
+
+   ```bash
+   git clone https://github.com/hackerbotindustries/hackerbot-python-package.git
+   cd hackerbot-python-package/
+   ```
+
+2. **Install Locally**
+
+   ```bash
+   pip install .
+   ```
+
+## Quick Start
+
+SSH into the Raspberry Pi or open a VNC viewer, then install the official Python package:
+
+```bash
+pip install hackerbot
+```
+
+Or upgrade the existing package:
+
+```bash
+pip install --upgrade hackerbot
+```
+
+Then, run `python3` to open up the Python interactive shell and copy and paste the following:
+
+```python
+from hackerbot import Hackerbot
+
+bot = Hackerbot()
+
+bot.base.drive(0, 65)
+bot.base.drive(200, 0)
+```
+
+You should see your Hackerbot leave the charger and move in the opposite direction.
+
+```python
+bot.head.look(180, 250, 70)
+```
+
+Now your robot should move its head and look up at you!
+
+```python
+bot.arm.move_joints(0, 0, 0, 0, 0, 0, 10)
+```
+
+You should see your elephant arm moving to a straight-up position.
+
+```python
+bot.base.destroy(auto_dock=True)
+```
+
+Safely clean up, and your Hackerbot will return to the charger. Once `destroy` is called, you need to create a new Hackerbot instance to perform new actions.
+
+## Usage
+
+After installation, you can import and use the package in your Python scripts:
+
+```python
+import hackerbot
+```
+
+## Testing
+
+To run the unit tests:
+
+```bash
+cd tests/unit_tests
+pytest
+```
+
+## Troubleshooting
+
+If you run into issues during installation or usage, try the following:
+
+* Use a virtual environment:
+
+  ```bash
+  python3 -m venv venv
+  source venv/bin/activate
+  ```
+
+* Upgrade `pip`:
+
+  ```bash
+  pip install --upgrade pip
+  ```

{hackerbot-0.5.0 → hackerbot-0.6.0}/pyproject.toml

@@ -6,7 +6,7 @@
 #
 # Created By: Allen Chien
 # Created:    April 2025
-# Updated:    2025.04.20
+# Updated:    2025.05.12
 #
 # This module contains the setup details for the hackerbot python package.
 #
@@ -17,7 +17,7 @@
 
 [project]
 name = "hackerbot"
-version = "0.5.0"
+version = "0.6.0"
 description = "This module contains the setup for the hackerbot python package."
 authors = [
   { name = "Allen Chien", email = "allen@hackerbot.co" }
@@ -31,6 +31,8 @@ dependencies = [
   "piper-tts",
   "sounddevice",
   "pyaudio",
+  "huggingface_hub",
+  "requests",
 ]
 
 [project.urls]

{hackerbot-0.5.0 → hackerbot-0.6.0}/src/hackerbot/base/__init__.py

@@ -16,8 +16,12 @@
 
 
 from hackerbot.utils.hackerbot_helper import HackerbotHelper
+from hackerbot.utils.tts_helper import TTSHelper
 from .maps import Maps
 import time
+import sounddevice as sd
+from piper.voice import PiperVoice
+import numpy as np
 
 class Base():    
     def __init__(self, controller: HackerbotHelper):
@@ -220,4 +224,67 @@ class Base():
         if auto_dock:
             time.sleep(3.0)
             self.dock(block=False)
-        self._controller.destroy()
+        self._controller.destroy()
+
+    def speak(self, model_src, text, speaker_id=None):
+        """
+        Synthesize and play speech audio based on the given text and voice model.
+
+        This function attempts to load a voice model, initialize an audio stream,
+        synthesize the given text into audio, and play it through the audio output
+        stream. If any step fails, an error is logged, and the process is aborted.
+
+        Args:
+            model_src: The source of the voice model to load for speech synthesis.
+            text: The text content to be synthesized into speech.
+            speaker_id (optional): The ID of the speaker to use, if applicable.
+
+        Returns:
+            None
+        """
+        try:
+            try:
+                tts_helper = TTSHelper()
+                model_path = tts_helper.get_or_download_model(model_src)
+            except Exception as e:
+                self._controller.log_error(f"Failed to get or download model: {e}")
+                return
+
+            try:
+                voice = PiperVoice.load(model_path)
+            except Exception as e:
+                self._controller.log_error(f"Failed to load voice model: {e}")
+                return
+
+            try:
+                stream = sd.OutputStream(
+                    samplerate=voice.config.sample_rate,
+                    channels=1,
+                    dtype='int16',
+                    blocksize=0  # Let sounddevice choose blocksize automatically
+                )
+            except Exception as e:
+                self._controller.log_error(f"Failed to initialize audio stream: {e}")
+                return
+
+            try:
+                with stream:
+                    for audio_bytes in voice.synthesize_stream_raw(text, speaker_id=speaker_id):
+                        try:
+                            int_data = np.frombuffer(audio_bytes, dtype=np.int16)
+                            stream.write(int_data)
+                        except Exception as e:
+                            self._controller.log_error(f"Error writing audio data to stream: {e}")
+                            break
+
+                    try:
+                        stream.stop()
+                    except Exception as e:
+                        self._controller.log_error(f"Failed to stop audio stream cleanly: {e}")
+
+                print("Finished speaking.")
+
+            except Exception as e:
+                self._controller.log_error(f"Error during audio streaming: {e}")
+        except Exception as e:
+            self._controller.log_error(f"Error in base:speak: {e}")

{hackerbot-0.5.0 → hackerbot-0.6.0}/src/hackerbot/head/__init__.py

@@ -17,9 +17,6 @@
 
 from hackerbot.utils.hackerbot_helper import HackerbotHelper
 from .eyes import Eyes
-import sounddevice as sd
-from piper.voice import PiperVoice
-import numpy as np
 
 class Head():
     def __init__(self, controller: HackerbotHelper):
@@ -62,26 +59,3 @@ class Head():
         except Exception as e:
             self._controller.log_error(f"Error in head:set_idle_mode: {e}")
             return False
-        
-    def speak(self, model_src, text, speaker_id = None):
-        model = model_src
-        voice = PiperVoice.load(model)
-
-        # Setup a sounddevice OutputStream with appropriate parameters
-        # The sample rate and channels should match the properties of the PCM data
-        stream = sd.OutputStream(
-            samplerate=voice.config.sample_rate,
-            channels=1,
-            dtype='int16',
-            blocksize=0  # Let sounddevice choose blocksize automatically
-        )
-
-        with stream:  # This automatically handles start/stop/close
-            for audio_bytes in voice.synthesize_stream_raw(text, speaker_id=speaker_id):
-                int_data = np.frombuffer(audio_bytes, dtype=np.int16)
-                stream.write(int_data)
-
-            # At this point, all data has been written,
-            # but we need to wait for any remaining buffered audio to play out.
-            stream.stop()  # Ensure stream stops cleanly
-            print("Finished speaking.")  # <-- You now know it's done

hackerbot-0.6.0/src/hackerbot/utils/tts_helper.py

@@ -0,0 +1,101 @@
+################################################################################
+# Copyright (c) 2025 Hackerbot Industries LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+# Created By: Allen Chien
+# Created:    April 2025
+# Updated:    2025.05.13
+#
+# This module contains the TTSHelper class that gets or downloads a Piper voice 
+# model from HuggingFace
+#
+# Special thanks to the following for their code contributions to this codebase:
+# Allen Chien - https://github.com/AllenChienXXX
+# Saad Elbeleidy - https://github.com/sbeleidy
+#
+# Credits:
+# This project makes use of functionality inspired by or adapted from:
+# Dimits - https://github.com/Reqeique/Dimits
+################################################################################
+
+
+import os
+from huggingface_hub import hf_hub_url
+import requests
+
+class TTSHelper:
+    """
+    Downloads a Piper voice model (.onnx + .json) from HuggingFace
+    and stores it in a local directory for future use.
+    """
+
+    def __init__(self, cache_dir: str = os.path.expanduser("~/piper_models")):
+        """
+        Args:
+            cache_dir (str): Directory where downloaded models will be stored. Defaults to "~/piper_models".
+        """
+        self.cache_dir = cache_dir
+        os.makedirs(self.cache_dir, exist_ok=True)
+
+    def get_or_download_model(self, model_src: str) -> str:
+        """
+        If model_src is a valid file path, returns it.
+        Otherwise treats it as a HuggingFace voice model name and downloads it.
+
+        Args:
+            model_src (str): Either local .onnx path or voice name (e.g., "en_US-amy-low").
+
+        Returns:
+            str: Path to ONNX model file.
+        """
+        if os.path.isfile(model_src):
+            return model_src
+        return self._download_model_from_huggingface(model_src)
+
+    def _download_model_from_huggingface(self, voice: str) -> str:
+        """
+        Downloads a Piper voice model (.onnx and .json) from HuggingFace.
+
+        Args:
+            voice (str): Voice model name, e.g., "en_US-amy-low".
+
+        Returns:
+            str: Path to downloaded .onnx model.
+
+        Raises:
+            RuntimeError: If the download fails.
+        """
+        try:
+            locale, person, pitch = voice.split('-')
+            lang, country = locale.split('_')
+        except ValueError:
+            raise RuntimeError(f"Invalid voice model name: {voice}")
+
+        base_path = f"{lang}/{locale}/{person}/{pitch}"
+        filename_onnx = f"{voice}.onnx"
+        filename_json = f"{voice}.onnx.json"
+
+        url_onnx = hf_hub_url(repo_id="rhasspy/piper-voices", filename=f"{base_path}/{filename_onnx}")
+        url_json = hf_hub_url(repo_id="rhasspy/piper-voices", filename=f"{base_path}/{filename_json}")
+
+        path_onnx = os.path.join(self.cache_dir, filename_onnx)
+        path_json = os.path.join(self.cache_dir, filename_json)
+
+        if not os.path.exists(path_onnx):
+            self._download_file(url_onnx, path_onnx)
+        if not os.path.exists(path_json):
+            self._download_file(url_json, path_json)
+
+        return path_onnx
+
+    def _download_file(self, url: str, dest_path: str):
+        try:
+            response = requests.get(url, stream=True)
+            response.raise_for_status()
+            with open(dest_path, 'wb') as f:
+                for chunk in response.iter_content(chunk_size=8192):
+                    f.write(chunk)
+        except Exception as e:
+            raise RuntimeError(f"Failed to download {url}: {e}")

hackerbot-0.6.0/src/hackerbot.egg-info/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: hackerbot
+Version: 0.6.0
+Summary: This module contains the setup for the hackerbot python package.
+Author-email: Allen Chien <allen@hackerbot.co>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/hackerbotindustries/hackerbot-python-package
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyserial
+Requires-Dist: pytest
+Requires-Dist: piper-tts
+Requires-Dist: sounddevice
+Requires-Dist: pyaudio
+Requires-Dist: huggingface_hub
+Requires-Dist: requests
+Dynamic: license-file
+
+![HackerBot](images/transparent_hb_horizontal_industries_.png)
+# Hackerbot Python Package
+
+The `hackerbot` Python package provides modules for controlling and managing the Hackerbot robotics system.
+
+## Installation
+
+You can now install the package directly from PyPI:
+
+```bash
+pip install hackerbot
+```
+
+This will automatically install all required dependencies and make the `hackerbot` package available in your Python environment.
+
+### (Optional) Installing from Source
+
+If you prefer to install from source for development purposes:
+
+1. **Clone the Repository**
+
+   ```bash
+   git clone https://github.com/hackerbotindustries/hackerbot-python-package.git
+   cd hackerbot-python-package/
+   ```
+
+2. **Install Locally**
+
+   ```bash
+   pip install .
+   ```
+
+## Quick Start
+
+SSH into the Raspberry Pi or open a VNC viewer, then install the official Python package:
+
+```bash
+pip install hackerbot
+```
+
+Or upgrade the existing package:
+
+```bash
+pip install --upgrade hackerbot
+```
+
+Then, run `python3` to open up the Python interactive shell and copy and paste the following:
+
+```python
+from hackerbot import Hackerbot
+
+bot = Hackerbot()
+
+bot.base.drive(0, 65)
+bot.base.drive(200, 0)
+```
+
+You should see your Hackerbot leave the charger and move in the opposite direction.
+
+```python
+bot.head.look(180, 250, 70)
+```
+
+Now your robot should move its head and look up at you!
+
+```python
+bot.arm.move_joints(0, 0, 0, 0, 0, 0, 10)
+```
+
+You should see your elephant arm moving to a straight-up position.
+
+```python
+bot.base.destroy(auto_dock=True)
+```
+
+Safely clean up, and your Hackerbot will return to the charger. Once `destroy` is called, you need to create a new Hackerbot instance to perform new actions.
+
+## Usage
+
+After installation, you can import and use the package in your Python scripts:
+
+```python
+import hackerbot
+```
+
+## Testing
+
+To run the unit tests:
+
+```bash
+cd tests/unit_tests
+pytest
+```
+
+## Troubleshooting
+
+If you run into issues during installation or usage, try the following:
+
+* Use a virtual environment:
+
+  ```bash
+  python3 -m venv venv
+  source venv/bin/activate
+  ```
+
+* Upgrade `pip`:
+
+  ```bash
+  pip install --upgrade pip
+  ```

{hackerbot-0.5.0 → hackerbot-0.6.0}/src/hackerbot.egg-info/SOURCES.txt

@@ -15,4 +15,5 @@ src/hackerbot/base/maps.py
 src/hackerbot/head/__init__.py
 src/hackerbot/head/eyes.py
 src/hackerbot/utils/hackerbot_helper.py
-src/hackerbot/utils/serial_helper.py
+src/hackerbot/utils/serial_helper.py
+src/hackerbot/utils/tts_helper.py

{hackerbot-0.5.0 → hackerbot-0.6.0}/src/hackerbot.egg-info/requires.txt

@@ -3,3 +3,5 @@ pytest
 piper-tts
 sounddevice
 pyaudio
+huggingface_hub
+requests

hackerbot-0.5.0/PKG-INFO

@@ -1,69 +0,0 @@
-Metadata-Version: 2.4
-Name: hackerbot
-Version: 0.5.0
-Summary: This module contains the setup for the hackerbot python package.
-Author-email: Allen Chien <allen@hackerbot.co>
-License-Expression: MIT
-Project-URL: Homepage, https://github.com/hackerbotindustries/hackerbot-python-package
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: pyserial
-Requires-Dist: pytest
-Requires-Dist: piper-tts
-Requires-Dist: sounddevice
-Requires-Dist: pyaudio
-Dynamic: license-file
-
-# Hackerbot Python Package
-
-Hackerbot python package (`hackerbot-python-package`) is a project that includes modules for controlling and managing the Hackerbot system.
-
-## Installation
-
-Follow these steps to clone the repository and set up the required dependencies.
-
-### 1. Clone the Repository
-Use SSH to clone the repository:
-```bash
-https://github.com/hackerbotindustries/hackerbot-python-package.git
-```
-This will create a directory named `hackerbot-python-package` and download all necessary files.
-
-### 2. Navigate to the Modules Directory
-Move into the `hackerbot_modules` directory:
-```bash
-cd hackerbot-python-package/
-```
-
-### 3. Install Dependencies
-Install the `hackerbot` package using `pip`:
-```bash
-pip install .
-```
-This will install the package locally for your Python environment.
-
-## Usage
-Once installed, you can import `hackerbot` in your Python scripts:
-```python
-import hackerbot
-```
-
-### 4. Testing
-To run the unit tests run:
-```bash
-cd tests/unit_tests
-pytest
-```
-
-## Troubleshooting
-If you run into issues with the installation, try the following:
-- Ensure you're using a virtual environment:  
-  ```bash
-  python3 -m venv venv
-  source venv/bin/activate
-  ```
-- Upgrade `pip` before installation:  
-  ```bash
-  pip install --upgrade pip
-  ```

hackerbot-0.5.0/README.md

@@ -1,52 +0,0 @@
-# Hackerbot Python Package
-
-Hackerbot python package (`hackerbot-python-package`) is a project that includes modules for controlling and managing the Hackerbot system.
-
-## Installation
-
-Follow these steps to clone the repository and set up the required dependencies.
-
-### 1. Clone the Repository
-Use SSH to clone the repository:
-```bash
-https://github.com/hackerbotindustries/hackerbot-python-package.git
-```
-This will create a directory named `hackerbot-python-package` and download all necessary files.
-
-### 2. Navigate to the Modules Directory
-Move into the `hackerbot_modules` directory:
-```bash
-cd hackerbot-python-package/
-```
-
-### 3. Install Dependencies
-Install the `hackerbot` package using `pip`:
-```bash
-pip install .
-```
-This will install the package locally for your Python environment.
-
-## Usage
-Once installed, you can import `hackerbot` in your Python scripts:
-```python
-import hackerbot
-```
-
-### 4. Testing
-To run the unit tests run:
-```bash
-cd tests/unit_tests
-pytest
-```
-
-## Troubleshooting
-If you run into issues with the installation, try the following:
-- Ensure you're using a virtual environment:  
-  ```bash
-  python3 -m venv venv
-  source venv/bin/activate
-  ```
-- Upgrade `pip` before installation:  
-  ```bash
-  pip install --upgrade pip
-  ```

hackerbot-0.5.0/src/hackerbot.egg-info/PKG-INFO

@@ -1,69 +0,0 @@
-Metadata-Version: 2.4
-Name: hackerbot
-Version: 0.5.0
-Summary: This module contains the setup for the hackerbot python package.
-Author-email: Allen Chien <allen@hackerbot.co>
-License-Expression: MIT
-Project-URL: Homepage, https://github.com/hackerbotindustries/hackerbot-python-package
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: pyserial
-Requires-Dist: pytest
-Requires-Dist: piper-tts
-Requires-Dist: sounddevice
-Requires-Dist: pyaudio
-Dynamic: license-file
-
-# Hackerbot Python Package
-
-Hackerbot python package (`hackerbot-python-package`) is a project that includes modules for controlling and managing the Hackerbot system.
-
-## Installation
-
-Follow these steps to clone the repository and set up the required dependencies.
-
-### 1. Clone the Repository
-Use SSH to clone the repository:
-```bash
-https://github.com/hackerbotindustries/hackerbot-python-package.git
-```
-This will create a directory named `hackerbot-python-package` and download all necessary files.
-
-### 2. Navigate to the Modules Directory
-Move into the `hackerbot_modules` directory:
-```bash
-cd hackerbot-python-package/
-```
-
-### 3. Install Dependencies
-Install the `hackerbot` package using `pip`:
-```bash
-pip install .
-```
-This will install the package locally for your Python environment.
-
-## Usage
-Once installed, you can import `hackerbot` in your Python scripts:
-```python
-import hackerbot
-```
-
-### 4. Testing
-To run the unit tests run:
-```bash
-cd tests/unit_tests
-pytest
-```
-
-## Troubleshooting
-If you run into issues with the installation, try the following:
-- Ensure you're using a virtual environment:  
-  ```bash
-  python3 -m venv venv
-  source venv/bin/activate
-  ```
-- Upgrade `pip` before installation:  
-  ```bash
-  pip install --upgrade pip
-  ```