Switch a live SLAM map to AMCL
==============================

Start SLAM and map the area first, for example with :doc:`navigation-simple`.
The configuration must support both SLAM and localization (contain AMCL settings).
New configurations saved by the panel's generator include both; add AMCL settings
to older SLAM-only configurations before switching.
Keep the robot stationary during the switch and confirm the map covers the
remaining route. The cutover follows five stages:

1. Pause route execution, cancel navigation goals and publish zero velocity.
2. Read the robot's pose with ``Spatial.LookupTransform(map, base_link)``.
3. Call ``Navigation.SaveMap`` to create a normal map-library entry.
4. Start a localization deployment with the existing configuration, saved map ID
   and captured initial pose.
5. Wait for that deployment generation to become ready, then resume execution.

The panel uses ``olo.internal.navigation.v1.Navigation.ControlRoute(pause)``
before cancellation and ``ControlRoute(resume)`` after readiness. It resumes
only a route that was playing before the switch, checks the route definition
and revision, and leaves an already paused route paused. Those dashboard route
RPCs are internal, not public SDK methods. For these standalone SDK examples,
pause any dashboard route and stop exploration first; your SDK route loop must
stop issuing goals until the example returns successfully.

The public SDK calls below perform the same map and deployment cutover. Base
braking uses ``Locomotion.Stop``: ``Kinematics.Stop`` cancels joint motion and
does not publish base zero velocity. Namespace-scoped handles keep every call
on the same robot.

.. tab-set::
    :sync-group: sdk-language

    .. tab-item:: Python
        :sync: python

        .. literalinclude:: scripts/navigation-slam-to-amcl.py
           :language: python

    .. tab-item:: TypeScript
        :sync: typescript

        .. literalinclude:: scripts/navigation-slam-to-amcl.ts
           :language: typescript

Snapshots remain ordinary library maps that users can rename or delete. The
deployment retains the map ID, configuration and seed. With **Relaunch Nav2 on
reconnect** enabled in Settings, an appliance restart reapplies localization on
that map. The existing opt-in still applies: when disabled, the platform clears
old running intent on reconnect instead of restarting navigation. Keep the map
while its deployment is in use.

Failure leaves execution stopped; there is no automatic rollback to SLAM or
automatic route resume. A saved map remains available even if startup fails.
After submitting a deployment, inspect its generation and logs before retrying:
a lost response can still mean the intent was accepted. The panel offers retry
only before deployment submission. Closing the visualizer or changing robots
ends its orchestration and leaves the route paused.