Ensenso-Nova

Ensenso integration for Wandelbots Nova.

This application exposes Ensenso SDK functionalities through an OpenAPI interface.

---

Features

• REST API for controlling and streaming Ensenso stereo cameras
• Full integration with Wandelbots Nova ecosystem
• Preset and calibration handling
• Docker/Podman containerized deployment
• Built and managed with Poetry
• Tested via pytest

---

Project Structure

• ensenso_nova/ – main application code (routes, models, helpers)
• config/ – configuration files
• assets/ – assets including filecams (sample camera streams) and logos
• build.sh / build.ps1 – build and publish container images
• Dockerfile – container definition
• poetry.toml / pyproject.toml – dependency management (Poetry)
• tests/ – Python tests

---

Prerequisites

• Nova CLI
• Poetry for Python dependency management
• Podman or Docker for building and running containers

---

Installation (Development)

# Install dependencies
poetry install

# Run tests
poetry run pytest

---

Building the Container

You can build the container locally with:

./build.sh        # Linux/macOS
./build.ps1       # Windows PowerShell

These scripts inject version and Git metadata automatically.

To build manually:

docker build -t ensenso-nova .

---

Deployment

When running the container with a real camera, the following is required:

docker run --network=host --shm-size=256M ensenso-nova

• --network=host: Ensures UDP GigE Vision broadcasts from cameras reach the container. Without this, cameras cannot be discovered.
• --shm-size=256M: Prevents memory issues when handling high-resolution images.

Additionally, GigE Vision UDP ports must be open on your system to allow camera communication.

---

API

The OpenAPI specification is provided in openapi.json.

---

Run Inside the Container

The image’s entrypoint is:

poetry run serve  # binds 0.0.0.0:8080 (FastAPI / Uvicorn)

Quick Start (real camera)

GigE Vision requires broadcast UDP. Use host networking.

docker run --rm -it \
  --network=host \
  --shm-size=256M \  -e LOG_LEVEL=info \  -e ENABLE_DEBUG_ENDPOINTS=false \  -e ENSENSO_INSTALL=/opt/ensenso \  -v $(pwd)/data:/data \  ensenso-nova:local

• --network=host is mandatory for camera discovery & streaming (GVCP/GVSP over UDP broadcast/unicast).
• -v $(pwd)/data:/data persists captures/config (matches app_description.json storage mount).
• --shm-size=256M avoids shared memory issues for large frames.

If host networking is not possible, at minimum open/forward GigE Vision ports:

• GVCP discovery/control: UDP 3956
• GVSP streaming: UDP 49152–65535 (device dependent) Exact ranges depend on camera/driver. Host networking is the recommended and simplest setup.

Environment Variables

Variable	Default	Purpose
LOG_LEVEL	info	Uvicorn log level.
ENABLE_DEBUG_ENDPOINTS	false	Enables extra debug routes (prints a one-time API key to logs).
ENSENSO_INSTALL	/opt/ensenso	Path to Ensenso SDK inside container.
RERUN_ADDR	(empty)	Optional host:port for rerun.io telemetry; when set the service resolves to an IP and connects.
APP_VERSION	(build-injected)	Version string shown in /about.
GIT_COMMIT / GIT_TAG / GIT_BRANCH	(build-injected)	Git metadata shown in /about and UI.

Avoid committing secrets. If you use private registries, pass credentials via your orchestrator’s secret store or docker login.

HTTP Endpoints

The service serves a minimal UI with the API at the root:

• Home / Stoplight UI: GET / (opens interactive docs based on openapi.json)
• Cameras: GET /cameras
• Calibrations: endpoints under /calibrations/*
• Icon: GET /app_icon.webp

Example:

curl http://localhost:8080/cameras

Health & Logs

• Server logs stream to stdout/stderr; set LOG_LEVEL=debug when diagnosing.
• Internal fault logs: /tmp/fault.log (inside the container).

Distribution Notice

This distribution archive (prepared for sharing) intentionally excludes certain large or proprietary assets:

• Filecams (sample/file-based camera streams)
• Logos / brand artwork

In a full development environment these assets are present under assets/.
If you need them, add your own filecam data or logos accordingly.

---

License

Licensed under the Apache License, Version 2.0 (the "License").
You may not use this project except in compliance with the License.
See LICENSE for details.

---

Trademarks

"Ensenso" and the Ensenso logos are trademarks or registered trademarks of Optonic GmbH.

---

Recommended Run Arguments

For reliable operation, always include:

--network=host
--shm-size=256M

---