How johnno/pydcm1 works
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.