Refactor architecture for extensibility: configuration, protocols, and capability interfaces

ARCHITECTURE.md

@@ -0,0 +1,271 @@
+# ProjectorController Architecture
+
+## Overview
+
+This document describes the improved architecture of the ProjectorController project, focusing on extensibility and ease of adding support for new projector models.
+
+## Architecture Improvements
+
+The refactored architecture addresses several key issues:
+
+1. **Configuration Flexibility**: Serial port settings are now configurable instead of hardcoded
+2. **Protocol Abstraction**: Different projector command protocols are separated from implementation
+3. **Capability Interfaces**: Clear contracts for what features a projector supports
+4. **Factory Pattern**: Centralized creation of different projector types
+5. **Extensibility**: Easy to add new projector models with different protocols
+
+## Core Components
+
+### 1. Configuration System
+
+**`ProjectorConfig`** - Builder pattern for configuring connection parameters:
+```java
+ProjectorConfig config = new ProjectorConfig.Builder()
+    .portName("/dev/ttyUSB0")
+    .baudRate(115200)
+    .dataBits(DataBits.DATABITS_8)
+    .stopBits(StopBits.STOPBITS_1)
+    .parity(Parity.PARITY_NONE)
+    .charset(StandardCharsets.US_ASCII)
+    .responseTerminator(">")
+    .build();
+```
+
+Pre-configured factory methods are available for common projector types:
+```java
+ProjectorConfig config = ProjectorConfig.createBenQConfig("/dev/ttyUSB0");
+```
+
+### 2. Protocol Abstraction
+
+**`CommandProtocol`** interface defines how to format commands for different projector types.
+
+Different manufacturers use different command formats:
+- **BenQ**: `\r*pow=on#\r` with `>` terminator
+- **Epson**: `PWR ON\r` with `:` terminator
+- **Sony**: May use different formats entirely
+
+Example implementations:
+- `BenQProtocol` - For BenQ projectors
+- `EpsonProtocol` - For Epson projectors (demonstration)
+
+### 3. Capability Interfaces
+
+Projectors implement capability interfaces based on what features they support:
+
+- **`PowerControl`** - Turn on/off, check power state
+- **`SourceControl`** - Switch input sources
+- **`CommandCapability`** - Send raw commands for advanced usage
+
+This allows clients to check at runtime what a projector can do:
+```java
+if (projector instanceof PowerControl) {
+    ((PowerControl) projector).turnOn();
+}
+```
+
+### 4. Projector Base Class
+
+**`Projector`** abstract class provides:
+- Common message queuing functionality
+- Protocol and configuration management
+- Port management
+
+All projector implementations extend this class.
+
+### 5. Factory Pattern
+
+**`ProjectorFactory`** provides centralized projector instantiation:
+
+```java
+// Simple creation with default port
+Projector projector = ProjectorFactory.createProjector(ProjectorType.BENQ_W1070);
+
+// Creation with specific port
+Projector projector = ProjectorFactory.createProjector(ProjectorType.BENQ_W1070, "/dev/ttyUSB0");
+
+// Creation with custom configuration
+ProjectorConfig config = ProjectorConfig.createBenQConfig("/dev/ttyUSB0");
+Projector projector = ProjectorFactory.createProjector(ProjectorType.BENQ_W1070, config);
+```
+
+## Adding a New Projector Type
+
+Adding support for a new projector is now straightforward. Here's how:
+
+### Step 1: Create a Protocol Implementation
+
+```java
+public class SonyProtocol implements CommandProtocol {
+    @Override
+    public String getPowerOnCommand() {
+        return "POWER ON\r\n";
+    }
+
+    @Override
+    public String getPowerOffCommand() {
+        return "POWER OFF\r\n";
+    }
+
+    // ... implement other methods
+
+    @Override
+    public String getResponseTerminator() {
+        return "\r\n";
+    }
+}
+```
+
+### Step 2: Create a Projector Class
+
+```java
+public class SonyVPL extends Projector implements PowerControl, SourceControl {
+    public SonyVPL(String portName) throws ... {
+        super.projectorName = "Sony VPL";
+
+        ProjectorConfig config = new ProjectorConfig.Builder()
+            .portName(portName)
+            .baudRate(9600)
+            // ... other Sony-specific settings
+            .build();
+
+        super.initialize(config, new SonyProtocol());
+    }
+
+    @Override
+    public void turnOn() {
+        // Implementation using protocol.getPowerOnCommand()
+    }
+
+    // ... implement other capability methods
+}
+```
+
+### Step 3: Add to Factory
+
+1. Add enum value to `ProjectorFactory.ProjectorType`:
+```java
+public enum ProjectorType {
+    BENQ_W1070,
+    EPSON_GENERIC,
+    SONY_VPL,  // New projector type
+}
+```
+
+2. Add cases to factory methods:
+```java
+case SONY_VPL:
+    return new SonyVPL(portName);
+```
+
+That's it! The new projector type is now fully integrated.
+
+## Benefits of the New Architecture
+
+### 1. Separation of Concerns
+- Connection settings are separate from projector logic
+- Command protocols are separate from projector implementations
+- Capabilities are clearly defined interfaces
+
+### 2. Extensibility
+- Easy to add new projector models
+- Easy to add new capabilities
+- Easy to support different protocols
+
+### 3. Flexibility
+- Runtime configuration of connection parameters
+- Runtime checking of projector capabilities
+- Multiple ways to instantiate projectors
+
+### 4. Maintainability
+- Clear structure and organization
+- Well-defined interfaces
+- Single responsibility for each class
+
+### 5. Testability
+- Easy to mock protocols for testing
+- Easy to test individual capabilities
+- Configuration can be injected for testing
+
+## Example Use Cases
+
+### Use Case 1: Basic Power Control
+```java
+Projector projector = ProjectorFactory.createProjector(ProjectorType.BENQ_W1070);
+if (projector instanceof PowerControl) {
+    PowerControl pc = (PowerControl) projector;
+    pc.turnOn();
+}
+projector.closePorts();
+```
+
+### Use Case 2: Custom Configuration
+```java
+ProjectorConfig config = new ProjectorConfig.Builder()
+    .portName("COM3")
+    .baudRate(115200)
+    .build();
+
+Projector projector = ProjectorFactory.createProjector(
+    ProjectorType.BENQ_W1070, 
+    config
+);
+```
+
+### Use Case 3: Multiple Projector Types
+```java
+Projector benq = ProjectorFactory.createProjector(
+    ProjectorType.BENQ_W1070, 
+    "/dev/ttyUSB0"
+);
+
+Projector epson = ProjectorFactory.createProjector(
+    ProjectorType.EPSON_GENERIC, 
+    "/dev/ttyUSB1"
+);
+
+// Both projectors can be controlled through the same interfaces
+if (benq instanceof PowerControl) {
+    ((PowerControl) benq).turnOn();
+}
+if (epson instanceof PowerControl) {
+    ((PowerControl) epson).turnOn();
+}
+```
+
+## Backward Compatibility
+
+The existing `W1070` class has been updated to use the new architecture while maintaining compatibility:
+
+```java
+// Old way still works
+W1070 projector = new W1070();
+projector.turnOn();
+projector.closePorts();
+
+// New way with more flexibility
+W1070 projector = new W1070("/dev/ttyUSB0");
+// or
+W1070 projector = new W1070(customConfig);
+```
+
+## Future Enhancements
+
+Possible future improvements:
+
+1. **More Capability Interfaces**: Add interfaces for audio control, picture settings, etc.
+2. **Configuration Files**: Load projector configurations from JSON/XML files
+3. **Auto-Detection**: Automatically detect projector type on a given port
+4. **Command Queue Priority**: Support for priority-based command queuing
+5. **Async Operations**: Support for asynchronous command execution with CompletableFuture
+6. **Event System**: Event-driven architecture for projector state changes
+
+## Conclusion
+
+The improved architecture makes it significantly easier to:
+- Add support for new projector models
+- Configure connection parameters
+- Test different components
+- Maintain and extend the codebase
+
+The key is the separation of concerns: configuration, protocol, and implementation are now independent, making each easier to work with and modify.