OLO Appliance
=============

The OLO Appliance is robot-side software. It connects to an OLO account using a
device API key, participates in a ROS 2 environment, hosts browser-initiated
script execution, and can expose the SDK v2 gRPC control plane.

Installation choices
--------------------

Cloud Sim environments provision their Appliance automatically. OLO hardware
appliances arrive with robot-side software installed. For a self-hosted release
on Linux or WSL with Ubuntu 22.04 or newer, the current public installer is:

.. code-block:: console

   $ curl -sSL https://raw.githubusercontent.com/OLO-Robotics/olo-appliance-release/main/install.sh | bash
   $ cd ~/olo-appliance/olo-appliance-release/app
   $ ./setup.sh --defaults --dist

The release setup expects ROS 2 and its robot-specific dependencies to be
available. ROS communication is handled in-process via rclnodejs; LAN clients
and code execution use ``ws://localhost:<port>/local-rosbridge``. Cloud clients
connect via the OLO server ``/rosbridge`` WebSocket and WebRTC data channels.
The setup prompts for OLO account credentials during the guided setup. For
production or automated deployment, prefer a provisioned device API key over
storing user credentials.

Registration and identity
-------------------------

Register an Appliance from the Portal's **Add Appliance** flow. Copy the
generated device API key when it is shown and provide it to the runtime:

.. code-block:: text

   OLO_APL_DEVICE_API_KEY=apl_your-device-api-key
   OLO_APL_APPLIANCE_NAME=My Appliance

``OLO_APL_ROBOT_ID`` is optional; the Appliance can resolve and persist its
robot identity after registration. Treat the device key as a secret. To rotate
it, use **Account & Security > Appliance Device Keys**, update the runtime
environment, and restart or recreate the Appliance process.

ROS 2 configuration
-------------------

The Appliance uses an in-process ROS 2 transport (rclnodejs). Cloud clients
connect via the OLO server ``/rosbridge`` WebSocket and WebRTC data channels.
LAN clients and code execution use ``ws://localhost:<port>/local-rosbridge`` on
the appliance HTTP port.

Set ``OLO_APL_ROS_DOMAIN_ID`` when the robot does not use the default domain,
and ensure that the Appliance process has sourced the same ROS distribution and
workspace as the robot drivers. See :doc:`ros-concepts` for domains and
namespaces.

SDK v2
------

SDK v2 is enabled by default in the Appliance configuration. Two variables
control it:

.. code-block:: text

   OLO_APL_SDK_V2=false     # opt out and fall back to the v1 rosbridge control plane
   OLO_APL_GRPC_PORT=50151  # listener port (50151 is the default)

The current runtime starts separate Core, Spatial, Kinematics, and Navigation
executors behind one Envoy listener. The listener host defaults to
``127.0.0.1`` and the port defaults to ``50151``. Playground scripts receive
that target automatically.

The SDK surface depends on the robot's ROS graph. Core topic operations require
matching topics and message types; Spatial requires TF data; Kinematics requires
a usable MoveIt setup; Navigation requires a usable Nav2 setup. Vision in SDK
v2 contains client-side camera geometry, depth, alignment, and tracking helpers;
it is not the Portal's video, recording, or AI-vision management API.

Platform management is separate
-------------------------------

The Appliance also has capability flags for remote shell, code execution,
maintenance, simulator control, MoveIt management, Nav2 management, log
streaming, topic throttling, remapping, and general settings. These flags
control Appliance and Portal management operations. They do not add methods to
the SDK v2 API. ``GET /capabilities`` and the ``capabilities`` field in
``GET /health`` report that management surface to the Portal.

For hardened deployments, review the Appliance release configuration before
enabling management operations or making any listener network-accessible.