ttl-barcoder 0.4.1__tar.gz → 0.4.2__tar.gz

{ttl_barcoder-0.4.1 → ttl_barcoder-0.4.2}/.gitignore

@@ -29,3 +29,5 @@ env/
 .idea/
 .vscode/
 .DS_Store
+site/
+uv.lock

ttl_barcoder-0.4.2/LICENSE

@@ -0,0 +1,31 @@
+Copyright (c) 2024-present Lars B. Rollik. All rights reserved.
+
+Permission is granted, free of charge, to use, copy, modify, and distribute
+this software and associated documentation files (the "Software") for
+non-commercial research or academic purposes only, subject to the following
+conditions:
+
+1. This copyright notice and permission notice must be included in all copies
+   or substantial portions of the Software.
+
+2. Any publication, presentation, or product that uses or builds upon the
+   Software must give clear attribution to the original work and its authors.
+
+3. Commercial use is prohibited without a separate written commercial licence
+   agreement with the copyright holder. Commercial use means incorporation of
+   the Software into anything for which fees or other compensation are charged
+   or received, including commercial products and commercial services.
+
+4. No patent licence, express or implied, is granted under these terms. Any
+   use that would require a patent licence from the copyright holder requires
+   a separate written agreement.
+
+5. Redistribution, in source or binary form, is permitted only for
+   non-commercial purposes and must retain this notice unmodified.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED. IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM,
+DAMAGES, OR OTHER LIABILITY ARISING FROM, OUT OF, OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR DEALINGS IN THE SOFTWARE.
+
+For commercial or patent licensing enquiries contact: lars@rollik.me

{ttl_barcoder-0.4.1 → ttl_barcoder-0.4.2}/PKG-INFO

@@ -1,17 +1,47 @@
 Metadata-Version: 2.4
 Name: ttl-barcoder
-Version: 0.4.1
+Version: 0.4.2
 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
+Author-email: "Lars B. Rollik" <lars@rollik.me>
+License: Copyright (c) 2024-present Lars B. Rollik. All rights reserved.
+        
+        Permission is granted, free of charge, to use, copy, modify, and distribute
+        this software and associated documentation files (the "Software") for
+        non-commercial research or academic purposes only, subject to the following
+        conditions:
+        
+        1. This copyright notice and permission notice must be included in all copies
+           or substantial portions of the Software.
+        
+        2. Any publication, presentation, or product that uses or builds upon the
+           Software must give clear attribution to the original work and its authors.
+        
+        3. Commercial use is prohibited without a separate written commercial licence
+           agreement with the copyright holder. Commercial use means incorporation of
+           the Software into anything for which fees or other compensation are charged
+           or received, including commercial products and commercial services.
+        
+        4. No patent licence, express or implied, is granted under these terms. Any
+           use that would require a patent licence from the copyright holder requires
+           a separate written agreement.
+        
+        5. Redistribution, in source or binary form, is permitted only for
+           non-commercial purposes and must retain this notice unmodified.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED. IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM,
+        DAMAGES, OR OTHER LIABILITY ARISING FROM, OUT OF, OR IN CONNECTION WITH THE
+        SOFTWARE OR THE USE OR DEALINGS IN THE SOFTWARE.
+        
+        For commercial or patent licensing enquiries contact: lars@rollik.me
 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: License :: Free for non-commercial use
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
@@ -34,6 +64,7 @@ Requires-Dist: pytest-cov; extra == 'dev'
 Requires-Dist: ruff; extra == 'dev'
 Provides-Extra: docs
 Requires-Dist: mkdocs-material; extra == 'docs'
+Requires-Dist: mkdocstrings[python]; extra == 'docs'
 Provides-Extra: pigpio
 Requires-Dist: pigpio>=1.78; extra == 'pigpio'
 Description-Content-Type: text/markdown
@@ -43,6 +74,8 @@ Description-Content-Type: text/markdown
 [![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.
+
+**[→ Full documentation](https://murineshiftwork.github.io/ttl-barcoder)**
 Barcodes encode a timestamp or random value as a sequence of timed HIGH/LOW pulses, transmittable over any digital output.
 
 

{ttl_barcoder-0.4.1 → ttl_barcoder-0.4.2}/README.md

@@ -3,6 +3,8 @@
 [![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.
+
+**[→ Full documentation](https://murineshiftwork.github.io/ttl-barcoder)**
 Barcodes encode a timestamp or random value as a sequence of timed HIGH/LOW pulses, transmittable over any digital output.
 
 

ttl_barcoder-0.4.2/VERSION

@@ -0,0 +1 @@
+0.4.2

{ttl_barcoder-0.4.1 → ttl_barcoder-0.4.2}/pyproject.toml

@@ -6,11 +6,11 @@ build-backend = "hatchling.build"
 name = "ttl-barcoder"
 dynamic = ["version"]
 authors = [
-    { name = "Lars B. Rollik", email = "L.B.Rollik@protonmail.com" }
+    { name = "Lars B. Rollik", email = "lars@rollik.me" }
 ]
 description = "Modular barcode generation for TTL synchronization with clean hardware separation"
 readme = "README.md"
-license = {text = "BSD-3-Clause"}
+license = { file = "LICENSE" }
 requires-python = ">=3.10"
 keywords = [
     "ttl", "barcode", "synchronization", "daq",
@@ -19,7 +19,7 @@ keywords = [
 classifiers = [
     "Development Status :: 4 - Beta",
     "Intended Audience :: Science/Research",
-    "License :: OSI Approved :: BSD License",
+    "License :: Free for non-commercial use",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.10",
@@ -47,6 +47,7 @@ dev = [
 ]
 docs = [
     "mkdocs-material",
+    "mkdocstrings[python]",
 ]
 
 [project.urls]
@@ -78,7 +79,7 @@ include = ["/src/ttl_barcoder", "/tests", "/examples", "/README.md", "/LICENSE",
 [tool.commitizen]
 name = "cz_conventional_commits"
 version_provider = "commitizen"
-version = "0.4.1"
+version = "0.4.2"
 tag_format = "v$version"
 update_changelog_on_bump = false
 version_files = ["VERSION"]

{ttl_barcoder-0.4.1 → ttl_barcoder-0.4.2}/src/ttl_barcoder/core/barcode_ttl.py

@@ -11,7 +11,11 @@ from ttl_barcoder.core.generator import (
 
 
 class BarcodeTTL:
-    """Main interface for TTL barcode generation and decoding."""
+    """Main interface for TTL barcode generation and decoding.
+
+    Constructs and owns a generator, encoder, and decoder whose parameters
+    are all derived from a single BarcodeConfig so they stay in sync.
+    """
 
     def __init__(self, config: BarcodeConfig | None = None) -> None:
         self.config = config or BarcodeConfig.default()
@@ -60,6 +64,11 @@ class BarcodeTTL:
         interval_s: float = 5.0,
         start_timestamp: float | None = None,
     ) -> list[list[tuple[bool, float]]]:
+        """Return timing sequences for multiple barcodes spaced interval_s apart.
+
+        For timestamp TTL the barcodes encode evenly spaced future times;
+        for random TTL each barcode is independently random.
+        """
         if self.config.ttl_type == TTLType.timestamp:
             assert isinstance(self.generator, TimestampGenerator)
             barcodes = self.generator.generate_sequence(
@@ -90,10 +99,12 @@ class BarcodeTTL:
 
     @classmethod
     def default_config(cls) -> BarcodeConfig:
+        """Return the default BarcodeConfig instance."""
         return BarcodeConfig.default()
 
     @property
     def info(self) -> dict:
+        """Return a summary dict covering config, generator, and encoder parameters."""
         return {
             "config": self.config.info(),
             "generator": self.generator.info,

{ttl_barcoder-0.4.1 → ttl_barcoder-0.4.2}/src/ttl_barcoder/core/decoder.py

@@ -2,7 +2,11 @@ import numpy as np
 
 
 class BarcodeDecoder:
-    """Decode edge timestamps back to barcode values."""
+    """Decode edge timestamps back to barcode values.
+
+    Must be constructed with parameters that match the encoder that produced
+    the signal. Use BarcodeConfig to keep encoder and decoder in sync.
+    """
 
     def __init__(
         self,
@@ -44,7 +48,7 @@ class BarcodeDecoder:
         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
+        # 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:
@@ -58,6 +62,7 @@ class BarcodeDecoder:
     def _decode_bits(
         self, data_times: list[float], data_levels: list[bool]
     ) -> list[int]:
+        """Sample each bit by majority level at the mid-point of its time slot."""
         bits = []
         current_level = False
         edge_idx = 0

{ttl_barcoder-0.4.1 → ttl_barcoder-0.4.2}/src/ttl_barcoder/core/encoder.py

@@ -17,6 +17,11 @@ class TimingEncoder:
         self.init_sequence_ms = 3 * init_duration_ms
 
     def encode_timing_sequence(self, bits: list[bool]) -> list[TimingSegment]:
+        """Encode bits into a full timing sequence including preamble and trailer.
+
+        The preamble is HIGH-LOW-HIGH so the first rising edge is always
+        detectable even when the output line idles LOW between trials.
+        """
         sequence = []
 
         # Start initialization: HIGH-LOW-HIGH
@@ -40,14 +45,17 @@ class TimingEncoder:
         return sequence
 
     def encode_state_durations(self, bits: list[bool]) -> list[float]:
+        """Return only the duration_ms values from the timing sequence (no levels)."""
         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 (level, duration_ms) pairs suitable for hardware drivers."""
         return [
             (seg.level, seg.duration_ms) for seg in self.encode_timing_sequence(bits)
         ]
 
     def get_total_duration(self, num_bits: int) -> float:
+        """Return total transmission duration in milliseconds for a given bit count."""
         return 2 * self.init_sequence_ms + num_bits * self.bit_duration_ms
 
     @property

{ttl_barcoder-0.4.1 → ttl_barcoder-0.4.2}/src/ttl_barcoder/core/generator.py

@@ -59,7 +59,7 @@ class TimestampGenerator(TTLGenerator):
         interval_s: float = 5.0,
         start_timestamp: float | None = None,
     ) -> list[int]:
-        """Generate a sequence of barcodes at fixed time intervals."""
+        """Generate count barcodes spaced interval_s seconds apart."""
         if start_timestamp is None:
             start_timestamp = time.time()
         return [self.generate(start_timestamp + i * interval_s) for i in range(count)]
@@ -67,7 +67,11 @@ class TimestampGenerator(TTLGenerator):
     def recover_timestamp(
         self, barcode_value: int, reference_time: float | None = None
     ) -> float:
-        """Recover timestamp from barcode value, resolving wraparound."""
+        """Recover Unix timestamp from a barcode value, resolving modular wraparound.
+
+        Checks the previous, current, and next bit-width windows relative to
+        reference_time and returns the candidate closest to the reference.
+        """
         if reference_time is None:
             reference_time = time.time()
         ref_units = int(reference_time * self._units_per_second)

{ttl_barcoder-0.4.1 → ttl_barcoder-0.4.2}/src/ttl_barcoder/hardware/bpod/sender.py

@@ -45,6 +45,7 @@ class BpodBarcodeSender:
         first_state_name: str = BARCODE_FIRST_STATE_NAME,
         last_state_name: str = "exit",
     ):
+        """Inject barcode states into sma; delegates to inject_barcode_states."""
         return inject_barcode_states(
             sma, timing_sequence, bnc_channel, first_state_name, last_state_name
         )

{ttl_barcoder-0.4.1 → ttl_barcoder-0.4.2}/src/ttl_barcoder/hardware/pigpio/sender.py

@@ -48,6 +48,7 @@ class PigpioConnection:
         self.sender = PigpioBarcodeSender(pin)
 
     def connect(self) -> bool:
+        """Connect to the pigpio daemon and configure the output pin."""
         try:
             self.pi = pigpio.pi(self.host, self.port)
             if not self.pi.connected:
@@ -86,6 +87,7 @@ class PigpioConnection:
             return False
 
     def disconnect(self):
+        """Stop any active wave and close the connection to the pigpio daemon."""
         if self.pi is not None:
             try:
                 self.pi.wave_tx_stop()

{ttl_barcoder-0.4.1 → ttl_barcoder-0.4.2}/tests/test_barcode_ttl.py

@@ -1,4 +1,4 @@
-"""Tests for BarcodeTTL — the main public interface."""
+"""Tests for BarcodeTTL: the main public interface."""
 
 from __future__ import annotations
 

{ttl_barcoder-0.4.1 → ttl_barcoder-0.4.2}/tests/test_bpod.py

@@ -1,4 +1,4 @@
-"""Tests for Bpod barcode injection — no pybpod installation required."""
+"""Tests for Bpod barcode injection: no pybpod installation required."""
 
 from __future__ import annotations
 

{ttl_barcoder-0.4.1 → ttl_barcoder-0.4.2}/tests/test_decoder.py

@@ -1,4 +1,4 @@
-"""Tests for BarcodeDecoder — roundtrip and edge-case handling."""
+"""Tests for BarcodeDecoder: roundtrip and edge-case handling."""
 
 from __future__ import annotations
 

{ttl_barcoder-0.4.1 → ttl_barcoder-0.4.2}/tests/test_encoder.py

@@ -1,4 +1,4 @@
-"""Tests for TimingEncoder — sequence structure and timing."""
+"""Tests for TimingEncoder: sequence structure and timing."""
 
 from __future__ import annotations
 

ttl_barcoder-0.4.1/LICENSE

@@ -1,29 +0,0 @@
-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/VERSION

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