diff --git a/TallyFlow/Integration/TallyFlow IoT Multi-Reader Benefits.md b/TallyFlow/Integration/TallyFlow IoT Multi-Reader Benefits.md new file mode 100644 index 0000000..11ca31e --- /dev/null +++ b/TallyFlow/Integration/TallyFlow IoT Multi-Reader Benefits.md @@ -0,0 +1,244 @@ +# TallyFlow IoT Multi-Reader Benefits + +**Status:** Customer talking points +**Date:** 2026-07-13 +**Audience:** Prospects with multiple fixed RFID readers (e.g. Impinj) per site + +## Elevator pitch (2 sentences) + +TallyFlow sits at each site and turns several readers into one clean tag feed. You get health, start/stop, and local visibility without building and maintaining that plumbing yourself. + +## Problem it solves + +Customers often ask why they should not call reader APIs (e.g. Impinj) directly. That works for a single reader in a lab. With **several fixed readers per site**, they still need: + +- Fan-in from many readers to one place +- A stable event shape for downstream systems (different readers have different event shapes) +- A path out to apps and reports (spreadsheet, API, or message bus) +- Day-2 ops: is the dock reading? restart inventory? which reader is down? + +Downstream systems consume data; they do not control readers. Something has to sit in the middle either way. TallyFlow IoT is that site edge layer. + +## Architecture story + +```text +[Fixed readers × N per site] + ↓ +[TallyFlow IoT edge] ← ops UI, start/stop, health + ↓ + Spreadsheet (CSV) / REST / AMQP (TallyFlow) / … + ↓ +[Downstream systems] +``` + +## Benefits of TallyFlow IoT + +General product strengths—useful even when the conversation is not only about multi-reader fan-in. + +### 1. Written in Rust for reliable operation + +- Built for long-running edge use: memory safety, strong performance, low overhead +- Async design handles many readers and streams without a heavyweight runtime stack +- Suited to unattended site deployments where restarts and flaky processes cost real downtime + +### 2. Multi-platform support + +- Runs on **Windows**, **Linux**, and **macOS** +- Windows Service install for production servers +- Same config model across platforms so IT is not locked to one OS per site + +### 3. Multi-vendor and multi-device + +- Fixed RFID: Impinj, Zebra, ATID (and growing) +- Barcode: SNAPI, Aurora where needed +- Remote/virtual readers for mobile and scripts +- One ops surface instead of a tool per brand + +### 4. Real-time visibility and control + +- Web UI for reader health, recent tags, and start/stop +- REST API for integration and automation +- Heartbeats and status so problems show up before the warehouse calls + +### 5. Flexible integration (processors) + +- Spreadsheet (CSV), REST, AMQP → TallyFlow out of the box +- Extensible processor model for site-specific paths +- Database and other sinks via apps (or future processors) without rewriting reader drivers + +### 6. Production-minded edge footprint + +- Local binary/service—works when cloud links are slow or down +- Optional on-site logging for audit and recovery +- Light resource needs relative to full app-server stacks + +### 7. Part of the wider TallyFlow story + +- Same family as mobile, print, and cloud workflows when the customer grows past fixed readers alone +- Clean handoff into TallyFlow via AMQP when they want Core/cloud, not only local files + +## Benefits vs managing readers directly + +### 1. One integration per site, not one per reader + +Direct vendor APIs mean N hostnames, logins, inventory presets, streams, reconnects, and firmware quirks. TallyFlow configures all readers in one place and runs one service per site. + +### 2. Clean, consistent tag data + +Events are normalized to a simple model: reader name, antenna, EPC, TID, RSSI, time, direction. Downstream tools do not have to parse vendor-specific stream formats. + +### 3. Unified data can go to a spreadsheet + +TallyFlow IoT’s CSV logger writes the combined feed from all readers into spreadsheet-friendly files: + +- One file (or folder of files) per site instead of N reader streams +- Easy pilot path before investing in heavier integration +- Familiar format for ops, QA, and light analysis + +### 4. Flexible handoff to other systems + +When a spreadsheet is not enough, TallyFlow can also export via: + +| Path | Status | Typical use | +| --------------------- | ----------------------------------- | ------------------------------------------------------------ | +| **CSV / spreadsheet** | Built into IoT (`logger`) | File or folder drop (simplest) | +| REST API | Built into IoT (`rest_api`) | Middleware, custom apps, automation (`/tags`, stream, etc.) | +| AMQP → TallyFlow | Built into IoT (`tallyflow`) | Cloud / Core path | +| **Database** | Via app, not a native IoT processor | App consumes REST (or AMQP later) and writes SQL/SQLite/etc. | +| MQTT export | Not shipped | Future processor candidate; same JSON shape as REST. | + +**Database path (today):** We do **not** write customer databases from TallyFlow IoT itself. Pattern in production: a site app talks to IoT over REST and persists what the customer needs. + +- Example: Alice+Olivia console (`alice_olivia_console`) connects to TallyFlow IoT REST, handles warehouse workflow, and stores box/EPC state in **local SQLite**. +- Sell as: “unified multi-reader feed + your app (or ours) into the database you already run”—not “IoT has a Postgres plugin” unless/until we add one. + +**Optional future:** a native DB processor in IoT is possible (same event bus as logger/REST), but app-level integration keeps schema and business rules with the customer app. + +### 5. Operations without opening each reader + +- Start / stop inventory (web UI and API) +- Health and heartbeats +- Recent tags for support (“is this portal still reading?”) +- Optional GPIO for local automation + +### 6. Site edge reliability + +Runs locally (Windows service or Linux). Can log on-site when the cloud is flaky. Timeouts and reconnects so one dead reader does not hang the whole site. + +### 7. Adding readers is config, not a new project + +Same pipeline for the 2nd reader and the 10th. Shared schema and egress for integrators and BI teams. + +### 8. Room to grow without rewriting consumers + +Today Impinj fixed; later handhelds, barcodes, another vendor, or keyboard wedge into WMS. Downstream feeds can stay the same. + +### 9. Lower software TCO + +They pay for reader hardware either way. The real cost of DIY is owning multi-reader orchestration, health, control, and egress forever. TallyFlow is that product. + +## When direct reader APIs may be enough + +- Single reader pilot / lab +- Strong internal IoT team with an existing broker and warehouse already +- Raw telemetry only, no need for ops UI, multi-vendor, or multi-site packaging + +## Suggested talking points + +1. Reader APIs control radios; apps and reports need a clean event feed. You need a middle layer. +2. TallyFlow is that layer for multi-reader sites. +3. It can put the unified multi-reader feed in a spreadsheet—or REST / TallyFlow (AMQP) when they outgrow files. +4. One schema, many readers. +5. Site staff can verify RFID without vendor tools or the downstream app. +6. More readers and sites later without rewriting every consumer. + +## Related + +- Product: TallyFlow IoT (edge service) +- Egress today: **spreadsheet (CSV)**, REST API, **AMQP → TallyFlow** +- Database today: **via app** (e.g. Alice+Olivia console → SQLite over REST), not a built-in IoT processor +- AI today: **MCP Streamable HTTP** at `/mcp` (read-only tools; see below) +- Not yet: MQTT *export* (MQTT is used inbound for Zebra today); optional native DB processor; full REST surface as MCP tools +- Typical stack: Impinj Speedway / R700 family fixed readers +- See also: [[ServiceNow Integration Approach]] (enterprise system-of-record pattern via Core) + +--- + +## AI integration (MCP) + +### What kind of AI interaction this is good for + +Today’s MCP surface is **narrow and read-only**. That is a feature for early use, not a full “AI operates the dock.” + +**Good fit today** + +| Interaction | Why MCP helps | +|-------------|----------------| +| **Ops / support copilot** | “Which readers are configured?” “Any recent tags?” “Is the service up?” without custom scripts | +| **Site awareness for agents** | An agent (Cursor, Claude Desktop, custom) that already talks MCP can poll health, reader list, and recent tag cache | +| **Troubleshooting** | Compare “UI shows tags” vs “API/MCP shows tags”; confirm IoT is running before blaming the reader | +| **Light inventory questions** | “What EPCs did we see lately?” from the in-memory recent-tag buffer (not full history or BI) | +| **Safe by default** | No start/stop/write over MCP → lower risk of an agent turning RF on/off by mistake | + +**Poor fit today (use REST, apps, or human UI instead)** + +- Continuous live stream of every tag (MCP is not the NDJSON stream) +- Long history / Power BI-style analytics (use CSV, warehouse, or TallyFlow) +- Autonomous dock control (start/stop inventory, GPO, tag write) +- Complex multi-step workflows that need transactional DB state (that’s the app layer, e.g. Alice+Olivia) + +**Mental model:** MCP = *ask the edge what it sees right now*. REST / CSV / AMQP / apps = *run the site and feed systems of record*. + +### Current (in the code) + +- **Transport:** Streamable HTTP at `GET`/`POST` `/mcp` when the REST API processor is enabled (`rmcp`) +- **Tools live today:** + - `get_health` — same idea as `GET /api/v1/health` + - `get_readers` — configured readers/scanners + - `get_tags` — recent tags/barcodes (in-memory, capped per reader) +- **Not exposed as MCP tools yet:** start/stop, write EPC, reader status/heartbeat POST, live stream, remote-reader submit +- **Generated OpenAPI → MCP JSON** (`api-mcp-gen`, under `core/api/mcp/`) describes a **fuller** REST surface for tooling/docs; the **running** server only registers the three read-only tools +- Smoke test: `core/scripts/test_mcp.sh` + +### Future (product options) + +Prioritize in order of risk vs value: + +1. **More read-only tools** — API info, per-reader status/heartbeat, optional filter on tags by reader name +2. **Guarded control tools** — start/stop (and later write/GPO) behind explicit confirmation, API key, and/or “AI control enabled” config so agents cannot act by default +3. **Align gen descriptors with live tools** — or generate the live router from OpenAPI so docs and runtime do not diverge +4. **Optional MQTT (or other) export** for agent/event buses — separate from MCP; still not required for copilot Q&A +5. **Higher-level “site summary” tool** — one call: readers up/down, last tag time, tag counts, obvious faults (better for LLMs than raw dumps) +6. **Cross-product AI** — IoT MCP + Core/ServiceNow patterns so an agent can go from “tag seen at dock” to business context (asset, order, location) + +**Sell carefully:** “AI can check site RFID status through TallyFlow IoT” is true today. “AI runs your readers” is a future, opt-in story. + +--- + +## Use cases + +### Benefits for Power BI + +TallyFlow sits at each site and turns several Impinj readers into one clean tag feed for Power BI. You get health, start/stop, and local visibility without building and maintaining that plumbing yourself. + +Power BI is a consumer of data, not a controller of readers. TallyFlow is the middle layer that makes multi-reader RFID practical for reporting. + +**Why this matters for Power BI customers:** + +- **Unified multi-reader feed** — all site readers in one schema (reader, antenna, EPC, TID, RSSI, time) +- **Spreadsheet path** — TallyFlow IoT can output that unified data to a **CSV/spreadsheet**; Power BI can load the file, folder, or gateway path with no custom Impinj client +- **Other paths when needed** — REST into middleware / Azure Function / a warehouse DB app, or AMQP into TallyFlow then downstream +- **Ops without opening Power BI** — site staff can confirm reads and reader health locally +- **Stable contract** — add readers or change hardware without rebuilding every report + +**Typical flow:** + +```text +[Impinj × N] → [TallyFlow IoT] → [CSV / REST / AMQP→TallyFlow] + ↓ + [optional app → database] + ↓ + [Power BI / reports] +``` + +