boiler-controller-app 0.1.3

This boiler app is used for starting, simulating an error and stopping boiler. It consists of many states and each change of state is logged in an event logger file.

Boiler Controller Application

Overview

The Boiler Controller Application is a Python-based simulation of an industrial boiler startup system. It models real-world boiler behavior including state transitions, safety interlocks, timed startup sequences, error handling, and persistent event logging.

The system is designed with a modular architecture to ensure maintainability, scalability, and testability. It begins in a safe Lockout state and provides a console-based interface for user interaction.

Features

Boiler Lifecycle Simulation

The application simulates a full boiler lifecycle with the following states:

• Lockout
• Ready
• Pre-Purge
• Ignition
• Operational
• Stopped

The startup sequence includes timed phases:

• Pre-Purge: 10 seconds
• Ignition: 10 seconds

Safety Interlock System

• Run Interlock switch supports Open and Closed states
• Boiler operations are permitted only when the interlock is Closed
• Each toggle is logged as a system event

Event Logging System

• All significant system events are logged to disk
• Logs are stored in CSV format
• Each entry contains:
  • Timestamp
  • Event
• Log file location:

boiler_event_log_file/event_log.csv

---

Error Handling

• Simulated errors can occur during operation
• On error, system transitions to Lockout state
• All errors are logged with timestamps and descriptions
• Invalid operations are handled gracefully with user feedback

Console Interface

The application provides a menu-driven interface with the following options:

• Start Boiler Sequence
• Stop Boiler Sequence
• Simulate Boiler Error
• Toggle Run Interlock Switch
• Reset Lockout
• View Event Log
• Exit Application

---

Project Structure

The project is organized in a modular, package-based structure, where each folder represents a clear functional responsibility.

boiler_controller_app/
│
├── __pycache__/                     # Python bytecode cache
├── .venv/                           # Virtual environment
│
├── boiler/
│   ├── __pycache__/
│   ├── __init__.py
│   └── boiler.py                    # Core boiler control logic
│
├── boiler_event_log_file/
│   └── event_log.csv                # CSV file storing boiler events
│
├── boiler_state/
│   ├── __pycache__/
│   ├── __init__.py
│   └── boiler_state.py              # Boiler state enumeration
│
├── boiler_terminal_app/
│   ├── __pycache__/
│   ├── __init__.py
│   ├── abstract_terminal_app.py     # Abstract base class for terminal apps
│   └── boiler_terminal_app.py       # Terminal-based boiler UI
│
├── event_logger/
│   ├── __pycache__/
│   ├── __init__.py
│   └── event_logger.py              # Event logging to CSV
│
├── interlock_switch/
│   ├── __pycache__/
│   ├── __init__.py
│   └── interlock_switch.py          # Safety interlock logic
│
├── menu_options/
│   ├── __pycache__/
│   ├── __init__.py
│   └── menu.py                      # Menu options enum
│
├── __init__.py                      # Root package initializer
├── main.py                          # Application entry point
├── main.spec                        # Build specification file
├── pyproject.toml                   # Project and dependency configuration
├── uv.lock                          # Dependency lock file
└── README.md                        # Project documentation

Installation

The package is available on PyPI at

https://pypi.org/project/boiler-controller-app/0.1.3/

You can install it using pip:

pip install boiler-controller-app

Ensure you are using Python 3.8 or above.

Running the Application

After installing the package from PyPI, you can start the application using the CLI command:

boiler-controller

This command launches the Boiler Controller application and initializes the system.

On startup, you will see:

Boiler Controller Initialized.

The system will then begin in the Lockout state with the interlock switch set to Open.

Usage Guide

Start Boiler Sequence

• Requires interlock switch to be Closed
• System transitions through:
  • Pre-Purge (10 seconds)
  • Ignition (10 seconds)
  • Operational state

Stop Boiler Sequence

• Stops operation safely
• Returns system to Lockout state

Simulate Boiler Error

• Available only in Operational state
• Forces system into Lockout state
• Logs error event

Toggle Run Interlock Switch

• Switch toggles between Open and Closed
• Each change is logged

Reset Lockout

• Transitions system from Lockout to Ready
• Requires interlock switch to be Closed

View Event Log

• Displays contents of event_log.csv in readable format

Exit Application

• Terminates the program safely

Event Log Specification

File Format

• CSV (Comma Separated Values)

File Header

Timestamp, Event

Example Log Entry

2026-04-22 10:15:30, Boiler Initialized, System started successfully
2026-04-22 10:16:00, Interlock Switch toggled to Closed
2026-04-22 10:16:10, Pre-Purge completed

Error Handling

The system ensures:

• Graceful handling of invalid user input
• Safe state transitions only
• Automatic transition to Lockout on failure
• Clear error messages displayed to the user
• All errors are logged with timestamps

Example error message:

Error: Ignition failure detected. System in Lockout.

Testing

Unit tests are designed to validate:

• Boiler state transitions
• Interlock switch behavior
• Event logging functionality
• Error handling mechanisms

Run tests using:

pytest

Design Principles

• Modular architecture with clear separation of concerns
• State-driven boiler control system
• Safety-first design using interlock enforcement
• Extensible structure for future enhancements
• Persistent event logging for traceability

Future Enhancements

• Graphical user interface for boiler control
• Real-time monitoring dashboard
• Configurable timing for simulation phases
• Database-backed logging system
• Remote control capabilities via API

License

This project is intended for educational and simulation purposes only.