ttl-barcoder 0.4.1__py3-none-any.whl

ttl_barcoder/__init__.py

@@ -0,0 +1,34 @@
+from importlib.metadata import PackageNotFoundError, version
+
+from ttl_barcoder.core import (
+    BarcodeConfig,
+    BarcodeDecoder,
+    BarcodeTTL,
+    RandomGenerator,
+    TimestampGenerator,
+    TimestampPrecision,
+    TimingEncoder,
+    TTLGenerator,
+    TTLType,
+    create_generator,
+    get_preset,
+)
+
+try:
+    __version__ = version("ttl-barcoder")
+except PackageNotFoundError:
+    __version__ = "unknown"
+
+__all__ = [
+    "BarcodeConfig",
+    "BarcodeDecoder",
+    "BarcodeTTL",
+    "RandomGenerator",
+    "TimestampGenerator",
+    "TimestampPrecision",
+    "TimingEncoder",
+    "TTLGenerator",
+    "TTLType",
+    "create_generator",
+    "get_preset",
+]

ttl_barcoder/core/__init__.py

@@ -0,0 +1,29 @@
+from ttl_barcoder.core.barcode_ttl import BarcodeTTL
+from ttl_barcoder.core.config import (
+    BarcodeConfig,
+    TimestampPrecision,
+    TTLType,
+    get_preset,
+)
+from ttl_barcoder.core.decoder import BarcodeDecoder
+from ttl_barcoder.core.encoder import TimingEncoder
+from ttl_barcoder.core.generator import (
+    RandomGenerator,
+    TimestampGenerator,
+    TTLGenerator,
+    create_generator,
+)
+
+__all__ = [
+    "BarcodeConfig",
+    "TimestampPrecision",
+    "TTLType",
+    "get_preset",
+    "TTLGenerator",
+    "TimestampGenerator",
+    "RandomGenerator",
+    "create_generator",
+    "TimingEncoder",
+    "BarcodeDecoder",
+    "BarcodeTTL",
+]

ttl_barcoder/core/barcode_ttl.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from ttl_barcoder.core.config import BarcodeConfig, TTLType
+from ttl_barcoder.core.decoder import BarcodeDecoder
+from ttl_barcoder.core.encoder import TimingEncoder
+from ttl_barcoder.core.generator import (
+    TimestampGenerator,
+    TTLGenerator,
+    create_generator,
+)
+
+
+class BarcodeTTL:
+    """Main interface for TTL barcode generation and decoding."""
+
+    def __init__(self, config: BarcodeConfig | None = None) -> None:
+        self.config = config or BarcodeConfig.default()
+        self.generator: TTLGenerator = create_generator(self.config)
+        self.encoder = TimingEncoder(
+            bit_duration_ms=self.config.bit_duration_ms,
+            init_duration_ms=self.config.init_duration_ms,
+        )
+        self.decoder = BarcodeDecoder(
+            barcode_bits=self.config.barcode_bits,
+            bit_duration_ms=self.config.bit_duration_ms,
+            init_duration_ms=self.config.init_duration_ms,
+            tolerance=self.config.tolerance,
+        )
+
+    def prepare(self) -> tuple[int, float, list[tuple[bool, float]]]:
+        """Capture wall time and return (barcode_value, wall_time, timing_sequence).
+
+        Wall time is captured before generate() so it matches the encoded timestamp.
+        """
+        import time
+
+        wall_time = time.time()
+        barcode_value = self.generator.generate(timestamp=wall_time)
+        timing_sequence = self.get_sequence(barcode=barcode_value)
+        return barcode_value, wall_time, timing_sequence
+
+    def get_sequence(self, barcode: int | None = None) -> list[tuple[bool, float]]:
+        """Return (level, duration_ms) timing sequence for hardware transmission."""
+        if barcode is None:
+            barcode = self.generator.generate()
+        bits = self.generator.encode_bits(barcode)
+        return self.encoder.encode_level_durations(bits)
+
+    def get_sequence_from_timestamp(self, timestamp: float) -> list[tuple[bool, float]]:
+        """Get timing sequence from a specific Unix timestamp (timestamp TTL only)."""
+        if self.config.ttl_type != TTLType.timestamp:
+            raise ValueError("get_sequence_from_timestamp requires TTLType.timestamp")
+        assert isinstance(self.generator, TimestampGenerator)
+        barcode = self.generator.generate(timestamp=timestamp)
+        return self.get_sequence(barcode=barcode)
+
+    def get_multiple_sequences(
+        self,
+        count: int = 1,
+        interval_s: float = 5.0,
+        start_timestamp: float | None = None,
+    ) -> list[list[tuple[bool, float]]]:
+        if self.config.ttl_type == TTLType.timestamp:
+            assert isinstance(self.generator, TimestampGenerator)
+            barcodes = self.generator.generate_sequence(
+                count=count, interval_s=interval_s, start_timestamp=start_timestamp
+            )
+        else:
+            barcodes = [self.generator.generate() for _ in range(count)]
+        return [self.get_sequence(b) for b in barcodes]
+
+    def decode_edges(
+        self, edge_timestamps: list[float], edge_levels: list[bool]
+    ) -> tuple[float, int] | None:
+        """Decode edge timestamps to (timestamp, barcode_value) or None."""
+        return self.decoder.decode_edges(
+            edge_timestamps=edge_timestamps, edge_levels=edge_levels
+        )
+
+    def recover_timestamp(
+        self, barcode_value: int, reference_time: float | None = None
+    ) -> float:
+        """Recover original timestamp from barcode value with wraparound handling."""
+        if self.config.ttl_type != TTLType.timestamp:
+            raise ValueError("recover_timestamp requires TTLType.timestamp")
+        assert isinstance(self.generator, TimestampGenerator)
+        return self.generator.recover_timestamp(
+            barcode_value=barcode_value, reference_time=reference_time
+        )
+
+    @classmethod
+    def default_config(cls) -> BarcodeConfig:
+        return BarcodeConfig.default()
+
+    @property
+    def info(self) -> dict:
+        return {
+            "config": self.config.info(),
+            "generator": self.generator.info,
+            "encoder": self.encoder.info,
+        }
+
+    def __str__(self) -> str:
+        return f"BarcodeTTL({self.config})"

ttl_barcoder/core/config.py

@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class TTLType(str, Enum):
+    """Type of barcode value to generate."""
+
+    timestamp = "timestamp"
+    random = "random"
+
+
+class TimestampPrecision(str, Enum):
+    """Timestamp quantization precision."""
+
+    seconds = "s"
+    milliseconds = "ms"
+    microseconds = "us"
+
+
+# Time units per second for each precision level
+PRECISION_UNITS_PER_SECOND: dict[TimestampPrecision, float] = {
+    TimestampPrecision.seconds: 1.0,
+    TimestampPrecision.milliseconds: 1_000.0,
+    TimestampPrecision.microseconds: 1_000_000.0,
+}
+
+
+class BarcodeConfig(BaseModel):
+    """Barcode configuration with Pydantic v2 validation."""
+
+    model_config = ConfigDict(validate_assignment=True, extra="forbid")
+
+    ttl_type: TTLType = TTLType.timestamp
+    barcode_bits: int = Field(
+        default=37, ge=16, le=64, description="Number of bits in barcode (16-64)"
+    )
+    timestamp_precision: TimestampPrecision = Field(
+        default=TimestampPrecision.milliseconds,
+        description="Timestamp quantization precision (s/ms/us)",
+    )
+    bit_duration_ms: float = Field(
+        default=35.0, gt=0, le=1000, description="Duration of each bit pulse in ms"
+    )
+    init_duration_ms: float = Field(
+        default=10.0, gt=0, le=100, description="Duration of init pulses in ms"
+    )
+    tolerance: float = Field(
+        default=0.25, ge=0.05, le=0.5, description="Timing tolerance (0.05-0.5)"
+    )
+
+    @classmethod
+    def default(cls) -> BarcodeConfig:
+        """Create default configuration."""
+        return cls()
+
+    @classmethod
+    def from_dict(cls, config_dict: dict[str, Any]) -> BarcodeConfig:
+        """Create configuration from dictionary."""
+        return cls(**config_dict)
+
+    @property
+    def coverage_years(self) -> float | None:
+        """Coverage in years (timestamp TTL only)."""
+        if self.ttl_type != TTLType.timestamp:
+            return None
+        units_per_second = PRECISION_UNITS_PER_SECOND[self.timestamp_precision]
+        coverage_seconds = (2**self.barcode_bits) / units_per_second
+        return coverage_seconds / (365.25 * 24 * 3600)
+
+    @property
+    def total_duration_ms(self) -> float:
+        """Total barcode duration in milliseconds."""
+        return 6 * self.init_duration_ms + self.barcode_bits * self.bit_duration_ms
+
+    @property
+    def safety_ratio(self) -> float:
+        """Safety ratio (bit_duration vs tolerance window)."""
+        return self.bit_duration_ms / (2 * self.bit_duration_ms * self.tolerance)
+
+    def info(self) -> dict[str, Any]:
+        """Configuration summary as dictionary."""
+        data = self.model_dump()
+        data["coverage_years"] = self.coverage_years
+        data["total_duration_ms"] = self.total_duration_ms
+        data["safety_ratio"] = self.safety_ratio
+        return data
+
+    def __str__(self) -> str:
+        parts = [f"{self.ttl_type.value}", f"{self.barcode_bits}-bit"]
+        if self.ttl_type == TTLType.timestamp:
+            parts.append(f"{self.timestamp_precision.value} precision")
+            if self.coverage_years is not None:
+                parts.append(f"{self.coverage_years:.1f}yr coverage")
+        parts += [
+            f"{self.bit_duration_ms}ms bits",
+            f"{self.total_duration_ms:.0f}ms total",
+        ]
+        return f"BarcodeConfig({', '.join(parts)})"
+
+
+# Preset configurations
+PRESETS: dict[str, BarcodeConfig] = {
+    "default": BarcodeConfig(),
+    "high_speed": BarcodeConfig(
+        barcode_bits=32,
+        timestamp_precision=TimestampPrecision.milliseconds,
+        bit_duration_ms=25.0,
+        init_duration_ms=8.0,
+    ),
+    "high_precision": BarcodeConfig(
+        barcode_bits=42,
+        timestamp_precision=TimestampPrecision.microseconds,
+        bit_duration_ms=50.0,
+        init_duration_ms=15.0,
+    ),
+    "conservative": BarcodeConfig(
+        barcode_bits=37,
+        timestamp_precision=TimestampPrecision.milliseconds,
+        bit_duration_ms=50.0,
+        init_duration_ms=15.0,
+        tolerance=0.20,
+    ),
+    "random": BarcodeConfig(
+        ttl_type=TTLType.random,
+        barcode_bits=32,
+    ),
+}
+
+
+def get_preset(name: str) -> BarcodeConfig:
+    """Get a preset configuration by name."""
+    if name not in PRESETS:
+        raise ValueError(f"Unknown preset '{name}'. Available: {list(PRESETS.keys())}")
+    return PRESETS[name]

ttl_barcoder/core/decoder.py

@@ -0,0 +1,76 @@
+import numpy as np
+
+
+class BarcodeDecoder:
+    """Decode edge timestamps back to barcode values."""
+
+    def __init__(
+        self,
+        barcode_bits: int = 37,
+        bit_duration_ms: float = 35.0,
+        init_duration_ms: float = 10.0,
+        tolerance: float = 0.25,
+    ):
+        self.barcode_bits = barcode_bits
+        self.bit_duration_ms = bit_duration_ms
+        self.init_duration_ms = init_duration_ms
+        self.tolerance = tolerance
+
+        self.init_wrapper_ms = 3 * init_duration_ms
+        self.min_init = init_duration_ms * (1 - tolerance)
+        self.max_init = init_duration_ms * (1 + tolerance)
+
+    def decode_edges(
+        self, edge_timestamps: list[float], edge_levels: list[bool]
+    ) -> tuple[float, int] | None:
+        """Decode edge timestamps to (timestamp, barcode_value) or None on failure."""
+        if len(edge_timestamps) < 6:
+            return None
+
+        start_time = edge_timestamps[0]
+        rel_times_ms = [(t - start_time) * 1000 for t in edge_timestamps]
+
+        if not self._validate_init_pattern(rel_times_ms):
+            return None
+
+        data_times = rel_times_ms[2:-2]
+        data_levels = edge_levels[2:-2]
+
+        if not data_times:
+            return None
+
+        bits = self._decode_bits(data_times, data_levels)
+        barcode_value = sum(bits[i] * (2**i) for i in range(len(bits)))
+        return (start_time, barcode_value)
+
+    def _validate_init_pattern(self, rel_times_ms: list[float]) -> bool:
+        # Require ≥1 init-duration gap (not 2): BNC idle-LOW + old encoder starting LOW
+        # leaves only 1 detectable gap. HIGH-LOW-HIGH encoder fix gives 2; requiring 1
+        # handles both encoder versions without breaking the fixed path.
+        if len(rel_times_ms) < 4:
+            return False
+        time_diffs = np.diff(rel_times_ms)
+        init_candidates = sum(
+            1 for diff in time_diffs[:3] if self.min_init <= diff <= self.max_init
+        )
+        return init_candidates >= 1
+
+    def _decode_bits(
+        self, data_times: list[float], data_levels: list[bool]
+    ) -> list[int]:
+        bits = []
+        current_level = False
+        edge_idx = 0
+        for bit in range(self.barcode_bits):
+            bit_sample_time = (
+                self.init_wrapper_ms
+                + bit * self.bit_duration_ms
+                + self.bit_duration_ms / 2
+            )
+            while (
+                edge_idx < len(data_times) and data_times[edge_idx] <= bit_sample_time
+            ):
+                current_level = data_levels[edge_idx]
+                edge_idx += 1
+            bits.append(1 if current_level else 0)
+        return bits

ttl_barcoder/core/encoder.py

@@ -0,0 +1,59 @@
+from typing import NamedTuple
+
+
+class TimingSegment(NamedTuple):
+    """Single timing segment in a barcode sequence."""
+
+    level: bool  # Signal level (True=HIGH, False=LOW)
+    duration_ms: float  # Duration in milliseconds
+
+
+class TimingEncoder:
+    """Encode barcode bits into timing sequences for hardware drivers."""
+
+    def __init__(self, bit_duration_ms: float = 35.0, init_duration_ms: float = 10.0):
+        self.bit_duration_ms = bit_duration_ms
+        self.init_duration_ms = init_duration_ms
+        self.init_sequence_ms = 3 * init_duration_ms
+
+    def encode_timing_sequence(self, bits: list[bool]) -> list[TimingSegment]:
+        sequence = []
+
+        # Start initialization: HIGH-LOW-HIGH
+        # Must start HIGH (not LOW) so the first edge always fires even when
+        # the BNC output is at LOW idle between trials. Starting LOW would
+        # suppress the first edge, leaving only 1 init gap visible to the
+        # decoder and causing init validation to fail for ~50% of barcodes
+        # (those where bit[0]=0, which produce no edge at t=30ms).
+        sequence.append(TimingSegment(True, self.init_duration_ms))
+        sequence.append(TimingSegment(False, self.init_duration_ms))
+        sequence.append(TimingSegment(True, self.init_duration_ms))
+
+        for bit in bits:
+            sequence.append(TimingSegment(bit, self.bit_duration_ms))
+
+        # End initialization: LOW-HIGH-LOW
+        sequence.append(TimingSegment(False, self.init_duration_ms))
+        sequence.append(TimingSegment(True, self.init_duration_ms))
+        sequence.append(TimingSegment(False, self.init_duration_ms))
+
+        return sequence
+
+    def encode_state_durations(self, bits: list[bool]) -> list[float]:
+        return [seg.duration_ms for seg in self.encode_timing_sequence(bits)]
+
+    def encode_level_durations(self, bits: list[bool]) -> list[tuple[bool, float]]:
+        return [
+            (seg.level, seg.duration_ms) for seg in self.encode_timing_sequence(bits)
+        ]
+
+    def get_total_duration(self, num_bits: int) -> float:
+        return 2 * self.init_sequence_ms + num_bits * self.bit_duration_ms
+
+    @property
+    def info(self) -> dict:
+        return {
+            "bit_duration_ms": self.bit_duration_ms,
+            "init_duration_ms": self.init_duration_ms,
+            "init_sequence_ms": self.init_sequence_ms,
+        }

ttl_barcoder/core/generator.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+import time
+from abc import ABC, abstractmethod
+
+import numpy as np
+
+from ttl_barcoder.core.config import (
+    PRECISION_UNITS_PER_SECOND,
+    BarcodeConfig,
+    TimestampPrecision,
+    TTLType,
+)
+
+
+class TTLGenerator(ABC):
+    """Abstract base for TTL barcode value generators."""
+
+    def __init__(self, barcode_bits: int) -> None:
+        self.barcode_bits = barcode_bits
+
+    @abstractmethod
+    def generate(self, timestamp: float | None = None) -> int:
+        """Generate a barcode value."""
+
+    def encode_bits(self, value: int) -> list[bool]:
+        """Encode barcode value as bit array (LSB first)."""
+        value = value % (2**self.barcode_bits)
+        return [bool((value >> i) & 1) for i in range(self.barcode_bits)]
+
+    @property
+    def max_value(self) -> int:
+        """Maximum possible barcode value."""
+        return (2**self.barcode_bits) - 1
+
+    @property
+    def info(self) -> dict:
+        return {"barcode_bits": self.barcode_bits, "max_value": self.max_value}
+
+
+class TimestampGenerator(TTLGenerator):
+    """Generate barcodes from Unix timestamps at configurable precision."""
+
+    def __init__(self, barcode_bits: int, precision: TimestampPrecision) -> None:
+        super().__init__(barcode_bits)
+        self.precision = precision
+        self._units_per_second: float = PRECISION_UNITS_PER_SECOND[precision]
+
+    def generate(self, timestamp: float | None = None) -> int:
+        """Generate barcode from timestamp (defaults to current time)."""
+        if timestamp is None:
+            timestamp = time.time()
+        units = int(timestamp * self._units_per_second)
+        return units % (2**self.barcode_bits)
+
+    def generate_sequence(
+        self,
+        count: int = 1,
+        interval_s: float = 5.0,
+        start_timestamp: float | None = None,
+    ) -> list[int]:
+        """Generate a sequence of barcodes at fixed time intervals."""
+        if start_timestamp is None:
+            start_timestamp = time.time()
+        return [self.generate(start_timestamp + i * interval_s) for i in range(count)]
+
+    def recover_timestamp(
+        self, barcode_value: int, reference_time: float | None = None
+    ) -> float:
+        """Recover timestamp from barcode value, resolving wraparound."""
+        if reference_time is None:
+            reference_time = time.time()
+        ref_units = int(reference_time * self._units_per_second)
+        window_size = 2**self.barcode_bits
+        window_number = ref_units // window_size
+        candidates = []
+        for w in (window_number - 1, window_number, window_number + 1):
+            candidate_units = w * window_size + barcode_value
+            candidate_time = candidate_units / self._units_per_second
+            candidates.append((abs(candidate_time - reference_time), candidate_time))
+        return min(candidates)[1]
+
+    @property
+    def coverage_seconds(self) -> float:
+        return (2**self.barcode_bits) / self._units_per_second
+
+    @property
+    def coverage_years(self) -> float:
+        return self.coverage_seconds / (365.25 * 24 * 3600)
+
+    @property
+    def info(self) -> dict:
+        return {
+            **super().info,
+            "type": "timestamp",
+            "precision": self.precision.value,
+            "units_per_second": self._units_per_second,
+            "coverage_years": self.coverage_years,
+        }
+
+
+class RandomGenerator(TTLGenerator):
+    """Generate random n-bit barcode values using numpy."""
+
+    def __init__(self, barcode_bits: int) -> None:
+        super().__init__(barcode_bits)
+        self._rng = np.random.default_rng()
+
+    def generate(self, timestamp: float | None = None) -> int:
+        """Generate a random barcode value."""
+        return int(self._rng.integers(0, 2**self.barcode_bits))
+
+    @property
+    def info(self) -> dict:
+        return {**super().info, "type": "random"}
+
+
+def create_generator(config: BarcodeConfig) -> TTLGenerator:
+    """Create TimestampGenerator or RandomGenerator from config."""
+    if config.ttl_type == TTLType.timestamp:
+        return TimestampGenerator(config.barcode_bits, config.timestamp_precision)
+    if config.ttl_type == TTLType.random:
+        return RandomGenerator(config.barcode_bits)
+    raise ValueError(f"Unknown TTL type: {config.ttl_type!r}")

ttl_barcoder/hardware/bpod/__init__.py

@@ -0,0 +1,3 @@
+from .sender import BARCODE_FIRST_STATE_NAME, BpodBarcodeSender, inject_barcode_states
+
+__all__ = ["BARCODE_FIRST_STATE_NAME", "BpodBarcodeSender", "inject_barcode_states"]

ttl_barcoder/hardware/bpod/sender.py

@@ -0,0 +1,50 @@
+from typing import Any
+
+try:
+    from pybpod import StateMachine
+
+    BPOD_AVAILABLE = True
+except ImportError:
+    StateMachine = None
+    BPOD_AVAILABLE = False
+
+BARCODE_FIRST_STATE_NAME = "barcode_start"
+
+
+def inject_barcode_states(
+    sma,
+    timing_sequence: list[tuple[bool, float]],
+    bnc_channel: Any,
+    first_state_name: str = BARCODE_FIRST_STATE_NAME,
+    last_state_name: str = "exit",
+):
+    """Inject barcode timing states into a pybpodapi StateMachine in-place."""
+    n = len(timing_sequence)
+    for i, (level, duration_ms) in enumerate(timing_sequence):
+        state_name = first_state_name if i == 0 else f"{first_state_name}_seg_{i}"
+        next_state = (
+            last_state_name if i == n - 1 else f"{first_state_name}_seg_{i + 1}"
+        )
+        sma.add_state(
+            state_name=state_name,
+            state_timer=duration_ms / 1000.0,
+            state_change_conditions={"Tup": next_state},
+            output_actions=[(bnc_channel, 1 if level else 0)],
+        )
+    return sma
+
+
+class BpodBarcodeSender:
+    """Stateful wrapper around inject_barcode_states for class-based workflows."""
+
+    def inject_states(
+        self,
+        sma,
+        timing_sequence: list[tuple[bool, float]],
+        bnc_channel: Any,
+        first_state_name: str = BARCODE_FIRST_STATE_NAME,
+        last_state_name: str = "exit",
+    ):
+        return inject_barcode_states(
+            sma, timing_sequence, bnc_channel, first_state_name, last_state_name
+        )

ttl_barcoder/hardware/pigpio/__init__.py

@@ -0,0 +1,3 @@
+from .sender import PigpioBarcodeSender, PigpioConnection, send_barcode_sequence
+
+__all__ = ["PigpioBarcodeSender", "PigpioConnection", "send_barcode_sequence"]

ttl_barcoder/hardware/pigpio/sender.py

@@ -0,0 +1,112 @@
+import time
+from typing import Any
+
+try:
+    import pigpio
+
+    PIGPIO_AVAILABLE = True
+except ImportError:
+    pigpio = None
+    PIGPIO_AVAILABLE = False
+
+
+class PigpioBarcodeSender:
+    """Prepares barcode pulses for pigpio without managing the connection."""
+
+    def __init__(self, pin: int = 18):
+        if not PIGPIO_AVAILABLE:
+            raise ImportError("pigpio not available. Install with: pip install pigpio")
+        self.pin = pin
+
+    def prepare_pulses(self, timing_sequence: list[tuple[bool, float]]) -> list[Any]:
+        """Convert (level, duration_ms) pairs to pigpio pulse objects."""
+        pulses = []
+        pin_mask = 1 << self.pin
+        for level, duration_ms in timing_sequence:
+            duration_us = int(duration_ms * 1000)
+            if level:
+                pulses.append(pigpio.pulse(pin_mask, 0, duration_us))
+            else:
+                pulses.append(pigpio.pulse(0, pin_mask, duration_us))
+        return pulses
+
+    def prepare_wave(self, timing_sequence: list[tuple[bool, float]]) -> int:
+        raise NotImplementedError("Use PigpioConnection.prepare_wave() instead")
+
+
+class PigpioConnection:
+    """Manages pigpio daemon connection and wave transmission."""
+
+    def __init__(self, pin: int = 18, host: str = "localhost", port: int = 8888):
+        if not PIGPIO_AVAILABLE:
+            raise ImportError("pigpio not available. Install with: pip install pigpio")
+        self.pin = pin
+        self.host = host
+        self.port = port
+        self.pi: Any = None
+        self.connected = False
+        self.sender = PigpioBarcodeSender(pin)
+
+    def connect(self) -> bool:
+        try:
+            self.pi = pigpio.pi(self.host, self.port)
+            if not self.pi.connected:
+                return False
+            self.pi.set_mode(self.pin, pigpio.OUTPUT)
+            self.pi.wave_tx_stop()
+            self.pi.wave_clear()
+            self.connected = True
+            return True
+        except Exception as e:
+            print(f"Failed to connect to pigpio daemon: {e}")
+            self.connected = False
+            return False
+
+    def send_sequence(self, timing_sequence: list[tuple[bool, float]]) -> bool:
+        """Send timing sequence via GPIO wave, blocking until complete."""
+        if not self.connected and not self.connect():
+            return False
+        try:
+            self.pi.wave_tx_stop()
+            self.pi.wave_clear()
+            pulses = self.sender.prepare_pulses(timing_sequence)
+            self.pi.wave_add_generic(pulses)
+            wid = self.pi.wave_create()
+            if wid >= 0:
+                self.pi.wave_send_once(wid)
+                while self.pi.wave_tx_busy():
+                    time.sleep(0.001)
+                self.pi.wave_delete(wid)
+                return True
+            else:
+                print("Failed to create pigpio wave")
+                return False
+        except Exception as e:
+            print(f"Failed to send sequence: {e}")
+            return False
+
+    def disconnect(self):
+        if self.pi is not None:
+            try:
+                self.pi.wave_tx_stop()
+                self.pi.wave_clear()
+                self.pi.stop()
+            except Exception:
+                pass
+            self.pi = None
+            self.connected = False
+
+    def __enter__(self):
+        self.connect()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.disconnect()
+
+
+def send_barcode_sequence(
+    timing_sequence: list[tuple[bool, float]], pin: int = 18
+) -> bool:
+    """Send a timing sequence via GPIO (convenience wrapper around PigpioConnection)."""
+    with PigpioConnection(pin) as gpio:
+        return gpio.send_sequence(timing_sequence)

ttl_barcoder-0.4.1.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,17 @@
+ttl_barcoder/__init__.py,sha256=KbookvXeQAyFUwv19dqFSzVJy1GPXNHEqxSpzHTZJKE,662
+ttl_barcoder/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ttl_barcoder/core/__init__.py,sha256=0wiD3l1-XO-UIgnvNZMOhtg4HFp9UJTF-ybS7T2EPLM,649
+ttl_barcoder/core/barcode_ttl.py,sha256=mQ3wx4nDvkygl2CTwjls_5Dqlm1So2gq-lm1iXN7AL8,4195
+ttl_barcoder/core/config.py,sha256=jpiYLA2ARPwtKy5yGommv7yPTze9RUPwFvXG6vF9OZk,4442
+ttl_barcoder/core/decoder.py,sha256=cvxyuKSvbHZMUqI2JraGMO7Um6r3ci50tezsYaF6IxA,2660
+ttl_barcoder/core/encoder.py,sha256=mWiuc1QfKNzmHiR9yUHldL_0R2-rjCz7BX9Q_Y6HWyE,2369
+ttl_barcoder/core/generator.py,sha256=5w1_4x8vOXjUJ7nF0WkLKqk5HplGJePK_5UkzDJJ2eM,4295
+ttl_barcoder/hardware/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ttl_barcoder/hardware/bpod/__init__.py,sha256=W9WnUbJO9wdeno4PYFzlSKRkHaVBoV0tiZzyT8qLpsQ,173
+ttl_barcoder/hardware/bpod/sender.py,sha256=AtVq9TDel3-P-cRR1fHY4eUj1R3-iBZ-QPDmidmDS1Y,1494
+ttl_barcoder/hardware/pigpio/__init__.py,sha256=j0CxEFA-38CrmBHTxVwYJ6ZD63v4DSUd_q2rkbmeuxM,161
+ttl_barcoder/hardware/pigpio/sender.py,sha256=JZ0S-aNFDWk6mq1CaXj-QuVzVlPpTQvL7Ele6pYop5I,3717
+ttl_barcoder-0.4.1.dist-info/METADATA,sha256=zXx7rGzTelAADAA1JiK1ylUKFjNC1qcTGTjQOw8nkls,5828
+ttl_barcoder-0.4.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+ttl_barcoder-0.4.1.dist-info/licenses/LICENSE,sha256=C65BqnvorE42oDpFOq6DByL3mR_Xq9rQlecMPiuvIfM,1522
+ttl_barcoder-0.4.1.dist-info/RECORD,,

ttl_barcoder-0.4.1.dist-info/WHEEL

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

ttl_barcoder-0.4.1.dist-info/licenses/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.