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

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

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

@@ -74,6 +74,8 @@ place, backgrounds and logo images.
 
 .. autodata:: mx_remote.proto.Constants.OSD_SYNC_RECORDS_MAX
 
+.. autodata:: mx_remote.proto.Constants.OSD_SETTINGS_ASKED
+
 .. autodata:: mx_remote.proto.Constants.OSD_SYNC_FONT_MAX
 
 .. autodata:: mx_remote.proto.Constants.OSD_SYNC_TEXT_MAX
@@ -409,6 +411,66 @@ The operations a mesh controller sends, and what a controller announces.
 .. autodata:: mx_remote.proto.FrameV2IPSources.ONEIP_SOURCE_LIST_MAX
 ```
 
+## Mesh replacement and kept settings
+
+Replacing an offline unit of a mesh, the settings each unit keeps for its mesh,
+and the numbering of a controller's bays.
+
+```{eval-rst}
+.. autoclass:: mx_remote.MeshReplaceUnit
+   :members:
+
+.. autoclass:: mx_remote.MeshReplaceUnits
+   :members:
+
+.. autoclass:: mx_remote.MeshReplaceable
+   :members:
+
+.. autoclass:: mx_remote.proto.Constants.MeshReplaceResult
+   :members:
+
+.. autoclass:: mx_remote.MeshSetting
+   :members:
+
+.. autoclass:: mx_remote.MeshConfigDigest
+   :members:
+
+.. autoclass:: mx_remote.MeshConfig
+   :members:
+
+.. autodata:: mx_remote.proto.Constants.MESH_REPLACE_UNITS_MAX
+
+.. autodata:: mx_remote.proto.Constants.MESH_REPLACE_NAME_MAX
+
+.. autodata:: mx_remote.proto.Constants.MESH_CONFIG_MAX
+
+.. autoclass:: mx_remote.MeshBay
+   :members:
+
+.. autoclass:: mx_remote.MeshBays
+   :members:
+
+.. autodata:: mx_remote.proto.Constants.MESH_BAYS_MAX
+```
+
+## Dedicated controllers
+
+What a dedicated mesh controller, such as a router, announces of itself and its
+state.
+
+```{eval-rst}
+.. autoclass:: mx_remote.ControllerHello
+   :members:
+
+.. autoclass:: mx_remote.ControllerPart
+   :members:
+
+.. autoclass:: mx_remote.proto.Constants.ControllerRole
+   :members:
+
+.. autodata:: mx_remote.proto.Constants.CONTROLLER_PARTS_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 → mx_remote-13.0.0}/docs/configuration.md

@@ -28,6 +28,29 @@ mx = mx_remote.Remote(uid_path="/var/lib/myapp/.mxr-uid")
 mx = mx_remote.Remote(mesh_device=True, serial="P9SN66660600", version="1.2.3")
 ```
 
+A client confined to one interface is invisible on every other, so a dedicated
+controller speaking the protocol on its mesh link alone is not listed by the
+units on its uplink LAN. `announce_interfaces` names interfaces that get each
+hello, and a dedicated controller's `CONTROLLER_STATE` hello, from a send-only
+socket bound to the interface's current address:
+
+```python
+mx = mx_remote.Remote(local_ip="10.8.80.30", dedicated_controller=True, announce_interfaces=["eth1"])
+mx.set_announce_interfaces(["eth1", "wlan0"])   # while running, announced at once
+```
+
+The socket is rebound when that address changes and skipped while there is
+none, as on a DHCP uplink; nothing arriving there is taken. The hello there
+leaves out `MANAGER` (a unit takes a promotion to controller from a manager),
+`MESH_MASTER` (a unit joining a mesh joins it) and `OSD_SYNC` (a source syncs
+every device with it, in any mesh). `MESH_MEMBER` stays, so no unit takes the
+client for one free to join.
+
+On Linux, the interface `local_ip` selects is the only one datagrams are taken
+from, so a device reachable only by another interface stays unknown, and
+starting fails when no interface holds the address. Elsewhere, broadcasts on
+every interface still arrive.
+
 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

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

@@ -43,6 +43,11 @@ await bay.set_hidden(True)   # hide
 await bay.set_hidden(False)  # show
 ```
 
+A device that lost its settings reports its bays' default names and hidden
+flags, with `BayStatusMask.SETTINGS_LOST` set. A bay keeps the name and hidden
+flag it had until the bit clears; a bay first heard while it is set takes what
+it is sent.
+
 ## EDID Profiles
 
 Change the EDID profile on input bays:

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

@@ -533,9 +533,49 @@ 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
+served over HTTP from this client, on `logo_port` or a free port, at `local_ip`
+when one is given and on every address otherwise; a changed `local_ip` moves
+the server there on the same port. Content a unit
 would refuse is refused before anything is sent; see `send_osd_sync`.
 
+A mesh controller holding the sync its units already took from another source
+keeps it without sending it again, and sends it to a unit that joins:
+
+```python
+await mx.keep_osd_sync(content)    # held and served, sent to no unit
+await mx.resend_osd_sync(joined)
+```
+
+A client made with `Remote(osd_sync=True)` takes a sync the way a unit does,
+which a dedicated controller needs to hold the mesh's overlays. Its hello
+announces `DeviceFeature.OSD_SYNC`, so a source sends it a sync of its own:
+
+```python
+await mx.request_osd_sync(OsdSyncWhat.CAPTIONS | OsdSyncWhat.LOGO_SLOTS)
+# MxrCallbacks.on_osd_sync(dev, sync): the sync naming this client
+await mx.request_osd_settings(dev, sync.seq, sync.what, missing=list(range(sync.records)))
+# MxrCallbacks.on_osd_sync_setting(dev, setting), once per setting
+url = sync.logo_url(sender_address, 1)    # where slot 1's PNG is fetched
+```
+
+A sync naming this client is read from any device for 10 s after it asked for
+one, and a setting naming it from the source of one of the last
+`OSD_SETTINGS_ASKED` (8) syncs it asked the settings of. A source sends a few
+settings at a time; a unit asks again for those still missing a second after
+the last one came. `setting.entry` converts a setting into the `OsdSyncEntry`
+that `send_osd_sync()` and `keep_osd_sync()` take, so the client can serve the
+sync it took. Fetching the logos is the caller's.
+
+Like a unit, it reports to the source at each stage, so the source lists it
+with the units that took the sync:
+
+```python
+await mx.send_osd_report(dev, OsdSyncReport(seq=sync.seq, state=OsdSyncState.DONE, written=3, refused=0,
+                                            reason=''))
+```
+
+The reason is cut to 63 bytes at a character boundary.
+
 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
@@ -654,6 +694,20 @@ 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.
 
+This client reports its own status the way a unit does, to every device:
+
+```python
+from mx_remote import UnitStatus
+
+await mx.send_unit_status(UnitStatus(flags=UnitFlag.FIRMWARE_UPGRADE, uptime=3600))
+```
+
+A mesh controller that runs no update checks of its own passes its members'
+upgrade flags on this way: a member that sees `UnitFlag.FIRMWARE_UPGRADE` or
+`UnitFlag.VIDEO_PROCESSOR_UPGRADE` appear in its controller's report checks
+for the upgrade itself. More than six temperatures, or a status message over
+48 bytes or holding a NUL, is refused before anything is sent.
+
 ## Mesh and firmware
 
 ```python
@@ -691,7 +745,9 @@ mx.set_mesh_bays_mapped(True)       # the role is announced only with bays mappe
 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_setup_completed(True)    # every unit that hears it
+mx.set_setup_completed(True)                # this client's own, in its hello
+await mx.set_member_setup_completed(unit, True)   # one member, 0x33 or later
 await mx.set_mesh_installer(0x1234)
 
 await output.set_oneip_mirroring(other_output)   # None to stop
@@ -702,6 +758,13 @@ await unit.set_rc_settings(rc_target=RCType.CEC, ip=None, cec_enabled=True, cec_
 await unit.set_rc_settings(forward_ir=True)      # the rest as the unit reported
 ```
 
+`set_mesh_setup_completed()` names no unit, so every unit that hears it takes
+it. `set_member_setup_completed()` reaches one member alone: a controller marks
+the members of the moment its setup completes, and sends it again to one that
+missed it until that member's hello carries `DeviceFeature.SETUP_COMPLETED`; a
+replacement takes the mark of the unit it replaced. A member takes it only from
+its own controller, and one whose mesh module predates it drops it.
+
 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
@@ -763,10 +826,137 @@ 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
+membership report as `mesh_master` and `mesh_membership_lost`. Every other mesh operation a device sends
 arrives at `MxrCallbacks.on_mesh_operation()`, one this library has no name for
 with its raw value.
 
+### Replacing a unit, and kept settings
+
+Units with the mesh module (protocol 0x32 for replacing, 0x33 for kept
+settings) let a unit outside any mesh take the place of an offline one. A
+device without the module answers nothing, and the library sends neither
+opcode to a unit below its version.
+
+```python
+await mx.query_mesh_replaceable()        # every device; at most every 2 s
+for r in mx.mesh_replaceable:            # listed in the last 30 s, each unit once
+    print(r.lister, r.offline_controller, r.unit.uid, r.unit.input_name)
+await mx.request_mesh_replace(lister, r.unit.uid)   # answered at on_mesh_replace_answered()
+```
+
+Each controller lists its own offline units, once it has been up 120 s, and a
+member whose controller is offline lists that controller. The device asked
+takes the replacing unit in: the unit's bays, their names and routes, and its
+kept settings. A member asked to replace its offline controller sends this
+client the controller's kept settings instead, and taking over is then this
+client's own: promoting itself to controller and having the members replace
+the old one with `send_mesh_operation()`. A request is refused before sending
+where the device would refuse it: the unit was not listed by that device in the
+last 30 s, this client follows a mesh controller or is on a default serial
+(one starting `P9SN0000` other than `P9SN00000000`), or the unit has a
+`ONEIP_SOURCE`, `ONEIP_SINK` or `MULTIVIEWER` feature this client lacks. As a
+controller this client answers with `send_mesh_replaceable()` and
+`send_mesh_replace_result()`.
+
+Every unit in a mesh keeps settings of its own, such as `led.status`, and
+announces their length and crc32 as `device.mesh_config_digest`. The controller
+keeps a copy of every member's, and every member one of its controller's, so a
+replacing unit inherits them:
+
+```python
+await mx.request_mesh_config(holder, subject.remote_id)  # holder's copy, or its own
+config = mx.mesh_config(subject.remote_id)               # once every frame has arrived
+await mx.send_mesh_config_hello(settings)                # this client's own, in a mesh
+await mx.send_mesh_config(to, subject_uid, settings)     # the answer to a request
+await mx.send_mesh_config_set(member, settings)          # a member takes these, resets the rest
+```
+
+Settings are taken only once every frame has arrived, in order, from one
+sender, and their crc32 matches. A set reaches `on_mesh_config_set_requested()`
+only from the controller this client follows; `send_mesh_config_set()` is
+refused unless the member reports this client as its controller, and a member
+whose settings changed restarts 3 s later. Names and values are at most 255
+bytes with no NUL, and all of them at most `MESH_CONFIG_MAX` (1984) bytes.
+
+A unit that lost its settings says so, and announces its defaults: `lost` is set
+on its `mesh_config_digest`, and on a `MeshConfig` of its own settings (never on
+a copy). A controller that keeps a record of it sends that record back as a
+set. Its membership report flags the same, as `device.mesh_membership_lost`:
+a controller that has it as a member adds it back rather than drop it for
+naming no master. Units that predate the flags never set them.
+
+A unit that takes over from a controller numbers its bays as that controller
+did, so drivers keep addressing the same ports. A controller answers for its
+own numbering, and a member with the copy it keeps of its controller's, also
+once that controller is offline:
+
+```python
+await mx.request_mesh_bays(member, controller.remote_id)
+bays = mx.mesh_bays(controller.remote_id)   # MeshBays, None until it arrived whole
+for bay in bays.bays:
+    print('input' if bay.input else 'output', bay.bay, bay.unit)
+
+# answering a request, MxrCallbacks.on_mesh_bays_requested(dev, subject)
+await mx.send_mesh_bays(dev, mx.uid, [MeshBay(input=True, bay=1, features=DeviceFeature.ONEIP_SOURCE,
+                                              unit=source.remote_id)])
+```
+
+A numbering arrives at `on_mesh_bays_received()`, put together as a dump is;
+bay 0 is the controller's own. It is asked only of a unit at 0x33 or later,
+and holds at most `MESH_BAYS_MAX` (512) bays.
+
+### Dedicated controllers
+
+A mesh controller without bays of its own, such as a router, marks itself as
+dedicated with a `CONTROLLER_STATE` (0x58) hello. A OneIP unit at protocol 0x34
+or later then takes the controller role from none while one it follows is
+online.
+
+```python
+print(device.dedicated_controller)   # True once it has sent such a hello
+print(device.controller_hello)       # ControllerHello: role, generation, primary, parts
+```
+
+`MxrCallbacks.on_controller_hello_changed(dev, hello)` reports each hello that
+differs from that device's last.
+
+A client made with `Remote(dedicated_controller=True)` sends one itself, right
+after its hello to every unit, at most every 10 s, in a mesh or not; its own
+hello stays at the 54 bytes every unit takes.
+
+```python
+mx = Remote(dedicated_controller=True)
+mx.set_controller_role(ControllerRole.PRIMARY, primary=mx.uid)   # sent at once when it changed
+```
+
+It starts as `ControllerRole.NONE` with no primary, and any other client is
+refused.
+
+Dedicated controllers replicate their state between themselves: the library
+does the transfer, and the application only gives and takes part bytes.
+
+```python
+# serving: the hello lists each part's length and crc32 under the generation
+mx.set_controller_parts(generation=3, parts=[(0, state_bytes), (1, logo_png)])
+
+# pulling a part another controller's hello lists
+part = router.controller_hello.parts[0]
+await mx.pull_controller_part(router, part.part, router.controller_hello.generation, part.length, part.crc)
+# arrives at MxrCallbacks.on_controller_part_received(dev, part, generation, data),
+# or ends at on_controller_part_failed(dev, part, generation)
+
+mx.allow_controller_state(new_router.remote_id)   # also a controller of no mesh of this client's
+```
+
+A request is answered with the window it asks, at most 8192 bytes, in frames of
+at most 1024. A pull asks from the first byte it lacks, again after 2 s without
+data and once on a frame out of order, and ends on a generation no longer held,
+a part other than the one its hello described, the device going offline, or
+ten asks without progress. Requests and data are taken only from a dedicated
+controller of this client's mesh, or the one `allow_controller_state()` names,
+and never from a sender that sent no hello. More than five parts, or one listed
+twice, is refused.
+
 ### Time zone and time
 
 The mesh controller announces its time zone and clock with every periodic

{mx_remote-12.0.0 → mx_remote-13.0.0}/mx_remote/Interface.py

@@ -2549,6 +2549,16 @@ class OsdSync:
     CRC differs from its own from http://source_ip:http_port/osd-sync/slotN.png,
     N being 1 to 4."""
 
+    def logo_url(self, sender:str, slot:int) -> str|None:
+        """Where a unit fetches the logo of slot, 1 to 4, of this sync sent from
+        sender, the sender's address: source_ip, or sender when it is
+        unspecified, at http_port, or 80 when it is zero. None for a slot
+        outside 1 to 4."""
+        if not (1 <= slot <= OSD_SYNC_SLOTS):
+            return None
+        host = sender if (self.source_ip == '0.0.0.0') else self.source_ip
+        return f"http://{host}:{self.http_port or 80}/osd-sync/slot{slot}.png"
+
 @dataclass(frozen=True)
 class OsdSyncRequest:
     """A unit asking for an overlay sync, or for settings of one it is taking,
@@ -2621,6 +2631,12 @@ class OsdSyncSetting:
     bits for a logo, and bit 0 for a background's colour."""
     value: OsdSyncValue
 
+    @property
+    def entry(self) -> 'OsdSyncEntry':
+        """The setting as this client sends it on, holding the sync it took
+        with Remote.send_osd_sync() or keep_osd_sync()."""
+        return OsdSyncEntry(value=self.value, set=self.set, size=self.size, layers=self.layers)
+
 @dataclass(frozen=True)
 class OsdSyncReport:
     """
@@ -2907,6 +2923,14 @@ class MeshOperationMessage:
         """The installer id a controller report carries."""
         return int.from_bytes(self.param.byte_value[4:6], 'little')
 
+    @property
+    def membership_lost(self) -> bool:
+        """Whether a membership report flags that its sender lost its
+        settings, and its membership possibly with them: bit 0 of the
+        parameter's first 32-bit word. Senders that predate the flag leave it
+        clear."""
+        return bool(int.from_bytes(self.param.byte_value[0:4], 'little') & 1)
+
     def __str__(self) -> str:
         return f"{self.operation} target={self.target} param={self.param}"
 
@@ -2918,6 +2942,145 @@ class MeshControllerReport:
     installer: int
     """The installer id its members take, 0 for none."""
 
+@dataclass(frozen=True)
+class MeshReplaceUnit:
+    """A unit a controller can have replaced: it has bays on the controller, it
+    is not the controller, and it is offline."""
+    uid: MxrDeviceUid
+    """The unit."""
+    features: DeviceFeature|int = DeviceFeature(0)
+    """Its features. A unit replacing it must have its ONEIP_SOURCE, ONEIP_SINK
+    and MULTIVIEWER too."""
+    input: int = 0
+    """Its first input bay on the controller, 0 when it has none."""
+    output: int = 0
+    """Its first output bay on the controller, 0 when it has none."""
+    input_name: str = ''
+    """The name of that input, at most MESH_REPLACE_NAME_MAX bytes."""
+    output_name: str = ''
+    """The name of that output, at most MESH_REPLACE_NAME_MAX bytes."""
+
+@dataclass(frozen=True)
+class MeshReplaceUnits:
+    """The units one device listed as replaceable."""
+    offline_controller: bool
+    """The units are the sender's own controller, which is offline. A member
+    lists its controller this way; a controller lists its own offline units."""
+    units: tuple[MeshReplaceUnit, ...]
+    """The units, as many of the list as has arrived."""
+    total: int
+    """How many units the whole list holds."""
+
+@dataclass(frozen=True)
+class MeshReplaceable:
+    """A unit this client can ask to replace, and who to ask."""
+    lister: MxrDeviceUid
+    """The device that listed it, which a request to replace it goes to."""
+    offline_controller: bool
+    """The unit is the lister's own controller, which is offline."""
+    unit: MeshReplaceUnit
+    """The unit."""
+
+@dataclass(frozen=True)
+class MeshSetting:
+    """One setting a unit keeps for its mesh: an application configuration name
+    and its value, each at most 255 bytes. A unit carries only the settings
+    that differ from their default."""
+    name: str
+    """The configuration name, such as led.status."""
+    value: str
+    """The value, as text."""
+
+@dataclass(frozen=True)
+class MeshConfigDigest:
+    """The length and crc32 of the settings a unit keeps for its mesh, as the
+    unit announces them: every 60 seconds while it is in a mesh, and shortly
+    after one of them changes."""
+    length: int
+    """The settings' length in bytes, as they are carried."""
+    crc32: int
+    """The crc32 of those bytes."""
+    lost: bool = False
+    """The unit lost its settings and announces defaults: a controller that
+    keeps a record of it restores that record, whatever the length and crc32
+    say. Never set by a unit that predates the flag."""
+
+@dataclass(frozen=True)
+class MeshConfig:
+    """A unit's kept settings, as a device sent them."""
+    subject: MxrDeviceUid
+    """The unit the settings belong to."""
+    holder: MxrDeviceUid
+    """The device that sent them."""
+    copy: bool
+    """They are a copy holder keeps of subject, not its own: the controller
+    keeps one of every member, and a member one of its controller."""
+    settings: tuple[MeshSetting, ...]
+    """The settings, in the order they were sent."""
+    lost: bool = False
+    """The unit lost its settings, and these are its defaults: a controller
+    that keeps a record of it drops them. Only ever set on a unit's own
+    settings, never on a copy."""
+
+@dataclass(frozen=True)
+class MeshBay:
+    """One bay of a controller's numbering: the unit that owns it."""
+    input: bool
+    """An input, or else an output."""
+    bay: int
+    """The bay number the controller gives it, as its /port/list Bay; 0 is the
+    controller's own."""
+    features: DeviceFeature
+    """The unit's ONEIP_SOURCE, ONEIP_SINK and MULTIVIEWER features as the
+    sender knows them, none when it doesn't."""
+    unit: MxrDeviceUid
+    """The unit that owns the bay."""
+
+@dataclass(frozen=True)
+class MeshBays:
+    """A controller's numbering, as a device sent it: the controller its own, a
+    member the copy it keeps of its controller's. A unit that takes over from
+    a controller numbers its bays the same, so drivers keep addressing the
+    same ports."""
+    subject: MxrDeviceUid
+    """The controller the numbering is of."""
+    holder: MxrDeviceUid
+    """The device that sent it."""
+    copy: bool
+    """It is a copy holder keeps of subject's numbering."""
+    bays: tuple[MeshBay, ...]
+    """The bays that name a unit, inputs first, each mode by bay number; a bay
+    naming none is left out."""
+
+@dataclass(frozen=True)
+class ControllerPart:
+    """One part of a dedicated controller's state, as its hello lists it."""
+    part: int
+    """Which part: 0 the state, 1 to 4 the PNG of that overlay logo slot."""
+    length: int
+    """The part's length in bytes."""
+    crc: int
+    """The crc32 of the whole part."""
+
+@dataclass(frozen=True)
+class ControllerHello:
+    """
+    A dedicated controller's CONTROLLER_STATE hello: its role, its state's
+    generation, the primary in its state and the parts its state is made of.
+
+    Sending one marks the sender as a dedicated controller, such as a router,
+    to every unit from protocol 0x34 on, which then lets no OneIP take the
+    controller role from it while it is online.
+    """
+    role: ControllerRole|int = ControllerRole.NONE
+    """Primary, failsafe or neither; a plain int where it has no name."""
+    generation: int = 0
+    """Raised on every change of the sender's state."""
+    primary: MxrDeviceUid|None = None
+    """The primary in the sender's state, None for none."""
+    parts: tuple[ControllerPart, ...] = ()
+    """The parts, at most CONTROLLER_PARTS_MAX."""
+
 @dataclass(frozen=True)
 class ThirdPartyMessage:
     """
@@ -3809,6 +3972,24 @@ class DeviceBase(ABC):
         '''What this device last announced about itself as a mesh controller,
         None until it has.'''
 
+    @property
+    @abstractmethod
+    def mesh_config_digest(self) -> MeshConfigDigest|None:
+        '''The length and crc32 of this unit's kept settings, as it last
+        announced them, None until it has.'''
+
+    @property
+    @abstractmethod
+    def controller_hello(self) -> ControllerHello|None:
+        '''The CONTROLLER_STATE hello this device last sent, None until it
+        has sent one.'''
+
+    @property
+    def dedicated_controller(self) -> bool:
+        '''This device is a dedicated mesh controller, such as a router: it has
+        sent a CONTROLLER_STATE hello, which controller_hello reads.'''
+        return (self.controller_hello is not None)
+
     @property
     @abstractmethod
     def is_mesh_master(self) -> bool:
@@ -4571,6 +4752,16 @@ class BayLinks:
 class DeviceRegistry(ABC):
     ''' all mx_remote devices on the network '''
 
+    def osd_sync_asked(self, at:float) -> bool:
+        '''Whether a sync naming this client, arriving at at, answers its own
+        request for one.'''
+        return False
+
+    def osd_settings_asked(self, source:MxrDeviceUid, seq:int) -> bool:
+        '''Whether a setting naming this client is of sync seq, which it asked
+        source the settings of.'''
+        return False
+
     @property
     @abstractmethod
     def local_ip(self) -> str|None:
@@ -4914,6 +5105,74 @@ class MxrCallbacks:
         An operation this library has no name for arrives with its raw value. '''
         pass
 
+    def on_mesh_replace_queried(self, dev:DeviceBase) -> None:
+        ''' called when 'dev', a unit outside any mesh, asked which units it can
+        replace. A controller answers with its offline units, and a member
+        whose controller is offline with that controller; see
+        Remote.send_mesh_replaceable(). '''
+        pass
+
+    def on_mesh_replace_units_received(self, dev:DeviceBase, units:MeshReplaceUnits) -> None:
+        ''' called when 'dev' listed units this client can ask it to have
+        replaced: the whole list it has sent so far, which
+        Remote.mesh_replaceable also reads. '''
+        pass
+
+    def on_mesh_replace_requested(self, dev:DeviceBase, unit:MxrDeviceUid) -> None:
+        ''' called when 'dev', a unit outside any mesh, asked to replace 'unit'
+        with it; see Remote.send_mesh_replace_result(). '''
+        pass
+
+    def on_mesh_replace_answered(self, dev:DeviceBase, unit:MxrDeviceUid, result:MeshReplaceResult|int) -> None:
+        ''' called when 'dev' answered this client's request to replace 'unit'.
+        A result this library has no name for arrives as a plain int. '''
+        pass
+
+    def on_mesh_config_requested(self, dev:DeviceBase, subject:MxrDeviceUid) -> None:
+        ''' called when 'dev' asked for the kept settings of 'subject': the
+        addressee's own when it is 'subject', otherwise the copy the addressee
+        keeps; see Remote.send_mesh_config(). '''
+        pass
+
+    def on_mesh_config_received(self, dev:DeviceBase, config:MeshConfig) -> None:
+        ''' called when 'dev' sent a unit's kept settings whole, which
+        Remote.mesh_config() also reads. '''
+        pass
+
+    def on_mesh_config_set_requested(self, dev:DeviceBase, settings:tuple[MeshSetting, ...]) -> None:
+        ''' called when 'dev', the controller this client follows, told it to
+        take these kept settings and reset every other one to its default. '''
+        pass
+
+    def on_mesh_bays_requested(self, dev:DeviceBase, subject:MxrDeviceUid) -> None:
+        ''' called when 'dev' asked for the numbering of controller 'subject':
+        this client's own when it is that controller, otherwise the copy it
+        keeps. Answer with Remote.send_mesh_bays(). '''
+        pass
+
+    def on_mesh_bays_received(self, dev:DeviceBase, bays:MeshBays) -> None:
+        ''' called when 'dev' sent a controller's numbering whole, which
+        Remote.mesh_bays() also reads. '''
+        pass
+
+    def on_controller_part_received(self, dev:DeviceBase, part:int, generation:int, data:bytes) -> None:
+        ''' called when a part this client pulled from 'dev' with
+        Remote.pull_controller_part() arrived whole, its crc32 matching. '''
+        pass
+
+    def on_controller_part_failed(self, dev:DeviceBase, part:int, generation:int) -> None:
+        ''' called when a pull of a part from 'dev' ended without it: the
+        generation is no longer held, the part is not the one its hello
+        described, 'dev' went offline, or ten asks went without progress. '''
+        pass
+
+    def on_controller_hello_changed(self, dev:DeviceBase, hello:ControllerHello) -> None:
+        ''' called when 'dev' sent a CONTROLLER_STATE hello other than its last:
+        it is a dedicated controller, such as a router, which
+        DeviceBase.dedicated_controller says from then on, and
+        DeviceBase.controller_hello reads. '''
+        pass
+
     def on_third_party_message(self, dev:DeviceBase, message:ThirdPartyMessage) -> None:
         ''' called when the application on 'dev' sent a message under its own
         vendor id. A message from a sender this client has not yet heard