# Series 4 Emitter

**Version:** 0.1.2

Micromate (Series 4) heartbeat emitter for Seismo Fleet Manager (SFM).

## Overview

Series 4 Emitter is a Python-based monitoring tool that scans for Micromate unit activity logs and reports their status. It monitors MLG (Micromate Log) files in the THORDATA directory structure, determines unit health based on last activity, and optionally transmits heartbeat data to a Seismo Fleet Manager backend.

## Features

- **Automatic MLG File Discovery**: Scans `C:\THORDATA\<Project>\<UM####>\*.MLG` for Micromate units
- **Intelligent Unit Tracking**: Automatically identifies the newest MLG file per unit based on timestamp
- **Status Classification**: Categorizes units as OK, LATE, or STALE based on configurable age thresholds
- **Console Heartbeat Display**: Real-time status dashboard with formatted output
- **SFM Backend Integration**: Optional HTTP POST of JSON telemetry to Fleet Manager
- **External Configuration**: JSON-based configuration file for easy customization
- **Robust Error Handling**: Graceful degradation with informative warnings
- **No External Dependencies**: Uses Python standard library only (urllib, json, datetime, etc.)

## Requirements

- Python 3.6 or higher
- Windows OS (designed for THOR PC/VM environments)
- Access to THORDATA directory structure

## Installation

1. Clone or copy this repository to your THOR PC/VM
2. Ensure Python 3.6+ is installed
3. Configure `config.json` (see Configuration section)
4. Run the emitter:

```bash
python series4_emitter.py
```

## Configuration

All configuration is managed through `config.json` in the same directory as the script.

### config.json Structure

```json
{
  "thordata_path": "C:\\THORDATA",
  "scan_interval": 60,
  "late_days": 2,
  "stale_days": 60,
  "sfm_endpoint": "http://<sfm backend ip>:8001/api/series4/heartbeat"
  "sfm_timeout": 5,
  "debug": true
}
```

### Configuration Options

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `thordata_path` | string | `C:\THORDATA` | Root directory containing project/unit MLG files |
| `scan_interval` | integer | `60` | Time in seconds between scans |
| `late_days` | integer | `2` | Days before a unit is marked as LATE |
| `stale_days` | integer | `60` | Days before a unit is marked as STALE |
| `sfm_endpoint` | string | `""` | SFM backend URL (leave empty to disable HTTP) |
| `sfm_timeout` | integer | `5` | HTTP request timeout in seconds |
| `debug` | boolean | `true` | Enable/disable debug logging |

### Fallback Behavior

If `config.json` is missing or malformed, the emitter will:
- Display a warning message
- Use built-in default values
- Continue running normally

## Usage

### Start the Emitter

```bash
python series4_emitter.py
```

### Console Output Example

```
Series 4 Emitter — Micromate Heartbeat (v0.1.2)
THORDATA root: C:\THORDATA
Now: 2025-12-08 14:30:00
--------------------------------------------------------------------------------
UM11719  OK     Age: 1h 12m  Last: 2025-12-08 13:18:00  Project: Clearwater - ECMS 57940
UM12345  LATE   Age: 3d 5h   Last: 2025-12-05 09:15:30  Project: Site Alpha
UM98765  STALE  Age: 65d     Last: 2025-10-04 08:22:15  Project: Legacy Site
--------------------------------------------------------------------------------
Total units: 3
Next scan in 60 seconds...
```

### Stop the Emitter

Press `Ctrl+C` to gracefully stop the emitter.

## Status Classification

Units are classified based on the age of their last MLG file:

- **OK**: Last activity within `late_days` threshold (default: < 2 days)
- **LATE**: Last activity between `late_days` and `stale_days` (default: 2-60 days)
- **STALE**: Last activity exceeds `stale_days` threshold (default: ≥ 60 days)

## SFM Backend Integration

When `sfm_endpoint` is configured, the emitter sends JSON payloads to the Seismo Fleet Manager:

### Payload Structure

```json
{
  "source": "series4_emitter",
  "generated_at": "2025-12-08T14:30:00",
  "units": [
    {
      "unit_id": "UM11719",
      "type": "micromate",
      "project_hint": "Clearwater - ECMS 57940",
      "last_call": "2025-12-08T13:18:00",
      "status": "OK",
      "age_days": 0.05,
      "age_hours": 1.2,
      "mlg_path": "C:\\THORDATA\\Clearwater - ECMS 57940\\UM11719\\UM11719_20251208131800.MLG"
    }
  ]
}
```

### Disabling SFM Integration

Set `sfm_endpoint` to an empty string in `config.json`:

```json
{
  "sfm_endpoint": ""
}
```

## MLG File Format

The emitter expects MLG files to follow this naming convention:

```
UM<unit_number>_YYYYMMDDHHMMSS.MLG
```

Example: `UM11719_20251208131800.MLG`

- `UM11719`: Unit ID
- `20251208131800`: Timestamp (2025-12-08 13:18:00)
- `.MLG`: Micromate Log file extension

## Directory Structure

Expected THORDATA folder structure:

```
C:\THORDATA\
├── Project A\
│   ├── UM11719\
│   │   ├── UM11719_20251208131800.MLG
│   │   ├── UM11719_20251207095430.MLG
│   │   └── ...
│   └── UM12345\
│       └── UM12345_20251205091530.MLG
└── Project B\
    └── UM98765\
        └── UM98765_20251004082215.MLG
```

## Troubleshooting

### Config file not found
If you see `[WARN] Config file not found`, create `config.json` in the same directory as `series4_emitter.py`.

### THORDATA path doesn't exist
Verify the `thordata_path` in `config.json` points to the correct directory.

### No units found
Ensure MLG files exist in the expected directory structure and follow the naming convention.

### SFM POST failures
Check that:
- `sfm_endpoint` URL is correct and accessible
- Network connectivity is available
- SFM backend is running and accepting requests

## License

Proprietary - Internal use only

## Version History

See [CHANGELOG.md](CHANGELOG.md) for detailed version history.

## Support

For issues or questions, contact the Seismo development team.