# johnno/pydcm1 architecture

> Architecture diagram of the GitHub repository johnno/pydcm1, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/johnno/pydcm1
- Repository: https://github.com/johnno/pydcm1

## Overview

##### Project type and purpose
- This is a Python library (pydcm1) plus a small CLI tool (main.py) for controlling a Crestron-style Cloud DCM1 Zone Mixer over TCP/IP (with a serial-to-IP adapter).
- It exposes an asyncio-based API (in pydcm1/mixer.py and pydcm1/protocol.py), a low-level protocol parser/serializer (in pydcm1/protocol.py), an event listener (pydcm1/listener.py), and a CLI entry point (main.py).

##### File structure
- Top level:
- main.py: CLI driver
- example.py: sample usage script
- generate_expected_commands.py: helper to build or validate raw protocol commands
- test_protocol.py: unit tests for protocol parsing/formatting
- setup.py, setup.cfg, requirements.txt: packaging & deps
- Package pydcm1/:
- protocol.py – Handles framing, parsing, and serialization of TCP command strings
- mixer.py – High-level API (“DCM1Mixer”) that enqueues commands, issues queries, processes responses, exposes methods like set_zone_volume_level()
- listener.py – Callback interface for application code to subscribe to status/event updates

##### Key insights from README
- Uses asyncio for background heartbeat polling and command queueing with priorities
- Maintains persistent TCP connection, auto-reconnects
- Supports query & set operations for zones and sources
- Designed for embedding in home-assistant or other Python apps

a. Main components
1. CLI Layer: main.py
2. Example App Layer: example.py or any consumer application
3. Library Core
– Mixer Service (DCM1Mixer)
– Protocol Engine (Framer, Parser, Serializer)
– Event Listener / Dispatcher
4. Transport Layer
– Asyncio TCP Client (socket connection to serial-to-IP converter)
5. External Hardware
– Serial-to-IP converter
– DCM1 Zone Mixer

b. Relationships & data flow
- CLI Layer / App → calls Mixer Service methods
- Mixer Service → enqueues command in PriorityQueue → Protocol Engine
- Protocol Engine → writes framed command over Asyncio TCP
- DCM1 Hardware → responds over TCP → Protocol Engine parses → notifies Listener
- Listener → pushes status updates back into Mixer Service or directly to application callback

c. Architectural patterns & design principles
- Layered architecture: CLI/App → Service → Protocol → Transport → Hardware
- Command pattern: each mixer action encapsulated as a command object with priority
- Event-driven & async I/O: heartbeat polling, notifications via listener callbacks
- Separation of concerns: mixer logic separate from protocol parsing

d. Key technologies & libraries
- Python 3.x, asyncio, priority queue (heapq or asyncio.PriorityQueue)
- Packaging: setuptools (setup.py), requirements.txt
- Testing: pytest/unittest (test_protocol.py)

##### Detail
- PriorityQueue inside Mixer or as a sub-component of the core.
- Asynchronous event loop driving both outgoing commands and incoming responses.
- Automatic reconnection logic in the transport layer.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Application Layer"
        CLI["CLI Tool (main.py)"]:::app
        Example["Example App (example.py)"]:::app
    end

    subgraph "Library Core"
        Mixer["DCM1Mixer Service"]:::core
        PQ["PriorityQueue"]:::core
        Protocol["Protocol Engine"]:::core
        Listener["Event Listener / Dispatcher"]:::core
        EventLoop["Asyncio Event Loop"]:::core
    end

    subgraph "Transport Layer"
        TCPClient["Asyncio TCP Client"]:::transport
    end

    subgraph "External Hardware"
        Hardware["Serial-to-IP Adapter + DCM1 Hardware"]:::external
    end

    CLI -->|"calls methods"| Mixer
    Example -->|"calls methods"| Mixer
    Mixer -->|"enqueue_command()"| PQ
    PQ -->|"dispatch to"| Protocol
    Protocol -->|"send_frame() / receive_frame()"| TCPClient
    TCPClient -->|"TCP send/recv"| Hardware
    Hardware -->|"TCP response"| TCPClient
    TCPClient -->|"receive_frame()"| Protocol
    Protocol -->|"on_status_update()"| Listener
    Listener -->|"callback"| Mixer
    Listener -->|"callback"| Example
    EventLoop -->|"heartbeat_poll() / command queue"| Mixer
    EventLoop -->|"drives I/O"| TCPClient

    click CLI "https://github.com/johnno/pydcm1/blob/main/main.py"
    click Example "https://github.com/johnno/pydcm1/blob/main/example.py"
    click Mixer "https://github.com/johnno/pydcm1/blob/main/pydcm1/mixer.py"
    click Protocol "https://github.com/johnno/pydcm1/blob/main/pydcm1/protocol.py"
    click Listener "https://github.com/johnno/pydcm1/blob/main/pydcm1/listener.py"
    click TCPClient "https://github.com/johnno/pydcm1/blob/main/pydcm1/mixer.py"
    click generate "https://github.com/johnno/pydcm1/blob/main/generate_expected_commands.py"
    click test "https://github.com/johnno/pydcm1/blob/main/test_protocol.py"
    click setup_py "https://github.com/johnno/pydcm1/blob/main/setup.py"
    click setup_cfg "https://github.com/johnno/pydcm1/blob/main/setup.cfg"
    click req "https://github.com/johnno/pydcm1/blob/main/requirements.txt"

    classDef app fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef core fill:#E6FFDD,stroke:#28A745,color:#28A745;
    classDef transport fill:#FFE8CC,stroke:#D47A23,color:#D47A23;
    classDef external fill:#F0F0F0,stroke:#6A737D,color:#6A737D;
```
