vention-barcode-scanner 0.1.0__tar.gz

vention_barcode_scanner-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+# Node / Nx
+node_modules/
+dist/
+.nx/
+tmp/
+coverage/
+
+# Python / uv
+.venv/
+**/.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Editor / OS
+.DS_Store
+*.log
+
+# Claude Code (local, per-developer)
+.claude/

vention_barcode_scanner-0.1.0/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: vention-barcode-scanner
+Version: 0.1.0
+Summary: Async barcode scanner fleet manager for Vention industrial automation. Supports Keyence TCP, USB evdev, and mock scanners.
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+# vention-barcode-scanner
+
+Async barcode scanner fleet manager for Vention industrial automation. Unified `Scanner` ABC over Keyence TCP, USB HID (evdev), and mock backends.
+
+## Scanner Types
+
+| Type | Protocol | Platform | Use Case |
+|------|----------|----------|----------|
+| `KeyenceScanner` | Async TCP (port 9004) | Any | Keyence SR-series (SR-1000, SR-2000, SR-5000) |
+| `EvdevScanner` | Linux USB (evdev) | Linux | USB keyboard-emulating barcode readers |
+| `MockScanner` | In-memory | Any | Simulation and testing |
+
+## Usage
+
+```python
+from barcode_scanner.models import ScannerConfig, ScannerFleetConfig
+from barcode_scanner.service import ScannerService
+
+config = ScannerFleetConfig(
+    scanners=[
+        ScannerConfig(id="s1", host="192.168.7.100", location_id="station-a"),
+        ScannerConfig(id="s2", host="192.168.7.101", location_id="station-b"),
+    ],
+)
+service = ScannerService.from_config(config, mode="real", scanner_type="keyence")
+
+await service.connect_all()
+result = await service.scan("station-a")
+await service.disconnect_all()
+
+result.status          # ScanStatus.OK | NO_READ | TIMEOUT | ERROR
+result.label_detected  # True / False
+result.label_string    # "GT-205" or None
+```
+
+### Label Validation
+
+Optional callback to reject invalid labels at the scanner layer:
+
+```python
+def validate_label(label: str) -> bool:
+    return label.startswith("GT-") and len(label) <= 20
+
+service = ScannerService.from_config(config, label_validator=validate_label)
+# Labels that fail validation are downgraded to NO_READ
+```
+
+### Metrics
+
+```python
+metrics = service.get_metrics()["s1"]
+metrics.total_scans      # 1234
+metrics.success_rate     # 0.89
+metrics.avg_scan_ms      # 45.2
+```
+
+### Tuning and Diagnostics
+
+```python
+await service.auto_tune("station-a")           # One-shot FTUNE + SAVE
+await service.tune("station-a", bank=0)         # Interactive TUNE per bank + TQUIT
+status = await service.get_scanner_status("station-a")
+# {"busy": 0, "last_cmd": 0, "error": 0}       # BUSYSTAT / CMDSTAT / ERRSTAT
+```
+
+### Structured Logging
+
+```python
+from barcode_scanner.logger import set_log_callback
+
+def on_scanner_log(code, source, level, message):
+    mqtt_publish("scanner/logs", {"code": code, "source": source, "message": message})
+
+set_log_callback(on_scanner_log)
+```
+
+## Keyence Protocol
+
+TCP port 9004. ASCII commands terminated with `\r`.
+
+**Scan sequence:** `LON\r` (open scan window) -> dwell -> `LOFF\r` (close window) -> read response. The scanner only sends data after LOFF.
+
+| Command | Response | Purpose |
+|---------|----------|---------|
+| `LON\r` | barcode or `ERROR\r` | Open scan window (default bank) |
+| `LON,01\r` | barcode or `ERROR\r` | Open scan window (bank 1) |
+| `LOFF\r` | -- | Close scan window |
+| `BCLR\r` | `OK\r` | Clear read buffer |
+| `RESET\r` | `OK\r` | Reset scanner (reboots, drops TCP) |
+| `FTUNE\r` | `OK,FTUNE\r` then result | One-shot auto-focus calibration |
+| `TUNE,00\r` | `OK\r` | Start interactive tuning (bank 0) |
+| `TQUIT\r` | `OK\r` | Stop tuning and save |
+| `SAVE\r` | `OK\r` | Persist settings across power cycles |
+| `BUSYSTAT\r` | `0`/`1`/`2` | Query busy state (idle/reading/tuning) |
+| `CMDSTAT\r` | `0`/`1`/`2` | Query last command result |
+| `ERRSTAT\r` | `0`/`1`/`2` | Query hardware error state |
+
+## API
+
+### ScannerService
+
+```python
+class ScannerService:
+    @classmethod
+    def from_config(cls, config, mode="real", scanner_type="keyence",
+                    label_validator=None) -> ScannerService
+
+    async def scan(self, location_id, timeout=None, bank=None) -> ScanResult
+    async def connect_all(self) -> dict[str, bool]
+    async def disconnect_all(self) -> None
+    async def reset(self, location_id) -> bool
+    async def reset_all(self) -> dict[str, bool]
+    async def auto_tune(self, location_id) -> bool
+    async def tune(self, location_id, bank=0) -> bool
+    async def get_scanner_status(self, location_id) -> dict
+    def get_metrics(self) -> dict[str, ScanMetrics]
+    def get_metrics_summary(self) -> dict
+```
+
+### ScanResult
+
+```python
+class ScanResult:
+    status: ScanStatus          # OK | NO_READ | TIMEOUT | ERROR
+    label_detected: bool
+    label_string: str | None
+    scanner_id: str
+    error: str | None
+```
+
+### Scanner ABC
+
+```python
+class Scanner(ABC):
+    async def scan(self, timeout=None, bank=None) -> ScanResult
+    async def connect(self) -> bool
+    async def disconnect(self) -> None
+    async def reset(self) -> bool
+    async def auto_tune(self) -> bool
+    async def tune(self, bank=0) -> bool
+    async def get_status(self) -> dict
+    connected: bool  # property
+```
+
+## Development
+
+```bash
+cd barcode-scanner
+uv sync
+make test          # 115 tests
+make lint          # ruff check + format
+make type-check    # pyright
+```

vention_barcode_scanner-0.1.0/README.md

@@ -0,0 +1,153 @@
+# vention-barcode-scanner
+
+Async barcode scanner fleet manager for Vention industrial automation. Unified `Scanner` ABC over Keyence TCP, USB HID (evdev), and mock backends.
+
+## Scanner Types
+
+| Type | Protocol | Platform | Use Case |
+|------|----------|----------|----------|
+| `KeyenceScanner` | Async TCP (port 9004) | Any | Keyence SR-series (SR-1000, SR-2000, SR-5000) |
+| `EvdevScanner` | Linux USB (evdev) | Linux | USB keyboard-emulating barcode readers |
+| `MockScanner` | In-memory | Any | Simulation and testing |
+
+## Usage
+
+```python
+from barcode_scanner.models import ScannerConfig, ScannerFleetConfig
+from barcode_scanner.service import ScannerService
+
+config = ScannerFleetConfig(
+    scanners=[
+        ScannerConfig(id="s1", host="192.168.7.100", location_id="station-a"),
+        ScannerConfig(id="s2", host="192.168.7.101", location_id="station-b"),
+    ],
+)
+service = ScannerService.from_config(config, mode="real", scanner_type="keyence")
+
+await service.connect_all()
+result = await service.scan("station-a")
+await service.disconnect_all()
+
+result.status          # ScanStatus.OK | NO_READ | TIMEOUT | ERROR
+result.label_detected  # True / False
+result.label_string    # "GT-205" or None
+```
+
+### Label Validation
+
+Optional callback to reject invalid labels at the scanner layer:
+
+```python
+def validate_label(label: str) -> bool:
+    return label.startswith("GT-") and len(label) <= 20
+
+service = ScannerService.from_config(config, label_validator=validate_label)
+# Labels that fail validation are downgraded to NO_READ
+```
+
+### Metrics
+
+```python
+metrics = service.get_metrics()["s1"]
+metrics.total_scans      # 1234
+metrics.success_rate     # 0.89
+metrics.avg_scan_ms      # 45.2
+```
+
+### Tuning and Diagnostics
+
+```python
+await service.auto_tune("station-a")           # One-shot FTUNE + SAVE
+await service.tune("station-a", bank=0)         # Interactive TUNE per bank + TQUIT
+status = await service.get_scanner_status("station-a")
+# {"busy": 0, "last_cmd": 0, "error": 0}       # BUSYSTAT / CMDSTAT / ERRSTAT
+```
+
+### Structured Logging
+
+```python
+from barcode_scanner.logger import set_log_callback
+
+def on_scanner_log(code, source, level, message):
+    mqtt_publish("scanner/logs", {"code": code, "source": source, "message": message})
+
+set_log_callback(on_scanner_log)
+```
+
+## Keyence Protocol
+
+TCP port 9004. ASCII commands terminated with `\r`.
+
+**Scan sequence:** `LON\r` (open scan window) -> dwell -> `LOFF\r` (close window) -> read response. The scanner only sends data after LOFF.
+
+| Command | Response | Purpose |
+|---------|----------|---------|
+| `LON\r` | barcode or `ERROR\r` | Open scan window (default bank) |
+| `LON,01\r` | barcode or `ERROR\r` | Open scan window (bank 1) |
+| `LOFF\r` | -- | Close scan window |
+| `BCLR\r` | `OK\r` | Clear read buffer |
+| `RESET\r` | `OK\r` | Reset scanner (reboots, drops TCP) |
+| `FTUNE\r` | `OK,FTUNE\r` then result | One-shot auto-focus calibration |
+| `TUNE,00\r` | `OK\r` | Start interactive tuning (bank 0) |
+| `TQUIT\r` | `OK\r` | Stop tuning and save |
+| `SAVE\r` | `OK\r` | Persist settings across power cycles |
+| `BUSYSTAT\r` | `0`/`1`/`2` | Query busy state (idle/reading/tuning) |
+| `CMDSTAT\r` | `0`/`1`/`2` | Query last command result |
+| `ERRSTAT\r` | `0`/`1`/`2` | Query hardware error state |
+
+## API
+
+### ScannerService
+
+```python
+class ScannerService:
+    @classmethod
+    def from_config(cls, config, mode="real", scanner_type="keyence",
+                    label_validator=None) -> ScannerService
+
+    async def scan(self, location_id, timeout=None, bank=None) -> ScanResult
+    async def connect_all(self) -> dict[str, bool]
+    async def disconnect_all(self) -> None
+    async def reset(self, location_id) -> bool
+    async def reset_all(self) -> dict[str, bool]
+    async def auto_tune(self, location_id) -> bool
+    async def tune(self, location_id, bank=0) -> bool
+    async def get_scanner_status(self, location_id) -> dict
+    def get_metrics(self) -> dict[str, ScanMetrics]
+    def get_metrics_summary(self) -> dict
+```
+
+### ScanResult
+
+```python
+class ScanResult:
+    status: ScanStatus          # OK | NO_READ | TIMEOUT | ERROR
+    label_detected: bool
+    label_string: str | None
+    scanner_id: str
+    error: str | None
+```
+
+### Scanner ABC
+
+```python
+class Scanner(ABC):
+    async def scan(self, timeout=None, bank=None) -> ScanResult
+    async def connect(self) -> bool
+    async def disconnect(self) -> None
+    async def reset(self) -> bool
+    async def auto_tune(self) -> bool
+    async def tune(self, bank=0) -> bool
+    async def get_status(self) -> dict
+    connected: bool  # property
+```
+
+## Development
+
+```bash
+cd barcode-scanner
+uv sync
+make test          # 115 tests
+make lint          # ruff check + format
+make type-check    # pyright
+```

vention_barcode_scanner-0.1.0/config/config.local.yaml.example

@@ -0,0 +1,17 @@
+# Local development overrides for barcode scanner service
+# Copy to config.local.yaml and customize for your environment.
+# This file is gitignored and will not be committed.
+#
+# Only include values you want to override — everything else
+# falls through to config.yaml defaults.
+
+# Force mock mode for local development (no hardware needed)
+scanner_type: "mock"
+
+# Increase mock label probability for easier testing
+mock_label_probability: 0.5
+mock_labels: ["LABEL-001", "LABEL-002", "LABEL-003", "LABEL-EMPTY"]
+
+# Override fleet with localhost scanners (for Keyence simulator testing)
+# fleet:
+#   - { id: "scanner-1", host: "127.0.0.1", port: 9004, location_id: "station-1" }

vention_barcode_scanner-0.1.0/config/config.yaml

@@ -0,0 +1,25 @@
+# vention-barcode-scanner — Example Fleet Configuration
+#
+# Each scanner needs a unique ID, its IP address,
+# and a location_id that the host application uses to trigger scans.
+#
+# Local overrides: config/config.local.yaml (gitignored)
+
+scanner_type: "keyence"
+
+default_timeout: 2.0
+reconnect_delay: 5.0
+max_reconnect_attempts: 0  # 0 = unlimited
+max_scan_retries: 2
+scan_retry_delay: 0.3
+keepalive_interval: 10.0  # BCLR ping every 10s to detect dead TCP connections
+
+mock_label_probability: 0.3
+mock_labels: ["LABEL-001", "LABEL-002", "LABEL-003"]
+
+fleet:
+  - { id: "scanner-1", host: "192.168.1.100", port: 9004, location_id: "zone-a" }
+  - { id: "scanner-2", host: "192.168.1.101", port: 9004, location_id: "zone-b" }
+
+  # Disabled scanner (skipped during fleet init)
+  # - { id: "scanner-3", host: "192.168.1.102", port: 9004, location_id: "zone-c", enabled: false }

vention_barcode_scanner-0.1.0/docs/planning/current-state.md

@@ -0,0 +1,28 @@
+# Current state — barcode-scanner
+
+What's actually built in `barcode-scanner` **now** — the fastest orientation for
+a new dev or agent. Read this first. Distinct from siblings:
+
+- **Repo-wide state** — [`../../../../docs/planning/current-state.md`](../../../../docs/planning/current-state.md).
+- `backlog.md` / `open-questions.md` / `tech-debt.md` — seeded here if/when this
+  lib has its own; it has none today (no empty stubs).
+
+It **grows by pruning, not accretion** — superseded state is rewritten, not
+appended. Last updated: 2026-06-03.
+
+## What's working
+
+- Async **scanner fleet manager** — a `Scanner` ABC + `KeyenceScanner` (TCP),
+  `EvdevScanner` (USB, Linux), `MockScanner`, behind `ScannerService`
+  (location-id → scanner). Config loader, log codes, structured logger.
+- **118 tests, 86% coverage**, ruff clean. Lifted from The Feed; unchanged in
+  behavior.
+- `evdev` is Linux/USB-only (omitted from coverage; exercised on CI).
+
+## Recently landed
+
+- 2026-06-02 — lifted into delivery-products as `scope:device`; `pytest-cov` wired.
+
+<!-- No backlog.md: no open lib-specific work. Repo-wide CI coverage gate
+     (≥80%) is tracked in ../../../../docs/planning/backlog.md — barcode-scanner
+     is at 86%. -->

vention_barcode_scanner-0.1.0/project.json

@@ -0,0 +1,30 @@
+{
+  "name": "barcode-scanner",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "projectType": "library",
+  "sourceRoot": "libs/barcode-scanner/src",
+  "tags": ["scope:device", "type:backend"],
+  "release": {
+    "version": { "generator": "@nxlv/python:release-version" }
+  },
+  "targets": {
+    "nx-release-publish": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "bash tools/publish-codeartifact.sh --projectRoot={projectRoot} --dryRun={args.dryRun}"
+      }
+    },
+    "lint": {
+      "executor": "nx:run-commands",
+      "options": { "command": "uv run ruff check .", "cwd": "libs/barcode-scanner" }
+    },
+    "test": {
+      "executor": "nx:run-commands",
+      "options": { "command": "uv run pytest -q --cov=barcode_scanner --cov-report=term-missing", "cwd": "libs/barcode-scanner" }
+    },
+    "check": {
+      "executor": "nx:run-commands",
+      "options": { "command": "uv run python -c \"import barcode_scanner\"", "cwd": "libs/barcode-scanner" }
+    }
+  }
+}

vention_barcode_scanner-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "vention-barcode-scanner"
+version = "0.1.0"
+description = "Async barcode scanner fleet manager for Vention industrial automation. Supports Keyence TCP, USB evdev, and mock scanners."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "pydantic>=2.0",
+    "pyyaml>=6.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/barcode_scanner"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3.4",
+    "pytest-asyncio>=0.24.0",
+    "pytest-cov>=5.0",
+    "ruff>=0.8.0",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.coverage.run]
+source = ["barcode_scanner"]
+omit = [
+    "src/barcode_scanner/__main__.py",  # CLI dev tool, not library code
+    "src/barcode_scanner/scanners/evdev.py",  # Linux-only, tested on CI
+]
+
+[tool.coverage.report]
+show_missing = true
+# CI coverage gate (backlog item, now wired): a device lib asserts full coverage,
+# so a drop below 80% fails the build. Currently ≈86%. The `test` target collects
+# coverage and CI runs it (affected + the Python matrix), so fail_under is enforced.
+fail_under = 80

vention_barcode_scanner-0.1.0/src/barcode_scanner/__init__.py

@@ -0,0 +1,8 @@
+"""Vention barcode scanner library.
+
+Unified async abstraction over different barcode scanner hardware.
+This is a library, not a service — no HTTP server, no separate process.
+Host applications import it and call service.scan(location_id) in-process.
+
+Supports Keyence (TCP), Evdev (USB), and Mock scanner types.
+"""