---
module: agent.atec-tcr-events
title: ATEC TCR Events — cassette + process monitoring for LG Teller Cash Recyclers
tab: Claude
order: 40
audience: dev
---

> **Internal · agent reference.** Terse. Confirmed against `hiveops-module-atec-tcr-events` source 2026-07-01.

## Identity
- Maven artifact: **`hiveops-module-atec-tcr-events`** (`com.hiveops`, version `1.0.0`, packaged as a standalone `jar`, parent `hiveops-agent-parent`).
- Agent module id (`getName()`, and the string to use in **`modules.disabled`**): **`tcr-events`** — NOT `atec-tcr-events`.
- Entry class: `com.hiveops.tcrevents.TcrEventsModule`, registered via `META-INF/services/com.hiveops.core.module.AgentModule`.
- Log package: `com.hiveops.tcrevents`.
- Activation gate: `device.type` must equal `ATEC_TCR` (or legacy `TCR`); any other value → module inert, `isEnabled()` returns `false`.
- Platform: Windows-only in practice (no runtime OS check in code — enforced by deployment convention).

## Config properties (exact keys)
| Key | Default | Required | Notes |
|---|---|---|---|
| `tcr.events.enabled` | `true` | no | `false` (case-insensitive) disables the module |
| `tcr.log.dir` | *(none)* | **yes** | must exist and be a directory or module disables itself with a warning log, no crash |
| `tcr.events.poll.interval.sec` | `30` | no | **read but NOT applied** — `start()` hardcodes `DEFAULT_POLL_SEC=30`; changing this property does nothing today |

Shared (not module-specific): `agent.endpoint` / `incident.endpoint` (prefix selection: `agent` if `agent.endpoint` is set, else `incident`), `agent.auth.token`, `agent.institution.key` / `incident.institution.key`.

## Event types emitted (exact strings)
| Event type | Source file | Trigger |
|---|---|---|
| `CASSETTE_EMPTY` | `CST_SNR_MMDD.log` | slot status transitions to `EMPT` |
| `TCR_SENSOR_FAULT` | `CST_SNR_MMDD.log` | slot status transitions to `SNRF` |
| `TCR_MANUAL_REQUIRED` | `CST_SNR_MMDD.log` | slot status transitions to `TMAN` |
| `TCR_SENSOR_MISMATCH` | `CST_SNR_MMDD.log` | line matches `** CST <slot> - SNR deposit count ... mismatch ...` |
| `TCR_PROCESS_RESTART` | `ACESSLog<MMDD>.txt` | line contains `Process restarted from abnormal termination` |
| `TCR_SHUTDOWN` | `ACESSLog<MMDD>.txt` | line contains `## Shutdown ##` or `## Shutdown for reboot ##` |

- `eventType` is a free-form `String` on `CreateJournalEventRequest` (`hiveops-agent-journal` DTO) — **not validated client-side**.
- The agent's own `com.hiveops.events.EventType` enum only contains `CASSETTE_EMPTY` from this list — the five `TCR_*` strings are **not** in that enum. Recognition happens in hiveops-incident's DB-backed `event_type` table, not agent code.
- `eventSource` sent: `"TCR_CST_SNR"` (cassette log events) or `"TCR_ACESS_LOG"` (access log events).
- `cassettePosition` (slot, e.g. `AH`, `AL`) is only populated for `CstSnsLogMonitor` events; null for access-log events.
- Transport: `POST {endpoint}/api/journal-events` via `IncidentEventClient.sendEvent()` — same client/endpoint as `journal-events` module.
- Recovery to `NORM` status emits **no event** — agent-log-only (`slot {} recovered`).

## Files monitored
- `{tcr.log.dir}/CST_SNR_<MMDD>.log` — cassette sensor/status log (daily rotation; date = `MMdd`, e.g. `CST_SNR_0701.log`).
- `{tcr.log.dir}/ACESSLog<MMDD>.txt` — TCR process/access log (daily rotation; **no underscore** in code: `ACESSLog0701.txt`).
- Both use tail-by-offset (`RandomAccessFile` + stored `fileOffset`), reset on daily rollover or file truncation.

## Deployment
- Delivered fleet-wide via **`INSTALL_MODULE`** fleet task (drops JAR into agent's `modules/` dir, restarts agent — `ProcessInstallModule` in `hiveops-file-collection`).
- Disable without uninstalling: add `tcr-events` to `modules.disabled`, push `CONFIG_UPDATE`.
- Event types must be registered in hiveops-incident → Settings → Event Types (DB `event_type` table) to be recognized/labeled correctly.

## Do NOT
- Do NOT use `atec-tcr-events` as the `modules.disabled` value — the actual module id is `tcr-events`.
- Do NOT expect changing `tcr.events.poll.interval.sec` to change the poll cadence — it's a known no-op bug; cadence is always 30s.
- Do NOT assume the five `TCR_*` event type strings exist in the agent's `EventType` enum — they don't; only `CASSETTE_EMPTY` does. Don't "fix" this by adding them there — the enum isn't what gates recognition (the DB `event_type` table in hiveops-incident is).
- Do NOT expect this module to run on non-`ATEC_TCR` device types — it's a no-op by design elsewhere, not a bug to chase.
- Do NOT expect retry/queueing on send failure — a failed `sendEvent()` call is logged and dropped, not persisted or retried on the next poll.
- Do NOT look for an underscore in the access-log filename — the code is `ACESSLog<MMDD>.txt` (e.g. `ACESSLog0701.txt`), not `ACESSLog_0701.txt`; the class javadoc's `ACESSLog_MMDD.txt` is stale.
- Do NOT confuse this with `hiveops-module-nh-tcr-events` (`NhTcrEventsModule`) or `hiveops-module-nh-tcr-journal` (`NhTcrJournalModule`) — separate modules, separate vendor (NH TCR), different log formats and event pipelines.
