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.