Metadata-Version: 2.4
Name: inorbit-edge
Version: 3.2.0
Summary: InOrbit Edge SDK for Python
Home-page: https://github.com/inorbit-ai/edge-sdk-python
Download-URL: https://github.com/inorbit-ai/edge-sdk-python/archive/refs/tags/v3.2.0.zip
Author: InOrbit, Inc.
Author-email: support@inorbit.ai
Maintainer: Leandro Pineda
Maintainer-email: leandro@inorbit.ai
License: MIT
Project-URL: Tracker, https://inorbit.youtrack.cloud/issues/ESP/?q=State:%20-Resolved%20
Project-URL: Contributing, https://github.com/inorbit-ai/edge-sdk-python/blob/v3.2.0/CONTRIBUTING.md
Project-URL: Code of Conduct, https://github.com/inorbit-ai/edge-sdk-python/blob/v3.2.0/CODE_OF_CONDUCT.md
Project-URL: Changelog, https://github.com/inorbit-ai/edge-sdk-python/blob/v3.2.0/CHANGELOG.md
Project-URL: Issue Tracker, https://github.com/inorbit-ai/edge-sdk-python/issues
Project-URL: License, https://github.com/inorbit-ai/edge-sdk-python/blob/n3.2.0/LICENSE
Project-URL: About, https://www.inorbit.ai/company
Project-URL: Contact, https://www.inorbit.ai/contact
Project-URL: Blog, https://www.inorbit.ai/blog
Project-URL: Twitter, https://twitter.com/InOrbitAI
Project-URL: LinkedIn, https://www.linkedin.com/company/inorbitai
Project-URL: GitHub, https://github.com/inorbit-ai
Project-URL: Website, https://www.inorbit.ai/
Project-URL: Source, https://github.com/inorbit-ai/edge-sdk-python
Keywords: inorbit,robops,robotics
Platform: Linux
Platform: Mac OS-X
Platform: Windows
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10, <3.14
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests<3.0,>=2.31
Requires-Dist: paho-mqtt<3.0,>=2.1.0
Requires-Dist: pillow~=12.1.1
Requires-Dist: pyaml<24.0,>=23.12
Requires-Dist: pydantic<3.0,>=2.6
Requires-Dist: pysocks<2.0,>=1.7
Requires-Dist: protobuf~=5.29.6
Requires-Dist: certifi>=2024.2
Requires-Dist: rdp2~=1.1.2
Provides-Extra: video
Requires-Dist: opencv-python-headless<5.0,>=4.9; extra == "video"
Provides-Extra: telemetry
Requires-Dist: opentelemetry-api~=1.41.0; extra == "telemetry"
Requires-Dist: opentelemetry-sdk~=1.41.0; extra == "telemetry"
Requires-Dist: opentelemetry-exporter-prometheus~=0.62b0; extra == "telemetry"
Requires-Dist: prometheus-client<1.0,>=0.20; extra == "telemetry"
Provides-Extra: dev
Requires-Dist: bump2version~=1.0; extra == "dev"
Requires-Dist: black~=26.3.1; extra == "dev"
Requires-Dist: coverage~=7.6; extra == "dev"
Requires-Dist: flake8~=7.1; extra == "dev"
Requires-Dist: flake8-pyproject~=1.2; extra == "dev"
Requires-Dist: pip~=26.0; extra == "dev"
Requires-Dist: pytest~=8.4; extra == "dev"
Requires-Dist: pytest-mock~=3.14; extra == "dev"
Requires-Dist: requests-mock~=1.12; extra == "dev"
Requires-Dist: setuptools~=80.9; extra == "dev"
Requires-Dist: tox~=4.32; extra == "dev"
Requires-Dist: twine~=6.2; extra == "dev"
Requires-Dist: wheel~=0.46.2; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: download-url
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: maintainer
Dynamic: maintainer-email
Dynamic: platform
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# InOrbit Python Edge SDK

![Build](https://github.com/inorbit-ai/edge-sdk-python/actions/workflows/build-main.yml/badge.svg) ![License](https://img.shields.io/badge/License-MIT-yellow.svg) ![PyPI - Package Version](https://img.shields.io/pypi/v/inorbit-edge) ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/inorbit-edge)

The `InOrbit Edge SDK` allows Python programs to communicate with `InOrbit`
platform on behalf of robots - providing robot data and handling robot actions.
Its goal is to ease the integration between `InOrbit` and any other software
that handles robot data.

---

## Features

- Robot session handling through a `RobotSessionPool`.
- Publish key-values.
- Publish robot poses.
- Publish robot odometry.
- Publish robot path.
- Publish robot laser.
- Execute callbacks on Custom Action execution.
- Execute scripts (or any program) in response to Custom Action execution.
- Stream camera frames from RTSP (or anything OpenCV opens).

## Quick Start

```python
from inorbit_edge.robot import RobotSessionFactory, RobotSessionPool


def my_command_handler(robot_id, command_name, args, options):
    """Callback for processing custom command calls.

    Args:
        robot_id (str): InOrbit robot ID
        command_name (str): InOrbit command e.g. 'customCommand'
        args (list): Command arguments
        options (dict): object that includes
            - `result_function` can be called to report command execution
            result with the following signature: `result_function(return_code)`
            - `progress_function` can be used to report command output with
            the following signature: `progress_function(output, error)`
            - `metadata` is reserved for the future and will contain additional
            information about the received command request.
    """
    if command_name == "customCommand":
        print(f"Received '{command_name}' for robot '{robot_id}'!. {args}")
        # Return '0' for success
        options["result_function"]("0")


robot_session_factory = RobotSessionFactory(
    api_key="<YOUR_API_KEY>"
)

# Register commands handlers. Note that all handlers are invoked.
robot_session_factory.register_command_callback(my_command_handler)
robot_session_factory.register_commands_path("./user_scripts", r".*\.sh")

robot_session_pool = RobotSessionPool(robot_session_factory)

robot_session = robot_session_pool.get_session(
    robot_id="my_robot_id_123", robot_name="Python SDK Quick Start Robot"
)

robot_session.publish_pose(x=0.0, y=0.0, yaw=0.0)
```

## Installation

**Stable Release:** `pip install inorbit-edge`<br>

**Development Head:** `pip install git+https://github.com/inorbit-ai/edge-sdk-python.git`

## Documentation

For full package documentation please
visit [InOrbit Developer Portal](https://developer.inorbit.ai/docs?hsLang=en#edge-sdk).

## Development

See [CONTRIBUTING.md](CONTRIBUTING.md) for information related to developing
the code.

## The Three Commands You Need To Know

1. `pip install -e .[dev]`

   This will install your package in editable mode with all the required
   development dependencies (i.e. `tox`).

2. `make build`

   This will run `tox` which will run all your tests in Python 3.10 - 3.13 as
   well as linting your code.

3. `make clean`

   This will clean up various Python and build generated files so that you can
   ensure that you are working in a clean environment.

## Camera streaming

Install the optional **video** extra (see `requirements-video.txt`), which pulls
in OpenCV:

`pip install inorbit-edge[video]`

Register a camera on a session. Frames are streamed only while the platform asks
for video -- for example when a user opens a camera view -- and the camera id is
the topic id the InOrbit camera must be configured with (`"0"` for the first
one):

```python
from inorbit_edge.video import OpenCVCamera

session.register_camera(
    "0", OpenCVCamera("rtsp://user:pass@192.0.2.10:554/stream1", rate=5)
)
```

For RTSP, set OpenCV's FFmpeg options **before** the first capture is opened
(they are read by OpenCV when it opens the stream, so export them or set them in
`os.environ` at import time):

```bash
export OPENCV_FFMPEG_CAPTURE_OPTIONS="rtsp_transport;tcp|timeout;3000000"
```

`rtsp_transport;tcp` because some cameras reject UDP, and `timeout`
(microseconds) bounds socket reads: without it, a camera that stops answering
mid-stream is only noticed after OpenCV's 30s watchdog, which delays both the
reopen and shutdown.

`OpenCVCamera` settings, all optional:

| Setting | Default | Meaning |
|---------|---------|---------|
| `rate` | `10` | Frames per second published |
| `scaling` | `0.3` | Downscale factor applied before JPEG encoding |
| `quality` | `35` | JPEG quality, 1-100 |
| `stale_frame_seconds` | `3.0` | Stop serving the buffered frame once it is older than this, so a stream that died shows no video instead of a frozen picture. `None` keeps serving the last frame |
| `api_preference` | auto | OpenCV backend to open with; URL sources default to `cv2.CAP_FFMPEG` |
| `REOPEN_BACKOFF_SECONDS` | `0.5s` to `10s` | Class attribute: delay before each attempt to rebuild a capture whose grabs are failing |
| `HEALTH_LOG_SECONDS` | `60.0` | Class attribute: how often the capture health line below is logged |

Each camera logs one health line per window, which is usually enough to tell
where video stopped:

```
Capture health: grabbed=1800 served=60 stale=0 reopens=0 in the last 60s
```

No line at all means the platform never requested video; `grabbed=0` means the
stream is unreachable; frames grabbed but not served means nothing is consuming
them; frames served with nothing visible in the platform points at the MQTT
side. The same signals are exported as the `video_frames_grabbed`,
`video_frames_stale` and `video_capture_reopens` counters (see Metrics below).

## Metrics

The SDK is capable of collecting internal metrics such as number of calls to
publishing functions. It uses [OpenTelemetry](https://opentelemetry.io/),
which supports various exporting mechanisms.
Connectors are responsible for configuring the exporter of their choice;
as well as adding more metrics if they chose to do so.

Install the optional **telemetry** extra (see `requirements-telemetry.txt`) so
the SDK records real OpenTelemetry metrics. Without it, built-in metrics are
no-ops and the base package has no OpenTelemetry dependency:

`pip install inorbit-edge[telemetry]`

To export to Prometheus, the extra above includes `opentelemetry-exporter-prometheus`
and `prometheus-client`. The following is an example initialization code that enables a
[Prometheus](https://prometheus.io/) HTTP endpoint, where all SDK metrics
(including system metrics such as CPU usage) and any metric added by the
connector can be scraped and exported to any external system (Grafana,
StackDriver, etc.)

```python
from inorbit_edge.metrics import setup_prometheus_meter_provider
from prometheus_client import start_http_server

# ...

if setup_prometheus_meter_provider(
    service_name="my-connector",
    service_instance_id="robot-123",
    service_version="1.2.3",
):
    start_http_server(port=9464, addr="0.0.0.0")
```

Custom metrics can use the same meter provider. Define instruments once during
module initialization, then record values where the connector does the work:

```python
from inorbit_edge.metrics import get_meter

meter = get_meter("my_connector")
messages_processed_counter = meter.create_counter(
    "messages_processed",
    unit="1",
    description="Number of input messages processed by the connector",
)


def process_message(robot_id, message):
    # ... connector-specific processing ...
    messages_processed_counter.add(1, {"robot_id": robot_id})
```

When exported to Prometheus with `service_name="my-connector"`, this appears as
`my_connector_messages_processed_total` with a `robot_id` label. Without the
`telemetry` extra installed, the same code is safe to run but records no data.

For call-count metrics, the SDK also provides a decorator. This keeps the
increment close to the function being counted:

```python
from inorbit_edge.metrics import get_meter, with_counter_metric

meter = get_meter("my_connector")
command_handler_counter = meter.create_counter(
    "command_handler_calls",
    unit="1",
    description="Number of command handler invocations",
)


@with_counter_metric(command_handler_counter, attributes={"command": "dock"})
def handle_dock_command(command_payload):
    # ... handle the command ...
    return "accepted"
```

If attributes depend on the function arguments, pass a callable instead of a
static dictionary:

```python
@with_counter_metric(
    command_handler_counter,
    attributes=lambda robot_id, command_payload: {"robot_id": robot_id},
)
def handle_command(robot_id, command_payload):
    # ... handle the command ...
    return "accepted"
```
