Skip to main content

AEI Readers

Automatic Equipment Identification, or AEI, is the reader/tag system used to detect railcars as they pass fixed reader locations. In the Iron Horse environment, AEI reads are used as an independent signal for inbound and outbound railcar movement, and they help identify gaps between what physically happened in the yard and what was entered into Trackage or BIRCH.

What AEI provides​

Each reader file provides a timestamped railcar detection event. The integration extracts:

  • Reader/site identifier
  • Reader direction
  • Event date and time
  • Railcar mark and number
  • Interpreted movement direction: inbound or outbound
  • Source file name for audit/debugging

AEI does not replace yard workflows. It provides a physical movement signal that still needs operational context from Trackage, BIRCH, work orders, customer records, holds, and manual corrections.

Current production flow​

Current implementation location:

API server: iht-api.tail2162ca.ts.net
Poller path: /home/ubuntu/api-server/ftp_poller.js
Local AEI file archive: /home/ubuntu/api-server/aei_data
State file: /home/ubuntu/api-server/aei_state.json

Secrets and connection details are intentionally not documented here. Keep FTP, database, and service credentials in approved server-side secret locations only.

Reader direction mapping​

The poller maps reader/direction pairs into inbound or outbound movements:

IHT0001_S → inbound
IHT0001_N → outbound
IHT0002_S → inbound
IHT0002_N → outbound
IHT0003_W → inbound
IHT0003_E → outbound
IHT0004_E → inbound
IHT0004_W → outbound

If readers are moved, renamed, or physically reoriented, this mapping must be reviewed before relying on the resulting inbound/outbound interpretation.

File format​

The current integration processes .t94 files from the reader repository.

High-level parsing behavior:

  1. Read the header line.
  2. Extract site ID, event date, event time, and direction.
  3. Read RRE lines for rail equipment.
  4. Use equipment type R for railcars.
  5. Normalize the car number to six digits.
  6. Store car IDs as mark plus normalized number.

Example normalized railcar shape:

ABCD001234

The source file name is preserved in state so an AEI event can be traced back to its originating reader file.

State model​

The poller maintains a JSON state file with three primary buckets:

processed → list of processed .t94 files
inbound   → cars read inbound but not yet cleared by a Trackage arrival
outbound  → recent outbound reads that are not currently active in-yard

State file:

/home/ubuntu/api-server/aei_state.json

Inbound behavior​

Inbound AEI reads are treated as a data-quality signal.

A car remains in the inbound exception set when:

  • AEI detected the car coming into the facility, and
  • Trackage does not have a matching arrival after the AEI detection timestamp.

This is intentionally not limited to a short time window. Inbound exceptions represent cars that physically appeared but may not have been entered into Trackage correctly.

BIRCH arrival update​

For active BIRCH work orders, the poller also updates BIRCH arrival data from AEI inbound reads.

Behavior:

  • Finds active BIRCH work orders for the railcar.
  • Updates the BIRCH arrival_date when needed.
  • Adds a BIRCH work update with source aei_inbound.
  • Adds a BIRCH log entry for auditability.

The BIRCH update user is a dedicated AEI/system user, not a human operator.

Outbound behavior​

Outbound AEI reads are treated as recent departure confirmations.

A car remains in the outbound set when:

  • AEI detected the car moving outbound within the current recency window, and
  • Trackage no longer shows the car as actively in the yard.

The current recency window is 48 hours. Older outbound reads are cleared from active state.

Operational value​

AEI readers help catch several classes of operational mismatch:

  • Cars physically arrived but were not entered into Trackage.
  • Cars departed but still appear active in the yard.
  • Arrival timestamps in BIRCH are missing or stale.
  • Manual entry missed or mistyped a car number.
  • Reader traffic indicates movement volume that does not match system records.

AEI should be treated as a high-confidence signal, not an absolute source of truth. Yard staff may still need to correct records when the physical move, reader placement, or customer workflow is more complicated than a simple inbound/outbound event.

Troubleshooting checklist​

When AEI counts or exceptions look wrong:

  1. Confirm the poller is running on the API server.
  2. Check the latest poller logs for FTP, parse, or database errors.
  3. Confirm new .t94 files are arriving in the reader repository.
  4. Confirm files are being archived locally under aei_data.
  5. Inspect aei_state.json for processed files, inbound cars, and outbound cars.
  6. Verify the reader direction mapping against physical reader orientation.
  7. Compare a sample AEI car against Trackage triplist arrival/departure records.
  8. Compare a sample active BIRCH work order against BIRCH arrival date and workupdates.

Do not paste credentials or raw secret-bearing connection strings into chat, docs, task logs, commits, or memory while troubleshooting.

Safe maintenance notes​

  • Preserve raw .t94 files for audit/debugging.
  • Back up aei_state.json before manual state edits.
  • Treat reader direction mapping changes as production-affecting.
  • Keep FTP and DB credentials server-side only.
  • If a secret is exposed in chat or docs, rotate it.
  • When adding readers, document the physical location, orientation, site ID, direction codes, and expected movement interpretation.
  • Trackage: yard inventory and arrival/departure tracking.
  • BIRCH: work orders and arrival-date updates.
  • API server: poller host and AEI processing runtime.
  • Reader repository: source of .t94 reader files.