Merge remote-tracking branch 'origin/main' into 277-load-cell-validity-check

Author: tkevinbest

.github/actions/setup-poetry-env/action.yml

@@ -29,14 +29,41 @@ runs:
       run: poetry config virtualenvs.in-project true
       shell: bash
 
+    # Re-enable caching with improved key and restore logic
     - name: Load cached venv
       id: cached-poetry-dependencies
       uses: actions/cache@v4
       with:
         path: .venv
-        key: venv-${{ runner.os }}-${{ inputs.python-version }}-${{ hashFiles('poetry.lock') }}
+        # Include poetry.toml in the cache key to catch configuration changes
+        key: venv-${{ runner.os }}-py${{ inputs.python-version }}-${{ hashFiles('poetry.lock', 'poetry.toml') }}-v2
 
     - name: Install dependencies
-      if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'
-      run: poetry install --no-interaction
+      run: |
+        if [ "${{ steps.cached-poetry-dependencies.outputs.cache-hit }}" == 'true' ]; then
+          echo "Using cached virtual environment"
+
+          # Validate the cached environment contains expected tools
+          if ! poetry run pre-commit --version &>/dev/null || \
+             ! poetry run pytest --version &>/dev/null || \
+             ! poetry run mypy --version &>/dev/null; then
+            echo "Cached environment is missing required tools. Reinstalling..."
+            rm -rf .venv
+            poetry install --no-interaction --with dev
+          fi
+        else
+          echo "Installing dependencies"
+          rm -rf .venv || true
+          poetry install --no-interaction --with dev
+        fi
+      shell: bash
+
+    - name: Verify development tools installation
+      run: |
+        echo "Verifying pre-commit installation..."
+        poetry run pre-commit --version
+        echo "Verifying pytest installation..."
+        poetry run pytest --version
+        echo "Verifying mypy installation..."
+        poetry run mypy --version
       shell: bash

.github/workflows/main.yml

@@ -22,6 +22,12 @@ jobs:
       - name: Set up the environment
         uses: ./.github/actions/setup-poetry-env
 
+      - name: Verify tools before running checks
+        run: |
+          poetry run which pre-commit
+          poetry run which mypy
+          poetry run which pytest
+
       - name: Run checks
         run: make check
 
@@ -43,9 +49,15 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
 
+      - name: Verify pytest before running tests
+        run: poetry run which pytest
+
       - name: Run tests
         run: poetry run pytest tests --cov --cov-config=pyproject.toml --cov-report=xml
 
+      - name: Verify mypy before type checking
+        run: poetry run which mypy
+
       - name: Check typing
         run: poetry run mypy
 

README.md

@@ -63,6 +63,28 @@ The library is available on PyPI and can be installed using pip:
 pip install opensourceleg
 ```
 
+### Hardware-Specific Dependencies
+
+To keep your installation lightweight, you can install only the dependencies needed for your specific hardware:
+
+```bash
+# For Dephy actuators
+pip install opensourceleg[dephy]
+
+# For Moteus actuators
+pip install opensourceleg[moteus]
+
+# For I2C communication
+pip install opensourceleg[communication]
+```
+
+| Extra           | Dependencies                         |
+| --------------- | ------------------------------------ |
+| `dephy`         | flexsea                              |
+| `moteus`        | moteus, moteus-pi3hat                |
+| `communication` | smbus2                               |
+| `messaging`     | grpcio, grpcio-tools, types-protobuf |
+
 For more details on the installation process, please refer to the [installation guide](https://neurobionics.github.io/opensourceleg/installation).
 
 ## 📚 Usage

docs/examples/assets/FSM_Diagram.svg

@@ -63,6 +63,28 @@ The library is available on PyPI and can be installed using pip:
 pip install opensourceleg
 ```
 
+### Hardware-Specific Dependencies
+
+To keep your installation lightweight, you can install only the dependencies needed for your specific hardware:
+
+```bash
+# For Dephy actuators
+pip install opensourceleg[dephy]
+
+# For Moteus actuators
+pip install opensourceleg[moteus]
+
+# For I2C communication
+pip install opensourceleg[communication]
+```
+
+| Extra | Dependencies |
+|-------|-------------|
+| `dephy` | flexsea |
+| `moteus` | moteus, moteus-pi3hat |
+| `communication` | smbus2 |
+| `messaging` | grpcio, grpcio-tools, types-protobuf |
+
 For more details on the installation process, please refer to the [installation guide](https://neurobionics.github.io/opensourceleg/installation).
 
 ## 📚 Usage

docs/index.md

@@ -51,6 +51,39 @@ source .venv/bin/activate
 # Step 3: Install opensourceleg
 pip install opensourceleg
 ```
+#### Hardware-Specific Dependencies
+
+The opensourceleg library supports a variety of actuators and sensors, each with its own dependencies. Rather than installing all possible dependencies (which can be extensive), we recommend installing only what you need for your specific hardware configuration.
+
+### Installing Hardware-Specific Packages
+
+You can easily install hardware-specific dependencies using pip's "extras" feature:
+
+```bash
+# For Dephy actuators
+pip install opensourceleg[dephy]
+
+# For Moteus actuators
+pip install opensourceleg[moteus]
+
+# For I2C communication
+pip install opensourceleg[communication]
+
+# For gRPC messaging functionality
+pip install opensourceleg[messaging]
+```
+
+### Available Extras
+
+| Extra | Dependencies |
+|-------|-------------|
+| `dephy` | flexsea |
+| `moteus` | moteus, moteus-pi3hat |
+| `communication` | smbus2 |
+| `messaging` | grpcio, grpcio-tools, types-protobuf |
+
+This approach keeps your installation lightweight and focused on just the hardware you're working with.
+
 
 💡 **Why Use a Virtual Environment?**
 Keeps your projects isolated

docs/installation.md

@@ -1,56 +1,68 @@
 # Using the Dephy Loadcell Amplifier
 
-This tutorial demonstrates how to use the Dephy Loadcell Amplifier with the Open Source Leg platform to measure forces and moments.
+This tutorial demonstrates how to use the Dephy Loadcell Amplifier with the Open Source Leg platform to measure forces and moments. It includes examples for both standard I2C communication and custom callbacks for advanced use cases, including using the Dephy Actpack to interface with the amplifier directly instead of the Raspberry Pi's I2C bus.
 
 ## Hardware Setup
 
-1. Connect the loadcell to the Dephy Loadcell Amplifier and the amplifier to the Raspberry Pi via I2C
-2. Verify proper power supply connections
-3. Ensure proper grounding
-4. Mount the loadcell securely
+1. Connect the loadcell to the Dephy Loadcell Amplifier and the amplifier to the Raspberry Pi via I2C. Alternatively, raw amplifier readings can be read from the `genvars` property of the `DephyActuator` class and fed into the amplifier update method as a custom callback (see example below).
+2. Verify proper power supply connections.
+3. Ensure proper grounding.
+4. Mount the loadcell securely.
 
 This example shows how to:
 
-- Initialize and configure a Dephy Loadcell Amplifier
-- Read forces and moments (6-axis measurements)
-- Log loadcell measurements
+- Initialize and configure a Dephy Loadcell Amplifier.
+- Read forces and moments (6-axis measurements).
+- Log loadcell measurements.
+- Use custom callbacks for advanced data handling.
+
+---
 
 ## Code Structure
 
-The [tutorial script](https://github.com/neurobionics/opensourceleg/blob/main/tutorials/sensors/reading_loadcell_data.py) is organized into several main sections:
+The [tutorial script](https://github.com/neurobionics/opensourceleg/blob/main/tutorials/sensors/reading_loadcell_data.py) for reading loadcell data has two main functions. The first shows the standard implementation where the I2C bus on a Raspberry Pi is used to communicate with the strain amplifier. The second shows an alternative use where raw ADC values are passed to the sensor in a custom data callback function. This second implementation is useful when the raw values are provided via a method other than I2C, such as reading them directly from a Dephy Actuator.
 
 ### 1. Initialization
 
 ```python
---8<-- "tutorials/sensors/reading_loadcell_data.py:1:40"
+--8<-- "tutorials/sensors/reading_loadcell_data.py:1:25"
 ```
 
 This section:
 
 - Sets up constants and configuration parameters
 - Defines the calibration matrix
-- Creates a data logger for recording measurements
-- Sets up a real-time loop for consistent timing
-- Initializes the DephyLoadcellAmplifier with specified parameters
 
-### 2. Main Loop
+### 2. Standard Setup with I2C Communication
+
+This section demonstrates how to use the loadcell with standard I2C communication. It includes:
+
+- Initializing the loadcell with I2C parameters.
+- Calibrating the loadcell.
+- Reading and logging force/torque data.
 
 ```python
---8<-- "tutorials/sensors/reading_loadcell_data.py:48:55"
+--8<-- "tutorials/sensors/reading_loadcell_data.py:28:53"
 ```
 
-The main loop:
+### 3. Custom Callback Communication
+This section demonstrates how to use a custom callback to provide raw data to the loadcell. It includes:
+
+- Using a DephyActuator to retrieve raw amplifier readings.
+- Passing the raw data to the loadcell using a callback function.
+- Calibrating the loadcell with the custom callback.
+- Reading and logging force/torque data.
 
-1. Updates the loadcell to get the latest reading
-2. Logs the time and current force/torque values
-3. Updates the logger
+```python
+--8<-- "tutorials/sensors/reading_loadcell_data.py:56:90"
+```
 
-## Loadcell Parameters
+## Important Class Parameters
 
-When initializing the DephyLoadcellAmplifier, several important parameters can be configured:
+When initializing the `DephyLoadcellAmplifier`, several important parameters can be configured:
 
 ```python
---8<-- "tutorials/sensors/reading_loadcell_data.py:32:40"
+--8<-- "tutorials/sensors/reading_loadcell_data.py:29:36"
 ```
 
 ### Parameter Details
@@ -86,7 +98,7 @@ When initializing the DephyLoadcellAmplifier, several important parameters can b
 
 ## Available Properties
 
-The DephyLoadcellAmplifier provides six measurement properties:
+The `DephyLoadcellAmplifier` provides six measurement properties:
 
 1. **Forces** (fx, fy, fz):
       - Linear forces in Newtons (N)
@@ -115,14 +127,20 @@ The DephyLoadcellAmplifier provides six measurement properties:
 
 2. Run the script:
    ```bash
-   python loadcell.py
+   python reading_loadcell_data.py
    ```
 
 3. Expected behavior:
       - Loadcell begins reading force/torque data continuously at 200Hz
       - Data is logged to `./logs/reading_loadcell_data.csv`
       - Force and moment values update as you apply loads to the sensor
 
+4. To change between I2C and using custom data callbacks, swap the `if __name__ == "__main__"` between the two demo function calls:
+
+```python
+--8<-- "tutorials/sensors/reading_loadcell_data.py:101:102"
+```
+
 ## Common Issues
 
 - **I2C Communication Errors**: Verify connections with `i2cdetect -y 1`
@@ -141,18 +159,6 @@ LOADCELL_CALIBRATION_MATRIX = np.array([
     # ... additional rows ...
 ])
 ```
-Should be replaced with your specific loadcell's calibration values.
-
-## Best Practices
-
-1. **Before Each Use**
-
-      - Verify all connections
-
-2. **Maintenance**
-
-      - Regular calibration checks
-      - Clean connections
-      - Monitor for drift
+should be replaced with your specific loadcell's calibration values.
 
 If you have any questions or need further assistance, please post on the [Open Source Leg community forum](https://opensourceleg.org/community).