flexitac 0.2.0__tar.gz

flexitac-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wesley Maa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

flexitac-0.2.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: flexitac
+Version: 0.2.0
+Summary: Python runtime and flashing tools for FlexiTac tactile sensors
+Author-email: Wesley Maa <wesley.maa@gmail.com>
+License-Expression: MIT
+Project-URL: Repository, https://github.com/WT-MM/PyFlexiTac.git
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: pyserial
+Provides-Extra: dev
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: matplotlib-stubs; extra == "dev"
+Provides-Extra: examples
+Requires-Dist: matplotlib; extra == "examples"
+Provides-Extra: all
+Requires-Dist: flexitac[dev]; extra == "all"
+Requires-Dist: flexitac[examples]; extra == "all"
+Dynamic: license-file
+
+# flexitac
+
+Python interface for [FlexiTac](https://flexitac.github.io/) tactile sensors:
+flash Arduino firmware, then read framed sensor data over serial.
+
+Defaults target the standard FlexiTac 12x32 sensor (12 rows wired to mux
+channels 4-15). Override `--rows`, `--cols`, and `--mux-offset` for variants.
+
+## Install
+
+```bash
+# recommended
+uv sync            # core deps only
+uv sync --extra examples  # include matplotlib for the heatmap CLI
+uv sync --extra dev       # dev tooling (ruff, mypy, pytest)
+
+# or with pip
+pip install flexitac
+pip install 'flexitac[examples]'  # include matplotlib
+```
+
+## Reading frames
+
+```python
+from flexitac import FlexiTacSensor
+
+with FlexiTacSensor("/dev/ttyUSB0") as sensor:  # rows=12, cols=32 by default
+    for frame in sensor:
+        print(frame.normalized.shape, frame.normalized.max())
+```
+
+`sensor.read()` returns a `FlexiTacFrame(seq, timestamp_s, raw, normalized)`.
+The first read auto-calibrates by collecting `init_frames` (default 30) and
+storing the per-pixel median as the baseline. Call `sensor.calibrate()` to
+recalibrate.
+
+## CLI tools
+
+All CLI commands are installed as entry points:
+
+```bash
+flexitac-stream  --port /dev/ttyUSB0               # stream frames & print stats
+flexitac-heatmap --port /dev/ttyUSB0               # live matplotlib heatmap
+flexitac-flash                                      # flash firmware (auto-detects board)
+flexitac-find-port                                  # identify sensor port by unplug
+
+# with uv (no install needed)
+uv run flexitac-stream  --port /dev/ttyUSB0
+uv run flexitac-heatmap --port /dev/ttyUSB0
+```
+
+### `flexitac-stream`
+
+Stream frames and print FPS / signal stats:
+
+```bash
+flexitac-stream --port /dev/ttyUSB0 --frames 30
+```
+
+```
+frame=    10 fps=  85.3 raw_max=104 norm_max=0.000
+frame=    20 fps=  87.1 raw_max=109 norm_max=0.123
+```
+
+What to check:
+
+- **`fps`** stabilizes near your expected rate (~100+ fps for a 12x32 sensor
+  at 2 Mbps). If it's 0 or you get `TimeoutError`, the firmware isn't sending
+  framed data -- confirm `--rows`/`--cols`/`--baud` match what you flashed.
+- **`raw_max`** is in `[0, 255]` and changes when you press the sensor.
+  A flat 0 or flat 255 indicates a wiring issue, not a flashing issue.
+- **`norm_max`** rises toward 1.0 under contact and stays near 0 at rest.
+
+### `flexitac-heatmap`
+
+Live heatmap visualization (requires `matplotlib` -- install with the `examples` extra):
+
+```bash
+flexitac-heatmap --port /dev/ttyUSB0
+```
+
+Press the sensor pad -- bright spots should track your touch.
+
+### `flexitac-find-port`
+
+Not sure which `/dev/tty*` your sensor is on? Run:
+
+```bash
+flexitac-find-port
+```
+
+It snapshots ports, asks you to unplug the sensor, then reports whichever port
+disappeared.
+
+### `flexitac-flash`
+
+Requires [`arduino-cli`](https://arduino.github.io/arduino-cli/latest/installation/).
+First-time setup:
+
+```bash
+brew install arduino-cli
+# or use the upstream install script:
+curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | sh
+
+# then install the Arduino AVR core
+arduino-cli core update-index
+arduino-cli core install arduino:avr  # AVR core for Uno/Nano/Mega/etc.
+```
+
+```bash
+# auto-detects the port + FQBN if exactly one Arduino is plugged in
+flexitac-flash
+
+# override geometry / wiring for non-standard sensors
+flexitac-flash --rows 16 --cols 32 --mux-offset 0
+
+# if unable to autodetect, pass --port and --fqbn explicitly:
+flexitac-flash --port /dev/ttyUSB0 --fqbn arduino:avr:uno
+```
+
+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`,
+`COLUMN_COUNT`, `BAUD_RATE`, and `MUX_CHANNEL_OFFSET`. To customize pin
+assignments, edit the template directly.
+
+## Wire protocol
+
+Each frame: marker `0xAA 0x55` followed by `rows * cols` uint8 ADC samples,
+streamed continuously at the configured baud rate.
+
+## Development
+
+```bash
+uv sync --extra dev
+
+make format         # ruff format + autofix
+make static-checks  # ruff + mypy
+make test           # pytest
+```

flexitac-0.2.0/README.md

@@ -0,0 +1,140 @@
+# flexitac
+
+Python interface for [FlexiTac](https://flexitac.github.io/) tactile sensors:
+flash Arduino firmware, then read framed sensor data over serial.
+
+Defaults target the standard FlexiTac 12x32 sensor (12 rows wired to mux
+channels 4-15). Override `--rows`, `--cols`, and `--mux-offset` for variants.
+
+## Install
+
+```bash
+# recommended
+uv sync            # core deps only
+uv sync --extra examples  # include matplotlib for the heatmap CLI
+uv sync --extra dev       # dev tooling (ruff, mypy, pytest)
+
+# or with pip
+pip install flexitac
+pip install 'flexitac[examples]'  # include matplotlib
+```
+
+## Reading frames
+
+```python
+from flexitac import FlexiTacSensor
+
+with FlexiTacSensor("/dev/ttyUSB0") as sensor:  # rows=12, cols=32 by default
+    for frame in sensor:
+        print(frame.normalized.shape, frame.normalized.max())
+```
+
+`sensor.read()` returns a `FlexiTacFrame(seq, timestamp_s, raw, normalized)`.
+The first read auto-calibrates by collecting `init_frames` (default 30) and
+storing the per-pixel median as the baseline. Call `sensor.calibrate()` to
+recalibrate.
+
+## CLI tools
+
+All CLI commands are installed as entry points:
+
+```bash
+flexitac-stream  --port /dev/ttyUSB0               # stream frames & print stats
+flexitac-heatmap --port /dev/ttyUSB0               # live matplotlib heatmap
+flexitac-flash                                      # flash firmware (auto-detects board)
+flexitac-find-port                                  # identify sensor port by unplug
+
+# with uv (no install needed)
+uv run flexitac-stream  --port /dev/ttyUSB0
+uv run flexitac-heatmap --port /dev/ttyUSB0
+```
+
+### `flexitac-stream`
+
+Stream frames and print FPS / signal stats:
+
+```bash
+flexitac-stream --port /dev/ttyUSB0 --frames 30
+```
+
+```
+frame=    10 fps=  85.3 raw_max=104 norm_max=0.000
+frame=    20 fps=  87.1 raw_max=109 norm_max=0.123
+```
+
+What to check:
+
+- **`fps`** stabilizes near your expected rate (~100+ fps for a 12x32 sensor
+  at 2 Mbps). If it's 0 or you get `TimeoutError`, the firmware isn't sending
+  framed data -- confirm `--rows`/`--cols`/`--baud` match what you flashed.
+- **`raw_max`** is in `[0, 255]` and changes when you press the sensor.
+  A flat 0 or flat 255 indicates a wiring issue, not a flashing issue.
+- **`norm_max`** rises toward 1.0 under contact and stays near 0 at rest.
+
+### `flexitac-heatmap`
+
+Live heatmap visualization (requires `matplotlib` -- install with the `examples` extra):
+
+```bash
+flexitac-heatmap --port /dev/ttyUSB0
+```
+
+Press the sensor pad -- bright spots should track your touch.
+
+### `flexitac-find-port`
+
+Not sure which `/dev/tty*` your sensor is on? Run:
+
+```bash
+flexitac-find-port
+```
+
+It snapshots ports, asks you to unplug the sensor, then reports whichever port
+disappeared.
+
+### `flexitac-flash`
+
+Requires [`arduino-cli`](https://arduino.github.io/arduino-cli/latest/installation/).
+First-time setup:
+
+```bash
+brew install arduino-cli
+# or use the upstream install script:
+curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | sh
+
+# then install the Arduino AVR core
+arduino-cli core update-index
+arduino-cli core install arduino:avr  # AVR core for Uno/Nano/Mega/etc.
+```
+
+```bash
+# auto-detects the port + FQBN if exactly one Arduino is plugged in
+flexitac-flash
+
+# override geometry / wiring for non-standard sensors
+flexitac-flash --rows 16 --cols 32 --mux-offset 0
+
+# if unable to autodetect, pass --port and --fqbn explicitly:
+flexitac-flash --port /dev/ttyUSB0 --fqbn arduino:avr:uno
+```
+
+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`,
+`COLUMN_COUNT`, `BAUD_RATE`, and `MUX_CHANNEL_OFFSET`. To customize pin
+assignments, edit the template directly.
+
+## Wire protocol
+
+Each frame: marker `0xAA 0x55` followed by `rows * cols` uint8 ADC samples,
+streamed continuously at the configured baud rate.
+
+## Development
+
+```bash
+uv sync --extra dev
+
+make format         # ruff format + autofix
+make static-checks  # ruff + mypy
+make test           # pytest
+```

flexitac-0.2.0/examples/__init__.py

@@ -0,0 +1 @@
+"""Example scripts for FlexiTac sensors, installable as CLI entry points."""

flexitac-0.2.0/examples/stream_frames.py

@@ -0,0 +1,47 @@
+"""Stream FlexiTac frames and print FPS / signal stats."""
+
+from __future__ import annotations
+
+import argparse
+import time
+
+from flexitac import FlexiTacSensor
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Stream FlexiTac frames.")
+    parser.add_argument("--port", required=True)
+    parser.add_argument("--rows", type=int, default=12)
+    parser.add_argument("--cols", type=int, default=32)
+    parser.add_argument("--baud", type=int, default=2_000_000)
+    parser.add_argument("--frames", type=int, default=0, help="0 = run forever")
+    parser.add_argument(
+        "--per-row",
+        action="store_true",
+        help="Print per-row raw mean / baseline (useful when some rows look dead)",
+    )
+    args = parser.parse_args()
+
+    started = time.monotonic()
+    with FlexiTacSensor(args.port, rows=args.rows, cols=args.cols, baud=args.baud) as sensor:
+        sensor.calibrate()
+        if args.per_row:
+            assert sensor.baseline is not None
+            print("baseline per row:", [round(float(v), 1) for v in sensor.baseline.mean(axis=1)])
+
+        for i, frame in enumerate(sensor, start=1):
+            fps = i / max(time.monotonic() - started, 1e-6)
+            print(
+                f"frame={i:6d} fps={fps:6.1f} raw_max={int(frame.raw.max()):3d} "
+                f"norm_max={float(frame.normalized.max()):.3f}"
+            )
+            if args.per_row and i % 20 == 0:
+                row_max = frame.raw.max(axis=1)
+                print("  raw_max per row:", [int(v) for v in row_max])
+            if args.frames and i >= args.frames:
+                break
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

flexitac-0.2.0/examples/visualize_heatmap.py

@@ -0,0 +1,61 @@
+"""Live heatmap of FlexiTac normalized frames using matplotlib."""
+
+from __future__ import annotations
+
+import argparse
+import time
+
+import matplotlib
+import numpy as np
+
+from flexitac import FlexiTacSensor
+
+for _backend in ("TkAgg", "Qt5Agg", "MacOSX"):
+    try:
+        matplotlib.use(_backend)
+        break
+    except Exception:  # noqa: BLE001
+        continue
+
+from matplotlib import animation, pyplot as plt  # noqa: E402
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Live FlexiTac heatmap.")
+    parser.add_argument("--port", required=True)
+    parser.add_argument("--rows", type=int, default=12)
+    parser.add_argument("--cols", type=int, default=32)
+    parser.add_argument("--baud", type=int, default=2_000_000)
+    parser.add_argument("--cmap", default="viridis")
+    args = parser.parse_args()
+
+    sensor = FlexiTacSensor(args.port, rows=args.rows, cols=args.cols, baud=args.baud).open()
+    sensor.calibrate()
+
+    fig, ax = plt.subplots(figsize=(8, 4.5))
+    im = ax.imshow(np.zeros((args.rows, args.cols), dtype=np.float32), cmap=args.cmap, vmin=0.0, vmax=1.0)
+    fig.colorbar(im, ax=ax, fraction=0.046, pad=0.04)
+    title = ax.set_title("FlexiTac")
+
+    started = time.monotonic()
+    count = 0
+
+    def update(_: int) -> list:
+        nonlocal count
+        frame = sensor.read_latest()
+        count += 1
+        im.set_data(frame.normalized)
+        fps = count / max(time.monotonic() - started, 1e-6)
+        title.set_text(f"FlexiTac | seq={frame.seq} fps={fps:.1f}")
+        return [im, title]
+
+    _anim = animation.FuncAnimation(fig, update, interval=16, blit=True, cache_frame_data=False)
+    try:
+        plt.show()
+    finally:
+        sensor.close()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

flexitac-0.2.0/flexitac/__init__.py

@@ -0,0 +1,6 @@
+"""Public package interface for flexitac."""
+
+from flexitac.sensor import FlexiTacFrame, FlexiTacSensor
+
+__all__ = ["FlexiTacFrame", "FlexiTacSensor"]
+__version__ = "0.2.0"

flexitac-0.2.0/flexitac/find_port.py

@@ -0,0 +1,55 @@
+"""Identify the FlexiTac serial port by snapshotting before/after unplug."""
+
+from __future__ import annotations
+
+import platform
+import time
+from pathlib import Path
+
+from serial.tools import list_ports
+
+from flexitac.logging_utils import configure_logging
+
+
+def list_serial_ports() -> set[str]:
+    """Return currently available serial port device paths."""
+    if platform.system() == "Windows":
+        return {port.device for port in list_ports.comports()}
+    return {str(path) for path in Path("/dev").glob("tty*")}
+
+
+def find_port(*, settle_s: float = 0.5) -> str:
+    """Prompt the user to unplug their sensor and return the port that vanished."""
+    logger = configure_logging(verbose=False)
+
+    before = list_serial_ports()
+    logger.info("Detected %d serial ports.", len(before))
+    input("Unplug the FlexiTac USB cable, then press Enter... ")
+
+    time.sleep(settle_s)
+    after = list_serial_ports()
+    diff = sorted(before - after)
+
+    if len(diff) == 1:
+        port = diff[0]
+        logger.info("FlexiTac port: %s", port)
+        logger.info("Reconnect the USB cable.")
+        return port
+    if not diff:
+        raise OSError("No port disappeared. Make sure you actually unplugged the device.")
+    raise OSError(f"Multiple ports disappeared: {diff}. Unplug only the FlexiTac.")
+
+
+def main(argv: list[str] | None = None) -> int:
+    """CLI entrypoint for ``flexitac-find-port``."""
+    del argv
+    try:
+        find_port()
+        return 0
+    except OSError as exc:
+        configure_logging(verbose=False).error("%s", exc)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

flexitac-0.2.0/flexitac/firmware/__init__.py

@@ -0,0 +1 @@
+"""Firmware helpers for template rendering and profile metadata."""

flexitac-0.2.0/flexitac/firmware/template.ino

@@ -0,0 +1,116 @@
+#define BAUD_RATE                 2000000
+#define ROW_COUNT                 12
+#define COLUMN_COUNT              32
+
+#define PIN_ADC_INPUT             A0
+#define PIN_SHIFT_REGISTER_DATA   2
+#define PIN_SHIFT_REGISTER_CLOCK  3
+#define PIN_MUX_CHANNEL_0         4
+#define PIN_MUX_CHANNEL_1         5
+#define PIN_MUX_CHANNEL_2         6
+#define PIN_MUX_CHANNEL_3         7
+#define PIN_MUX_INHIBIT_0         8
+#define PIN_MUX_INHIBIT_1         9
+
+#define START_MARKER_0            0xAA
+#define START_MARKER_1            0x55
+
+#define SET_SR_DATA_HIGH()        PORTD|=B00000100
+#define SET_SR_DATA_LOW()         PORTD&=~B00000100
+#define SET_SR_CLK_HIGH()         PORTD|=B00001000
+#define SET_SR_CLK_LOW()          PORTD&=~B00001000
+
+#define ROWS_PER_MUX              16
+#define MUX_COUNT                 1
+#define CHANNEL_PINS_PER_MUX      4
+#define MUX_CHANNEL_OFFSET        4
+
+#ifndef cbi
+#define cbi(sfr, bit) (_SFR_BYTE(sfr) &= ~_BV(bit))
+#endif
+#ifndef sbi
+#define sbi(sfr, bit) (_SFR_BYTE(sfr) |= _BV(bit))
+#endif
+
+int current_enabled_mux = MUX_COUNT - 1;
+
+void setup()
+{
+  Serial.begin(BAUD_RATE);
+  pinMode(PIN_ADC_INPUT, INPUT);
+  pinMode(PIN_SHIFT_REGISTER_DATA, OUTPUT);
+  pinMode(PIN_SHIFT_REGISTER_CLOCK, OUTPUT);
+  pinMode(PIN_MUX_CHANNEL_0, OUTPUT);
+  pinMode(PIN_MUX_CHANNEL_1, OUTPUT);
+  pinMode(PIN_MUX_CHANNEL_2, OUTPUT);
+  pinMode(PIN_MUX_CHANNEL_3, OUTPUT);
+  pinMode(PIN_MUX_INHIBIT_0, OUTPUT);
+  pinMode(PIN_MUX_INHIBIT_1, OUTPUT);
+
+  sbi(ADCSRA, ADPS2);
+  cbi(ADCSRA, ADPS1);
+  cbi(ADCSRA, ADPS0);
+}
+
+void loop()
+{
+  Serial.write(START_MARKER_0);
+  Serial.write(START_MARKER_1);
+
+  for (int i = 0; i < ROW_COUNT; i++)
+  {
+    setRow(i);
+    shiftColumn(true);
+    shiftColumn(false);
+
+    for (int j = 0; j < COLUMN_COUNT; j++)
+    {
+      int raw_reading = analogRead(PIN_ADC_INPUT);
+      byte send_reading = (byte)(raw_reading >> 2);
+
+      Serial.write(send_reading);
+      shiftColumn(false);
+    }
+  }
+}
+
+void setRow(int row_number)
+{
+  if ((row_number % ROWS_PER_MUX) == 0)
+  {
+    digitalWrite(PIN_MUX_INHIBIT_0 + current_enabled_mux, HIGH);
+    current_enabled_mux++;
+    if (current_enabled_mux >= MUX_COUNT)
+    {
+      current_enabled_mux = 0;
+    }
+    digitalWrite(PIN_MUX_INHIBIT_0 + current_enabled_mux, LOW);
+  }
+
+  int mux_channel = row_number + MUX_CHANNEL_OFFSET;
+  for (int i = 0; i < CHANNEL_PINS_PER_MUX; i++)
+  {
+    if (bitRead(mux_channel, i))
+    {
+      digitalWrite(PIN_MUX_CHANNEL_0 + i, HIGH);
+    }
+    else
+    {
+      digitalWrite(PIN_MUX_CHANNEL_0 + i, LOW);
+    }
+  }
+}
+
+void shiftColumn(boolean is_first)
+{
+  if (is_first)
+  {
+    SET_SR_DATA_HIGH();
+  }
+  SET_SR_CLK_HIGH();
+  SET_SR_CLK_LOW();
+  if (is_first)
+  {
+    SET_SR_DATA_LOW();
+  }
+}