SLASD 0.0.0__py3-none-any.whl

slasd/__init__.py

@@ -0,0 +1,8 @@
+"""Marks the package containing the SLASD driver."""
+
+import importlib.metadata
+
+try:
+    __version__ = importlib.metadata.version(__name__)
+except importlib.metadata.PackageNotFoundError:
+    __version__ = '0.0.0'  # Fallback for development mode

slasd/commands/__init__.py

@@ -0,0 +1 @@
+"""Marks the package containing the SLASD Commands."""

slasd/commands/command.py

@@ -0,0 +1,34 @@
+"""Collection of serial command interfaces."""
+
+from typing import Protocol
+
+import serial
+
+
+class SerialCommand(Protocol):
+    """Interface describing a generic serial command to the Arduino.
+
+    Attributes
+    ----------
+    _commandId : str
+        ID of the command. Usually a single ASCII char.
+    _payload : bytearray
+        Data payload to send with command.
+
+    """
+
+    _commandId: str
+    _payload: bytearray
+
+    def send(self, ser: serial.Serial) -> None:
+        """Send a single serial command to the Arduino.
+
+        Parameters
+        ----------
+        ser : serial.Serial
+            Serial connection to send the frame on.
+
+
+        """
+        cmdBytes = bytes(self._commandId, 'ASCII')
+        ser.write(cmdBytes + self._payload)

slasd/commands/noResp.py

@@ -0,0 +1,24 @@
+"""Fastrak serial commands with no response path."""
+
+from .command import SerialCommand
+
+
+class SetLedState(SerialCommand):
+    """Send a command to the Arduino to set the LED array state."""
+
+    def __init__(
+        self,
+        data: bytearray,
+    ) -> None:
+        """Class constructor.
+
+        Parameters
+        ----------
+        data : bytearray
+            The data payload to provide to the Arduino.
+
+        """
+        self._commandId = 'S'
+        self._payload = bytearray()
+        self._payload = data
+        self._payload += b'\n'

slasd/fastrakAnimator.py

@@ -0,0 +1,133 @@
+"""Contains the Fastrak device angular illuminator class."""
+
+import struct
+from math import floor
+from typing import TypedDict
+
+from fastrakSerialDriver.fastrakPosition import FastrakPostion
+from typing_extensions import Unpack
+
+from .ledAnimationDriver import LedAnimationDevice
+
+
+class FastrakParams(TypedDict):
+    r"""Describe the typing of the kwargs for the Fastrak animation state computation.
+
+    Attributes
+    ----------
+    posData : FastrakPostion
+        A position reported by a Fastrak hardware device.
+    angleToLight : int
+        The angular range $\\theta$, in degrees, to light up. In the example below the `O`
+        correspond to lit LED and `X` to unlit LED.
+        ```ascii
+                         OOOOOOOOOOO
+                    OOOOO           OOOOO
+                  OO                     OO
+                XO           θ           .'XX
+               X  `.      -------      .'    X
+              X     `.  /         \  .'       X
+             X        `.            /          X
+            X           `.        .'            X
+           X                ,-. .'               X
+           X              _(*_*)_                X
+           X             (_  o  _)               X
+           X               / o \                 X
+           X              (_/ \_)                X
+            X                                   X
+             X                                 X
+              X                               X
+               X                             X
+                XX                         XX
+                  XX                     XX
+                    XXXXX           XXXXX
+                         XXXXXXXXXXX
+        ```
+
+    colorR : int
+        The red component of the LED lit color.
+    colorG : int
+        The green component of the LED lit color.
+    colorB : int
+        The blue component of the LED lit color.
+    """
+
+    posData: FastrakPostion
+    angleToLight: int
+    colorR: int
+    colorG: int
+    colorB: int
+
+
+class FastrakAnimationDevice(LedAnimationDevice):
+    """Implements LedAnimationDevice for the Fastrak look position use case."""
+
+    def _computeState(self, **kwargs: Unpack[FastrakParams]) -> bytearray:  # ty:ignore[invalid-method-override]
+        """Compute the state array for the LED in the Fastrak look position use case.
+
+        Parameters
+        ----------
+         **kwargs : Unpack[FastrakParams]
+            Collection of key word arguments for the Fastrak look position use case.
+
+        Returns
+        -------
+        bytearray
+            The on/off and color state for each LED in the array.
+
+
+        """
+        if (
+            kwargs is None
+            or 'posData' not in kwargs
+            or 'angleToLight' not in kwargs
+            or 'colorR' not in kwargs
+            or 'colorG' not in kwargs
+            or 'colorB' not in kwargs
+            or type(kwargs['posData']) is not FastrakPostion
+            or type(kwargs['angleToLight']) is not int
+            or type(kwargs['colorR']) is not int
+            or type(kwargs['colorG']) is not int
+            or type(kwargs['colorB']) is not int
+        ):
+            raise TypeError
+
+        if kwargs['colorR'] < 0 or kwargs['colorR'] > 255:
+            raise TypeError
+        if kwargs['colorG'] < 0 or kwargs['colorG'] > 255:
+            raise TypeError
+        if kwargs['colorB'] < 0 or kwargs['colorB'] > 255:
+            raise TypeError
+
+        byteCr = struct.pack('<B', kwargs['colorR'])
+        byteCg = struct.pack('<B', kwargs['colorG'])
+        byteCb = struct.pack('<B', kwargs['colorB'])
+
+        if len(byteCb) != 1 or len(byteCg) != 1 or len(byteCr) != 1:
+            raise TypeError
+
+        pos = kwargs['posData']
+        lightAngle = kwargs['angleToLight']
+        litCenterLed = floor((self._ledCount / 360) * pos.psi)
+        lookAngleCnt = floor((self._ledCount / 360) * lightAngle)
+        payload = bytearray(b'\0' * (3 * self._ledCount))
+
+        for i in range(
+            floor(litCenterLed - (lookAngleCnt / 2)),
+            litCenterLed,
+            3,
+        ):
+            payload[i] = byteCr[0]
+            payload[i + 1] = byteCg[0]
+            payload[i + 2] = byteCb[0]
+
+        for i in range(
+            litCenterLed,
+            floor(litCenterLed + (lookAngleCnt / 2)) + 1,
+            3,
+        ):
+            payload[i] = byteCr[0]
+            payload[i + 1] = byteCg[0]
+            payload[i + 2] = byteCb[0]
+
+        return payload

slasd/ledAnimationDriver.py

@@ -0,0 +1,121 @@
+"""Base class for an LED animation driver."""
+
+from serial import Serial
+
+from .commands.noResp import SetLedState
+
+
+class LedAnimationDevice:
+    """Defines interface for connecting, setting up, and streaming from a Fastrak.
+
+    Attributes
+    ----------
+    _ser : Serial | None
+        Serial connection to an Arduino.
+
+    _COMport :
+        String representing the COM port to be connected to.
+
+    _baud : SerialBaudrates
+        Baudrate for the serial connection.
+
+    _timeout : int, default: 1second
+        Serial timeout for the connection.
+
+    _ledCount: int
+        The number of LED in the array.
+
+    """
+
+    _ser: Serial | None
+    _COMport: str
+    _baud: int
+    _timeout: int
+    _ledCount: int
+
+    def __init__(
+        self,
+        COMport: str = 'COM1',
+        baud: int = 115200,
+        timeout: int = 1,
+        ledCount: int = 100,
+        setup: bool = True,
+    ) -> None:
+        """Construct a LedAnimationDevice class.
+
+        Parameters
+        ----------
+        COMport : str
+            String representing the COM port to be connected to.
+
+        baud : int, default: 1115200
+            Baudrate for the serial connection.
+
+        timeout : int, default: 1second
+            Serial timeout for the connection.
+
+        ledCount: int, defualt: 100
+            The number of LED in the array.
+
+        setup : int, default: True
+            Flag indicating if the device should connect to the serial interface.
+
+        """
+        self._ser = None
+        self._COMport = COMport
+        self._baud = baud
+        self._timeout = timeout
+        self._ledCount = ledCount
+        if setup:
+            self.connect()
+
+    def connect(self) -> None:
+        """Connect to the serial device."""
+        if self._ser is not None:
+            if not self._ser.is_open:
+                self._ser.open()
+        else:
+            self._ser = Serial(self._COMport, self._baud, timeout=self._timeout)
+
+    def _sendState(self, data: bytearray) -> None:
+        """Send state data to the serial device.
+
+        Parameters
+        ----------
+        data : bytearray
+            LED array state data to send to the device.
+
+
+        """
+        if self._ser is not None:
+            SetLedState(data).send(self._ser)
+
+    def _computeState(self, **kwargs) -> bytearray:
+        """State computation interface.
+
+        Parameters
+        ----------
+        **kwargs: dict
+            Collection of keyword arguments. Unique to each animation class.
+
+
+        Returns
+        -------
+        bytearray
+            The computed state of the LED array.
+
+
+        """
+        raise NotImplementedError
+
+    def compNSndState(self, **kwargs) -> None:
+        """Compute and set the state of the LED array.
+
+        Parameters
+        ----------
+        **kwargs : dict
+            Collection of keyword arguments. Unique to each animation class.
+
+        """
+        payload = self._computeState(**kwargs)
+        self._sendState(payload)

slasd-0.0.0.dist-info/METADATA

@@ -0,0 +1,311 @@
+Metadata-Version: 2.5
+Name: SLASD
+Version: 0.0.0
+Summary: A serial driver and arduino project for 'animating' on a simple LED string.         
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: fastrakserialdriver>=0.2.1
+Requires-Dist: pyserial>=3.5
+Description-Content-Type: text/markdown
+
+---
+title: Simple Arduino Controlled LED Serial Driver
+authors:
+  - joe_starr
+---
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![White Logo image](https://brainmade.org/white-logo.svg){width=10%}](https://brainmade.org)
+
+![hero](./infra/assets/logo.svg)
+
+/// caption
+Arduino Mega from `amperka/hardware-drawings` [@amperka_hardware_drawings_2016]
+///
+
+## Note to Reader
+
+### What Am I?
+
+This repository contains an Arduino sketch which uses the FastLED library to control a collection
+(strip) of NEOPIXEL LED. The repository also contains a Python serial driver for commanding the
+Arduino. The python side is primarily designed around controlling the LED array based on feedback
+from a [Polhemus Fastrak](https://polhemus.com/all-trackers/fastrak).
+
+Simple installation by pip. You should probably be using uv projects: `uv add SLASD`
+
+### About the Documentation
+
+The following document describes the "rules" and expectation for development. The
+["API Reference"](./reference/fastrakSerialDriver/) page contains the technical context descriptions
+found in the source files. The ["Use Cases"](./content/usecase/usecase) page contains a collection
+of use cases and a use case diagram for the tool. The ["Decisions"](./content/madr/) page contains a
+collection of [architectural decision records](https://adr.github.io/madr/) [@Kopp2018] giving
+context on why this tool is the way it is.
+
+### Issues
+
+If you discover an issue with this repository or have a question, please feel free to open an issue.
+I've included templates for the following issues:
+
+- 🖋️ Spelling and Grammar: Found some language that is incorrect?
+- 🤷 Clarity: Found a section that just makes no sense?
+- ❓ Question: Do you have a general question?
+- 🐞 Bug: Found an error in the code?
+- 🚀 Enhancement: Have a suggestion for improving the toolchain?
+
+[:fontawesome-solid-paper-plane: Open Issue!](https://github.com/Nontrivial-Solutions/psychopy-6dof/issues/new/choose){ .md-button }
+
+## 📃 Cite Me
+
+## ⚖️ License
+
+Documentation:
+[![License: CC BY-SA 4.0](https://licensebuttons.net/l/by-sa/4.0/80x15.png)](https://creativecommons.org/licenses/by-sa/4.0/)
+
+Code:
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Planning and Administration
+
+### Tasks
+
+Tasks are tracked as GitHub issues.
+
+### Version Control
+
+The toolchain shall be kept under Git versioning. Development shall take place on branches with
+`main` on GitHub as a source of truth. GitHub pull requests shall serve as the arbiter for inclusion
+on main with the following quality gates:
+
+- Running and passing the unit test suite.
+- Running and passing linting and style enforcers.
+- Successful generation of documentation.
+
+#### Release Tagging
+
+The project shall be tagged when a new feature or bug fix is merged into main. The tag shall follow
+[semantic versioning](https://semver.org) for labels.
+
+```text
+vMAJOR.MINOR.PATCH
+```
+
+### Project Structure
+
+Files and directories shall be lower case, where capital is not required by a tool, and contain no
+`' '`.
+
+```text
+📁 .
+├── 📁 .github
+│   ├── 📁 ISSUE_TEMPLATE
+│   ├── 📁 PULL_REQUEST_TEMPLATE
+│   ├── 📁 workflows
+│   └── 📝 pull_request_template.md
+├── 📁 .vscode
+│   └── ⚙️ launch.json
+├── 📁 docs
+│   ├── 📁 contentt
+│   │   ├── 📁 madr
+│   │   ├── 📁 units
+│   │   └── 📁 usecase
+│   ├── 📁 infra
+│   └── 📖 README.md
+├── 📁 arduino_src 
+│   └── 🇨 arduino_src.ino
+├── 📁 slasd 
+│   └── 🐍 __init__.py
+├── ⚙️ .editorconfig
+├── 🙈 .gitignore
+├── 🛠️ .pre-commit-config.yaml
+├── ⚙️ .rumdl.toml
+├── ❄️ flake.lock
+├── ❄️ flake.nix
+├── 🛠️ Justfile
+├── 📜 LICENSE
+├── 📄 mkdocs.yml
+├── 🐍 pyproject.toml
+└── 🔒 uv.lock
+```
+
+### Directories of Interest
+
+- docs: This directory contains the high level documentation for the tool.
+- arduino_src: This directory contains the source code of the Arduino side of the tool.
+- slasd: This directory contains the source code of the python side of the tool.
+- .github: This directory contains the GitHub infrastructure.  
+- .vscode: This directory contains the debugger configuration.  
+
+### Define a Unit
+
+A unit shall be a Python module.
+
+### Quality
+
+The tool and its units shall fail-safe, that is the tool and its units can fail, but the failure
+must be detectable. A segfault is okay, an off by one error that computes the wrong value is not.
+
+#### Unit Testing
+
+No unit testing in the project only integration testing. See
+[ADR00002][./content/madr/00002_testing.md].
+
+#### Integration Testing
+
+The plugin shall have manual integration testing.
+
+### Requirements
+
+#### Use Cases
+
+Requirements are described as a collection of use cases and actors. There are two collections of the
+artifacts one for the [client](./content/arduino_src/usecase/) and one for the
+[server](./content/python_driver/usecase/usecase/). These are in turn collected into the following
+use case diagrams:
+
+##### Client
+
+```mermaid
+flowchart LR
+  aS["👤  Server"]
+
+  SS(["Set State"])
+  RC(["Receive Command"])
+
+  aS --> RC
+
+  RC -. include .->SS
+```
+
+##### Server
+
+```mermaid
+flowchart LR
+  aU["👤 User"]
+
+  SC(["Send Command"])
+
+  aU --> SC
+```
+
+##### Architectural Decisions
+
+Architectural decisions [MADR](<https://github.com/adr/madr>) [@Kopp2018] serve as the primary
+documentation for architectural decisions.
+
+The following is the order of operations for the proposal of a MADR:
+
+1. Create a branch for a proposal with the name:
+
+    ```text
+    proposal-{{short title}}
+    ```
+
+1. Create a pull request with this template.
+1. In the branch create a Markdown file based on the
+    [MADR Template](https://github.com/adr/madr/blob/4.0.0/template/adr-template.md). Name the
+    Markdown file:
+
+    ```text
+    {{issue# padded to five digits}}-{{title}}
+    ```
+
+1. When a decision is made change the status to:
+    - "accepted" and pull the branch into main branch
+    - "rejected" and pull the branch into main branch
+
+#### Nonfunctional Requirements
+
+##### Colors
+
+Diagrams included in documentation for features (use case and unit descriptions) are expected to use
+the [COLORS](https://clrs.cc) color palette.
+
+##### Technologies
+
+###### Languages and Frameworks
+
+- git
+- Python
+- mermaid.js
+- prek
+- tombi
+- rumdl
+- ruff
+- uv
+- MADR[@Kopp2018]
+
+###### Documentation of Implementation
+
+###### Code Style Guide
+
+Python code shall be formatted with ruff using the included style settings. Markdown files shall be
+formatted with ruff using the included style settings. TOML files shall be formatted with tombi
+using the included style settings.
+
+## Design and Documentation
+
+### System
+
+#### Block Diagram
+
+```mermaid
+flowchart LR
+    device["BaseLedAnimator"]
+    cwr@{ shape: processes, label: "{{Collection}}<br>Device specific animators" }
+    commands@{ shape: processes, label: "{{Collection}}<br>Available Commands" }
+
+    device --> cwr
+    device --> commands 
+```
+
+#### Class Diagram
+
+```mermaid
+classDiagram
+    class LedAnimationDevice {
+        + init( COMport, baud, timeout, ledCount) 
+        + connect() 
+        + compNSndState( **kwargs) 
+        - sendState( data) 
+        - computeState( **kwargs) 
+    }
+
+    class FastrakAnimationDevice {
+        - computeState( **kwargs) 
+    }
+
+    class FastrakParams {
+        + FastrakPostion posData
+        + int angleToLight
+        + int colorR
+        + int colorG
+        + int colorB
+    }
+
+
+    class SetLedState {
+        + init(self, data) 
+    }
+    
+    class SerialCommand {
+        <<interface>>
+        - str commandId
+        - bytearray payload
+        + send(ser) 
+    }
+
+    SetLedState ..|> SerialCommand
+
+    FastrakAnimationDevice --|> LedAnimationDevice
+
+    FastrakParams --* FastrakAnimationDevice 
+    SetLedState --* LedAnimationDevice 
+
+```
+
+#### Unit Designs
+
+Unit designs (and test description) for the client and server units (public members and methods) is
+found under their respective documentation sections.

slasd-0.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+slasd/__init__.py,sha256=1woE1s4Dk7Jc9BGPlw4xKww2jBURu8Nf-ZzIkr8yMEI,248
+slasd/fastrakAnimator.py,sha256=qfE3q4pyyOblf2SyZxkOFsxgeP3PvvelBBxtxrnMX_I,4471
+slasd/ledAnimationDriver.py,sha256=Td-JTnqrrRZ4n3TBGjPxnB-M2xVJoFspRJGGQosnD9Y,2971
+slasd/commands/__init__.py,sha256=n2FGkS4jOSkVD_NJhlYWtpvSDvD_Fxw97gdKEqoSTXw,55
+slasd/commands/command.py,sha256=qPvRmlArAseudxJs-pCy05x8t4Fo9N5Z-aMUnVybt7Y,756
+slasd/commands/noResp.py,sha256=S1o8DEfe_MgGFGBLNAL7dDVoC5bXn_pFiR-uwnvQlRA,555
+slasd-0.0.0.dist-info/METADATA,sha256=yUaTCQIw7AsAuJUxVwc2phaowanh0uPY4-f-GS7jVcs,8553
+slasd-0.0.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+slasd-0.0.0.dist-info/licenses/LICENSE,sha256=1MTKLFfNXi_QF-p6BP0RGjsHRii9jsza5z1ExtHxvwM,1065
+slasd-0.0.0.dist-info/RECORD,,

slasd-0.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

slasd-0.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joe Starr
+
+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.