Migrate from SDK v1
===================

SDK v2 is a new client and control plane, not a drop-in upgrade. Migrate one
behavior at a time and validate it against a simulation or safely constrained
robot.

Identify v1 code
----------------

Code is using v1 if it imports ``oloclient`` or ``olo-client``, constructs
``OLOClient``, authenticates with a Portal username or token, calls
``getUserRobots()``, or connects by Portal robot ID. Methods such as
``sendVelocity``, ``moveFor``, ``startVideo``, rosbag management, script
scheduling, terminal access, and maintenance operations also belong to the v1
or Platform management surfaces.

Do not copy those signatures into a v2 program. They are intentionally omitted
from this site's examples and API reference.

Connection model
----------------

v1 combined OLO account authentication, remote Appliance selection, rosbridge
operations, and Platform management in one client. SDK v2 connects to one
Appliance gRPC endpoint:

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

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

      .. code-block:: python

         from olo import Client

         with Client("192.168.1.10:50151") as client:
             robot = client.robot()

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

      .. code-block:: typescript

         import { connect } from "olo/node";

         const client = connect("192.168.1.10:50151");
         const robot = await client.robot();

In the SDK Playground, omit the target because the Appliance supplies its local
endpoint. Outside it, your deployment must make the endpoint reachable. Portal
login and cloud routing are not v2 ``Client`` features.

Map concepts, not method names
------------------------------

* Replace account robot selection with ``client.robot(namespace)``. A namespace
  identifies a robot in the Appliance's ROS graph; it is not a Portal robot ID.
* Replace bare topic strings with ``TopicInfo`` objects containing the ROS
  message type. Use Core publishers, subscriptions, latest-message reads, and
  parameter methods documented in :doc:`api/core`.
* Replace callback subscriptions with the v2 streaming abstraction. Python
  subscriptions are iterators; TypeScript subscriptions are
  ``AsyncIterable``.
* Replace ad-hoc pose and transform dictionaries with typed Spatial values such
  as ``Point``, ``Quaternion``, ``Pose``, and ``Transform``.
* Replace v1 MoveIt helpers with the typed Kinematics planning, execution,
  robot-state, speed-scaling, and end-effector operations in
  :doc:`api/kinematics`.
* Replace ``moveFor`` with ``robot.locomotion.move`` for a relative planar pose.
  These commands measure motion from odometry instead of estimating it from
  elapsed time.
* Replace ``sendVelocity`` and ``startVelocityHold`` with repeated
  ``robot.locomotion.send_velocity`` / ``robot.locomotion.sendVelocity`` calls. Each call
  refreshes a short Appliance-owned lease; motion stops automatically if the
  caller stops refreshing it.
* Replace v1 Nav2 helpers with :doc:`api/navigation` where an equivalent v2
  operation exists.

Portal-only and Appliance-only features
---------------------------------------

Keep using the Portal or the appropriate Appliance management interface for
account authentication, appliance registration, saved scripts, schedules,
terminal and maintenance operations, Cloud Sim lifecycle, browser
visualization, and WebRTC video. Do not assume an equivalent SDK v2 method
exists.

Persisted outputs (images, videos, rosbags) use the archive module in v2:

- ``robot.archive.captureImage`` saves a JPEG to appliance disk (distinct from ``core.getImage``, which returns an in-memory frame).
- ``robot.archive.captureVideo`` returns a session; call ``stop()`` for the MP4 result.
- ``robot.archive.recordBag`` / ``listBags`` / ``inspectBag`` / ``playBag`` control local rosbag recording and playback.

Cloud catalogs: ``client.platform.archive.listBags()``, ``listVideos()``, and
``listImages()`` list durable org artifacts. Cloud sync and
cross-location transfer remain Portal or future platform APIs.

SDK v1 ``videoRecording.startRecording(topic, opts)`` maps to ``robot.archive.captureVideo({ topic, ... })`` and ``session.stop()``.

Vision is another important boundary: SDK v2 Vision provides local data
conversion and geometry helpers. Portal video sessions and managed AI-vision
providers are separate capabilities.

Behavioral differences to test
------------------------------

Python v2 is synchronous; remove v1 ``await`` expressions around Python client
calls and use a ``with Client(...)`` block or close the client explicitly.
TypeScript remains asynchronous and uses camelCase methods and millisecond
timeout options. Both languages raise typed ``OloError`` subclasses for gRPC
failures.

Test namespace resolution, topic message types, timeouts, cancellation, and
robot-stop behavior explicitly. A v1 convenience command may have included
repeated publishing or cleanup that is not implied by a lower-level v2 publish
call.