Svc::BufferLogger

1. Introduction

The BufferLogger component logs binary data to files on the on-board filesystem. It accepts data either as Fw::Buffer objects (typically raw payloads such as sensor data) or as Fw::Com buffers (typically packetized telemetry or events), and writes each received item to the currently open log file, prefixed with a length field. Buffers received on the bufferSendIn port are forwarded downstream after logging so the component can be inserted transparently into a buffer pipeline.

2. Requirements

Name	Description	Validation
SVC-BUFFERLOGGER-001	The BufferLogger component shall log the contents of buffers received on its bufferSendIn port	unit test
SVC-BUFFERLOGGER-002	The BufferLogger component shall log the contents of Com buffers received on its comIn port	unit test
SVC-BUFFERLOGGER-003	The BufferLogger component shall forward buffers received on bufferSendIn to bufferSendOut regardless of logging state	unit test
SVC-BUFFERLOGGER-004	The BufferLogger component shall prefix each logged buffer with a configurable-width size field	unit test
SVC-BUFFERLOGGER-005	The BufferLogger component shall open a new log file when the configured maximum file size would be exceeded	unit test
SVC-BUFFERLOGGER-006	The BufferLogger component shall provide commands to open a log file, close the log file, flush the log file, and enable or disable logging	unit test
SVC-BUFFERLOGGER-007	The BufferLogger component shall write a hash (validation) file when closing each log file	unit test
SVC-BUFFERLOGGER-008	The BufferLogger component shall report file errors via events	unit test

3. Design

The BufferLogger is an active component. Data arriving on the async bufferSendIn and comIn ports is dispatched on the component's thread and written synchronously to the log file.

3.1 Port Description

Port	Kind	Type	Description
bufferSendIn	async input	Fw.BufferSend	Buffers to log; forwarded to bufferSendOut after logging
bufferSendOut	output	Fw.BufferSend	Forwarded buffers (e.g., for return to a buffer manager)
comIn	async input	Fw.Com	Com buffers to log (not forwarded)
pingIn / pingOut	async input / output	Svc.Ping	Health ping
schedIn	async input	Svc.Sched	Run-time scheduling (currently unused)

3.2 Logging State

Logging is controlled by a volatile state (LogState): LOGGING_ON (default at construction) or LOGGING_OFF, set by the BL_SetLogging command. When logging is off, incoming data is not written, but bufferSendIn data is still forwarded to bufferSendOut. Setting the state to LOGGING_OFF closes the current file.

3.3 File Management

• File names have the form <prefix><baseName><suffix> for the first file after BL_OpenFile, and <prefix><baseName><counter><suffix> for subsequent files, where the counter increments each time a file fills up.
• Each logged buffer is written as a size field (of sizeOfSize bytes, configured via initLog) followed by the buffer data.
• When a write would exceed the configured maximum file size, the current file is closed and a new one is opened.
• On close, a companion hash file is written for ground-side validation (see Utils::Hash); failures produce BL_LogFileValidationError.
• Logging before any BL_OpenFile command has set a base name produces BL_NoLogFileOpenInitError.

3.4 Commands

Command	Description
BL_OpenFile	Set the log file base name and reset the unique file counter to 0
BL_CloseFile	Close the currently open log file, if any
BL_SetLogging	Set the volatile logging state (LOGGING_ON / LOGGING_OFF)
BL_FlushFile	Flush the open log file to disk; a no-op with F Prime's unbuffered file I/O, so always returns success

3.5 Events

Event	Severity	Description
BL_LogFileClosed	diagnostic	A log file was closed
BL_LogFileOpenError	warning high	Error opening a log file
BL_LogFileValidationError	warning high	Error writing a validation (hash) file
BL_LogFileWriteError	warning high	Error writing to a log file
BL_Activated / BL_Deactivated	activity low	Logging was enabled / disabled
BL_NoLogFileOpenInitError	warning high	Data received before a log file base name was set
BL_LogFileNameError	warning high	Error formatting a log file name

3.6 Telemetry

Channel	Type	Description
BufferLogger_NumLoggedBuffers	U32	The number of buffers logged

4. Usage

1. Instantiate the component in the topology and start its thread.
2. Initialize the log parameters by calling initLog(prefix, suffix, maxFileSize, sizeOfSize) from topology setup code.
3. Open a log file by sending the BL_OpenFile command with the desired base name.
4. Stream data into bufferSendIn and/or comIn.
5. Close or rotate files with BL_CloseFile/BL_OpenFile as needed.

Note that bufferSendIn forwards ownership of each buffer to bufferSendOut; the topology must route the forwarded buffers to their owner (e.g., a Svc::BufferManager).

5. Change Log

Date	Description
2026-08-10	Initial SDD