# Svc::ComLogger

## 1. Introduction

The ComLogger component logs `Fw::Com` buffers (e.g., framed telemetry, events, or command packets) to files on the on-board filesystem. Each received Com buffer is written to the currently open log file, optionally prefixed with a 2-byte length field. Log files are timestamped and automatically rotated when they reach a configured maximum size, and a companion hash file is written on close for ground-side validation.

## 2. Requirements

| Name | Description | Validation |
|---|---|---|
| SVC-COMLOGGER-001 | The ComLogger component shall log the contents of Com buffers received on its `comIn` port | unit test |
| SVC-COMLOGGER-002 | The ComLogger component shall optionally prefix each logged buffer with a 2-byte (U16) length field | unit test |
| SVC-COMLOGGER-003 | The ComLogger component shall close the current file and open a new one when the configured maximum file size would be exceeded | unit test |
| SVC-COMLOGGER-004 | The ComLogger component shall name log files using the configured prefix and the time of file opening | inspection |
| SVC-COMLOGGER-005 | The ComLogger component shall write a hash (validation) file when closing each log file | unit test |
| SVC-COMLOGGER-006 | The ComLogger component shall provide a command to close the currently open file | unit test |
| SVC-COMLOGGER-007 | The ComLogger component shall report file errors via events | unit test |

## 3. Design

The ComLogger is an active component. Com buffers arriving on the async `comIn` port are dispatched on the component's thread and written synchronously to the log file.

### 3.1 Port Description

| Port | Kind | Type | Description |
|---|---|---|---|
| `comIn` | async input | `Fw.Com` | Com buffers to log |
| `pingIn` / `pingOut` | async input / output | `Svc.Ping` | Health ping |

### 3.2 File Management

* Log files are named `<prefix>_<timeBase>_<seconds>_<microseconds>.com`, using the component's time at file-open.
* Files are opened lazily on the first received buffer and re-opened after rotation or a commanded close.
* When `storeBufferLength` is enabled (the default), each buffer is preceded by its size as a U16; this permits ground tools to re-segment the log into individual packets.
* When a write would exceed `maxFileSize`, the current file is closed and a new one opened.
* On close, a companion hash file (`<fileName><hash extension>`) is written via `Utils::Hash`; failures produce `FileValidationError`.
* Open and write errors are reported once per file via `FileOpenError` and `FileWriteError` to avoid event flooding.

### 3.3 Initialization

The component may be constructed either fully initialized — `ComLogger(compName, filePrefix, maxFileSize, storeBufferLength)` — or with the name-only constructor followed by a call to `init_log_file(filePrefix, maxFileSize, storeBufferLength)` before logging begins. Receiving data while uninitialized produces the throttled `FileNotInitialized` warning.

### 3.4 Commands

| Command | Description |
|---|---|
| `CloseFile` | Force a close of the currently opened file, if any |

### 3.5 Events

| Event | Severity | Description |
|---|---|---|
| `FileOpenError` | warning high | Error opening a log file |
| `FileWriteError` | warning high | Error writing to a log file |
| `FileValidationError` | warning low | Error creating a validation (hash) file |
| `FileClosed` | diagnostic | A file was closed successfully on command |
| `FileNotInitialized` | warning low | Data received before initialization (throttled after 5 occurrences) |

## 4. Usage

1. **Instantiate** the component in the topology and start its thread.
2. **Initialize** with a file prefix (which may include a directory path), maximum file size, and buffer-length storage option — either via the initializing constructor or `init_log_file`.
3. **Connect** the com stream to be logged (e.g., the downlink stream out of a framer or `Svc::ComQueue`) to `comIn`.
4. **Close files** on demand with the `CloseFile` command; files also close automatically on rotation and component destruction.

## 5. Change Log

| Date | Description |
|---|---|
| 2026-08-10 | Initial SDD |