Metadata-Version: 2.4
Name: navel-remote
Version: 0.4.8
Summary: A remote interface to control navel robot
Project-URL: Homepage, https://gitlab.com/robothouse/rh-projects/hospital-at-home/navel-remote/
Project-URL: Bug Tracker, https://gitlab.com/robothouse/rh-projects/hospital-at-home/navel-remote/issues/
Author-email: Patrick Holthaus <patrick.holthaus@googlemail.com>
License-Expression: BSD-2-Clause
License-File: LICENSE
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Requires-Dist: navel>=0.18.9
Requires-Dist: pillow>=12.3.0
Requires-Dist: zfl
Requires-Dist: ztl-web
Requires-Dist: ztl>=0.3.1
Description-Content-Type: text/markdown

# Navel Remote

This project will be deployed on the navel robot to enable remote control via ZTL

## Installation

Clone the repository and set up a virtual environment:

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install navel-remote
```

This installs `navel-remote` in editable mode along with its dependencies (`navel`, `ztl`, `ztl-web`).

### Usage

Once installed, two CLI commands are available:

```bash
navel-remote --help
navel-camera --help
```

## Remote control server (`navel-remote`)

Runs the remote control service on the robot and responds to commands received over ZTL.

```
navel-remote [-h] [-p PORT] [-s SCOPE] [-f]
```

| Flag | Default | Description |
| --- | --- | --- |
| `-p`, `--port` | `5565` | Port to listen on for incoming remote control commands. |
| `-s`, `--scope` | `/navel` | Scope to respond to. Clients must use the same scope when publishing commands. |
| `-f`, `--federated-logging` | Disabled | Enable federated data logging. Requires a configured `federation` remote and publisher. |
| `-h`, `--help` | - | Show help information and exit. |

### Examples

Start the remote control service with the default configuration:

```bash
navel-remote
```

Listen on a custom port and scope:

```bash
navel-remote --port 6000 --scope /robot
```

Enable federated logging:

```bash
navel-remote --federated-logging
```

### Notes

- The service must be running on the robot before remote clients can connect and issue commands.
- The configured port and scope must match those used by the remote client.
- Federated logging is optional and only required when integrating with a configured federation logging infrastructure.
- You can use `.service` files in the `etc` folder to enable systemd autostarting.



## Camera stream (`navel-camera`)

Publishes frames from the robot's head camera over ZTL.

```
navel-camera [-p PORT] [-s SCOPE] [--compress | --no-compress] [-q JPEG_QUALITY]
```

| Flag | Default | Description |
| --- | --- | --- |
| `-p`, `--port` | `5665` | Port to publish on. |
| `-s`, `--scope` | `/head_cam` | Scope to publish data under. |
| `--compress` / `--no-compress` | `--compress` | JPEG-compress frames before publishing. Cuts payload size roughly 10-20x, which matters over WiFi where an uncompressed ~920KB/frame stream needs ~9.2MB/s to sustain 10fps. Use `--no-compress` to publish raw `navel.Frame` objects instead (e.g. for lossless capture on a fast/local link). |
| `-q`, `--jpeg-quality` | `80` | JPEG quality (1-95) when `--compress` is enabled; lower values trade image quality for less bandwidth. Ignored with `--no-compress`. |
| `-h`, `--help` | - | Show help information and exit. |

On startup, `navel-camera` logs which mode it's running in, e.g. `JPEG compression enabled (quality=80)` or `JPEG compression disabled, publishing raw frames` — check that line to confirm compression is actually on.

### Viewing the stream

`test/display.py` is a standalone script (not an installed CLI command) that subscribes to a running `navel-camera` and displays the stream with matplotlib. Compression is configured entirely on the publisher side (`navel-camera`'s `--compress`/`--no-compress`, on by default); `display.py` has no matching flag because it doesn't need one — it inspects each incoming frame and transparently decodes whichever format was actually sent, JPEG-compressed or raw. Just point it at the remote host:

```bash
./test/display.py -r 10.0.1.184
```

| Flag | Default | Description |
| --- | --- | --- |
| `-r`, `--remote` | `navel1-1` | Remote host running `navel-camera` to subscribe to. |
| `-p`, `--port` | `5665` | Remote port to subscribe to (must match `navel-camera`'s `--port`). |
| `-s`, `--scope` | `/head_cam` | Scope data is published under (must match `navel-camera`'s `--scope`). |
