flexitac 0.2.2__tar.gz → 0.3.1__tar.gz

{flexitac-0.2.2/flexitac.egg-info → flexitac-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flexitac
-Version: 0.2.2
+Version: 0.3.1
 Summary: Python runtime and flashing tools for FlexiTac tactile sensors
 Author-email: Wesley Maa <wesley.maa@gmail.com>
 License-Expression: MIT
@@ -22,7 +22,7 @@ Requires-Dist: flexitac[dev]; extra == "all"
 Requires-Dist: flexitac[examples]; extra == "all"
 Dynamic: license-file
 
-# flexitac
+# PyFlexiTac
 
 Python interface for [FlexiTac](https://flexitac.github.io/) tactile sensors.
 Allows you to easily [flash](#flexitac-flash) Arduino firmware and read framed sensor data over serial.
@@ -30,6 +30,10 @@ Allows you to easily [flash](#flexitac-flash) Arduino firmware and read framed s
 Defaults target the standard FlexiTac 12x32 sensor (12 rows wired to mux
 channels 4-15). Override `--rows`, `--cols`, and `--mux-offset` for variants.
 
+Serial port permissions apply to both flashing and reading. If you hit
+`Permission denied` with either `flexitac-flash` or read tools like
+`flexitac-stream`/`flexitac-heatmap`, see the note in [`flexitac-flash`](#flexitac-flash).
+
 ## Install
 
 ```bash
@@ -142,6 +146,24 @@ flexitac-flash --rows 16 --cols 32 --mux-offset 0
 flexitac-flash --port /dev/ttyUSB0 --fqbn arduino:avr:uno
 ```
 
+If flashing fails with a serial `Permission denied` error:
+
+- On Linux, add your user to the serial group, then re-login:
+
+  ```bash
+  sudo usermod -aG dialout "$USER"
+  ```
+
+- On macOS, permissions are usually managed automatically, but if needed you can
+  grant temporary read/write access to the device (replace with your actual port):
+
+  ```bash
+  sudo chmod a+rw /dev/tty.usbmodem*
+  ```
+
+As a last-resort fallback, you can run `sudo chmod 666 /dev/tty...`,
+but this is overly permissive.
+
 Defaults: `rows=12`, `cols=32`, `baud=2000000`, `mux-offset=4` (standard
 FlexiTac 12x32 sensor wired to mux channels 4-15). The firmware is generated
 from `flexitac/firmware/template.ino` by substituting `ROW_COUNT`,
@@ -162,3 +184,23 @@ make format         # ruff format + autofix
 make static-checks  # ruff + mypy
 make test           # pytest
 ```
+
+## Citation
+
+If you use this software in research or publications, please cite the repository.
+On GitHub, use **Cite this repository**.
+
+```bibtex
+@misc{maa_pyflexitac_2026,
+  author = {Maa, Wesley},
+  title = {{PyFlexiTac}: Python runtime and flashing tools for FlexiTac tactile sensors},
+  year = {2026},
+  howpublished = {\url{https://github.com/WT-MM/PyFlexiTac}},
+  note = {Version 0.3.1},
+}
+```
+
+## Acknowledgments
+
+- [Binghao Huang](https://binghao-huang.github.io/), for the Arduino firmware template this project's firmware is derived from.
+- [Naian Tao](https://tna001-ai.github.io/), for leading the [LeFlexiTac](https://tna001-ai.github.io/tactile-lerobot-website/) project that motivated this code.

{flexitac-0.2.2 → flexitac-0.3.1}/README.md

@@ -1,4 +1,4 @@
-# flexitac
+# PyFlexiTac
 
 Python interface for [FlexiTac](https://flexitac.github.io/) tactile sensors.
 Allows you to easily [flash](#flexitac-flash) Arduino firmware and read framed sensor data over serial.
@@ -6,6 +6,10 @@ Allows you to easily [flash](#flexitac-flash) Arduino firmware and read framed s
 Defaults target the standard FlexiTac 12x32 sensor (12 rows wired to mux
 channels 4-15). Override `--rows`, `--cols`, and `--mux-offset` for variants.
 
+Serial port permissions apply to both flashing and reading. If you hit
+`Permission denied` with either `flexitac-flash` or read tools like
+`flexitac-stream`/`flexitac-heatmap`, see the note in [`flexitac-flash`](#flexitac-flash).
+
 ## Install
 
 ```bash
@@ -118,6 +122,24 @@ flexitac-flash --rows 16 --cols 32 --mux-offset 0
 flexitac-flash --port /dev/ttyUSB0 --fqbn arduino:avr:uno
 ```
 
+If flashing fails with a serial `Permission denied` error:
+
+- On Linux, add your user to the serial group, then re-login:
+
+  ```bash
+  sudo usermod -aG dialout "$USER"
+  ```
+
+- On macOS, permissions are usually managed automatically, but if needed you can
+  grant temporary read/write access to the device (replace with your actual port):
+
+  ```bash
+  sudo chmod a+rw /dev/tty.usbmodem*
+  ```
+
+As a last-resort fallback, you can run `sudo chmod 666 /dev/tty...`,
+but this is overly permissive.
+
 Defaults: `rows=12`, `cols=32`, `baud=2000000`, `mux-offset=4` (standard
 FlexiTac 12x32 sensor wired to mux channels 4-15). The firmware is generated
 from `flexitac/firmware/template.ino` by substituting `ROW_COUNT`,
@@ -138,3 +160,23 @@ make format         # ruff format + autofix
 make static-checks  # ruff + mypy
 make test           # pytest
 ```
+
+## Citation
+
+If you use this software in research or publications, please cite the repository.
+On GitHub, use **Cite this repository**.
+
+```bibtex
+@misc{maa_pyflexitac_2026,
+  author = {Maa, Wesley},
+  title = {{PyFlexiTac}: Python runtime and flashing tools for FlexiTac tactile sensors},
+  year = {2026},
+  howpublished = {\url{https://github.com/WT-MM/PyFlexiTac}},
+  note = {Version 0.3.1},
+}
+```
+
+## Acknowledgments
+
+- [Binghao Huang](https://binghao-huang.github.io/), for the Arduino firmware template this project's firmware is derived from.
+- [Naian Tao](https://tna001-ai.github.io/), for leading the [LeFlexiTac](https://tna001-ai.github.io/tactile-lerobot-website/) project that motivated this code.

{flexitac-0.2.2 → flexitac-0.3.1}/flexitac/__init__.py

@@ -3,4 +3,4 @@
 from flexitac.sensor import FlexiTacFrame, FlexiTacSensor
 
 __all__ = ["FlexiTacFrame", "FlexiTacSensor"]
-__version__ = "0.2.2"
+__version__ = "0.3.1"

{flexitac-0.2.2 → flexitac-0.3.1}/flexitac/flash.py

@@ -61,6 +61,15 @@ def detect_board() -> tuple[str, str]:
     raise FlashError(f"multiple boards detected; pass --port and --fqbn:\n{listing}")
 
 
+def _require_arduino_cli() -> None:
+    if shutil.which("arduino-cli") is None:
+        raise FlashError(
+            "arduino-cli not found on PATH. Install it (e.g. `brew install arduino-cli`) and run "
+            "`arduino-cli core install arduino:avr`. See "
+            "https://arduino.github.io/arduino-cli/latest/installation/"
+        )
+
+
 def flash(
     *,
     port: str,
@@ -72,10 +81,7 @@ def flash(
     verbose: bool = False,
 ) -> None:
     """Render firmware and upload it to ``port``."""
-    if shutil.which("arduino-cli") is None:
-        raise FlashError(
-            "arduino-cli not found on PATH. Install from https://arduino.github.io/arduino-cli/latest/installation/"
-        )
+    _require_arduino_cli()
 
     rendered = render_template(rows=rows, cols=cols, baud=baud, mux_offset=mux_offset)
     with tempfile.TemporaryDirectory(prefix="flexitac-") as tmp:
@@ -93,7 +99,7 @@ def _run(cmd: list[str], *, verbose: bool = False, capture: bool = False) -> sub
     except FileNotFoundError as exc:
         raise FlashError(f"command not found: {cmd[0]}") from exc
     if result.returncode != 0:
-        msg = (result.stderr or result.stdout or "").strip()
+        msg = (result.stderr or result.stdout or "").strip() or "(see output above)"
         raise FlashError(f"{' '.join(cmd)} failed: {msg}")
     return result
 
@@ -118,12 +124,7 @@ def main(argv: list[str] | None = None) -> int:
     logger = configure_logging(verbose=args.verbose)
 
     try:
-        if shutil.which("arduino-cli") is None:
-            raise FlashError(
-                "arduino-cli not found on PATH. Install it (e.g. `brew install arduino-cli`) and run "
-                "`arduino-cli core install arduino:avr`. See "
-                "https://arduino.github.io/arduino-cli/latest/installation/"
-            )
+        _require_arduino_cli()
 
         port, fqbn = args.port, args.fqbn
         if port is None or fqbn is None:

{flexitac-0.2.2 → flexitac-0.3.1}/flexitac/sensor.py

@@ -40,7 +40,27 @@ class FlexiTacSensor:
         noise_scale: float = 30.0,
         init_frames: int = 30,
         read_timeout_s: float = 5.0,
+        baseline: NDArray[np.float32] | float | None = None,
     ) -> None:
+        """Initialize a FlexiTac sensor.
+
+        Args:
+            port: Serial device path (e.g. ``/dev/ttyUSB0``).
+            rows: Number of tactile rows (default 12).
+            cols: Number of tactile columns (default 32).
+            baud: Serial baud rate matching the flashed firmware (default 2_000_000).
+            threshold: Contact-detection threshold in ADC counts above baseline.
+            noise_scale: Divisor used to normalize readings below ``threshold``.
+            init_frames: Number of frames sampled during ``calibrate()`` (default 30).
+                Higher values give a more robust baseline at the cost of startup time.
+            read_timeout_s: Maximum time ``read()`` will wait for a full frame.
+            baseline: If provided, skips auto-calibration on first ``read()``. Pass a
+                ``(rows, cols)`` array of per-pixel baselines, or a scalar applied to
+                every pixel. Typical resting ADC values land around 10-40 for an
+                unloaded sensor, so a scalar like ``20.0`` is a reasonable default
+                when you can't afford the startup delay of a full calibration. For
+                accurate contact detection, prefer letting ``calibrate()`` run.
+        """
         self.port = port
         self.rows = rows
         self.cols = cols
@@ -56,6 +76,9 @@ class FlexiTacSensor:
         self._baseline: NDArray[np.float32] | None = None
         self._seq = 0
 
+        if baseline is not None:
+            self._baseline = np.broadcast_to(np.float32(baseline), (rows, cols)).copy()
+
     def open(self) -> FlexiTacSensor:
         """Open the serial port if not already open."""
         if self._serial is None or not self._serial.is_open:
@@ -126,16 +149,24 @@ class FlexiTacSensor:
 
     def _latest_buffered_frame(self) -> NDArray[np.uint8] | None:
         latest: NDArray[np.uint8] | None = None
-        while True:
-            idx = self._buf.find(MARKER)
-            if idx < 0 or len(self._buf) - idx - 2 < self._frame_bytes:
-                break
-            del self._buf[: idx + 2]
-            payload = bytes(self._buf[: self._frame_bytes])
-            del self._buf[: self._frame_bytes]
-            latest = np.frombuffer(payload, dtype=np.uint8).reshape(self.rows, self.cols).copy()
+        while (frame := self._pop_frame()) is not None:
+            latest = frame
         return latest
 
+    def _pop_frame(self) -> NDArray[np.uint8] | None:
+        """Extract one frame from ``self._buf``; trim leading garbage if no marker."""
+        idx = self._buf.find(MARKER)
+        if idx < 0:
+            if len(self._buf) > 1:
+                del self._buf[:-1]
+            return None
+        if len(self._buf) - idx - 2 < self._frame_bytes:
+            return None
+        del self._buf[: idx + 2]
+        payload = bytes(self._buf[: self._frame_bytes])
+        del self._buf[: self._frame_bytes]
+        return np.frombuffer(payload, dtype=np.uint8).reshape(self.rows, self.cols).copy()
+
     def _normalize(self, raw: NDArray[np.uint8]) -> NDArray[np.float32]:
         assert self._baseline is not None
         signal = raw.astype(np.float32) - self._baseline - self.threshold
@@ -158,18 +189,8 @@ class FlexiTacSensor:
                 if len(self._buf) > 50_000:
                     del self._buf[: len(self._buf) - 50_000]
 
-            idx = self._buf.find(MARKER)
-            if idx < 0:
-                if len(self._buf) > 1:
-                    del self._buf[:-1]
-                continue
-
-            if len(self._buf) - idx - 2 < self._frame_bytes:
-                continue
-
-            del self._buf[: idx + 2]
-            payload = bytes(self._buf[: self._frame_bytes])
-            del self._buf[: self._frame_bytes]
-            return np.frombuffer(payload, dtype=np.uint8).reshape(self.rows, self.cols).copy()
+            frame = self._pop_frame()
+            if frame is not None:
+                return frame
 
         raise TimeoutError(f"timed out after {self.read_timeout_s:.2f}s waiting for a frame")

{flexitac-0.2.2 → flexitac-0.3.1/flexitac.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flexitac
-Version: 0.2.2
+Version: 0.3.1
 Summary: Python runtime and flashing tools for FlexiTac tactile sensors
 Author-email: Wesley Maa <wesley.maa@gmail.com>
 License-Expression: MIT
@@ -22,7 +22,7 @@ Requires-Dist: flexitac[dev]; extra == "all"
 Requires-Dist: flexitac[examples]; extra == "all"
 Dynamic: license-file
 
-# flexitac
+# PyFlexiTac
 
 Python interface for [FlexiTac](https://flexitac.github.io/) tactile sensors.
 Allows you to easily [flash](#flexitac-flash) Arduino firmware and read framed sensor data over serial.
@@ -30,6 +30,10 @@ Allows you to easily [flash](#flexitac-flash) Arduino firmware and read framed s
 Defaults target the standard FlexiTac 12x32 sensor (12 rows wired to mux
 channels 4-15). Override `--rows`, `--cols`, and `--mux-offset` for variants.
 
+Serial port permissions apply to both flashing and reading. If you hit
+`Permission denied` with either `flexitac-flash` or read tools like
+`flexitac-stream`/`flexitac-heatmap`, see the note in [`flexitac-flash`](#flexitac-flash).
+
 ## Install
 
 ```bash
@@ -142,6 +146,24 @@ flexitac-flash --rows 16 --cols 32 --mux-offset 0
 flexitac-flash --port /dev/ttyUSB0 --fqbn arduino:avr:uno
 ```
 
+If flashing fails with a serial `Permission denied` error:
+
+- On Linux, add your user to the serial group, then re-login:
+
+  ```bash
+  sudo usermod -aG dialout "$USER"
+  ```
+
+- On macOS, permissions are usually managed automatically, but if needed you can
+  grant temporary read/write access to the device (replace with your actual port):
+
+  ```bash
+  sudo chmod a+rw /dev/tty.usbmodem*
+  ```
+
+As a last-resort fallback, you can run `sudo chmod 666 /dev/tty...`,
+but this is overly permissive.
+
 Defaults: `rows=12`, `cols=32`, `baud=2000000`, `mux-offset=4` (standard
 FlexiTac 12x32 sensor wired to mux channels 4-15). The firmware is generated
 from `flexitac/firmware/template.ino` by substituting `ROW_COUNT`,
@@ -162,3 +184,23 @@ make format         # ruff format + autofix
 make static-checks  # ruff + mypy
 make test           # pytest
 ```
+
+## Citation
+
+If you use this software in research or publications, please cite the repository.
+On GitHub, use **Cite this repository**.
+
+```bibtex
+@misc{maa_pyflexitac_2026,
+  author = {Maa, Wesley},
+  title = {{PyFlexiTac}: Python runtime and flashing tools for FlexiTac tactile sensors},
+  year = {2026},
+  howpublished = {\url{https://github.com/WT-MM/PyFlexiTac}},
+  note = {Version 0.3.1},
+}
+```
+
+## Acknowledgments
+
+- [Binghao Huang](https://binghao-huang.github.io/), for the Arduino firmware template this project's firmware is derived from.
+- [Naian Tao](https://tna001-ai.github.io/), for leading the [LeFlexiTac](https://tna001-ai.github.io/tactile-lerobot-website/) project that motivated this code.