crestron-nvx

An unofficial async Python client for direct local communication with Crestron DM NVX AV-over-IP endpoints.

API provenance

This library implements Crestron's publicly documented DM NVX REST API. The authoritative external references are Crestron's public:

• DM NVX REST API reference
• DM NVX API authentication guide

Those references describe the API's HTTPS authentication, GET/POST methods, object paths, property types, and model-specific applicability. This repository does not copy or redistribute Crestron manuals, schemas, examples, firmware, or other proprietary material. The external documentation and device behaviour may change, and continued compatibility is not guaranteed.

See API_PROVENANCE.md for the project's source and fixture policy.

Status

Version 0.2 remains deliberately read-only. It authenticates over HTTPS and reads device identity, device-specific state, A/V I/O status, receive streams, and transmit streams. An allow-listed read method also supports safe exploration of documented objects such as Preview.

await client.async_get_preview_info() detects optional preview capability. await client.async_get_preview() returns NvxPreviewImage (JPEG bytes and dimensions), or raises NvxPreviewUnavailable when no local image is available. Other failures use existing typed API exceptions. Unsupported/string-valued objects are normal on old firmware. No firmware cutoff is assumed.

Only same-origin JPEG paths without redirects are accepted. Responses are limited to 2 MiB and bounded dimensions, with one authentication retry. Client operations are serialized to protect the session. Images are not persisted or logged. Preview display and updates have been validated through Home Assistant on a firmware 7.1 DM-NVX-360, including remote iOS viewing. Other models and physical outage/restart recovery remain to be validated.

No reboot, routing, input, mode, stream, or configuration write can be issued by this release.

The declared initial support scope is:

The parser detects capabilities from returned objects and fields. It does not reject other firmware versions, but versions outside this table are currently best-effort.

A DM-NVX-350 on 1.3707.00028 also passed authentication and API-shape probing; its string-valued Preview response is treated as unsupported. HA and lifecycle testing on this firmware remain pending.

Installation

Install the package from PyPI:

python -m pip install crestron-nvx

For development:

python -m pip install --editable '.[test]'

Usage

from aiohttp import ClientSession
from crestron_nvx import NvxClient

async with ClientSession() as session:
    client = NvxClient(
        session,
        "192.0.2.10",
        "username",
        "password",
        verify_ssl=False,
    )
    snapshot = await client.async_get_snapshot()
    print(snapshot.device.model)

verify_ssl=False accepts an endpoint without authenticating its certificate. This is often necessary for factory/self-signed DM NVX certificates, but an on-path device could then impersonate the endpoint and receive its credentials. Use that mode only on a trusted, isolated local network. Prefer verify_ssl=True whenever the endpoint certificate is trusted by the client host. Never log credentials, authentication cookies, raw device responses, or personally identifying endpoint data.

Development

Install the test dependencies and run:

ruff format --check .
ruff check .
mypy
pytest --cov=crestron_nvx --cov-report=term-missing
python -m build
twine check dist/*

Tests use small, invented fixtures that describe only the fields required to exercise library behaviour. Raw device responses must not be committed.

Licence

Copyright © 2026 Daniel Wilson (@Danw33)

Licensed under the Apache License, Version 2.0. See LICENSE and NOTICE. The licence covers this project's code and documentation; it does not grant rights to third-party trademarks, firmware, documentation, or other materials.

Crestron and DM NVX are trademarks of their respective owners.