ttl-barcoder 0.4.1__tar.gz

ttl_barcoder-0.4.1/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+*.so
+*.egg
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Testing
+.coverage
+.coverage.*
+.pytest_cache/
+htmlcov/
+.tox/
+.nox/
+
+# Type checkers / linters
+.mypy_cache/
+.ruff_cache/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE / OS
+.idea/
+.vscode/
+.DS_Store

ttl_barcoder-0.4.1/CITATION.cff

@@ -0,0 +1,11 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+type: software
+title: "ttl-barcoder: TTL barcode generation for multi-system DAQ synchronization"
+version: "0.4.0"
+repository-code: https://github.com/murineshiftwork/ttl-barcoder
+license: BSD-3-Clause
+authors:
+  - family-names: Rollik
+    given-names: Lars B.
+    orcid: https://orcid.org/0000-0003-0160-6971

ttl_barcoder-0.4.1/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2024, Lars B. Rollik
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

ttl_barcoder-0.4.1/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: ttl-barcoder
+Version: 0.4.1
+Summary: Modular barcode generation for TTL synchronization with clean hardware separation
+Project-URL: Homepage, https://github.com/murineshiftwork/ttl-barcoder
+Project-URL: Documentation, https://murineshiftwork.github.io/ttl-barcoder/
+Project-URL: Issue Tracker, https://github.com/murineshiftwork/ttl-barcoder/issues
+Author-email: "Lars B. Rollik" <L.B.Rollik@protonmail.com>
+License: BSD-3-Clause
+License-File: LICENSE
+Keywords: barcode,bpod,daq,gpio,neuroscience,pigpio,raspberry-pi,synchronization,ttl
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Interface Engine/Protocol Translator
+Classifier: Topic :: System :: Hardware :: Hardware Drivers
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.20
+Requires-Dist: pydantic>=2.0
+Provides-Extra: bpod
+Requires-Dist: pybpod-api; extra == 'bpod'
+Provides-Extra: dev
+Requires-Dist: commitizen; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material; extra == 'docs'
+Provides-Extra: pigpio
+Requires-Dist: pigpio>=1.78; extra == 'pigpio'
+Description-Content-Type: text/markdown
+
+# TTL Barcoder
+
+[![PyPI](https://img.shields.io/pypi/v/ttl-barcoder.svg)](https://pypi.org/project/ttl-barcoder)
+
+Generate and decode binary barcodes over TTL signals to synchronize multiple data acquisition systems.
+Barcodes encode a timestamp or random value as a sequence of timed HIGH/LOW pulses, transmittable over any digital output.
+
+
+## Quick Start
+
+```python
+from ttl_barcoder.core import BarcodeTTL, BarcodeConfig, TTLType, TimestampPrecision
+
+# Timestamp barcode (default) — encodes current time at ms precision
+barcoder = BarcodeTTL()
+sequence = barcoder.get_sequence()   # [(level: bool, duration_ms: float), ...]
+
+# Random barcode
+config = BarcodeConfig(ttl_type=TTLType.random, barcode_bits=32)
+barcoder = BarcodeTTL(config)
+sequence = barcoder.get_sequence()
+```
+
+### Bpod
+```python
+from ttl_barcoder.core import BarcodeTTL
+from ttl_barcoder.hardware.bpod import inject_barcode_states
+
+barcoder = BarcodeTTL()
+sequence = barcoder.get_sequence()
+inject_barcode_states(sma, sequence, bnc_channel='BNC1', first_state_name='send_sync', last_state_name='next')
+```
+
+### Raspberry Pi GPIO
+```python
+from ttl_barcoder.hardware.pigpio import send_barcode_sequence
+
+send_barcode_sequence(barcoder.get_sequence(), pin=18)
+```
+
+
+## Installation
+
+```bash
+pip install ttl-barcoder          # core only
+pip install ttl-barcoder[bpod]    # + Bpod
+pip install ttl-barcoder[pigpio]  # + Raspberry Pi GPIO
+```
+
+
+## Configuration
+
+`BarcodeConfig` is a Pydantic model — all fields are validated on construction.
+
+```python
+from ttl_barcoder.core import BarcodeConfig, TTLType, TimestampPrecision
+
+config = BarcodeConfig(
+    ttl_type=TTLType.timestamp,            # or TTLType.random
+    barcode_bits=37,                        # 16–64 bits
+    timestamp_precision=TimestampPrecision.milliseconds,  # s / ms / us
+    bit_duration_ms=35.0,
+    init_duration_ms=10.0,
+    tolerance=0.25,
+)
+```
+
+**Presets**: `default`, `high_speed`, `conservative`, `high_precision`, `random`
+
+```python
+from ttl_barcoder.core import get_preset
+config = get_preset("conservative")
+```
+
+| Preset           | Bits | Precision | Bit duration | TX duration | Coverage |
+|------------------|------|-----------|--------------|-------------|----------|
+| `default`        | 37   | ms        | 35 ms        | 1355 ms     | 4.4 yr   |
+| `high_speed`     | 32   | ms        | 25 ms        | 848 ms      | 49 days  |
+| `conservative`   | 37   | ms        | 50 ms        | 1940 ms     | 4.4 yr   |
+| `high_precision` | 42   | us        | 50 ms        | 2190 ms     | 51 days  |
+
+
+## Architecture
+
+```
+ttl_barcoder/
+├── core/
+│   ├── config.py        # BarcodeConfig (Pydantic), TTLType, TimestampPrecision
+│   ├── generator.py     # TTLGenerator ABC → TimestampGenerator / RandomGenerator
+│   ├── encoder.py       # bits → (level, duration_ms) timing sequence
+│   ├── decoder.py       # edge timestamps → barcode value
+│   └── barcode_ttl.py   # BarcodeTTL — main interface combining the above
+└── hardware/
+    ├── bpod/            # Bpod StateMachine integration
+    └── pigpio/          # Raspberry Pi GPIO via pigpio
+```
+
+- The generator is selected via a factory (`create_generator(config)`) based on `TTLType`.
+- `TimestampGenerator` quantizes Unix time at the configured precision
+- `RandomGenerator` draws from a numpy RNG. Both share the same `encode_bits` / `max_value` interface on the `TTLGenerator` base class.
+
+
+## Examples
+
+- `examples/dry_simulation.py` — full walkthrough, no hardware needed
+- `examples/bpod_loopback.py` — Bpod StateMachine with loopback test
+- `examples/pigpio_send.py` — Raspberry Pi GPIO transmission
+
+
+## Contributing
+
+1. Fork and create a feature branch
+2. Add tests for new functionality
+3. Run `pytest`
+4. Submit a pull request
+
+
+## Acknowledgments
+
+- Based on barcode synchronization from University of Colorado ONE Core
+- Inspired by Open Ephys protocols
+- Built for the neuroscience and scientific DAQ community
+
+
+## License & sources
+
+This software is released under the **[BSD 3-Clause License](LICENSE)**.

ttl_barcoder-0.4.1/README.md

@@ -0,0 +1,127 @@
+# TTL Barcoder
+
+[![PyPI](https://img.shields.io/pypi/v/ttl-barcoder.svg)](https://pypi.org/project/ttl-barcoder)
+
+Generate and decode binary barcodes over TTL signals to synchronize multiple data acquisition systems.
+Barcodes encode a timestamp or random value as a sequence of timed HIGH/LOW pulses, transmittable over any digital output.
+
+
+## Quick Start
+
+```python
+from ttl_barcoder.core import BarcodeTTL, BarcodeConfig, TTLType, TimestampPrecision
+
+# Timestamp barcode (default) — encodes current time at ms precision
+barcoder = BarcodeTTL()
+sequence = barcoder.get_sequence()   # [(level: bool, duration_ms: float), ...]
+
+# Random barcode
+config = BarcodeConfig(ttl_type=TTLType.random, barcode_bits=32)
+barcoder = BarcodeTTL(config)
+sequence = barcoder.get_sequence()
+```
+
+### Bpod
+```python
+from ttl_barcoder.core import BarcodeTTL
+from ttl_barcoder.hardware.bpod import inject_barcode_states
+
+barcoder = BarcodeTTL()
+sequence = barcoder.get_sequence()
+inject_barcode_states(sma, sequence, bnc_channel='BNC1', first_state_name='send_sync', last_state_name='next')
+```
+
+### Raspberry Pi GPIO
+```python
+from ttl_barcoder.hardware.pigpio import send_barcode_sequence
+
+send_barcode_sequence(barcoder.get_sequence(), pin=18)
+```
+
+
+## Installation
+
+```bash
+pip install ttl-barcoder          # core only
+pip install ttl-barcoder[bpod]    # + Bpod
+pip install ttl-barcoder[pigpio]  # + Raspberry Pi GPIO
+```
+
+
+## Configuration
+
+`BarcodeConfig` is a Pydantic model — all fields are validated on construction.
+
+```python
+from ttl_barcoder.core import BarcodeConfig, TTLType, TimestampPrecision
+
+config = BarcodeConfig(
+    ttl_type=TTLType.timestamp,            # or TTLType.random
+    barcode_bits=37,                        # 16–64 bits
+    timestamp_precision=TimestampPrecision.milliseconds,  # s / ms / us
+    bit_duration_ms=35.0,
+    init_duration_ms=10.0,
+    tolerance=0.25,
+)
+```
+
+**Presets**: `default`, `high_speed`, `conservative`, `high_precision`, `random`
+
+```python
+from ttl_barcoder.core import get_preset
+config = get_preset("conservative")
+```
+
+| Preset           | Bits | Precision | Bit duration | TX duration | Coverage |
+|------------------|------|-----------|--------------|-------------|----------|
+| `default`        | 37   | ms        | 35 ms        | 1355 ms     | 4.4 yr   |
+| `high_speed`     | 32   | ms        | 25 ms        | 848 ms      | 49 days  |
+| `conservative`   | 37   | ms        | 50 ms        | 1940 ms     | 4.4 yr   |
+| `high_precision` | 42   | us        | 50 ms        | 2190 ms     | 51 days  |
+
+
+## Architecture
+
+```
+ttl_barcoder/
+├── core/
+│   ├── config.py        # BarcodeConfig (Pydantic), TTLType, TimestampPrecision
+│   ├── generator.py     # TTLGenerator ABC → TimestampGenerator / RandomGenerator
+│   ├── encoder.py       # bits → (level, duration_ms) timing sequence
+│   ├── decoder.py       # edge timestamps → barcode value
+│   └── barcode_ttl.py   # BarcodeTTL — main interface combining the above
+└── hardware/
+    ├── bpod/            # Bpod StateMachine integration
+    └── pigpio/          # Raspberry Pi GPIO via pigpio
+```
+
+- The generator is selected via a factory (`create_generator(config)`) based on `TTLType`.
+- `TimestampGenerator` quantizes Unix time at the configured precision
+- `RandomGenerator` draws from a numpy RNG. Both share the same `encode_bits` / `max_value` interface on the `TTLGenerator` base class.
+
+
+## Examples
+
+- `examples/dry_simulation.py` — full walkthrough, no hardware needed
+- `examples/bpod_loopback.py` — Bpod StateMachine with loopback test
+- `examples/pigpio_send.py` — Raspberry Pi GPIO transmission
+
+
+## Contributing
+
+1. Fork and create a feature branch
+2. Add tests for new functionality
+3. Run `pytest`
+4. Submit a pull request
+
+
+## Acknowledgments
+
+- Based on barcode synchronization from University of Colorado ONE Core
+- Inspired by Open Ephys protocols
+- Built for the neuroscience and scientific DAQ community
+
+
+## License & sources
+
+This software is released under the **[BSD 3-Clause License](LICENSE)**.

ttl_barcoder-0.4.1/VERSION

@@ -0,0 +1 @@
+0.4.1

ttl_barcoder-0.4.1/examples/bpod_loopback.py

@@ -0,0 +1,161 @@
+#!/usr/bin/env python3
+"""
+Example: Bpod loopback test
+
+Demonstrates Bpod StateMachine integration with loopback testing
+on the same device (BNC1 out -> BNC1 in).
+"""
+
+from ttl_barcoder.core import BarcodeConfig, BarcodeTTL
+
+
+def main():
+    print("TTL Barcoder - Bpod Loopback Example")
+    print("=" * 45)
+
+    try:
+        from pybpod import StateMachine
+
+        from ttl_barcoder.hardware.bpod import BpodBarcodeSender, inject_barcode_states
+    except ImportError as e:
+        print(f"Bpod not available: {e}")
+        print("Install with: pip install pybpod")
+        return
+
+    # Configuration for demo
+    config = BarcodeConfig(
+        barcode_bits=32,  # Shorter for demo
+        bit_duration_ms=50.0,  # Slower for visualization
+        init_duration_ms=15.0,
+    )
+
+    print(f"Using config: {config}")
+
+    # Create barcode system
+    barcoder = BarcodeTTL(config)
+
+    # Get barcode sequence
+    test_barcode = 12345
+    timing_sequence = barcoder.get_sequence(test_barcode)
+
+    print(f"\nGenerated sequence for barcode {test_barcode}:")
+    print(f"  {len(timing_sequence)} segments")
+    print(f"  Total duration: {config.total_duration_ms:.0f}ms")
+
+    # Create StateMachine
+    sma = StateMachine()
+
+    # Initial state
+    sma.add_state(
+        state_name="start",
+        state_timer=1.0,
+        state_change_conditions={"Tup": "send_barcode"},
+        output_actions=[],
+    )
+
+    # Method 1: Direct injection (recommended)
+    print("\nMethod 1: Direct injection")
+    sender = BpodBarcodeSender()
+    sender.inject_states(
+        sma=sma,
+        timing_sequence=timing_sequence,
+        bnc_channel="BNC1",
+        first_state_name="send_barcode",
+        last_state_name="listen_barcode",
+    )
+
+    # Listen for barcode return
+    sma.add_state(
+        state_name="listen_barcode",
+        state_timer=config.total_duration_ms / 1000.0 + 0.5,  # Give extra time
+        state_change_conditions={"BNC1High": "detected", "Tup": "timeout"},
+        output_actions=[],
+    )
+
+    # Detection states
+    sma.add_state(
+        state_name="detected",
+        state_timer=0.1,
+        state_change_conditions={"Tup": "success"},
+        output_actions=[("LED", 255)],  # Success indicator
+    )
+
+    sma.add_state(
+        state_name="timeout",
+        state_timer=0.1,
+        state_change_conditions={"Tup": "exit"},
+        output_actions=[],
+    )
+
+    sma.add_state(
+        state_name="success",
+        state_timer=2.0,
+        state_change_conditions={"Tup": "exit"},
+        output_actions={"LED": 255},
+    )
+
+    print(f"Created StateMachine with {len(sma.state_names)} states")
+    print("State sequence:", " -> ".join(sma.state_names))
+
+    # Method 2: Convenience function
+    print("\nMethod 2: Convenience function")
+    sma2 = StateMachine()
+    sma2.add_state(
+        state_name="start",
+        state_timer=1.0,
+        state_change_conditions={"Tup": "barcode"},
+        output_actions=[],
+    )
+
+    inject_barcode_states(
+        sma=sma2,
+        timing_sequence=timing_sequence,
+        bnc_channel="BNC1",
+        first_state_name="barcode",
+        last_state_name="end",
+    )
+
+    sma2.add_state(
+        state_name="end",
+        state_timer=0.1,
+        state_change_conditions={"Tup": "exit"},
+        output_actions=[],
+    )
+    print(f"Method 2 StateMachine: {len(sma2.state_names)} states")
+
+    # Connection and execution (commented for safety)
+    print("\nTo run on actual Bpod device:")
+    print("1. Connect Bpod at /dev/ttyACM0")
+    print("2. Wire BNC1 output to BNC1 input (loopback)")
+    print("3. Uncomment execution code below")
+
+    """
+    # Uncomment to run on actual device
+    class BpodConnection:
+        def __init__(self, device_path):
+            self.bpod = BpodBase(device_path)
+
+        def __enter__(self):
+            return self
+
+        def __exit__(self, *_):
+            self.bpod.close()
+
+        def run(self, sma):
+            self.bpod.send_state_machine(sma)
+            self.bpod.run_state_machine(sma)
+
+    try:
+        with BpodConnection("/dev/ttyACM0") as bpod:
+            print("Connected to Bpod, running state machine...")
+            bpod.run(sma)
+            print("StateMachine completed successfully!")
+    except Exception as e:
+        print(f"Bpod execution failed: {e}")
+    """
+
+    print("\nBpod loopback example completed!")
+
+
+if __name__ == "__main__":
+    main()

ttl_barcoder-0.4.1/examples/dry_simulation.py

@@ -0,0 +1,88 @@
+from ttl_barcoder.core import BarcodeConfig, BarcodeTTL, get_preset
+
+
+def main():
+    print("TTL Barcoder - Dry Simulation Example")
+    print("=" * 45)
+
+    # 1. Basic configuration
+    print("\n1. Basic Configuration:")
+    config = BarcodeConfig.default()
+    print(f"Default config: {config}")
+    print(f"Config info: {config.info()}")
+
+    # 2. Create BarcodeTTL instance
+    barcoder = BarcodeTTL(config)
+    print(f"\nBarcoder: {barcoder}")
+
+    # 3. One-liner sequence generation
+    print("\n2. One-liner Sequence Generation:")
+    sequence = barcoder.get_sequence()  # Current timestamp
+    print(f"Generated sequence: {len(sequence)} segments")
+
+    # Show first few segments
+    print("First 5 segments:")
+    for i, (level, duration) in enumerate(sequence[:5]):
+        level_str = "HIGH" if level else "LOW"
+        print(f"  {i}: {level_str} for {duration:.1f}ms")
+
+    # 4. Specific barcode
+    print("\n3. Specific Barcode:")
+    specific_sequence = barcoder.get_sequence(12345)
+    print(f"Barcode 12345 sequence: {len(specific_sequence)} segments")
+
+    # 5. Multiple sequences
+    print("\n4. Multiple Sequences:")
+    multi_sequences = barcoder.get_multiple_sequences(count=3, interval_s=1.0)
+    print(f"Generated {len(multi_sequences)} sequences")
+
+    # 6. Test different configurations
+    print("\n5. Configuration Presets:")
+    for preset_name in ["high_speed", "conservative", "high_precision"]:
+        preset_config = get_preset(preset_name)
+        preset_barcoder = BarcodeTTL(preset_config)
+        preset_sequence = preset_barcoder.get_sequence()
+
+        print(
+            f"{preset_name:15s}: {len(preset_sequence)} segments, "
+            f"{preset_config.total_duration_ms:.0f}ms total"
+        )
+
+    # 7. Simulate decode test
+    print("\n6. Decode Simulation:")
+    # Simulate perfect edge detection
+    test_sequence = barcoder.get_sequence(99999)
+    simulated_edges = simulate_perfect_edges(test_sequence)
+
+    decoded = barcoder.decode_edges(*simulated_edges)
+    if decoded:
+        timestamp, barcode_value = decoded
+        print(f"Simulated decode successful: barcode = {barcode_value}")
+    else:
+        print("Simulated decode failed")
+
+    print("\nDry simulation completed!")
+
+
+def simulate_perfect_edges(timing_sequence):
+    """Convert timing sequence to perfect edge timestamps for testing."""
+    edge_times = []
+    edge_levels = []
+
+    current_time = 0.0
+    current_level = False  # Start LOW
+
+    for target_level, duration_ms in timing_sequence:
+        if target_level != current_level:
+            # Level change - record edge
+            edge_times.append(current_time)
+            edge_levels.append(target_level)
+            current_level = target_level
+
+        current_time += duration_ms / 1000.0  # Convert to seconds
+
+    return edge_times, edge_levels
+
+
+if __name__ == "__main__":
+    main()