crestron-swamp-controller 1.0.0__py3-none-any.whl

crestron_swamp_controller-1.0.0.dist-info/METADATA

@@ -0,0 +1,297 @@
+Metadata-Version: 2.4
+Name: crestron-swamp-controller
+Version: 1.0.0
+Summary: Interactive controller for Crestron SWAMP media amplifier systems
+Author-email: jaroy <noreply@github.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jaroy/swamp-controller
+Project-URL: Documentation, https://github.com/jaroy/swamp-controller#readme
+Project-URL: Repository, https://github.com/jaroy/swamp-controller
+Project-URL: Issues, https://github.com/jaroy/swamp-controller/issues
+Keywords: crestron,swamp,home-assistant,audio,multi-zone
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0.1
+Requires-Dist: prompt-toolkit>=3.0.43
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.3; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Dynamic: license-file
+
+# SWAMP Controller
+
+Interactive command-line controller for Crestron SWAMP media amplifier systems.
+
+## Features
+
+- **Interactive Shell**: User-friendly command prompt with autocomplete
+- **TCP Server**: Listens for connections from SWAMP devices
+- **State Management**: Maintains local state synchronized with device
+- **Multi-zone Support**: Commands automatically broadcast to all zones in a target
+- **Pluggable Protocol**: Protocol handler designed for easy extension
+- **Home Assistant Integration**: Native HA integration with media player entities
+
+## Home Assistant Integration
+
+This project includes a **Home Assistant integration** that exposes your Crestron SWAMP system as media player entities in Home Assistant. Each target (room/zone) appears as a controllable media player with volume control, source selection, and power control.
+
+### Installation via HACS (Recommended)
+
+[![hacs_badge](https://img.shields.io/badge/HACS-Custom-orange.svg)](https://github.com/hacs/integration)
+[![PyPI](https://img.shields.io/pypi/v/crestron-swamp-controller)](https://pypi.org/project/crestron-swamp-controller/)
+
+1. Ensure [HACS](https://hacs.xyz/) is installed in your Home Assistant instance
+2. Add this repository as a custom repository in HACS:
+   - Open HACS in Home Assistant
+   - Go to "Integrations"
+   - Click the three dots menu (top right) and select "Custom repositories"
+   - Add `https://github.com/jaroy/swamp-controller` as an Integration
+   - Click "Add"
+3. Find "Crestron SWAMP Controller" in HACS and click "Download"
+4. Restart Home Assistant
+5. Add the integration through Settings > Devices & Services > Add Integration
+
+The `crestron-swamp-controller` package will be automatically installed from PyPI when you add the integration.
+
+See [HOMEASSISTANT.md](HOMEASSISTANT.md) for more detailed installation instructions and configuration options.
+
+### Features
+- Media player entity for each target/zone
+- Real-time state updates from SWAMP device
+- Volume control (0-100%)
+- Source selection from configured sources
+- Power on/off control
+- Device availability tracking
+
+---
+
+## CLI Installation
+
+1. Ensure Python 3.12+ is installed
+2. Create and activate virtual environment:
+   ```bash
+   python -m venv .venv
+   source .venv/bin/activate  # On Linux/Mac
+   # or
+   .venv\Scripts\activate  # On Windows
+   ```
+3. Install dependencies:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+## Configuration
+
+Edit `config/config.yaml` to define your audio sources and target zones:
+
+```yaml
+sources:
+  - id: music-a
+    name: Player A
+    swamp-source-id: 4
+
+targets:
+  - id: office-terrace
+    name: Office Terrace
+    swamp-zones:
+      - unit: 3
+        zone: 1
+```
+
+### On the SWAMP
+We have to tell the SWAMP to connect to us instead of a Crestron processor.
+Use these TELNET commands:
+```
+adds 51 <IP address> 4 <port>
+reboot
+```
+
+Note that you can see the currently configured controller with the `ipt` command:
+```
+$ telnet 192.168.1.89
+Trying 192.168.1.89...
+Connected to 192.168.1.89.
+Escape character is '^]'.
+
+SWAMP Control Console
+Connected to Host: SWAMP-00107FE7C4CD
+
+SWAMP>ipt
+CIP_ID  Type    Status     DevID  Port   IP Address/SiteName
+    51  GWAY    ONLINE        4   41794  010.194.005.251
+```
+
+## Usage
+
+Start the controller:
+```bash
+python -m swamp
+```
+
+Or with custom port:
+```bash
+python -m swamp --port 41794
+```
+
+Or with custom config:
+```bash
+python -m swamp --config /path/to/config.yaml
+```
+
+## Available Commands
+
+Once the shell is running, you can use these commands:
+
+### Route audio source to target
+```
+route <source-id> <target-id>
+```
+Example: `route music-a office`
+
+### Set volume
+```
+volume <target-id> <level>
+```
+Example: `volume office 75`
+
+### Adjust volume relatively
+```
+volume <target-id> +/-<delta>
+```
+Example: `volume office +10` or `volume office -5`
+
+### Power control
+```
+power <target-id> on <source-id>
+power <target-id> off
+```
+Power on requires a source (zones need a source to be "on"). Power off sets the source to 0.
+
+Examples:
+- `power office on music-a` - Power on office with music-a as source
+- `power office off` - Power off office
+
+### Show status
+```
+status [target-id]
+```
+Example: `status office` or `status` (shows all)
+
+### Send WHOIS request
+```
+whois
+```
+Sends a WHOIS request (0f 00 01 02) to the connected SWAMP device. This is automatically sent when a device connects.
+
+### List sources or targets
+```
+list sources
+list targets
+```
+
+### Get help
+```
+help
+```
+
+### Exit
+```
+quit
+```
+
+## Architecture
+The controller works by impersonating a Crestron processor gateway, e.g. a Crestron CP3. The client
+is the SWAMP and it connects to our server which then establishes the communication link.
+
+```
+User Shell (REPL)
+       ↓
+Controller (orchestration)
+       ↓
+State Manager (zone/source mapping)
+       ↓
+Protocol Handler (pluggable)
+       ↓
+TCP Server (asyncio)
+```
+
+### Components
+
+- **Models**: Data classes for configuration and state
+- **Core**: Configuration loading, state management, orchestration
+- **Protocol**: Abstract protocol handler with stub implementation
+- **Network**: Asyncio TCP server for SWAMP device connections
+- **Shell**: Command parser and interactive REPL
+
+## Protocol Implementation
+The Protocol Handler partially implements the Crestron Internet Protocol (CIP), a proprietary protocol 
+for communication between Crestron devices. Only the message types for basic control of the SWAMP system
+are implemented.
+
+### Message Format
+All CIP messages follow this format:
+- **Byte 0**: Message type
+- **Bytes 1-2**: Remaining length (total bytes - 3) in big-endian
+- **Bytes 3+**: Payload
+
+Example: `0a 00 0a 00 51 a3 42 40 02 00 00 00 00`
+- Type: `0x0a` (CLIENT_SIGNON)
+- Length: `0x00 0x0a` = 10 bytes remaining
+- Payload: `00 51 a3 42 40 02 00 00 00 00` (10 bytes)
+- Total: 1 + 2 + 10 = 13 bytes
+
+### Implemented Messages
+- **WHOIS** (`0f 00 01 02`) - Sent automatically when client connects, also available via `whois` command
+- **PING** (`0d 00 02 00 00`) - Automatically detected and triggers PONG response. Sent periodically in the background.
+- **PONG** (`0e 00 02 00 00`) - Sent automatically in response to PING
+- **CLIENT_SIGNON** (`0a ...`) - Sent by device on connect, triggers CONN_ACCEPTED response
+- **CONN_ACCEPTED** (`02 00 04 00 00 00 03`) - Sent automatically in response to CLIENT_SIGNON
+- **JOIN** (`05 ...`) - The actual control messages for setting and getting information about the SWAMP
+
+### Unknown Message Handling
+Any message not recognized will be printed to the console in hex format, making it easy to discover and implement new message types.
+
+Example output:
+```
+Unknown message type ff (4 bytes): ff aa bb cc
+Recognized but unimplemented message type 0a (13 bytes): 0a 00 0a 00 51 a3 42 40 02 00 00 00 00
+```
+
+### Adding New Message Types
+To add support for a new message type, edit `swamp/protocol/swamp_protocol.py`:
+
+1. Add the message type to `decode_message()` dispatcher
+2. Create a `_decode_message_type_XX()` method
+3. Implement encoding methods if needed:
+   - `encode_route_command()` - Route audio source to zone
+   - `encode_volume_command()` - Set zone volume
+   - `encode_power_command()` - Control zone power
+
+## Development
+
+Run tests:
+```bash
+pytest
+```
+
+The test suite uses dynamic port allocation (via `get_free_port()`) to avoid conflicts with running instances of the controller.
+
+Enable debug logging:
+```bash
+python -m swamp --log-level DEBUG
+```
+
+Run on a different port:
+```bash
+python -m swamp --port 41795
+```
+
+## License
+
+Copyright © 2025

crestron_swamp_controller-1.0.0.dist-info/RECORD

@@ -0,0 +1,25 @@
+crestron_swamp_controller-1.0.0.dist-info/licenses/LICENSE,sha256=dMSjtMcKJMdiIDWu6JE39B2ax1nqNQOE0bCUtLM2Uq0,1062
+swamp/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+swamp/__main__.py,sha256=ZK3CudlshUda0T94nuYlhUkuRQ6Lmh6LG5e8XDxsgzE,4248
+swamp/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+swamp/core/config_manager.py,sha256=I-LJq750SVeaeOB9h17zFXVZUtPGJVX5Xz4fmJAm6Qk,942
+swamp/core/controller.py,sha256=m2TIEFHpmBhdhPo8X4NGhOgvoIPbVQ9pO4suM4e0oW4,4678
+swamp/core/state_manager.py,sha256=DftNTNNt3EkWgKO5zuolaxaEfKPmKgF_vPz2tSxN6hE,3201
+swamp/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+swamp/models/commands.py,sha256=xjDfHzP98yy0U3CKzYmsxD5h1Qz9QbN0pFv7kGLbRZ8,379
+swamp/models/config.py,sha256=OABJCUFC_j9ejPRrgjsybNA68V1d_qjFBcPkXONsRE4,499
+swamp/models/state.py,sha256=V-a-j_7kYBJYSgq6C0tnkahasU5sWehHEVtdQnNEsos,1222
+swamp/network/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+swamp/network/tcp_server.py,sha256=uIbhArXCbXPc7sNLTG1Npyk4Ws70JYwud9nw41hs-N4,10413
+swamp/protocol/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+swamp/protocol/base.py,sha256=x7GQWPlX-d2FkgS2q2m1VJ2gvw-e55DRmhF9iTqs6Jg,1295
+swamp/protocol/swamp_protocol.py,sha256=JtBEdfXO9rG3SCaTDNCz2rrp1faeGMZtt3DxiWHzCOw,11150
+swamp/shell/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+swamp/shell/commands.py,sha256=Wic5xjXQUW7q6aYjSiRRW9Rj3l-9O318Le-18FyuQY4,7578
+swamp/shell/parser.py,sha256=O6iZYyl9EG375eldcNyO2q7c4Yk__qVBPNQCG35VMCk,935
+swamp/shell/repl.py,sha256=d2z3WSRqKE2C0TXyiRaOy4cY9hbI1kiJKDOqJ8OBAu4,1731
+crestron_swamp_controller-1.0.0.dist-info/METADATA,sha256=bqpOSP2KaFAFpU6ndqeYLQ7NiqlO0ZnU0pTfeq1T8pw,8605
+crestron_swamp_controller-1.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+crestron_swamp_controller-1.0.0.dist-info/entry_points.txt,sha256=DcckC32qrpdJDe0nq8lovn-aTtRfCthhaZo1ET_AkdA,46
+crestron_swamp_controller-1.0.0.dist-info/top_level.txt,sha256=buHlyr_xSlQ015_eeHPs4NDqmjU_HhEiLCevIdeTAW0,6
+crestron_swamp_controller-1.0.0.dist-info/RECORD,,

crestron_swamp_controller-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

crestron_swamp_controller-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+swamp = swamp.__main__:main

crestron_swamp_controller-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 jaroy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

crestron_swamp_controller-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+swamp

swamp/__main__.py

@@ -0,0 +1,120 @@
+import argparse
+import asyncio
+import logging
+from pathlib import Path
+
+from swamp.core.config_manager import ConfigManager
+from swamp.core.state_manager import StateManager
+from swamp.core.controller import SwampController
+from swamp.protocol.swamp_protocol import SwampProtocol
+from swamp.network.tcp_server import SwampTcpServer
+from swamp.shell.parser import CommandParser
+from swamp.shell.commands import CommandHandlers
+from swamp.shell.repl import InteractiveShell
+
+
+def setup_logging(level: str):
+    """Setup logging configuration"""
+    numeric_level = getattr(logging, level.upper(), None)
+    if not isinstance(numeric_level, int):
+        raise ValueError(f'Invalid log level: {level}')
+
+    logging.basicConfig(
+        level=numeric_level,
+        format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+        datefmt='%Y-%m-%d %H:%M:%S'
+    )
+
+
+async def main_async():
+    """Main async entry point"""
+    parser = argparse.ArgumentParser(description='SWAMP Media Controller')
+    parser.add_argument('--port', type=int, default=41794,
+                       help='TCP port to listen on for SWAMP device (default: 41794)')
+    parser.add_argument('--config', type=Path,
+                       default=Path('config/config.yaml'),
+                       help='Path to configuration file (default: config/config.yaml)')
+    parser.add_argument('--log-level', choices=['DEBUG', 'INFO', 'WARNING', 'ERROR'],
+                       default='INFO', help='Logging level (default: INFO)')
+
+    args = parser.parse_args()
+
+    setup_logging(args.log_level)
+    logger = logging.getLogger(__name__)
+
+    logger.info('Starting SWAMP Controller')
+
+    try:
+        config = ConfigManager.load(args.config)
+        logger.info(f'Loaded config: {len(config.sources)} sources, {len(config.targets)} targets')
+    except Exception as e:
+        logger.error(f'Failed to load config: {e}')
+        return 1
+
+    protocol = SwampProtocol()
+    state_manager = StateManager(config)
+    tcp_server = SwampTcpServer(args.port, protocol, state_manager)
+    controller = SwampController(config, tcp_server, state_manager)
+
+    cmd_parser = CommandParser()
+    handlers = CommandHandlers(controller)
+
+    cmd_parser.register('route', handlers.cmd_route)
+    cmd_parser.register('volume', handlers.cmd_volume)
+    cmd_parser.register('power', handlers.cmd_power)
+    cmd_parser.register('status', handlers.cmd_status)
+    cmd_parser.register('whois', handlers.cmd_whois)
+    cmd_parser.register('list', handlers.cmd_list)
+    cmd_parser.register('help', handlers.cmd_help)
+
+    shell = InteractiveShell(cmd_parser, handlers)
+
+    print(f"SWAMP Controller v0.1.0")
+    print(f"Listening for SWAMP device on port {args.port}")
+    print(f"Type 'help' for available commands\n")
+
+    server_task = asyncio.create_task(tcp_server.start())
+
+    try:
+        await shell.run()
+    except KeyboardInterrupt:
+        logger.info('Interrupted by user')
+    finally:
+        logger.info('Shutting down')
+        # Close any active client connections first
+        if tcp_server.client_writer and not tcp_server.client_writer.is_closing():
+            try:
+                tcp_server.client_writer.close()
+                await asyncio.wait_for(
+                    tcp_server.client_writer.wait_closed(),
+                    timeout=1.0
+                )
+            except asyncio.TimeoutError:
+                logger.warning('Timeout waiting for client connection to close')
+            except Exception as e:
+                logger.debug(f'Error closing client connection: {e}')
+
+        # Cancel server task (the async with context will close the server)
+        server_task.cancel()
+        try:
+            await asyncio.wait_for(server_task, timeout=2.0)
+        except asyncio.CancelledError:
+            logger.debug('Server task cancelled successfully')
+        except asyncio.TimeoutError:
+            logger.warning('Timeout waiting for server to close')
+        except Exception as e:
+            logger.debug(f'Error during server shutdown: {e}')
+
+    return 0
+
+
+def main():
+    """Main entry point"""
+    try:
+        return asyncio.run(main_async())
+    except KeyboardInterrupt:
+        return 0
+
+
+if __name__ == '__main__':
+    exit(main())

swamp/core/config_manager.py

@@ -0,0 +1,36 @@
+import yaml
+from pathlib import Path
+from ..models.config import AppConfig, Source, Target, SwampZone
+
+
+class ConfigManager:
+    """Loads and validates configuration"""
+
+    @staticmethod
+    def load(config_path: Path) -> AppConfig:
+        """Load config from YAML file"""
+        with open(config_path) as f:
+            data = yaml.safe_load(f)
+
+        sources = [
+            Source(
+                id=s['id'],
+                name=s['name'],
+                swamp_source_id=s['swamp-source-id']
+            )
+            for s in data['sources']
+        ]
+
+        targets = [
+            Target(
+                id=t['id'],
+                name=t['name'],
+                swamp_zones=[
+                    SwampZone(unit=z['unit'], zone=z['zone'])
+                    for z in t['swamp-zones']
+                ]
+            )
+            for t in data['targets']
+        ]
+
+        return AppConfig(sources=sources, targets=targets)

swamp/core/controller.py

@@ -0,0 +1,120 @@
+import logging
+from ..models.config import AppConfig
+
+
+logger = logging.getLogger(__name__)
+
+
+class SwampController:
+    """Main coordinator - orchestrates all layers"""
+
+    def __init__(self, config: AppConfig, tcp_server, state_manager):
+        self.config = config
+        self.tcp = tcp_server
+        self.state = state_manager
+
+    async def route_source_to_target(self, source_id: str, target_id: str) -> None:
+        """High-level routing command"""
+        source = self.state.get_source_by_id(source_id)
+        zones = self.state.get_zones_for_target(target_id)
+
+        logger.info(f"Routing {source.name} to {target_id} ({len(zones)} zones)")
+
+        for zone_state in zones:
+            command_bytes = await self.tcp.protocol.encode_route_command(
+                zone_state.unit, zone_state.zone, source.swamp_source_id
+            )
+            await self.tcp.send_command(command_bytes)
+
+            zone_state.source_id = source.swamp_source_id
+
+    async def set_volume(self, target_id: str, level: int) -> None:
+        """Set volume for target"""
+        zones = self.state.get_zones_for_target(target_id)
+
+        logger.info(f"Setting {target_id} volume to {level} ({len(zones)} zones)")
+
+        for zone_state in zones:
+            command_bytes = await self.tcp.protocol.encode_volume_command(
+                zone_state.unit, zone_state.zone, level
+            )
+            await self.tcp.send_command(command_bytes)
+
+            zone_state.volume = level
+
+    async def set_power(self, target_id: str, power_on: bool, source_id: str | None = None) -> None:
+        """Set power for target (really just routes source to zone)
+
+        Power on requires a source_id. Power off sets source to 0.
+        """
+        zones = self.state.get_zones_for_target(target_id)
+
+        if power_on:
+            if not source_id:
+                raise ValueError("Power on requires a source_id")
+            # Power on = route source to zone
+            source = self.state.get_source_by_id(source_id)
+            swamp_source_id = source.swamp_source_id
+            logger.info(f"Powering on {target_id} with source {source_id} ({len(zones)} zones)")
+
+            for zone_state in zones:
+                # Use route command for power on (sets the actual source)
+                command_bytes = await self.tcp.protocol.encode_route_command(
+                    zone_state.unit, zone_state.zone, swamp_source_id
+                )
+                await self.tcp.send_command(command_bytes)
+                zone_state.power = True
+                zone_state.source_id = swamp_source_id
+        else:
+            # Power off = route source 0 (no source) to zone
+            logger.info(f"Powering off {target_id} ({len(zones)} zones)")
+
+            for zone_state in zones:
+                command_bytes = await self.tcp.protocol.encode_power_command(
+                    zone_state.unit, zone_state.zone, False
+                )
+                await self.tcp.send_command(command_bytes)
+                zone_state.power = False
+                zone_state.source_id = None
+
+    async def send_whois(self) -> None:
+        """Send WHOIS request to connected device"""
+        logger.info("Sending WHOIS request")
+        whois_bytes = await self.tcp.protocol.encode_whois()
+        await self.tcp.send_command(whois_bytes)
+
+    async def get_status(self) -> dict:
+        """Get current system status"""
+        state = self.state.state
+
+        # Calculate time since last message
+        time_since_last = None
+        if state.last_message_received:
+            from datetime import datetime
+            time_since_last = (datetime.now() - state.last_message_received).total_seconds()
+
+        return {
+            'connected': state.connected,
+            'socket_connected': state.socket_connected,
+            'conn_accepted_sent': state.conn_accepted_sent,
+            'client_address': state.client_address,
+            'last_message_seconds': time_since_last,
+            'targets': [
+                {
+                    'id': target.id,
+                    'name': target.name,
+                    'zones': [
+                        {
+                            'unit': z.unit,
+                            'zone': z.zone,
+                            'power': z.power,
+                            'volume': z.volume,
+                            'source': z.source_id,
+                            'source_received': z.source_received
+                        }
+                        for z in self.state.get_zones_for_target(target.id)
+                    ]
+                }
+                for target in self.config.targets
+            ]
+        }