{"id":31802056,"url":"https://github.com/cast-robotics/surenav_core","last_synced_at":"2025-10-11T00:16:32.936Z","repository":{"id":309741662,"uuid":"1036840167","full_name":"CAST-Robotics/surenaV_core","owner":"CAST-Robotics","description":"collection of codes to execute on Surena-V humanoid robot","archived":false,"fork":false,"pushed_at":"2025-10-04T15:55:05.000Z","size":15339,"stargazers_count":8,"open_issues_count":1,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-04T16:09:51.665Z","etag":null,"topics":["humanoid","robotics","ros"],"latest_commit_sha":null,"homepage":"https://surenahumanoid.com/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CAST-Robotics.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-12T16:56:37.000Z","updated_at":"2025-10-01T16:47:11.000Z","dependencies_parsed_at":"2025-08-13T16:12:36.157Z","dependency_job_id":"af6d8b74-2c16-498f-a162-2985cd64bf33","html_url":"https://github.com/CAST-Robotics/surenaV_core","commit_stats":null,"previous_names":["cast-robotics/surenav_core"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/CAST-Robotics/surenaV_core","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CAST-Robotics%2FsurenaV_core","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CAST-Robotics%2FsurenaV_core/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CAST-Robotics%2FsurenaV_core/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CAST-Robotics%2FsurenaV_core/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CAST-Robotics","download_url":"https://codeload.github.com/CAST-Robotics/surenaV_core/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CAST-Robotics%2FsurenaV_core/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279005657,"owners_count":26083941,"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-10-10T02:00:06.843Z","response_time":62,"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":["humanoid","robotics","ros"],"created_at":"2025-10-11T00:16:29.432Z","updated_at":"2025-10-11T00:16:32.928Z","avatar_url":"https://github.com/CAST-Robotics.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Surena-V Core ROS Workspace\n\nThis repository contains the **ROS1 (Noetic) workspace** for operating the humanoid robot **Surena-V**, the fifth generation of Iran’s national humanoid robotics project, developed at the **Center for Advanced Systems and Technologies (CAST), University of Tehran**.  \n\nIt provides stable packages for **control, electronics, simulation, planning, and teleoperation**, along with the necessary communication interfaces for integrating AI modules such as perception (object/face detection), sound source localization, and language/vision models.\n\n\n## Quick Start\n\n### Simulation\n\nOpen separate terminals, navigate to `~/surena_ws`, **source the workspace** in each one (`source devel/setup.bash`), and then run the following commands (one per terminal):\n\n```bash\n  roslaunch surenaV_gazebo surenaV_gazebo.launch    # Launch Gazebo  \n  rosrun robot_manager robot_manager_node           # Start manager  \n  rosservice call /keyboard_walk                    # Example: start walking  \n  rosrun keyboard_teleop keyboard_teleop_node       # Start keyboard teleop node\n```\n\n### Real Robot\n```bash\n  rosrun surena_eth surena_eth                      # Start hardware interface  \n  rosservice call /ActivateLegs \"nodeID: 0\"         # Initialize legs  \n  rosservice call /ActivateHands \"nodeID: 255\"      # Initialize hands  \n  rosrun robot_manager robot_manager_node           # Start manager  \n```\n\n\n## Workspace Overview\n\nThe workspace is organized into modular ROS packages:\n\n- **gait_planner**  \n  Core locomotion package. Generates trajectories (walk, step, COM, ankle, DCM), provides joint control, and exposes services for commanding the legs.\n\n- **hand_planner**  \n  Manages humanoid hand kinematics and planning (e.g., minimum jerk interpolation, grasping, head/hand movement). Provides services for moving single/both hands, online gripping, head tracking, and object-class–based actions.\n\n- **keyboard_teleop**  \n  Lightweight keyboard interface for triggering basic teleoperation commands such as walking.\n\n- **robot_manager**  \n  High-level scenario manager. Coordinates robot behaviors through YAML-defined scenarios and exposes the `/ExecuteScenario` service.\n\u003c!-- \n- **robot_teleop**  \n  Qt-based GUI teleoperation panel for higher-level control and monitoring.\n\n- **offlinePublisher**  \n  Tools for replaying data offline, GUI for visualizing logged trajectories. --\u003e\n\n- **simulation/surenaV_description \u0026 simulation/surenaV_gazebo**  \n  URDF description, Gazebo integration, and controllers for Surena-V. Allows full humanoid simulation with physics.\n\n- **surena_eth**  \n  Core hardware interface. Handles *EtherCAT/UDP communication* with the physical robot’s electronics (motors, sensors, F/T sensors). This package must run first on the real robot.\n\n\n## Installation\n\n### Prerequisites\n- [ROS Noetic](http://wiki.ros.org/noetic/Installation) (Ubuntu 20.04 recommended)\n- Dependencies:  \n```bash\n  sudo apt install ros-noetic-ros-control ros-noetic-ros-controllers \\\n                   libeigen3-dev libqt5core5a libqt5gui5 libqt5widgets5 \\\n                   build-essential cmake git \n```\n  (plus OpenCV, Eigen, and other standard ROS dependencies)\n\n### Build\n```bash\n  mkdir -p ~/surena_ws/src  \n  cd ~/surena_ws/src  \n  git clone https://github.com/CAST-Robotics/surenaV_core.git  \n  cd ..  \n  catkin_make  \n  source devel/setup.bash  \n```\n\n## Usage\n\n### 1. Simulation Mode (Gazebo)\n1. Launch simulation:  \n```bash\n  roslaunch surenaV_gazebo surenaV_gazebo.launch  \n```\n   \u003e In Gazebo, press the ▶ Play button to start physics.  \n\n2. Start the robot manager:  \n```bash\n  rosrun robot_manager robot_manager_node  \n```\n3. Call services (walking, hand motions, head, etc.).  \n\n   **Example**: make the robot walk  \n```bash   \n  rosservice call /keyboard_walk  \n```\n\n**Note**: To enable simulation mode in hand_planner, set the `simulation` flag at the top of HandManager.cpp.\n\n\n### 2. Real Robot Mode\n1. Start the hardware communication node:  \n```bash\n  rosrun surena_eth surena_eth  \n```\n\n2. Initialize hardware:  \n```bash\n  rosservice call /ResetAllNodes \"nodeID: 255\" \n  rosservice call /ActivateLegs \"nodeID: 0\"  \n  rosservice call /ActivateHands \"nodeID: 255\"   \n```\n\n3. Run the robot manager:  \n```bash\n  rosrun robot_manager robot_manager_node  \n```\n\n4. Use services exactly as in simulation (see below).  \n\n\n\n## Core Services\n\n| Service | Type | Description |\n|---------|------|-------------|\n| `/walk_service` | `gait_planner/Trajectory` | Generate and execute walking gait with custom parameters (step length, width, COM height, etc.). |\n| `/keyboard_walk` | `std_srvs/Empty` | Start walking sequence from keyboard teleop. |\n| `/get_data` | `gait_planner/getdata` | Stream robot state data for a specified duration. |\n| `/joint_command` | `gait_planner/command` | Direct joint/motor command (IDs + angles). |\n| `/move_hand_single_srv` | `hand_planner/move_hand_single` | Execute hand motion scenario on left/right hand. |\n| `/move_hand_both_srv` | `hand_planner/move_hand_both` | Execute coordinated bimanual motion. |\n| `/grip_online_srv` | `hand_planner/gripOnline` | Start/finish online grasping controller. |\n| `/head_track_srv` | `hand_planner/head_track` | Perform head tracking for a given duration. |\n| `/set_target_class_srv` | `hand_planner/SetTargetClass` | Set object class for manipulation. |\n| `/home_service` | `std_srvs/Empty` | Return robot to home posture. |\n\n\n## Example Commands\n\n- **Walking with specific parameters**  \n```bash\n  rosservice call /walk_service \"alpha: 0.0  \n  t_double_support: 0.2  \n  t_step: 0.8  \n  step_length: 0.2  \n  step_width: 0.1  \n  COM_height: 0.85  \n  step_count: 4  \n  ankle_height: 0.05  \n  dt: 0.005  \n  theta: 0.0  \n  step_height: 0.04  \n  com_offset: 0.0  \n  is_config: false\"  \n```\n- **Perform an specific scenario with right hand**  \n```bash\n  rosservice call /move_hand_single_srv \"mode: 'righthand'  \n  ee_ini_pos: 'init'  \n  scenario: ['shakeHands']  \n  scen_count: 1  \n  t_total: 8\"  \n```\n- **Move a servo joint (degrees | absolute)**  \n```bash\n  rosservice call /joint_command \"motor_id: 21 angle: 170\"  \n```\n- **Move a non-servo joint (radians | relative)**  \n```bash\n  rosservice call /joint_command \"motor_id: 0 angle: 0.05\"  \n```\n- **Echo force–torque sensor data**  \n```bash\n  rostopic echo /surena/ft_r_state  \n```\n\n\n## Capabilities\n\nSurena-V integrates multiple **AI and perception modules**, including:  \n- Object detection \u0026 tracking  \n- Face recognition \u0026 tracking  \n- Microphone array for sound localization  \n- Large Language Models (LLM) \u0026 Vision-Language Models (VLM) for interactive tasks  \n\n\n\n## Contributing\n\nWe welcome contributions, bug reports, and feature requests!\n\n- Issues: Submit in GitHub Issues tab with logs and steps.  \n- Pull Requests: Fork, improve, and submit a PR.  \n\n\n## License\nThis repository is released under [MIT](https://github.com/CAST-Robotics/surenaV_core/blob/main/LICENSE) license.  \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcast-robotics%2Fsurenav_core","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcast-robotics%2Fsurenav_core","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcast-robotics%2Fsurenav_core/lists"}