توثيق تطوير SDK لهيكل Tbot ثلاثي الأبعاد

يعتمد بروتوكول rosbridge WebSocket للتحكم في الهيكل بلغات متعددة دون الحاجة إلى بيئة ROS. توثّق هذه الصفحة بالكامل حقول الطلب والاستجابة لكل Topic / Service (النوع + الوصف).

1. نظرة عامة على البروتوكول

2. اشتراك Topic (الهيكل ← التطبيق)

اشتراك. الرسالة المستقبلة في حقل msg.

3. جدول ملخص Service

2.1 تحديد موقع الروبوت nav_msgs/Odometry

الهيكل يرسل الوضعية الحالية دورياً.

{
  "pose": { "pose": {
    "position": {"x": 1.23, "y": 4.56, "z": 0.0},
    "orientation": {"x": 0, "y": 0, "z": 0.5, "w": 0.866}
  }}
}

2.2 المسار العام nav_msgs/Path

بعد بدء الملاحة يُرسل مرة كل 5 ثوانٍ، 5 مرات (حوالي 30 ثانية).

{ "poses": [
  {"pose":{"position":{"x":0,"y":0,"z":0}}},
  {"pose":{"position":{"x":1,"y":2,"z":0}}}
]}

2.3 قائمة الخرائط kitty_runtime_manager/MapList

بعد الاشتراك يُرجع كل الخرائط ونقاط الهدف المحفوظة.

{ "maps": [
  {"map_name":"Lobby","map_path":"/maps/floor1",
   "goals":[
     {"name":"Reception","x":1.0,"y":2.0,"theta":0.5},
     {"name":"Elevator","x":3.0,"y":4.0,"theta":1.2}
   ]}
]}

2.4 حالة الملاحة std_msgs/Float64MultiArray

Topic: /ebot_goal_status_local_planner.

2.5 البطارية وحالة الشحن std_msgs/Float64MultiArray

Topic: /ebot_work_state.

3.1 بدء بناء الخريطة std_srvs/Trigger

Service:/start_mapping_kitty

{}

{ "success": true, "message": "Mapping started" }

3.2 حفظ الخريطة kitty_runtime_manager/SaveMap

Service:/save_map_kitty

{ "filepath": "map_name" }

{ "success": true, "message": "Map saved" }

3.3 اختيار خريطة وبدء الملاحة kitty_runtime_manager/SaveMap

Service:/select_map_and_start_kitty

{ "filepath": "map_name" }

{ "success": true, "message": "Map selected and navigation started" }

3.4 حذف الخريطة kitty_runtime_manager/DeleteMap

Service:/delete_map_kitty

{ "map_name": "map_name" }

{ "success": true, "message": "Deleted successfully" }

3.5 العودة لمحطة الشحن std_srvs/Trigger

Service:/docking_kitty

{}

{ "success": true, "message": "Docking started" }

3.6 الملاحة لنقطة الهدف nav_msgs/GetPlan

Service:/navigate_to_pose

{
  "goal": { "pose": { "position": { "x": 1.0, "y": 2.0, "z": 0.0 } } }
}

{ "plan": { "poses": [
  {"pose":{"position":{"x":0,"y":0,"z":0}}},
  {"pose":{"position":{"x":1,"y":2,"z":0}}}
]}}

3.7 إلغاء الملاحة nav_msgs/GetPlan

Service:/navigate_to_pose（(مع الملاحة في نفس الخدمة، تمييز بإحداثيات خاصة)）

{
  "goal": { "pose": { "position": { "x": 999999, "y": 888888, "z": 0 } } }
}

{ "plan": { "poses": [] } }

3.8 إضافة نقطة هدف kitty_runtime_manager/AddGoal

Service:/add_goal_kitty

{
  "map_name": "Lobby",
  "goal_name": "Reception",
  "x": 1.0, "y": 2.0, "theta": 0.5
}

{ "success": true, "message": "Added successfully" }

3.9 حذف نقطة الهدف kitty_runtime_manager/DeleteGoal

Service:/delete_goal_kitty

{ "map_name": "Lobby", "goal_name": "Reception" }

{ "success": true, "message": "Deleted successfully" }

4. أمثلة تطوير متعددة اللغات

تعرض كل لغة مثالاً سريعاً افتراضياً (اتصال + اشتراك مستوى البطارية + العودة إلى الإرساء)، وبالنقر على «عرض الكود الكامل» يُفتح العرض الكامل لكل 5 Topics + 9 Services.

4.1 Python（roslibpy）عرض الكود الكامل (كل الواجهات)

التبعيات:pip install roslibpy

import roslibpy, time
client = roslibpy.Ros(host='192.168.1.151', port=9090)
client.run()

# Subscribe to battery state
roslibpy.Topic(client,'/ebot_work_state','std_msgs/Float64MultiArray').subscribe(
    lambda m: print(f"Battery {m['data'][1]}% charging={m['data'][0]==1}"))
# Dock to charger
roslibpy.Service(client,'/docking_kitty','std_srvs/Trigger').call(roslibpy.ServiceRequest(),
    callback=lambda r: print("Docking:", r['message']))
try:
    while True: time.sleep(1)
except KeyboardInterrupt: client.terminate()

import roslibpy, time, math
client = roslibpy.Ros(host='192.168.1.151', port=9090)
client.run()

# ===== Subscribe to all 5 Topics =====
# 1) Localization
def on_odom(m):
    p = m['pose']['pose']['position']; o = m['pose']['pose']['orientation']
    yaw = math.atan2(2*(o['w']*o['z']+o['x']*o['y']), 1-2*(o['z']**2+o['y']**2))
    print(f"[Pose] x={p['x']:.2f} y={p['y']:.2f} yaw={math.degrees(yaw):.1f}°")
roslibpy.Topic(client,'/fast_lio_localization','nav_msgs/Odometry').subscribe(on_odom)
# 2) Global path
roslibpy.Topic(client,'/aft_pgo_path','nav_msgs/Path').subscribe(
    lambda m: print(f"[Path] {len(m['poses'])}  points"))
# 3) Map list
roslibpy.Topic(client,'/map_list_kitty','kitty_runtime_manager/MapList').subscribe(
    lambda m: [print(f"[Map] {mp['map_name']}  goals:{[g['name'] for g in mp['goals']]}") for mp in m['maps']])
# 4) Navigation status
roslibpy.Topic(client,'/ebot_goal_status_local_planner','std_msgs/Float64MultiArray').subscribe(
    lambda m: m['data'][0]==1 and print("✅ Arrived"))
# 5) Battery
roslibpy.Topic(client,'/ebot_work_state','std_msgs/Float64MultiArray').subscribe(
    lambda m: print(f"[Battery] {m['data'][1]:.0f}% {'Charging' if m['data'][0]==1 else 'Not charging'}"))

# ===== Call all 9 Services =====
def call(svc, args, srv):
    r = roslibpy.Service(client, svc, srv).call(roslibpy.ServiceRequest(args))
    print(f"[SVC] {svc} → {dict(r)}")
time.sleep(1)
call('/start_mapping_kitty', {}, 'std_srvs/Trigger')
call('/save_map_kitty', {'filepath':'test_map'}, 'kitty_runtime_manager/SaveMap')
call('/select_map_and_start_kitty', {'filepath':'test_map'}, 'kitty_runtime_manager/SaveMap')
call('/navigate_to_pose', {'goal':{'pose':{'position':{'x':1.0,'y':2.0,'z':0.0}}}}, 'nav_msgs/GetPlan')
call('/navigate_to_pose', {'goal':{'pose':{'position':{'x':999999,'y':888888,'z':0}}}}, 'nav_msgs/GetPlan')
call('/add_goal_kitty', {'map_name':'test_map','goal_name':'Reception','x':1.0,'y':2.0,'theta':0.5}, 'kitty_runtime_manager/AddGoal')
call('/delete_goal_kitty', {'map_name':'test_map','goal_name':'Reception'}, 'kitty_runtime_manager/DeleteGoal')
call('/docking_kitty', {}, 'std_srvs/Trigger')
call('/delete_map_kitty', {'map_name':'test_map'}, 'kitty_runtime_manager/DeleteMap')

try:
    while True: time.sleep(1)
except KeyboardInterrupt: client.terminate()

4.2 JavaScript / HTMLعرض الكود الكامل (كل الواجهات)

بلا تبعيات، الصقه في وسماً