mx-remote 6.3.0__tar.gz → 8.0.2__tar.gz

{mx_remote-6.3.0 → mx_remote-8.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mx_remote
-Version: 6.3.0
+Version: 8.0.2
 Summary: Python 3 library for interfacing with MX Remote compatible devices
 Project-URL: Homepage, https://github.com/opdenkamp/mx-remote/
 Project-URL: Documentation, https://opdenkamp.github.io/mx-remote/

{mx_remote-6.3.0 → mx_remote-8.0.2}/docs/api.md

@@ -31,6 +31,60 @@ they are what the registry hands out and what a callback receives.
    :members:
 ```
 
+## Bay content
+
+What the source on an input is showing, and how much of it a unit keeps.
+
+```{eval-rst}
+.. autodata:: mx_remote.proto.Constants.BAY_CONTENT_KEY_MAX
+
+.. autodata:: mx_remote.proto.Constants.BAY_CONTENT_VALUE_MAX
+```
+
+## Overlay sync
+
+A management unit having other units copy its overlay captions, logo choice and
+place, backgrounds and logo images.
+
+```{eval-rst}
+.. autoclass:: mx_remote.proto.Constants.OsdSyncWhat
+   :members:
+
+.. autoclass:: mx_remote.proto.Constants.OsdSyncState
+   :members:
+
+.. autoclass:: mx_remote.proto.Constants.OsdSyncSize
+   :members:
+
+.. autoclass:: mx_remote.proto.Constants.OsdCaptionAlign
+   :members:
+
+.. autoclass:: mx_remote.proto.Constants.OsdCaptionFormat
+   :members:
+
+.. autoclass:: mx_remote.proto.Constants.OsdCaptionField
+   :members:
+
+.. autoclass:: mx_remote.proto.Constants.OsdLogoField
+   :members:
+
+.. autodata:: mx_remote.proto.Constants.OSD_SYNC_SLOTS
+
+.. autodata:: mx_remote.proto.Constants.OSD_SYNC_RECORDS_MAX
+
+.. autodata:: mx_remote.proto.Constants.OSD_SYNC_FONT_MAX
+
+.. autodata:: mx_remote.proto.Constants.OSD_SYNC_TEXT_MAX
+
+.. autodata:: mx_remote.proto.Constants.OSD_SYNC_IMAGE_MAX
+
+.. autodata:: mx_remote.proto.Constants.OSD_SYNC_IMAGE_WIDTH_MAX
+
+.. autodata:: mx_remote.proto.Constants.OSD_SYNC_IMAGE_HEIGHT_MAX
+
+.. autodata:: mx_remote.proto.Constants.OSD_SYNC_PERCENT_MAX
+```
+
 ## Device identity
 
 ```{eval-rst}
@@ -81,6 +135,9 @@ bit, and the range of the infrared profiles.
 .. autoclass:: mx_remote.OneIPPowerSaveSchedule
    :members:
 
+.. autoclass:: mx_remote.proto.Constants.OneIPPowerSaveLevel
+   :members:
+
 .. autoclass:: mx_remote.OneIPVlan
    :members:
 
@@ -94,6 +151,95 @@ bit, and the range of the infrared profiles.
 .. autodata:: mx_remote.proto.Constants.ONEIP_VLAN_ID_MAX
 ```
 
+## OneIP PTP
+
+A device's PTP settings, which it reports and a controller writes, and the PTP
+state only the device reports.
+
+```{eval-rst}
+.. autoclass:: mx_remote.OneIPPtpState
+   :members:
+
+.. autoclass:: mx_remote.proto.Constants.OneIPPtpMode
+   :members:
+
+.. autoclass:: mx_remote.proto.Constants.OneIPPtpFlag
+   :members:
+
+.. autoclass:: mx_remote.proto.Constants.OneIPPtpLock
+   :members:
+
+.. autodata:: mx_remote.proto.Constants.ONEIP_DEVICE_SETTINGS_PTP
+
+.. autoclass:: mx_remote.OneIPPtpMessages
+   :members:
+
+.. autodata:: mx_remote.proto.Constants.ONEIP_DEVICE_SETTINGS_PTP_MESSAGES
+
+.. autodata:: mx_remote.proto.Constants.ONEIP_DEVICE_SETTINGS_BLOCK
+
+.. autodata:: mx_remote.proto.Constants.ONEIP_STREAM_TTL_DEFAULT
+
+.. autodata:: mx_remote.proto.Constants.ONEIP_PTP_DOMAIN_MAX
+```
+
+## Unit status and commands
+
+A unit's health and IP configuration, and the commands sent to one unit.
+
+```{eval-rst}
+.. autoclass:: mx_remote.UnitStatus
+   :members:
+
+.. autoclass:: mx_remote.UnitNetConfig
+   :members:
+
+.. autoclass:: mx_remote.proto.Constants.UnitFlag
+   :members:
+
+.. autoclass:: mx_remote.proto.Constants.UnitCommandKind
+   :members:
+
+.. autoclass:: mx_remote.proto.Constants.UnitCommandFlag
+   :members:
+
+.. autodata:: mx_remote.proto.Constants.UNIT_MAX_TEMPERATURES
+
+.. autoclass:: mx_remote.proto.Constants.UnitPowerSave
+   :members:
+
+.. autodata:: mx_remote.proto.Constants.UNIT_POWER_SAVE_LEVELS
+```
+
+## OneIP session descriptions
+
+What an output plays from a session description, and how it is timed.
+
+```{eval-rst}
+.. autoclass:: mx_remote.OneIPSinkSdp
+   :members:
+
+.. autoclass:: mx_remote.proto.Constants.OneIPSdpFlag
+   :members:
+
+.. autoclass:: mx_remote.proto.Constants.OneIPSdpEncoding
+   :members:
+
+.. autoclass:: mx_remote.proto.Constants.OneIPSdpMediaClock
+   :members:
+
+.. autoclass:: mx_remote.proto.Constants.OneIPSdpRefClock
+   :members:
+
+.. autoclass:: mx_remote.proto.Constants.OneIPSdpClockMode
+   :members:
+
+.. autoclass:: mx_remote.proto.Constants.OneIPSdpClockState
+   :members:
+
+.. autodata:: mx_remote.proto.Constants.ONEIP_SDP_MAX
+```
+
 ## OneIP test card
 
 A sink's test pattern, tone and lip-sync flash, and the ranges it accepts.

{mx_remote-6.3.0 → mx_remote-8.0.2}/docs/callbacks.md

@@ -51,7 +51,7 @@ Available callback methods:
 | `on_status_signal_detected_changed` | signal detect status changed |
 | `on_status_faulty_changed` | fault status changed |
 | `on_status_hidden_changed` | hidden status changed |
-| `on_status_poe_powered_changed` | PoE power status changed |
+| `on_status_zone_powered_changed` | The amplifier zone a bay drives powered on or off (ProAmp8v2) |
 | `on_status_hdbt_connected_changed` | HDBaseT link status changed |
 | `on_status_signal_type_changed` | signal type changed |
 | `on_status_hpd_detected_changed` | hotplug detect changed |

mx_remote-8.0.2/docs/devices-and-bays.md

@@ -0,0 +1,94 @@
+# Devices and bays
+
+Naming, hiding, EDID and the device registry.
+
+## Device Management
+
+```python
+# reboot a device
+await device.reboot()
+
+# ask a device to hello now; False for one below protocol 0x2A
+await device.ping()
+
+# read the device log
+log = await device.get_log()
+
+# call an HTTP API endpoint on the device
+result = await device.get_api("system/status")
+```
+
+A device on protocol 0x2A pings a peer it suspects is gone and takes it
+offline when nothing answers within about 1.5s. The client answers a ping
+addressed to it with a hello at once, from any sender.
+
+## Bay Naming
+
+```python
+await bay.set_name("Living Room TV")
+```
+
+## Bay Visibility
+
+Hide or show bays:
+
+```python
+await bay.set_hidden(True)   # hide
+await bay.set_hidden(False)  # show
+```
+
+## EDID Profiles
+
+Change the EDID profile on input bays:
+
+```python
+from mx_remote import EdidProfile
+
+await bay.select_edid_profile(EdidProfile.TEMPLATE_1080P_STEREO)
+await bay.select_edid_profile(EdidProfile.TEMPLATE_4K_HDR_7_1)
+await bay.select_edid_profile(EdidProfile.LOWEST_COMMON_DENOMINATOR)
+```
+
+## Bay Content
+
+A unit with a source driver, such as the Sky Q one, reports what the source on
+an input is showing as named values, in the order they are meant to be shown:
+
+```python
+print(bay.content)                 # e.g. name='BBC One', number='101'
+print(bay.content.get('name'))     # None when the source reports no such value
+```
+
+The names are open-ended: a driver for a new kind of source adds its own, so
+pass on the ones you do not know. Each value is cleaned as a receiving unit
+cleans it, so it reads as the unit's own API shows it. The content outlives the
+signal, so check `signal_detected` before showing it. `on_bay_content_changed`
+reports a change, and an empty `content` is a source showing nothing.
+
+## Mesh Bays
+
+A OneIP unit lists the inputs and outputs of the other units in its mesh as
+bays of its own. Such a mesh bay stands for bay 0 in the same direction on the
+unit its `oneip_uid` names, and `is_local` is False for it.
+
+A mesh bay keeps only its identity: its port, `bay_name`, bay number, features
+and `oneip_uid`. Everything else - its user name, signal, status, routes and
+volume - is read from the bay it stands for, since what one unit reports about
+another unit's bay is a copy that is never refreshed. Until that unit has
+reported the bay, the rest reads as never reported. A change to the bay is
+reported for every mesh bay standing for it too, except its registration and
+the key presses and actions that arrive on it.
+
+A command about a mesh bay - a rename, hide, EDID profile, action, key,
+power, volume, zone settings or route - goes to the unit it stands for, about
+that unit's bay, and is refused while that unit has not reported the bay. A
+route names that unit as the sink, and its source by port in the numbering of
+the unit listing the mesh bay.
+
+Mesh bays are created by the unit's bay mappings, numbered by port in the
+unit's own numbering: from protocol 0x2B input n is port n and output n port
+127 + n; below it the first 16 bays of each direction come first.
+
+---
+
+[Documentation index](README.md) | [Project README](https://github.com/opdenkamp/mx-remote#readme)

{mx_remote-6.3.0 → mx_remote-8.0.2}/docs/oneip.md

@@ -107,9 +107,9 @@ output mode. Each is written behind its own validity bit, so moving one leaves
 the other where it is.
 
 ```python
-# what the sink reports. Trust this block only from a device whose hello carries
+# what the sink reports, read only from a device whose hello carries
 # CONFIG_INITIALISED - firmware without it builds the block over uninitialised
-# stack, where the valid bit itself is noise.
+# stack, where the valid bit itself is noise. No released build announces it.
 scaling = device.oneip_details.scaling
 print(scaling.auto_scaling)        # None when the sender did not say
 print(scaling.configured_mode)     # (signal type, refresh), None when it has none
@@ -133,6 +133,9 @@ in silence. Setting the mode first and turning automatic scaling back on
 afterwards is the order that survives, because the mode is checked while
 automatic scaling is still off.
 
+These are refused for a unit below protocol 0x2F: released firmware drops a
+scaling write from management.
+
 Nothing acknowledges any of these. `set_oneip_output_mode` returns False for a
 mode no sink would take, but a True only says the frame went out: the sink
 weighs the format against the display's EDID and against what its own output
@@ -222,6 +225,82 @@ goes out at 176 bytes: a receiver with the schedule ignores the settings of a
 shorter frame, and one whose settings end at the idle minutes takes it all the
 same.
 
+How far a device powers down is its power save level: reduced, low or off, each
+powering more down than the one before. Its unit status says which levels it
+supports and what wakes it at each.
+
+```python
+from mx_remote import OneIPPowerSaveLevel, UnitPowerSave
+
+print(settings.power_save_level)
+print(device.unit_status.power_save_level(OneIPPowerSaveLevel.LOW))  # e.g. SUPPORTED|INPUT_WAKE
+
+await device.set_oneip_power_save_level(OneIPPowerSaveLevel.LOW)
+```
+
+A level this library does not name is refused before it is sent, and not cached
+from another controller's write.
+
+`OneIPDeviceSetting.POWER_SAVE_DISABLED` is a switch that keeps a device from
+powering down by itself; a power save request still powers it down. A device
+that takes a power save level switches it off, so a level write, this client's
+or another sender's, clears it unless the same frame states it. Firmware
+without the bit never reports it, and the switch is refused there.
+
+### PTP
+
+A device's PTP mode, domain and grandmaster priority1 are settings like the
+others, each behind its own bit.
+
+```python
+from mx_remote import OneIPPtpMode
+
+print(settings.ptp_mode, settings.ptp_domain, settings.ptp_priority1)
+
+await device.set_oneip_ptp_mode(OneIPPtpMode.AUTO)   # follow, or lead when no one does
+await device.set_oneip_ptp_domain(0)                 # up to ONEIP_PTP_DOMAIN_MAX
+await device.set_oneip_ptp_priority1(128)            # lower wins
+```
+
+A mode this library does not name and a domain above `ONEIP_PTP_DOMAIN_MAX` are
+refused before they are sent, and not cached from another controller's write.
+
+How the device paces its PTP messages is five settings more, whose values
+travel in a block of their own: the announce, sync and delay request intervals
+as base-2 logarithms of seconds, the announce timeout and the messages' DSCP.
+
+```python
+from mx_remote import OneIPDeviceSetting, OneIPPtpMessages
+
+print(settings.ptp_messages)   # None until the device reports one of them
+
+await device.set_oneip_ptp_messages(
+    OneIPDeviceSetting.PTP_SYNC | OneIPDeviceSetting.PTP_DSCP,
+    OneIPPtpMessages(log_sync_interval=-3, dscp=46))   # 125 ms, EF
+```
+
+The SAP expiry in minutes and announcement interval in seconds travel in the
+same block, behind `SAP_EXPIRE` and `SAP_INTERVAL`, and are set the same way;
+`SAP_LISTEN` and `SAP_ANNOUNCE` are switches like the other on/off settings.
+A device with an encoder reports its streams' TTL there too, behind
+`STREAM_TTL`; a TTL of 0 is refused, as a device changes nothing for one.
+
+Only the values behind the bits named are sent. A DSCP above `ONEIP_DSCP_MAX` is
+refused, and not cached from another controller's write. A write carrying one of
+these runs on to 224 bytes, or 232 with the TTL; every other write keeps the 176
+every device knows.
+
+What the device's clock is actually doing is its PTP state, which only the
+device reports about itself and nothing writes:
+
+```python
+ptp = device.oneip_ptp        # None: no report yet, no PTP, or in power save
+if ptp is not None:
+    print(ptp.mode, ptp.domain, ptp.lock, ptp.port_state)   # port_state per IEEE 1588
+    print(ptp.followed)       # locked to a master since PTP started
+    print(ptp.grandmaster)    # its clock identity, None while there is none
+```
+
 ### VLAN
 
 A device that announces `DeviceFeature.VLAN` tags its uplink by a VLAN
@@ -282,6 +361,57 @@ falls outside them in silence: see `OneIPTestTone.is_valid()` and
 as the sink stops it regardless. The frame needs protocol 0x2B, so a sink
 announcing less is refused as well.
 
+### Session descriptions
+
+An output plays an AES67 stream from a session description it is handed, and
+reports what it plays when that changes and at least once a minute.
+
+```python
+await sink.play_oneip_sdp(sdp_text)     # sent in 1 KB pages, played once the last is in
+await sink.set_oneip_sdp_screen(1)      # what it shows while it plays audio alone
+await sink.request_oneip_sink_sdp()     # report now
+await sink.stop_oneip_sdp()
+
+print(sink.oneip_sink_sdp)   # None until the output has reported
+```
+
+An output takes these only from its mesh controller or a management
+application, which this client announces itself as, and only from protocol
+0x2E. A description is 1 to `ONEIP_SDP_MAX` bytes: an output drops a longer one
+after its last page, so one is refused before it is sent. Nothing acknowledges
+the pages; `oneip_sink_sdp` reads what the output reports next.
+
+### Overlay sync
+
+A management unit can have the other units copy its overlay captions, logo
+choice and place, backgrounds and logo images. Watching one between units:
+
+```python
+print(controller.osd_sync)         # the last sync it sent
+print(unit.osd_sync_report)        # taking, done, failed or deferred, and why
+```
+
+This client can send one too, which every unit then takes:
+
+```python
+from mx_remote import OsdCaption, OsdSyncContent, OsdSyncEntry, OsdSyncImage
+from mx_remote.proto.Constants import OsdCaptionField, OsdSyncWhat
+
+seq = await mx.send_osd_sync(OsdSyncContent(
+    what=OsdSyncWhat.CAPTIONS,
+    entries=(OsdSyncEntry(value=OsdCaption(text='Lobby'), set=OsdCaptionField.TEXT),),
+    images=None))                  # or four OsdSyncImage, served by this client
+await mx.resend_osd_sync(unit)     # one unit again
+await mx.clear_osd_sync()          # stop answering for it
+```
+
+Each unit asks for the settings it lacks and takes only those, so this client
+holds the content and answers until it is replaced or cleared, announcing
+itself meanwhile as the mesh's overlay sync manager: a unit waking from power
+save then takes this content rather than the controller's. Logo images are
+served over HTTP from this client, on `logo_port` or a free port. Content a unit
+would refuse is refused before anything is sent; see `send_osd_sync`.
+
 ### Every device at once
 
 One broadcast changes settings on every OneIP device of the mesh. Each device
@@ -300,7 +430,44 @@ await mx.set_all_oneip_device_settings(OneIPDeviceSettings(
 Nothing is cached from it: each device that applies a change reports its
 settings, and its `oneip_settings` reads that. What every device would ignore is
 refused rather than sent - no setting at all, one only a device reports about
-itself, a profile out of range, or a schedule time that is not a time of day.
+itself, a profile, PTP mode or PTP domain out of range, or a schedule time that
+is not a time of day.
+
+## Unit status and commands
+
+A unit on protocol 0x2C reports its health and IP configuration with its
+periodic broadcast, and within a few seconds of a change to its flags, status
+or addresses.
+
+```python
+from mx_remote import UnitFlag
+
+status = device.unit_status     # None until the unit has reported
+print(status.uptime, status.boot_count, status.reboot_count)
+print(status.network)           # address, netmask, gateway, two DNS servers
+print(status.fan_rpm, status.temperatures, status.status_message)
+print(UnitFlag.DHCP in status.flags, status.network_pending)
+```
+
+A unit takes a command only from its mesh controller or a management
+application, which this client announces itself as:
+
+```python
+from mx_remote import UnitNetConfig
+
+await device.clear_unit_status()
+await device.upgrade_unit_video_processor(force=False)
+await device.set_unit_network(UnitNetConfig(
+    ip='10.1.2.3', netmask='255.255.255.0', gateway='10.1.2.254', dns1='10.1.2.254'))
+await device.confirm_unit_network()    # keep it, once the unit reports it
+await device.set_unit_dhcp()
+```
+
+A changed IP configuration applies at once and reverts unless the mesh
+controller confirms it in time; `status.network_pending` says whether it still
+waits. Each command returns False without sending for a device that is not a
+OneIP unit, one below 0x2C, or an address and netmask a unit cannot hold.
+Nothing acknowledges a command: `unit_status` reads what the unit reports next.
 
 ## Mesh and firmware
 

{mx_remote-6.3.0 → mx_remote-8.0.2}/docs/routing.md

@@ -19,6 +19,12 @@ await output.select_video_source_by_user_name("Blu-ray")
 await output.select_audio_source(source=0)
 ```
 
+On a OneIP output the audio follows the video once the video is routed: a
+separate audio route is dropped, so route the audio after the video to keep the
+two apart. A unit below protocol 0x27 is told the source's audio stream
+instead, since some of those route no audio for "follow the video".
+`audio_source` reads the video source while the audio follows it.
+
 ---
 
 [Documentation index](README.md) | [Project README](https://github.com/opdenkamp/mx-remote#readme)