mx-remote 9.4.0__tar.gz → 12.0.0__tar.gz

{mx_remote-9.4.0 → mx_remote-12.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mx_remote
-Version: 9.4.0
+Version: 12.0.0
 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-9.4.0 → mx_remote-12.0.0}/docs/api.md

@@ -13,8 +13,10 @@ the directive source as prose and the build still succeeds.
 
 ## Client
 
-`Remote` owns the socket, the device registry and the background probe that
-keeps both in step with the mesh.
+`Remote` owns the two endpoints, the device registry and the background probe
+that keeps both in step with the mesh. `reboot_all()`, `reboot_mesh()`,
+`factory_reset_all()`, `request_all_oneip_power_save()` and
+`upgrade_all_video_processors()` act on every unit at once.
 
 ```{eval-rst}
 .. automodule:: mx_remote.remote.Remote
@@ -126,6 +128,15 @@ The key and action codes a bay reports, and the target a key was aimed at.
    :members:
    :undoc-members:
 
+.. autoclass:: mx_remote.proto.Constants.RCStatus
+   :members:
+   :undoc-members:
+
+.. autoclass:: mx_remote.RCSettings
+   :members:
+
+.. autodata:: mx_remote.KEEP_REPORTED
+
 .. autodata:: mx_remote.proto.Constants.MXR_PROTOCOL_VERSION
 ```
 
@@ -185,6 +196,26 @@ How a device's output mixes 5.1 and 7.1 PCM down to stereo.
 .. autodata:: mx_remote.proto.Constants.ONEIP_DOWNMIX_LFE_MAX
 ```
 
+## OneIP locale
+
+The locale a device runs, by its name, such as `NL_NL`.
+
+```{eval-rst}
+.. autodata:: mx_remote.proto.Constants.ONEIP_LOCALE_MAX
+```
+
+## OneIP tiling
+
+The window a OneIP output takes for a video wall.
+
+```{eval-rst}
+.. autodata:: mx_remote.proto.Constants.ONEIP_TILING_X_STEP
+
+.. autodata:: mx_remote.proto.Constants.ONEIP_TILING_WIDTH_STEP
+
+.. autodata:: mx_remote.proto.Constants.ONEIP_TILING_MIN
+```
+
 ## OneIP PTP
 
 A device's PTP settings, which it reports and a controller writes, and the PTP
@@ -357,6 +388,27 @@ The time zone and clock a mesh controller announces.
    :members:
 ```
 
+## Mesh control
+
+The operations a mesh controller sends, and what a controller announces.
+
+```{eval-rst}
+.. autoclass:: mx_remote.MeshOperationMessage
+   :members:
+
+.. autoclass:: mx_remote.MeshControllerReport
+   :members:
+
+.. autoclass:: mx_remote.proto.Constants.MeshOperation
+   :members:
+
+.. autodata:: mx_remote.proto.Constants.ONEIP_SOURCE_FILTER_MAX
+
+.. autodata:: mx_remote.proto.Constants.MXR_RC_STATUS_MAX
+
+.. autodata:: mx_remote.proto.FrameV2IPSources.ONEIP_SOURCE_LIST_MAX
+```
+
 ## Names from before OneIP
 
 Releases up to 5.11 used the firmware's internal names in the public API: V2IP

mx_remote-12.0.0/docs/audio.md

@@ -0,0 +1,98 @@
+# Audio
+
+Volume, mute and remote-control passthrough.
+
+## Volume Control
+
+```python
+bay.volume_up()
+bay.volume_down()
+bay.volume_set(volume=50)           # set to 50%
+bay.volume_set(volume=50, muted=False)
+bay.mute_set(mute=True)
+```
+
+## Audio endpoints
+
+A OneIP device reports its audio endpoints, each with its features and a status
+word on the same bits: `FEATURE_MUTE` while it is muted, `FEATURE_TRIGGER`
+while its trigger is active, and `FEATURE_AUDIO_LOCK` while its audio source is
+locked.
+
+```python
+ep = device.audio_endpoint_by_id(1)
+print(ep.features, ep.status, ep.audio_locked)
+
+# keep the endpoint's audio source when the video route changes
+await device.set_audio_endpoint_locked(1, True)
+```
+
+Only an endpoint whose features include `FEATURE_AUDIO_LOCK` is written, since
+the device ignores the rest. Once the frame is away `audio_locked` reads the new
+lock, until the device reports its endpoints again. A report whose only change
+is a status, the routing or the device's own address fires the device's
+callbacks.
+
+`device.audio_endpoints.address` is the device's own address and HTTP port, as
+its report gives them. `device.audio_reported` is when its last report was
+taken, as `time.time()` read it.
+
+### What a command holds
+
+For 500 ms after an audio command to a device, its features and links reports
+are ignored, so one it sent before it took the command cannot undo what the
+command set. The report after that replaces it.
+
+## Audio routes
+
+A route can run from an endpoint on one unit to an endpoint on another, such as
+an encoder's HDMI input to a decoder's HDMI output. Every unit owning an
+endpoint on the way switches its own hops, and each finds the path itself from
+the two units' endpoint tables. `audio_route()` finds the same path and returns
+it hop by hop from the source, or `None` when there is none:
+
+```python
+hops = mx.audio_route(decoder.remote_id, 3, encoder.remote_id, 2)
+for hop in hops:    # AudioHop(sink_device, sink, source_device, source)
+    print(hop)
+
+await mx.select_audio_endpoint_input(decoder.remote_id, 3, encoder.remote_id, 2)
+```
+
+`select_audio_endpoint_input()` sends the request to every unit on the path,
+from the sink's end, and each unit's own hops read routed once its frame is
+away. It is refused, sending nothing, when no reported path leads from the
+source to the sink, and when the path reaches a unit on released firmware up to
+4.4.2 from another unit, since such a unit routes only between its own
+endpoints. An output bay's `select_audio_source(source, endpoint=...)` goes the
+same way.
+
+The path is searched back from the sink, within the sink's unit, depth first.
+An endpoint takes the source directly when it is routed from the source's
+endpoint id, or when it receives a OneIP stream and the source sends one.
+Otherwise the endpoints it is routed from are tried in ascending id, a later
+one kept only when its path is strictly shorter. Failing that, the source
+unit's first sending endpoint feeds the sink unit's first receiving one.
+
+## Remote Control
+
+Send remote control key presses and actions:
+
+```python
+from mx_remote import RCKey, RCAction
+
+# send a key press
+await bay.send_key(RCKey.KEY_SELECT)
+await bay.send_key(RCKey.KEY_UP)
+
+# send a remote control action
+await bay.tx_action(RCAction.ACTION_POWER_ON)
+await bay.tx_action(RCAction.ACTION_POWER_OFF)
+await bay.tx_action(RCAction.ACTION_POWER_TOGGLE)
+await bay.tx_action(RCAction.ACTION_VOLUME_UP)
+await bay.tx_action(RCAction.ACTION_VOLUME_DOWN)
+```
+
+---
+
+[Documentation index](README.md) | [Project README](https://github.com/opdenkamp/mx-remote#readme)

{mx_remote-9.4.0 → mx_remote-12.0.0}/docs/callbacks.md

@@ -41,6 +41,7 @@ Available callback methods:
 | `on_device_config_changed` | device configuration updated |
 | `on_device_config_complete` | all device configuration received |
 | `on_device_online_status_changed` | device went online/offline |
+| `on_device_unregistered` | device forgotten after three offline windows of silence |
 | `on_device_temperature_changed` | temperature readings changed |
 | `on_bay_registered` | new bay discovered |
 | `on_video_source_changed` | video routing changed |
@@ -68,6 +69,7 @@ Available callback methods:
 | `on_amp_zone_settings_changed` | amplifier zone settings changed |
 | `on_amp_dolby_settings_changed` | amplifier Dolby settings changed |
 | `on_third_party_message` | another application sent a message under its vendor id |
+| `on_mesh_operation` | a device sent a mesh operation other than a membership or controller report |
 
 You can also register per-device and per-bay callbacks:
 

{mx_remote-9.4.0 → mx_remote-12.0.0}/docs/configuration.md

@@ -6,28 +6,46 @@ Opening a connection and keeping it in step with the mesh.
 
 ### Remote
 
-`Remote` is the main entry point. It manages the UDP connection (multicast or broadcast), handles device discovery, and maintains a registry of all discovered devices.
+`Remote` is the main entry point. It manages the UDP connection, handles device discovery, and maintains a registry of all discovered devices.
 
 ```python
-# default: multicast on 224.8.8.8:8812
+# both endpoints a unit has: the group 224.8.8.8:8812 and the subnet broadcast on 8811
 mx = mx_remote.Remote()
 
-# use broadcast instead
-mx = mx_remote.Remote(broadcast=True)
-
 # bind to a specific network interface
 mx = mx_remote.Remote(local_ip="192.168.1.100")
 
-# custom target address and port
-mx = mx_remote.Remote(target_ip="10.8.8.255", port=8811)
+# tests and development only: one endpoint on a scratch address in place of both
+mx = mx_remote.Remote(target_ip="239.255.77.90", port=18890)
 
 # offline mode for processing capture files
 mx = mx_remote.Remote(open_connection=False)
 
 # separate identity, to run concurrent clients from one account
 mx = mx_remote.Remote(uid_path="/var/lib/myapp/.mxr-uid")
+
+# a mesh device that can take the controller role, under its own serial and version
+mx = mx_remote.Remote(mesh_device=True, serial="P9SN66660600", version="1.2.3")
 ```
 
+Each frame leaves by the endpoints a unit picks for it:
+
+- a frame for every unit at once goes to both: a discover, reboot or factory
+  reset of every unit, the monitoring pulse, bay detection and the video
+  processor upgrade;
+- the hello goes to both when it is the first since the sockets opened, or the
+  last one there went 30 s ago or more;
+- a frame meant for one device alone, such as a ping or a remote-control
+  action, goes by the endpoint that device is heard by;
+- every other frame goes to the group, and to the broadcast address as well
+  while some peer has not been heard by multicast for two minutes or reports
+  that its multicast fails.
+
+A peer heard only by broadcast in that time has this client announce
+`DeviceFeature.STATUS_MCAST_FAULT` itself, at once. A datagram arriving by both
+endpoints within 100 ms is acted on once. `broadcast=` is deprecated and
+ignored.
+
 The uid at `uid_path` (default `~/.mxr-uid`) is this client's identity on the mesh:
 addressing is by uid in the payload, and a frame carrying our own uid is dropped as
 an echo. Two clients sharing a uid are one peer to every device and each silently
@@ -37,6 +55,13 @@ discards everything the other sends, so give concurrent clients separate paths.
 
 A `DeviceBase` represents a physical device on the network (a Pulse-Eight neo matrix, OneIP unit, or ProAmp8 amplifier). Devices are automatically registered when they respond to discovery requests.
 
+The registry is kept as a unit keeps its own. Every frame from a live device
+keeps it alive, and only a hello brings back one gone silent. A device silent
+for three times the window that takes it offline is forgotten:
+`on_device_unregistered` fires, and a hello from it later registers it as a new
+device. `mx.device_tree` lists every device and this client as a unit lists
+them: depth first, each under the device whose topology report names it.
+
 ```python
 # look up a device by serial number or unique ID
 device = mx.get_by_serial("AB1234")
@@ -49,7 +74,14 @@ device.model_name      # model (e.g. "neo:8", "OneIP Transmitter")
 device.address         # IP address
 device.version         # firmware version
 device.online          # True if responding
+device.bays_online     # online, and its bays have arrived since it was heard,
+                       # rebooted or went offline, as a unit judges it
+device.multicast       # heard by multicast in the last two minutes; None on one endpoint
 device.status          # DeviceStatus enum (ONLINE, OFFLINE, REBOOTING, BOOTING, INACTIVE)
+device.raw_name        # name, version and serial as the bytes announced,
+device.raw_version     # never substituted or decoded
+device.raw_serial
+device.igmp_querier    # the IGMP querier its last uplink report names, or None
 device.features        # DeviceFeatures bitmask
 device.config_initialised  # False if the device broadcasts config blocks built from
                            # uninitialised memory; scaling, bay 0 addresses and the
@@ -97,6 +129,7 @@ bay.hidden           # hidden from UI
 bay.online           # device is online
 bay.features         # BayFeaturesMask
 bay.status           # DeviceStatus enum
+bay.status_word      # the whole BayStatusMask as last sent, or None
 
 # video/audio routing (output bays)
 bay.video_source              # currently selected video source bay
@@ -119,10 +152,7 @@ Update connection settings at runtime:
 
 ```python
 await mx.update_config(
-    target_ip="10.8.8.255",
-    port=8811,
     local_ip="192.168.1.100",
-    broadcast=True,
     callbacks=MyCallbacks(),
     name="My Application",
 )

{mx_remote-9.4.0 → mx_remote-12.0.0}/docs/devices-and-bays.md

@@ -20,14 +20,20 @@ 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.
+addressed to it with a hello at once, from a device it has heard, as a unit
+does.
 
 ## Bay Naming
 
 ```python
 await bay.set_name("Living Room TV")
+await bay.set_name("")     # back to the default name the unit picks
 ```
 
+An empty name asks the unit to reset the bay to its default. The unit picks
+that name itself, so the bay keeps its current name until the unit reports the
+new one in its next bay list.
+
 ## Bay Visibility
 
 Hide or show bays:
@@ -65,6 +71,32 @@ 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.
 
+## Signal and Connected Device
+
+`signal_type` is a description written for display. `video_details` holds the
+parts it is written from, so a caller can name the signal its own way:
+
+```python
+d = bay.video_details
+if d is not None and d.from_report:
+    print(d.width, d.height, d.colour, d.bpp, d.interlaced, d.hdr)
+```
+
+A signal status report carries all of them for a valid stream, with `svd` 0 and
+the measured size for a stream whose mode the CTA table lacks. The bay config
+snapshot, which `video_details` falls back to, carries no size or flags, and
+leaves them None.
+
+A unit reports the Pulse-Eight device connected to a bay, such as an amplifier
+on a matrix output, in the long form of its connect frame:
+
+```python
+if (p8 := bay.p8_device) is not None:
+    print(p8.model, p8.serial, p8.version, p8.ip)
+```
+
+It is None after a short or a disconnecting connect frame.
+
 ## Mesh Bays
 
 A OneIP unit lists the inputs and outputs of the other units in its mesh as

{mx_remote-9.4.0 → mx_remote-12.0.0}/docs/diagnostics.md

@@ -14,14 +14,21 @@ for port_id, port_status in device.network_status.items():
         print(f"  IP: {port_status.ip}")
     if port_status.mac_address:
         print(f"  MAC: {port_status.mac_address}")
+    if port_status.uplink:
+        print("  the device's uplink")
+    if port_status.video_link:
+        print("  carries video")
 ```
 
+`uplink` and `video_link` are read from protocol 0x22; an older report marks
+neither.
+
 ## CLI Application
 
 The `mxr` console application is installed with the package. It discovers devices and logs all received frames in human-readable form.
 
 ```
-usage: mxr [-h] [-i INPUT] [-f FILTER] [-o OUTPUT] [-l LOCAL_IP] [-b]
+usage: mxr [-h] [-i INPUT] [-f FILTER] [-o OUTPUT] [-l LOCAL_IP]
 
 MX Remote Manager / Debugger
 
@@ -31,9 +38,11 @@ options:
   -f FILTER     only log frames from this ip address
   -o OUTPUT     write output to a file
   -l LOCAL_IP   local ip address of the network interface to use
-  -b            use broadcast mode instead of multicast
 ```
 
+`mxr` always runs both endpoints a unit has, the multicast group and the subnet
+broadcast. `-b` is still accepted, and ignored.
+
 ### Examples
 
 ```bash
@@ -43,9 +52,6 @@ mxr
 # bind to a specific network interface
 mxr -l 192.168.1.100
 
-# use broadcast mode
-mxr -b
-
 # log output to a file
 mxr -o /path/to/output.txt
 

{mx_remote-9.4.0 → mx_remote-12.0.0}/docs/oneip.md

@@ -32,6 +32,12 @@ if device.oneip_details:
     if details.dscp and details.dscp.complete:
         print(f"DSCP: {details.dscp}")     # video / audio / anc, 0..63
 
+# mark a source's three streams; a unit takes a marking only for all three at
+# once, so a partial one or one above ONEIP_DSCP_MAX is refused before sending,
+# as is a device that announces no source. Read back from oneip_details.dscp
+# until the device reports its own.
+await device.set_oneip_dscp(mx_remote.OneIPDscpConfig(video=46, audio=34, anc=26))
+
 # streaming statistics
 # The subscription lapses 60s after the request and there is no free-running
 # mode, so call this again inside the minute to keep the 1Hz reports coming.
@@ -125,6 +131,11 @@ await device.set_oneip_output_mode(mode)
 await device.set_oneip_auto_scaling(True)    # back on, if that is what you want
 
 await device.clear_oneip_output_mode()       # the only way to say "no mode"
+
+# skip the check that the display lists 4:2:0; one validity bit covers this and
+# match-source, so the write restates match-source as the sink last reported it
+print(scaling.skip_420, scaling.match_source)
+await device.set_oneip_skip_420(True)
 ```
 
 **Set the mode with automatic scaling off.** A sink scaling automatically
@@ -240,8 +251,16 @@ print(device.unit_status.power_save_level(OneIPPowerSaveLevel.LOW))  # e.g. SUPP
 
 await device.set_oneip_power_save(True)
 await mx.set_all_oneip_power_save(False)   # every OneIP device of the mesh
+
+# ask for the state now, as a mesh controller does, rather than the setting
+await device.request_oneip_power_save(True)      # 0x41 naming the unit
+await mx.request_all_oneip_power_save(False)     # 0x41 with the flag alone
 ```
 
+A power save request reaches a unit only from its mesh controller or a
+management application, and one that cannot power down ignores it. A unit tells
+the two forms apart by their exact length.
+
 Switched off, `OneIPDeviceSetting.POWER_SAVE_DISABLED` is on: the device does
 not power down by itself, and a power save request still powers it down.
 Switching on is written as a mesh controller writes it, with that switch clear
@@ -335,7 +354,10 @@ the LFE channel is mixed in at, which a controller writes, and the state and
 channel count, which only the device reports. A device that reports none has
 no downmix to set, so a write to one is refused, as is a mode, level or LFE
 percent out of range. The write sends the mode, level and LFE together; the
-state and channels are never sent.
+status, whether the stream is mixed down now, is the device's own and never
+sent. After this client's write it is None until the device reports how it
+mixes the new settings; another controller's write keeps the status the device
+reported.
 
 ```python
 from mx_remote import OneIPDownmix
@@ -344,7 +366,8 @@ from mx_remote.proto.Constants import OneIPDownmixMode, OneIPDownmixLevel
 downmix = device.oneip_downmix    # None: no report yet, or no downmix
 if downmix is not None:
     print(downmix.mode, downmix.level, downmix.lfe)   # LFE up to ONEIP_DOWNMIX_LFE_MAX
-    print(downmix.state, downmix.channels)            # the device's own
+    if downmix.status is not None:                    # the device's own
+        print(downmix.status.state, downmix.status.channels)
     await device.set_oneip_downmix(OneIPDownmix(mode=OneIPDownmixMode.AUTO,
                                                 level=OneIPDownmixLevel.NORMALISED, lfe=50))
 ```
@@ -352,6 +375,42 @@ if downmix is not None:
 The downmix ends the settings block, behind a second valid word, so the write
 runs on to 248 bytes and carries no other setting.
 
+### Locale
+
+A device whose firmware has locales reports the one it runs by its name, such
+as `NL_NL`: up to `ONEIP_LOCALE_MAX` bytes, NUL padded, at the end of its
+settings block, behind the preview group.
+
+```python
+print(device.oneip_locale)        # 'EN_UK', or None: no report yet, or no locales
+await device.set_oneip_locale('NL_NL')
+```
+
+A device stores a locale it knows and ignores one it does not, so the write goes
+also to a device that has not reported its settings yet, and the locale is
+cached once sent until the device's next report. The write runs on to 256
+bytes, as a device takes a locale only from a block that holds the whole name.
+Refused before sending: a name that is empty, longer than `ONEIP_LOCALE_MAX`
+bytes or not printable ASCII, and a device whose settings arrived without a
+locale, as its firmware has none. Another controller's write reaches only a
+device that reports a locale.
+
+### Live preview
+
+A device whose firmware sends a live preview names the multicast group it sends
+it to at the end of its settings block. The preview is RFC 2435 RTP/JPEG on
+UDP port `ONEIP_PREVIEW_PORT` (50024), after the stream ports.
+
+```python
+from mx_remote.proto.Constants import ONEIP_PREVIEW_PORT
+
+print(device.oneip_preview)       # '239.7.8.9', or None: no report, or no preview
+```
+
+Only the device's own report names it; another sender's configuration about the
+device leaves it alone. A group of 0, or a block too short to hold one, is
+firmware that sends no preview.
+
 ### VLAN
 
 A device that announces `DeviceFeature.VLAN` tags its uplink by a VLAN
@@ -368,12 +427,18 @@ print(vlan.device, vlan.port, vlan.pinned_uplink_port, vlan.active_uplink_port)
 print(vlan.is_pending, vlan.revert_s)
 
 await device.set_oneip_vlan(OneIPVlan(device=10, port=(0, 20, 0), uplink=2))
+if device.oneip_vlan.is_pending:
+    await device.confirm_oneip_vlan()   # keep it, as the mesh controller does
 ```
 
 Only the device knows what it runs, so `oneip_vlan` is read only from the device
 describing itself, and a write is not cached. The device applies a change at
 once and reverts it after `revert_s` seconds unless the mesh controller, hearing
-it report the change as pending, confirms it.
+it report the change as pending, confirms it. `confirm_oneip_vlan()` sends that
+confirmation: the pending configuration echoed with its trunk bit and CONFIRM. A
+device repeats its report every 3 s while the change is pending, so a
+confirmation lost or sent twice is answered by the next report. Refused unless
+the device announces the VLAN feature and last reported a pending change.
 
 Only the ids, the uplink and the trunk bit are written. Refused before sending:
 a device without the VLAN feature or that has not reported its configuration, an
@@ -384,7 +449,7 @@ frame it already understood.
 
 ### Test pattern, tone and lip-sync
 
-A sink whose video processor reports `OneIPVideoProcessorFeature.SINK_TEST_PATTERN` draws a
+A sink whose video processor reports `OneIPVideoProcessorFeature.RTOS` draws a
 test card on its output: a pattern, a test tone, and a lip-sync flash that marks
 a frame and beeps a set number of sample periods after it.
 
@@ -471,6 +536,11 @@ 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`.
 
+A caption setting with `OsdCaptionField.DEFAULT_TEXT` in place of
+`OsdCaptionField.TEXT`, and no text, sends a unit back to its layout's default
+caption, drawn in its own locale. A unit whose firmware predates it keeps the
+text it has.
+
 ### Overlay messages
 
 A unit shows a message on its output, over the picture, until it restarts. The
@@ -509,6 +579,11 @@ await mx.request_all_oneip_privacy()    # every source unit of the mesh
 print(source.oneip_privacy)   # None until the unit has reported
 ```
 
+The video processor picks a new key generator every boot, so a hello showing
+the unit may have restarted - it was offline, flipped its reboot toggle or is
+about to reboot - drops the report, and `oneip_privacy` reads None until the
+unit reports again.
+
 A request to a unit that is not a source, or that is below protocol 0x30, is
 refused before it is sent.
 
@@ -557,6 +632,7 @@ from mx_remote import UnitNetConfig
 
 await device.clear_unit_status()
 await device.upgrade_unit_video_processor(force=False)
+await mx.upgrade_all_video_processors()    # every unit, flashing only a differing image
 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
@@ -568,6 +644,9 @@ await device.stop_locating_unit()
 A unit is located only once its status carries `UnitFlag.LOCATE_SUPPORTED`. Its
 board-ID LED flashes and an output shows "Locate Device"; `UnitFlag.LOCATE` in
 the cached status says so from the moment the command is sent.
+`UnitFlag.FIRMWARE_UPGRADE` says the update service offered the unit a firmware
+upgrade, and `UnitFlag.UPGRADE_INSTALLING` that it is writing one to its flash,
+with its picture gone until it restarts.
 
 A changed IP configuration applies at once and reverts unless the mesh
 controller confirms it in time; `status.network_pending` says whether it still
@@ -595,6 +674,99 @@ the source's next configuration report carries the addresses it ends up with, in
 `oneip_details`. A device that is not a source, or announces less than protocol
 0x2B, would ignore the operation, so it is refused before anything is sent.
 
+### Taking the controller role
+
+A client can stand in for a unit as mesh controller. It announces itself as a
+mesh device rather than a management application, so a mesh takes it as a
+member, and under a serial and version of its own so the device list tells it
+apart from the unit it replaces. A unit counts a mesh device without bays as a
+member only under a serial that is `P9SN00000000` or does not start `P9SN0000`:
+
+```python
+from mx_remote import MeshOperationMessage
+
+mx = mx_remote.Remote(mesh_device=True, serial='P9SN66660600', version='1.2.3')
+mx.set_mesh_controller(mx.uid)      # follow itself as controller; None for none
+mx.set_mesh_bays_mapped(True)       # the role is announced only with bays mapped
+await mx.send_mesh_operation(MeshOperationMessage.report_controller(mx.uid, priority=1, installer=0x1234))
+await mx.send_mesh_operation(MeshOperationMessage.register(unit.remote_id, mx.uid))
+await mx.send_oneip_source_list(sources)   # the mesh's whole source list
+await mx.set_mesh_setup_completed(True)
+await mx.set_mesh_installer(0x1234)
+
+await output.set_oneip_mirroring(other_output)   # None to stop
+await output.set_oneip_source_filter([source.remote_id])
+await output.set_oneip_tiling(pos_x=0, pos_y=0, width=1920, height=1080)
+await unit.set_rc_settings(rc_target=RCType.CEC, ip=None, cec_enabled=True, cec_auto_on=True,
+                           forward_rc=True, forward_ir=False)
+await unit.set_rc_settings(forward_ir=True)      # the rest as the unit reported
+```
+
+The tiling window is in pixels of the decoded source picture: the output crops
+it out and scales it up. A width or height of 0 shows the whole picture. An
+output ignores, without a word, a window whose `pos_x` is not a multiple of
+`ONEIP_TILING_X_STEP` (64), whose width is not a multiple of
+`ONEIP_TILING_WIDTH_STEP` (4), or whose sides are under `ONEIP_TILING_MIN` (64),
+so the library refuses those before sending. The output keeps a window in
+memory only and does not report it: a reboot, a stream restart or a change of
+source format drops it.
+
+Every unit reports its remote control settings itself, periodically and right
+after a change, and `unit.rc_settings` holds the last report (an `RCSettings`).
+A report is what runs, not what is stored: `rc_type` is the driver in use, and
+the CEC switches read False while the unit's CEC module is not loaded. A
+setting `set_rc_settings()` is not given, or `ip` left at `KEEP_REPORTED`, is
+sent as last reported, so it can store what runs; it is refused until the unit
+has reported.
+
+`set_mesh_controller()` changes only the announcement, at once: membership
+while there is a controller, and the controller role while it is this client
+and `set_mesh_bays_mapped()` says it has bays, as a unit announces it.
+`mx.features` is what the hello announces as of now. `send_oneip_detect_bays()`
+asks every unit to detect its bays, which current firmware ignores.
+Membership reports and the units that follow this client are the caller's to
+keep in step. A mesh device's writes reach a unit only while that unit follows
+it as its controller.
+
+A unit named in a source list, hearing it from the controller it follows,
+registers every unit listed and unregisters every source unit that is not, so
+the list must always be complete. A list longer than 36 entries goes in
+numbered pages.
+
+What is set on an output is held once the frame is away: `mirroring` and
+`filtered` on its output bay read it until the output reports again. Each write
+is refused before anything is sent where a unit would drop it: a device that is
+not a OneIP output (or unit, for remote control settings), an output whose bay
+has not been reported, an output mirroring itself, a filter longer than
+`ONEIP_SOURCE_FILTER_MAX` (89), or a field that does not fit its width.
+
+A controller routes an output unit by the streams a source unit advertises for
+its own input, so the output plays them whether or not it lists the source:
+
+```python
+await output.route_oneip_unit(source)                    # audio follows the video
+await output.route_oneip_unit(source, audio=other)       # audio from another unit's input
+await output.route_oneip_unit(source, power_on=False)    # leave the display as it is
+await output.route_oneip_unit_with_arc(source, tv_unit)  # audio from tv_unit's audio return
+await output.unroute_oneip_unit()                        # names no streams
+```
+
+Each powers the output's display on with the switch unless `power_on=False`. An
+output below protocol 0x27 is told the source's own audio rather than none, as
+`select_video_source()` does. `route_oneip_unit_with_arc()` names the audio
+return group the other unit last reported in `oneip_details.arc`. The output
+resolves that group to the other unit's audio return, but audio return is
+compiled out of OneIP firmware, so such a route plays no audio. It is what a
+controller sends all the same. A route is refused
+before anything is sent where the device is not a OneIP output, a source has no
+input of its own or has not reported its stream addresses, or the other unit has
+not reported a usable audio return group.
+
+A unit's controller report is kept as `device.mesh_controller_report`, and its
+membership report as `mesh_master`. Every other mesh operation a device sends
+arrives at `MxrCallbacks.on_mesh_operation()`, one this library has no name for
+with its raw value.
+
 ### Time zone and time
 
 The mesh controller announces its time zone and clock with every periodic