serversdown/thor-emitter
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

documentation added

Browse Source
This commit is contained in:
serversdwn
2025-12-08 17:23:20 -05:00
parent 5526a79557
commit 43aa6a9e63
3 changed files with 246 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
CHANGELOG.md Normal file
View File

@@ -0,0 +1,32 @@
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [0.1.1] - 2025-12-08
### Changed
- Moved configuration from hard-coded values to external `config.json` file
- Configuration now loads from JSON file with graceful fallback to defaults
- Config file is loaded relative to script location for portability
### Added
- `config.json` - External configuration file for all application settings
- `load_config()` function with error handling and default value fallback
- Warning messages when config file is missing or malformed
## [0.1.0] - 2025-12-04
### Added
- Initial release of Series 4 Emitter
- Micromate (Series 4) heartbeat monitoring for Seismo Fleet Manager
- THORDATA folder scanner for MLG files
- Automatic detection of newest MLG file per unit by timestamp
- Age calculation and status classification (OK / LATE / STALE)
- Console heartbeat display with formatted output
- Optional HTTP POST to SFM backend endpoint
- Configurable age thresholds and scan intervals
- Debug logging capability
- Graceful error handling for filesystem and network operations

205
README.md Normal file
View File

@@ -0,0 +1,205 @@
# Series 4 Emitter
**Version:** 0.1.1
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://10.0.0.41:1001",
"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.1)
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.

9
config.example.json Normal file
View File

@@ -0,0 +1,9 @@
{
"thordata_path": "C:\\THORDATA",
"scan_interval": 60,
"late_days": 2,
"stale_days": 60,
"sfm_endpoint": "",
"sfm_timeout": 5,
"debug": true
}