Metadata-Version: 2.4
Name: crestron-nvx
Version: 0.2.0
Summary: Unofficial async Python client for Crestron DM NVX devices
Author: Dan Wilson
License-Expression: Apache-2.0
Project-URL: Documentation, https://github.com/Danw33/py-crestron-nvx#readme
Project-URL: Issues, https://github.com/Danw33/py-crestron-nvx/issues
Project-URL: Source, https://github.com/Danw33/py-crestron-nvx
Keywords: crestron,dm-nvx,av-over-ip,asyncio
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: yarl>=1.9.4
Provides-Extra: test
Requires-Dist: build>=1.2.2; extra == "test"
Requires-Dist: mypy>=1.15.0; extra == "test"
Requires-Dist: pytest>=8.3.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.25.0; extra == "test"
Requires-Dist: pytest-cov>=6.0.0; extra == "test"
Requires-Dist: ruff>=0.9.0; extra == "test"
Requires-Dist: twine>=6.1.0; extra == "test"
Dynamic: license-file

# crestron-nvx

[![CI](https://github.com/Danw33/py-crestron-nvx/actions/workflows/ci.yml/badge.svg)](https://github.com/Danw33/py-crestron-nvx/actions/workflows/ci.yml)
[![Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
![Python Version from PEP 621 TOML](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2FDanw33%2Fpy-crestron-nvx%2Frefs%2Fheads%2Fmain%2Fpyproject.toml)
[![PyPI Version](https://img.shields.io/pypi/v/crestron-nvx)](https://pypi.org/project/crestron-nvx)

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

> [!IMPORTANT]
> This is an independent, unofficial community project. It is not affiliated
> with, endorsed by, sponsored by, or supported by Crestron Electronics, Inc.
> Crestron, DigitalMedia, DM, DM NVX, and related names and marks are trademarks
> or registered trademarks of Crestron Electronics, Inc. in the United States
> and/or other countries. Their use here identifies compatible products only.
> Do not contact Crestron support for help with this library.

## 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](https://sdkcon78221.crestron.com/sdk/DM_NVX_REST_API/Content/Topics/API-Reference.htm)
- [DM NVX API authentication guide](https://sdkcon78221.crestron.com/sdk/DM_NVX_REST_API/Content/Topics/Authentication.htm)

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](docs/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:

| Model | Firmware 6.0 | Firmware 7.1 |
| --- | --- | --- |
| DM-NVX-350 | Supported; validation pending | Supported; hardware validated |
| DM-NVX-360 | Supported; validation pending | Supported; hardware validated |
| DM-NVX-E30 | Supported; hardware validated | Supported; validation pending |

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:

```console
python -m pip install crestron-nvx
```

For development:

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

## Usage

```python
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:

```console
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](https://github.com/Danw33))

Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) and [NOTICE](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.
