{"id":19963310,"url":"https://github.com/advrhumanoids/kyon_config","last_synced_at":"2025-07-29T02:05:43.458Z","repository":{"id":235118585,"uuid":"790094318","full_name":"ADVRHumanoids/kyon_config","owner":"ADVRHumanoids","description":"Low level configuration files for Kyon","archived":false,"fork":false,"pushed_at":"2025-07-02T16:19:26.000Z","size":78,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-07-17T15:54:26.846Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ADVRHumanoids.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-04-22T08:53:57.000Z","updated_at":"2025-07-02T16:19:30.000Z","dependencies_parsed_at":null,"dependency_job_id":"312a52d6-2c3b-4b6f-b4d8-d3e2b37aba7e","html_url":"https://github.com/ADVRHumanoids/kyon_config","commit_stats":null,"previous_names":["advrhumanoids/kyon_config"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/ADVRHumanoids/kyon_config","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ADVRHumanoids%2Fkyon_config","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ADVRHumanoids%2Fkyon_config/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ADVRHumanoids%2Fkyon_config/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ADVRHumanoids%2Fkyon_config/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ADVRHumanoids","download_url":"https://codeload.github.com/ADVRHumanoids/kyon_config/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ADVRHumanoids%2Fkyon_config/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267617643,"owners_count":24116208,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-29T02:00:12.549Z","response_time":2574,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-13T02:15:34.746Z","updated_at":"2025-07-29T02:05:43.428Z","avatar_url":"https://github.com/ADVRHumanoids.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Kyon Robot Configuration\n\nThis repository contains the comprehensive configuration files and management tools for the Kyon robot system. It provides a complete framework for controlling and monitoring the robot through a web-based interface and managing its real-time control processes.\n\n## Overall System Architecture\n\nThe Kyon robot software stack consists of several interconnected components that work together to provide a complete robot control solution:\n\n1. **`xbot2-core`**:\n   - **Role**: The central real-time robot control software.\n   - **Implementation**: C++ library/middleware.\n   - **Execution**: Runs directly on the robot's hardware (or in simulation), typically within a Docker container.\n   - **Functionality**:\n     - Interfaces with motors and sensors via a Hardware Abstraction Layer (HAL).\n     - Executes real-time control algorithms (loaded as plugins).\n     - Communicates with higher-level systems (e.g., ROS).\n     - Configured by `xbot2/kyon_basic.yaml` and related HAL/plugin config files.\n\n2. **Concert Launcher (`executor.py`)**: \n   - **Role**: The execution engine responsible for launching and managing software processes.\n   - **Implementation**: Python library (`concert_launcher/src/concert_launcher/executor.py`).\n   - **Functionality**:\n     - Reads process definitions from `launcher_config.yaml`.\n     - Starts, stops, and monitors processes.\n     - Manages processes locally, remotely via SSH, and inside Docker containers.\n     - Utilizes `tmux` for reliable background process management.\n     - Provides status checking and output streaming capabilities.\n   - **Documentation**: For detailed documentation on the Concert Launcher, see the [Concert Launcher README](https://github.com/ADVRHumanoids/concert_launcher).\n\n3. **`xbot2_gui_server` (Implemented in `launcher.py`)**: \n   - **Role**: The backend web server providing a Graphical User Interface for managing the robot software.\n   - **Implementation**: Python web server using `aiohttp` (`robot_monitoring/server/src/xbot2_gui_server/launcher.py`).\n   - **Functionality**:\n     - Acts as a bridge between the web-based GUI and the Concert Launcher.\n     - Uses the Concert Launcher to manage the processes defined in `launcher_config.yaml`.\n     - Provides an HTTP API and WebSocket interface for the web frontend.\n     - Allows users to view process status, start/stop processes, select configuration variants, and view live console output.\n\nIn essence, the `xbot2_gui_server` serves as a web-based remote control panel that translates user actions from the GUI into commands for the Concert Launcher. The Concert Launcher then handles the low-level details of starting, stopping, and monitoring the actual robot software components based on the specifications in `launcher_config.yaml`.\n\n## Repository Structure\n\nThe Kyon configuration repository is available at: https://github.com/ADVRHumanoids/kyon_config/tree/master/xbot2\n\n```\nkyon_config/\n├── gui/\n│   ├── gui_server_config.yaml      # Primary configuration for xbot2_gui_server\n│   └── launcher_config.yaml        # Process definitions for Concert Launcher\n├── xbot2/\n│   ├── kyon_basic.yaml             # Main configuration for xbot2-core\n│   ├── hal/                        # Hardware Abstraction Layer configurations\n│   │   ├── kyon_hal_ec_idle.yaml   # EtherCAT idle mode configuration\n│   │   ├── kyon_hal_ec_pos.yaml    # EtherCAT position control configuration\n│   │   └── ...\n│   └── friction/                    # Plugin configurations\n│       ├── fc_config.yaml          # Friction compensation configuration\n│       └── ...\n├── compose.yaml                    # Docker Compose configuration\n└── setup.sh                        # Setup and launch script\n```\n\n## Detailed Configuration Files\n\n### 1. `gui_server_config.yaml`\n\nThis minimal file tells the `xbot2_gui_server` where to find the main process configuration file:\n\n```yaml\nlauncher:\n  launcher_config: launcher_config.yaml  # Path relative to this file or absolute\n```\n\n**Purpose**: This configuration file is loaded by the `xbot2_gui_server` application (`launcher.py`) and specifies the path to the main process configuration file (`launcher_config.yaml`) used by the Concert Launcher.\n\n### 2. `launcher_config.yaml`\n\nThis is the core configuration file for the Concert Launcher (`executor.py`). It defines what software components need to be run, where they should run, and how to run them:\n\n```yaml\ncontext:\n  session: kyon  # Default name for the tmux session where processes are grouped\n  params:\n    hw_type: ec_pos  # Default global parameter; can be used in 'cmd' via {hw_type}\n  .defines:  # YAML Anchors (\u0026) defining reusable aliases\n    - \u0026embedded embedded@10.24.12.100  # Alias 'embedded' -\u003e SSH target (robot onboard)\n    - \u0026control kyon@10.24.12.102       # Alias 'control' -\u003e SSH target (control station)\n    - \u0026vision kyon@10.24.12.101        # Alias 'vision' -\u003e SSH target (vision computer)\n    - \u0026docker-xeno focal-ros1-xeno-dev-1  # Alias 'docker-xeno' -\u003e Docker container name (with Xenomai)\n    - \u0026docker-base focal-ros1-dev-1       # Alias 'docker-base' -\u003e Docker container name (base env)\n\n# Process Definitions (each top-level key except 'context' is a process)\nimu:\n  cmd: roslaunch vectornav vectornav.launch  # The command to execute\n  machine: *embedded  # WHERE: Run via SSH on the host referenced by 'embedded' alias\n  docker: *docker-xeno  # HOW: Run inside the container named by 'docker-xeno'\n  ready_check: timeout 5 rostopic echo /xbotcore/imu/imu_link -n 1  # Command to verify readiness\n\necat:\n  cmd: ecat_master\n  machine: *embedded\n  docker: *docker-xeno\n  # No ready_check specified for this process\n\nxbot2:\n  cmd: xbot2-core --hw {hw_type}  # Command uses the 'hw_type' parameter\n  machine: *embedded\n  docker: *docker-xeno\n  ready_check: timeout 5 rostopic echo /xbotcore/joint_states -n 1\n  variants:  # Defines alternative ways to run this process, selectable in the GUI\n    verbose:  # Simple flag variant\n      cmd: \"{cmd} -V\"  # Appends '-V' to the base command string\n    ctrl:  # Group of mutually exclusive variants (like radio buttons in GUI)\n      # Select one of these to override the 'hw_type' parameter for this launch\n      - ec_idle:  # Variant name\n          params:  # Variant-specific parameters\n            hw_type: ec_idle  # Sets hw_type to 'ec_idle' when this variant is chosen\n      - ec_pos:  # Variant name\n          params:\n            hw_type: ec_pos  # Sets hw_type to 'ec_pos'\n```\n\n**Purpose**: This file defines all the processes that can be managed through the system, along with their execution environments and configuration options.\n\n**Key Sections Explained**:\n   * **`context`**: Defines global settings for the launcher.\n     * `session`: Sets the `tmux` session name used by the launcher.\n     * `params`: Defines default parameters accessible via `{param_name}` substitution.\n     * `.defines`: Uses YAML Anchors to create reusable aliases for SSH targets and Docker containers.\n   * **Process Definitions**: Each top-level key (except `context`) defines a manageable process.\n     * `cmd`: The command-line string to execute, with optional parameter placeholders.\n     * `machine`: Specifies the target machine using a defined alias. If omitted or `local`, runs on the local machine.\n     * `docker`: Specifies a Docker container within which the command should be executed.\n     * `ready_check`: An optional command that verifies if the process is fully operational.\n     * `variants`: Defines alternative configurations or command modifications selectable via the GUI.\n\n### 3. `xbot2/kyon_basic.yaml`\n\nThis is the primary configuration file for the `xbot2-core` process itself:\n\n```yaml\n# Defines robot model using URDF/SRDF found via ROS paths\nXBotInterface:\n  urdf_path: \"$(command xacro $(rospack find kyon_description)/urdf/kyon.urdf upper_body:=true use_mimic_tag:=false)\"\n  srdf_path: \"$(rospack find kyon_description)/srdf/kyon.srdf\"\n\n# Configuration for the dynamics library\nModelInterface:\n  # Dynamics library settings\n\n# Maps --hw argument values to specific HAL configuration files\nxbotcore_device_configs:\n  sim: \"$(rospack find kyon_config)/hal/kyon_gz.yaml\"\n  dummy: \"$(rospack find kyon_config)/hal/kyon_dummy.yaml\"\n  ec_idle: \"$(rospack find kyon_config)/hal/kyon_hal_ec_idle.yaml\"\n  ec_pos: \"$(rospack find kyon_config)/hal/kyon_hal_ec_pos.yaml\"\n\n# Defines execution threads and their scheduling properties\nxbotcore_threads:\n  rt_main: { sched: fifo, prio: 60, period: 0.001 }  # 1ms Real-Time thread\n  nrt_main: { sched: other, prio: 0, period: 0.005 }  # 5ms Non-Real-Time thread\n\n# Lists plugins to load, configure, and assign to threads\nxbotcore_plugins:\n  # Homing plugin configuration\n  - plugin_name: homing_example\n    type: XBot::Cartesian::Plugins::Homing  # Plugin class\n    thread: nrt_main  # Run in non-real-time thread\n    params:\n      ctrl_mode_map: { l_arm_link_6: 11, r_arm_link_6: 11 }\n\n  # ROS Interface plugin\n  - plugin_name: ros_io\n    type: XBot::RosIO\n    thread: nrt_main\n    params: { queue_size: 1, update_period: 0.01 }\n\n  # ROS Control Interface plugin\n  - plugin_name: ros_control\n    type: XBot::RosControl\n    thread: nrt_main\n    params: { update_period: 0.01 }\n\n  # Friction Compensation plugin loading external params\n  - plugin_name: friction_comp\n    type: XBot::FrictionCompensation\n    thread: rt_main  # Run in real-time thread\n    params:\n      config_path: \"$(rospack find kyon_config)/xbot2/friction/fc_config.yaml\"\n\n  # Additional plugins...\n\n# Global framework parameters\nxbotcore_param:\n  sense_map_vel_from_pos_diff: true\n  hal_common_config: { enable_brake_on_idle: true }\n```\n\n**Purpose**: When `xbot2-core` starts, it reads this file to understand the robot's structure, which hardware interface to use, how to schedule its internal tasks, and which control/utility plugins to load and configure.\n\n**Key Sections Explained**:\n   * **`XBotInterface`**: Defines the robot's kinematic and dynamic model.\n   * **`xbotcore_device_configs`**: Maps hardware configuration names to actual HAL configuration files.\n   * **`xbotcore_threads`**: Defines named execution threads with specific scheduling properties.\n   * **`xbotcore_plugins`**: Lists the modular plugins to be loaded into `xbot2-core`.\n   * **`xbotcore_param`**: Global parameters accessible throughout the `xbot2-core` framework.\n\n### 4. `compose.yaml`\n\nDefines the Docker services, their base images, configurations, networking, and volumes:\n\n```yaml\nservices:\n  base: \u0026base_service  # Using YAML anchor for reusability\n    image: hhcmhub/kyon-cetc-focal-ros1-base\n    stdin_open: true\n    tty: true\n    privileged: true  # WARNING: High privileges needed for HW access\n    network_mode: host  # Required for ROS networking across containers/host\n    cap_add:\n      - ALL  # WARNING: Grants all capabilities\n    restart: \"no\"  # Default restart policy (overridden by specific services)\n    ulimits: { core: -1 }\n    volumes:\n      - /tmp/.X11-unix:/tmp/.X11-unix:rw  # For X11 GUI Forwarding\n      - ~/.ssh:/home/user/.ssh  # Share host SSH keys\n    environment:\n      - TERM=xterm-256color\n      - DISPLAY  # Inherit DISPLAY from host\n      - HHCM_FOREST_CLONE_DEFAULT_PROTO=https\n\n  dev:  # Development container\n    \u003c\u003c: *base_service  # Merge settings from base_service\n    volumes:\n      - ~/.cache/kyon-cetc-focal-ros1-base:/home/kyon_ros1/data\n      # Add project source code mounts here if needed\n\n  xbot2_gui_server:  # GUI backend container\n    \u003c\u003c: *base_service  # Merge settings from base_service\n    entrypoint: bash -ic \"echo 'Waiting for ROS Master...'; until rostopic list \u003e /dev/null 2\u003e\u00261; do sleep 1; done; echo 'ROS Master found. Starting GUI Server.'; sleep 1; xbot2_gui_server /home/kyon_ros1/xbot2_ws/src/kyon_config/gui/gui_server_config.yaml\"\n    restart: always  # Keep the GUI server running\n```\n\n**Purpose**: This Docker Compose file defines the multi-container Docker application, specifying the services, their base images, configurations, networking, volumes, and dependencies needed for the system.\n\n**Key Services Explained**:\n   * **`base`**: A reusable configuration template defining common settings for other services.\n   * **`dev`**: A service intended for development, providing a containerized shell environment.\n   * **`xbot2_gui_server`**: The container that runs the GUI backend server, with a custom entrypoint that waits for the ROS master before starting.\n\n### 5. `setup.sh`\n\nA shell script designed to automate the setup and launch of the Docker Compose environment:\n\n```bash\n#!/bin/bash\n\n# Placeholder for ROS environment setup function\nros1() {\n    # Example: source /opt/ros/noetic/setup.bash\n    echo \"ROS1 environment setup placeholder executed.\"\n}\n\nSCRIPT_DIR=$( cd -- \"$( dirname -- \"${BASH_SOURCE[0]}\" )\" \u0026\u003e /dev/null \u0026\u0026 pwd )\ncd \"$SCRIPT_DIR\" || exit 1  # Change to script dir or exit if failed\n\necho \"Allowing local root access to X server for Docker GUI forwarding...\"\n# WARNING: Modifies X server access control\nxhost +local:root\n\necho \"Bringing up Docker Compose services (dev, xbot2_gui_server)...\"\n# Start 'dev' and implicitly its dependencies in detached mode. Don't recreate if up-to-date.\ndocker compose up dev -d --no-recreate\n\necho \"Executing shell inside the 'dev' container...\"\n# Attach an interactive bash shell to the running 'dev' container\ndocker compose exec dev bash\n```\n\n**Purpose**: This script automates the setup and launch of the Docker Compose environment, including necessary host configurations like X11 permissions.\n\n**Key Steps**:\n1. Defines helper functions (like `ros1()`)\n2. Determines the script's directory and changes to it\n3. Runs `xhost +local:root` to grant permissions for X display forwarding\n4. Uses Docker Compose to start the services\n5. Executes an interactive shell inside the `dev` container\n\n## Web Server Implementation (`launcher.py`)\n\nThe `robot_monitoring/server/src/xbot2_gui_server/launcher.py` file implements the backend web server application (`xbot2_gui_server`) using the `aiohttp` framework. It serves as the intermediary between the user interface and the Concert Launcher.\n\n**Key Functionality**:\n- **Initialization**: Loads configuration, instantiates the Concert Launcher's Executor, and sets up web routes\n- **HTTP API Handlers**:\n  - `/process/get_list`: Retrieves the list of defined processes and their status\n  - `/process/{name}/command/{command}`: Handles process control actions (start, stop, kill)\n  - `/process/custom_command`: Allows executing arbitrary commands (if configured)\n- **WebSocket Communication**: Streams real-time updates to connected clients, including process output and status changes\n- **Background Tasks**: Periodically checks process status and manages streaming tasks\n\n**Interaction Flow**:\n1. The server reads `gui_server_config.yaml` to find `launcher_config.yaml`\n2. It instantiates the Concert Launcher's Executor with this configuration\n3. When a client connects to the web interface, it serves the frontend assets\n4. The frontend establishes a WebSocket connection for real-time updates\n5. User actions in the GUI generate HTTP requests to the appropriate API endpoints\n6. The server translates these requests into Executor commands\n7. Process output and status updates are streamed back to the client via WebSocket\n\n## External Dependencies\n\nThis project relies on several external components:\n\n1. **Concert Launcher**: The process management framework used by the GUI server.\n   - Repository: [https://github.com/ADVRHumanoids/concert_launcher](https://github.com/ADVRHumanoids/concert_launcher)\n   - The Concert Launcher README contains comprehensive documentation about the process execution engine, including detailed explanations of the configuration format, API, and integration patterns.\n\n## Detailed Interaction Flow\n\nThe typical sequence of events when using the system via the GUI:\n\n1. **System Startup**:\n   - User runs `./setup.sh`\n   - Host command `xhost +local:root` allows GUI forwarding from Docker\n   - Docker Compose starts the necessary containers, including `xbot2_gui_server`\n   - The user is placed inside the `dev` container shell\n\n2. **GUI Server Initialization**:\n   - The `xbot2_gui_server` container starts its entrypoint script\n   - The script waits for the ROS master to be available\n   - The `xbot2_gui_server` Python application starts and loads configuration\n   - The web server begins listening for HTTP and WebSocket connections\n\n3. **User Accesses GUI**:\n   - User opens a web browser to the server address\n   - The frontend establishes a WebSocket connection for real-time updates\n   - The frontend requests the process list from `/process/get_list`\n   - The server responds with process definitions and current status\n   - The frontend renders the UI accordingly\n\n4. **User Action: Start Process**:\n   - User selects variant options and clicks \"Start\" for a process\n   - Frontend sends HTTP request to `/process/xbot2/command/start` with selected variants\n   - Server calls `executor.execute_process()` with appropriate parameters\n   - Executor connects to the target machine, starts the process in a tmux session\n   - If defined, the ready check is executed periodically\n   - Status updates and process output are streamed to the frontend via WebSocket\n\n5. **Process Execution**:\n   - The target process (e.g., `xbot2-core`) starts running\n   - It loads its own configuration (e.g., `xbot2/kyon_basic.yaml`)\n   - For `xbot2-core`, it initializes the robot model, threads, and plugins\n   - Process output is captured and streamed back to the GUI\n\n6. **User Action: Stop Process**:\n   - User clicks \"Stop\" for a running process\n   - Frontend sends HTTP request to `/process/xbot2/command/stop`\n   - Server calls `executor.kill()` with appropriate parameters\n   - Executor sends the appropriate signal to the process\n   - Status updates are sent to the frontend\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadvrhumanoids%2Fkyon_config","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadvrhumanoids%2Fkyon_config","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadvrhumanoids%2Fkyon_config/lists"}