How s4851211/edge_operator works
1. What this repository is
- This is an edge-side operator application for a Fairino robot, used to receive trajectories from VILMA, inspect status, and execute robot motion locally.
- The codebase is split into a small operator UI, a set of background service modules, local trajectory/data files, and a vendored robot SDK.
2. System boundary
- The repository is not just an app; it spans:
- Local Python control software
- Robot vendor SDK bindings
- ROS 2 / DDS connectivity infrastructure
- Docker-managed bridge/services
- The supported runtime is Ubuntu 22.04, with Python managed by uv.
3. Infrastructure layer
- docker-compose.yml starts the external runtime dependencies:
- Zenoh DDS bridge (zenoh_edge)
- Vulcanexus / ROS 2 Humble environment (vulcanexus_vm)
- These containers provide the communication path between the upstream trajectory producer and the edge operator, and a ROS-compatible environment for debugging or future integration.
4. Operator UI
- ui/app.py is the Streamlit-based control panel.
- It is the human-facing entry point for:
- checking robot/trajectory status
- viewing received trajectories
- initiating execution actions
- The UI is likely a thin orchestration layer that calls into the service modules rather than directly talking to hardware.
5. Trajectory ingress path
- The trajectory receiver is centered around services/trajectory_receiver.py.
- Per the README, it waits for /learned_trajectory and saves incoming data to:
- data/trajectories/received_trajectory.csv
- This is the main data ingestion flow from VILMA into the edge system.
6. Trajectory storage and working data
- data/trajectories/ is the local persistence boundary for received motion programs.
- The repository also includes example/reference motion artifacts such as:
- skill_reuse_live_screwdriver_1_events_mm.csv
- pick_place_points.json
- These files suggest the system supports both imported learned trajectories and task-specific point definitions.
7. Execution pipeline
- services/trajectory_executor.py is the component that likely turns a stored trajectory into executable robot commands.
- It sits between trajectory data and the robot control layer, which makes it the key execution boundary for:
- loading the chosen CSV/trajectory
- applying calibration/coordinate transforms
- dispatching motion steps to the robot driver
8. Robot control layer
- services/robot_service.py is the abstraction over the physical Fairino robot.
- The actual low-level robot API is vendored in fairino-python-sdk-main/, which contains platform-specific bindings for Linux and Windows, though the README says Windows is not supported in this project.
- This layer is the hard boundary to hardware: everything above it is application logic, everything below it is vendor SDK / robot communication.
9. Gripper and task scripts
- gripper_linux.py and pick_place_linux.py look like standalone robot task scripts, likely for manual operation or specific demos.
- They are separate from the main UI/service flow and represent task-oriented automation examples built on the same robot SDK.
10. Status and observability
- services/status_service.py appears to consolidate system state for the UI.
- services/receiver_service.py likely tracks trajectory reception state, while services/robot_service.py handles robot connectivity/health.
- This creates an internal status plane so the Streamlit UI can present current readiness and execution conditions without directly coupling to every backend module.
11. ROS/Zenoh integration services
- services/zenoh_service.py, services/zenoh_launcher.py, services/ros2_service.py, and services/receiver_launcher.py suggest the project manages some background processes programmatically.
- These modules are the integration boundary between:
- Zenoh transport
- ROS 2 / DDS tooling
- the Python operator workflow
- They likely encapsulate startup, connection management, and process lifecycle for the infrastructure services.
12. Calibration and coordinate frames
- Several JSON files define robot and environment calibration inputs:
- colleague_cam2base_calibration.json
- identity_robot_calibration.json
- trajectory_calibration.json
- These are important because execution depends on consistent frame transforms between camera, robot base, and trajectory coordinates.
13. Configuration and build tooling
- config/settings.yaml is the main application configuration file.
- pyproject.toml, uv.lock, and .python-version define the Python environment and dependency management.
- The project is designed to be run by first bringing up Docker services, then activating the Python environment, then launching the Streamlit UI or receiver process.
14. Overall data flow
- The main runtime flow is:
- VILMA produces a trajectory
- the Zenoh/DDS bridge transports it to the edge
- trajectory_receiver stores it locally as CSV
- the UI inspects the received result and status
- trajectory_executor sends motion commands through robot_service
- the robot executes the trajectory, potentially using calibration data and gripper/task helpers
Main entry points: robot_service.py Robot Service · app.py Operator UI · status_service.py Status · trajectory_executor.py Executor
Components 23
Runtime
Python operator and task entrypoints.
- Operator UI · Human-facing control panel for status, trajectories, and execution.
ui/app.py - Main · Top-level application launcher for the operator workflow.
main.py - CSV Runner · Standalone script for following a CSV trajectory.
fairino_follow_csv_trajectory.py - Gripper Task · Standalone Linux task script for gripper control.
gripper_linux.py - Pick Place · Standalone Linux task script for pick-and-place motion.
pick_place_linux.py
Services
Background control, execution, and integration modules.
- Status · Aggregates robot, receiver, and execution readiness for the UI.
services/status_service.py - Receiver State · Tracks trajectory reception and storage state.
services/receiver_service.py - Trajectory Rx · Waits for learned trajectories and writes received CSV data.
services/trajectory_receiver.py - Executor · Loads stored trajectories and dispatches execution steps.
services/trajectory_executor.py - Robot Service · Abstraction over the Fairino robot connection and motion API.
services/robot_service.py - Zenoh Service · Manages Zenoh bridge connectivity and process lifecycle.
services/zenoh_service.py - Zenoh Launcher · Starts and supervises the Zenoh bridge runtime.
services/zenoh_launcher.py - ROS 2 Service · Manages ROS 2 / DDS integration process lifecycle.
services/ros2_service.py - Receiver Launcher · Starts and supervises the trajectory receiver runtime.
services/receiver_launcher.py
Infra
Docker and connectivity runtime dependencies.
- Docker Compose · Brings up the Zenoh bridge and Vulcanexus / ROS 2 environment.
docker-compose.yml
Assets
Local trajectory, calibration, and config data.
- Settings · Main application configuration.
config/settings.yaml - Trajectories · Local persistence for received and reference trajectories.
data/trajectories - Traj Calib · Calibration inputs for trajectory-to-robot alignment.
trajectory_calibration.json - Robot Calib · Base-frame calibration for the robot setup.
identity_robot_calibration.json - Cam Calib · Camera-to-base calibration for coordinate transforms.
colleague_cam2base_calibration.json - Task Points · Named point definitions for pick-and-place style motions.
pick_place_points.json - Example Traj · Reference learned trajectory artifact in CSV form.
skill_reuse_live_screwdriver_1_events_mm.csv
Vendor SDK
Vendored Fairino robot bindings.
- Fairino SDK · Vendored Fairino robot SDK and platform-specific C/Python bindings.
fairino-python-sdk-main
Connections 26
- Main → Operator UI: starts · Launches the operator UI.
- Main → Trajectory Rx: runs · Can start the receiver workflow.
- Operator UI → Status: reads · Displays system readiness and robot state.
- Operator UI → Receiver State: reads · Shows trajectory reception state.
- Operator UI → Executor: triggers · Initiates trajectory execution.
- Receiver Launcher → Trajectory Rx: starts · Supervises the ingress worker.
- Trajectory Rx → Zenoh Service: listens via · Receives trajectories through the transport layer.
- Trajectory Rx → Trajectories: writes · Persists received trajectories as local CSV.
- Receiver State → Trajectories: tracks · Reports stored trajectory availability.
- Executor → Trajectories: loads · Reads the selected trajectory for execution.
- Executor → Robot Service: commands · Sends motion steps to the robot adapter.
- Executor → Traj Calib: uses · Applies trajectory calibration during execution.
- Robot Service → Fairino SDK: wraps · Uses the vendored Fairino SDK for hardware control.
- Robot Service → Robot Calib: uses · Relies on robot frame calibration data.
- Robot Service → Cam Calib: uses · Supports camera-to-base transforms.
- Robot Service → Task Points: uses · Consumes named points for task scripts.
- Zenoh Launcher → Docker Compose: depends on · Runs alongside containerized transport services.
- ROS 2 Service → Docker Compose: depends on · Uses the ROS 2 / DDS environment provided by containers.
- Zenoh Service → Docker Compose: bridges · Connects the edge app to the external transport runtime.
- Status → Robot Service: queries · Collects robot health and connectivity.
- Status → Receiver State: queries · Collects ingestion readiness.
- Status → Zenoh Service: queries · Collects transport status.
- CSV Runner → Robot Service: uses · Drives robot motion from a CSV file.
- Gripper Task → Robot Service: uses · Controls the gripper through the robot adapter.
- Pick Place → Robot Service: uses · Runs a pick-and-place task through the robot adapter.
- Settings → Main: configures · Provides runtime configuration for the application.