Skip to content

About

Another dora-rs usb camera node

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

English | 中文

Patch 2.1.3 includes the current locked Quinn dependency fixes (quinn-proto 0.11.19, quinn-udp 0.5.16). This remains a Forge 2.x / Dora 1.x release. Forge 2.x is a BREAKING CHANGE from 1.x; align Forge libraries, nodes and Dora before connecting nodes.

English | 简体中文

USB camera

BREAKING CHANGE: Forge 2.x / Dora 1.x migration

This migration from Forge 1.x / Dora 0.4.x requires coordinated deployment. Align the Forge packages, Dora CLI/coordinator/daemon, this node and its peer nodes before connecting a dataflow; replacing only one node in a Forge 1.x deployment is unsupported. Rebuild and redeploy executable artifacts with the matching environment. Keep stable/1.x for deployments that still use the previous stack.

The validated Python baseline is forge-msgs==2.1.0, Pillow==13.0.0, forge-common==2.1.0, the applicable forge-robot / forge-policy / forge-kinematics / forge-tool packages at 2.0.0, and dora-rs==1.0.1. Respect this repository's Python and SDK platform requirements. Forge package families have independent versions. Rust nodes retain the published forge_msgs crate 2.0.0 with Dora 1.0.1; Python Msgs 2.1.0 does not require a nonexistent Rust 2.1.0 release. The forge_msgs.v1 message namespace remains unchanged.

This notice describes the deployment break from the previous stack; it does not declare hardware, real-model or sustained-run acceptance complete. See this round's verification report for actual tests and outstanding gates.

Linux V4L2/UVC camera capture with raw RGB, JPEG and PNG Dora outputs.

Migration status

Target node version: 2.1.2. These changes are candidates pending the platform, hardware and sustained-stream acceptance gates below. A version declaration does not mean a stable release has been accepted.

usb_camera_test_sink validates every frame, fails on malformed or insufficient input, and supports positive min_frames and delay_ms for slow-consumer tests. A zero minimum cannot pass an empty stream.

Runtime and platform

  • First validation combination: Dora CLI/coordinator/daemon/node APIs 1.0.1, Rust Msgs 2.0.0 / Python Msgs 2.1.0 and Common 2.1.0; use only the families required by this node.
  • Forge wire schemas remain forge_msgs.v1. Dora 0.x and 1.x cannot share a runtime.
  • Use Python 3.12 for Python builds. Camera-only Python packages may also declare Python 3.11 support; test that interpreter separately before claiming it.
  • Rust packages enable arrow-v59; the committed lock uses Arrow 59.3.0.
  • Hardware camera/robot artifacts target Linux. macOS development tests do not qualify Linux binaries. GPU/rendering and vendor SDK prerequisites still apply.
  • Keep a recoverable stable/1.x runtime and artifact combination.

Setup and commands

Run from the repository root:

cargo build --locked
usb_camera --config config/sensor.example.yaml

Use usb_camera --help (or uv run --frozen usb_camera --help) for supported CLI options. The example configuration is config/sensor.example.yaml; choose the actual device and supported stream profiles before starting. This command requires an appropriate Dora dataflow.

Message contract

The configured output_id carries Forge Image or CompressedImage. Capture timestamps are preserved as user metadata.

Keep bounded queues for high-rate image consumers and document whether old images are dropped or producers experience backpressure. Preserve image dimensions, dtype, encoding, units and capture metadata across the node boundary.

Tests and build

cargo test --locked
cargo clippy --locked --all-targets --all-features -- -D warnings
cargo build --release --locked

Use the committed Cargo.lock and frozen/locked installs. Python vendor SDK tests require the supported SDK platform. For Linux headless MuJoCo rendering, install the required EGL or OSMesa libraries and select the appropriate MUJOCO_GL backend.

Validate every delivered example or rendered template with:

dora validate path/to/dataflow.yaml

Schema validation is followed by a real start, message exchange and stop test. Keep the existing detailed configuration and device setup reference in the Chinese guide and the repository's config/, examples/ and scripts/ directories where present.

Acceptance and release

  1. Build candidate archives from the selected commit/tag and record actual embedded dependency versions, platform, archive SHA256 and unpacked executable SHA256.
  2. Install the final archive into a clean supported environment. Verify the CLI, message contract, resource cleanup and error exits.
  3. For image producers, run real supported RGB/depth configurations for at least four continuous hours after warmup. Exercise slow/multiple consumers, stalled consumption, failures and repeated start/stop. Define throughput, latency and memory limits before testing, and retain time series rather than frame payloads.
  4. Exercise the relevant device; synthetic streams do not qualify hardware capture. Demonstrate rollback to the complete old node/runtime combination.
  5. Publish the exact accepted archive. Rebuilding invalidates that artifact's acceptance; repeat it before publication. Never overwrite published tags/assets.

License

Apache-2.0. See LICENSE and any bundled third-party notices.

Versioned releases

Mandatory tag-first release rule: merge the version/lock change, create an annotated version tag on that reviewed commit, build that exact tag, validate the artifacts, then publish. Moving branch names, untagged commit IDs and replacement of published tags are not release inputs.

Release line Source Node/package version Runtime
Forge 1.x stable/1.x 1.x, tag v1.X.Y Forge 1.x / Dora 0.4.x
Forge 2.x master 2.x, tag v2.X.Y Forge 2.x / Dora 1.x

Legacy normalization: nodes previously at 0.x on stable/1.x release as 1.0.0, retaining Forge 1.x / Dora 0.4.x dependencies and runtime behavior. Existing 1.x package versions are retained. Node/package majors now follow the Forge compatibility line; a 0.x tag is rejected.

Run Build versioned release from master for either line. First merge the version/lock changes into the selected source branch, then create an unused annotated tag on that reviewed commit. The tag must match package metadata. Never move existing tags or reuse a published version. Dispatch uses the workflow's reviewed tooling with the exact tagged source, so legacy tags need not contain the new release helper.

# Replace with an existing, reviewed and unpublished tag matching source metadata.
TAG=v1.X.Y
gh workflow run release.yml --ref master -f release_line=1.x -f tag="$TAG"
TAG=v2.X.Y
gh workflow run release.yml --ref master -f release_line=2.x -f tag="$TAG"

The workflow verifies tag type, source commit, branch ancestry, source version and locked Forge/Dora compatibility. It builds source archives and wheel/sdist where supported, checks Python distribution metadata and SHA-256, and creates or attaches to a draft GitHub Release. Published releases/assets are not overwritten; review all build results and acceptance evidence before publishing. This workflow does not publish node packages to PyPI.

Set build_binaries=true to call the existing Ubuntu 20.04 binary workflow; its existing architecture, CLI and archive checks remain in force. You can also run build-ubuntu20.yml directly with ref, version and release_line; ref must be an annotated tag, not a moving branch. Binary artifacts are attached only after all selected jobs succeed.

The source archive preserves the tagged tree; external SDKs/submodules, model downloads and site configuration remain separate prerequisites. A dependency or SDK build failure is not successful release acceptance. Build success does not establish single-node or Gateway-chain dora run, hardware, real-model, sustained-run or rollback acceptance. Every acceptance chain must include adapter-forge-gateway from the same compatibility line. Forge 2.x is a breaking change: align Forge libraries, node versions and Dora across the entire deployment; keep 1.x on its maintenance branch.

Dependency maintenance

Cargo.lock uses quinn-proto 0.11.19 and quinn-udp 0.5.16 to address the reported QUIC vulnerabilities. The RustSec audit remains enabled; message and device interfaces are unchanged.

About

Another dora-rs usb camera node

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages