• 1. Team
• 2. Project Overview
• 3. Key Features
• 4. Core Technologies
• 5. Technical Challenges and Solutions
• 6. System Design
• 7. Project Structure
• 8. Tech Stack
• 9. Project Management
• 10. License

📄 Looking for the Korean version? See README.ko.md.

Name	GitHub	Role
Jinhyuk Jang		Project planning & overall leadership ROS2 architecture, package layout, and FSM design Vision AI model & Vision Service implementation ROS2 × PyQt Robot GUI development

Name	GitHub	Role
Jiyeon Kim		Backend development & DB design micro-ROS IO controller HTTP/WebSocket × PyQt Admin GUI Robot hardware fabrication
Jongmyeong Kim		FreeRTOS-based robot arm control HTTP/WebSocket × HTML/JS/CSS Guest GUI HTTP/WebSocket × PyQt Staff GUI Jira schedule management & robot hardware build
Hyojin Park		SLAM & navigation lead Static/dynamic obstacle-handling algorithms Path planning & driving behaviors System integration for delivery/escort/elevator features

Room Service Delivery

Wayfinding Escort

Inter-floor Travel

Admin Monitoring

• Project Goal

  • Let the robot autonomously take over repetitive hotel operations so that staff workload is reduced and guests receive a novel, convenient service.

• Project Timeline

  • July 7, 2025 – August 13, 2025 (38 days)

Robot arm control principle

Button press with the arm

View the detailed design

• Hardware
  • Servo motors
  • 2D camera
  • Button-click end effector
• Button detection
  • Compute base → wrist → camera → button coordinates
• Motion sequence
  • Observation pose → pre-push pose → button press → confirmation
• Control method
  • Apply a Gaussian velocity/acceleration profile to minimize jitter

Path creation

Static obstacle avoidance

Dynamic obstacle avoidance

• Nav2-based navigation
  • Generate and follow global/local paths
• Waypoint-driven path creation
  • Match depth-camera obstacles to pre-defined waypoints
  • Use the A* algorithm to compute the optimal route
• Dynamic obstacle handling
  • Detect obstacles via the depth camera in real time
  • Stop within a threshold distance and resume once the path clears
• RTR motion (Rotate–Translate–Rotate)
  • Provides precise alignment and backward motion inside elevators

Obstacle detection while driving

Elevator exterior perception

DeepSORT-based guest tracking

• YOLOv8n object detection
  • Obstacles: static, dynamic, glass doors
  • Elevators: buttons, displays, doors, direction indicators
• Accuracy boosters
  • CNN classifies detailed button types
  • EasyOCR reads the floor indicator
• Person tracking
  • YOLOv8n detects people
  • DeepSORT tracks a specific guest and publishes coordinates

Ultrasonic sensors for load and door detection

Drawer control via micro-ROS

• Drawer-door detection
  • Measure the distance between the sensor and door
  • If the distance exceeds 5.0 cm, the drawer is considered open
• Load detection
  • Side-mounted sensors measure the internal width
  • If the distance is below 25.0 cm, cargo is detected
• RFID card reader
  • MFRC522 reads the UID of each RFID card
  • Interprets the 4-byte value stored in block 4 as location_id
  • Publishes success=true + the location value on success; success=false, location_id=-1 otherwise
• RGB LED status

  • Control the LED color based on the RobotState

  • 💡 View the control logic

    
    

    State ID	State name	RGB LED
    0	INITIAL	Cyan
    1, 2, 11, 13, 21, 23	CHARGING, WAITING, PICKUP_WAITING, DELIVERY_WAITING, GUIDE_WAITING, DESTINATION_SEARCHING	Green
    10, 12, 20, 22, 30, 31	PICKUP_MOVING, DELIVERY_MOVING, CALL_MOVING, GUIDE_MOVING, RETURN_MOVING, ELEVATOR_RIDING	Blue
    90	ERROR	Red

• Problem: Constant-velocity control created small jitter at the end effector.
• Solution: Applied Gaussian velocity/acceleration profiles to smooth out the motion.

• Problem: The robot could not re-route when corridors were narrow or blocked.
• Solution: Added waypoint-based detours and ran the A* algorithm to compute bypass paths in advance.

YOLOv8n + CNN pipeline for buttons

YOLOv8n + EasyOCR pipeline for floors

• Problem: Adding more classes to YOLO degraded accuracy.
• Solution: YOLOv8n generates the ROI, a CNN classifies the button, and EasyOCR interprets the floor indicator.

• Problem: Plain Nav2 navigation struggled with button pressing and precise alignment.
• Solution: Introduced RTR (Rotate–Translate–Rotate) patterns to enable fine alignment and backward motion.

[Priority Legend]
- `R` : Required implementation 
- `O` : Optional implementation  

[Priority Legend]
- `R` : Required implementation 
- `O` : Optional implementation  

Elevators are notorious for unstable or non-existent network connectivity.
To stay reliable, Roomie embeds the Vision Service on the robot (on-device AI) so that buttons, doors, and floor indicators can be recognized offline.

Roomie/
├── ros2_ws/                            # Shared ROS2 workspace
│   ├── build/                          # Created by colcon build
│   ├── install/
│   ├── log/
│   └── src/
│       ├── micro_ros_setup/            # micro-ROS build tools
│       ├── roomie_msgs/                # Shared messages (msg/srv/action)
│       ├── roomie_rc/                  # Robot Controller node (RC)
│       ├── roomie_rgui/                # Robot GUI node (RGUI)
│       ├── roomie_vs/                  # Vision Service node (VS)
│       ├── roomie_rms/                 # Main server node (RMS)
│       ├── roomie_agui/                # Admin GUI node (AGUI)
│       ├── roomie_ac/                  # Arm Controller node (AC)
│       └── bringup/                    # Integrated launch files
│
├── esp32_firmware/                     # ESP32 firmware for micro-ROS
│   ├── arm_unit/                       # Servo control firmware for the arm
│   │   └── src/
│   └── io_controller/                  # Sensor, drawer, LED control
│       └── src/
│
├── gui/                                # Non-ROS GUI apps
│   ├── staff_gui/                      # Staff GUI
│   └── guest_gui/                      # Guest GUI
│
├── assets/                             # Images and resources
│   └── images/
│
├── docs/                               # Design documents
│   ├── architecture/                   # System architecture
│   ├── interface.md                    # Communication interface definitions
│   └── state_diagram/                  # State diagram
│
├── .gitignore
├── README.md
└── LICENSE

Category	Technologies
ML / DL
GUI
Network & Protocol
Robotics
Environment

▪ Managed via Jira with six sprints. ▪ Organized the backlog with Epic → Task hierarchies.

▪ Documented the workflow in Confluence across planning, design, research, implementation, and testing. ▪ Logged progress at regular intervals.

This project is licensed under the Apache License 2.0. Refer to the LICENSE file for details.