Metadata-Version: 2.4
Name: boiler-controller-app
Version: 0.1.3
Summary: 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.
Author: Krisha
Requires-Python: >=3.8
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Description-Content-Type: text/markdown

# 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:
```bash
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.

```text
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
```bash
https://pypi.org/project/boiler-controller-app/0.1.3/
```
You can install it using pip:

```bash
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:

```bash
boiler-controller
```


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

On startup, you will see:

```bash
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
```bash
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:
```bash
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:
```bash
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.
