← صفحه لیگ Air English version

آموزش مقدماتی شبیه‌ساز FIRA Air (فارسی)

English version: TUTORIAL_EN.md

زمان مطالعه: حدود ۲۰ دقیقه. در پایان، مسیر تمرینی U14 را با examples/base_u14.py پرواز داده‌اید و معنی هر دستور را می‌دانید.

ایدهٔ اصلی: شما کد معمولی DJITelloPy می‌نویسید. شبیه‌ساز وانمود می‌کند یک پهپاد واقعی DJI Tello در آدرس 192.168.10.1 است. همان برنامه، پهپاد واقعی را هم پرواز می‌دهد. هر چیزی که با تست نشده علامت خورده، هنوز در شبیه‌ساز تأیید نشده است.


۱. نصب Python و کتابخانه‌ها

  1. Python 3.12 را از python.org نصب کنید (گزینهٔ «Add python.exe to PATH» را تیک بزنید).
  2. یک ترمینال (PowerShell) باز کنید و اجرا کنید:
pip install djitellopy opencv-python pupil-apriltags av
بسته کاربرد
djitellopy کلاینت SDK تلو (کلاس Tello()) – ضروری
opencv-python پردازش تصویر و نمایش دوربین (cv2)
pupil-apriltags خواندن تگ‌های AprilTag زیر گیت‌ها
av دیکد کردن ویدیوی H.264 (برای streamon لازم است)

بررسی: python -c "import djitellopy, cv2, pupil_apriltags, av; print('ok')"

۲. باز کردن شبیه‌ساز و انتخاب مسیر

  1. FIRA_Air_Simulator.exe را اجرا کنید (برگزارکننده قبلاً tools\setup_network.ps1 را اجرا کرده که آدرس 192.168.10.1 را به سیستم اضافه می‌کند).
  2. دسته را انتخاب کنید: U14 یا U19.
  3. مسیر Practice را انتخاب کنید و وارد زمین (arena) شوید. پهپاد روی پد START نشسته و رو به اولین گیت است.
  4. برنامهٔ خود را روی همان کامپیوتر (یا لپ‌تاپی در شبکهٔ 192.168.10.0/24) اجرا کنید.

در هر لحظه فقط یک برنامه می‌تواند پهپاد را کنترل کند (مثل تلوی واقعی).

۳. مسیری که پرواز می‌دهید

تمرین U14 (configs/stages/practice_u14_demo_v1.json)

نمای بالای U14 با مسیر تأییدشده

نمای بالای مسیر تمرینی U14: START در z = 4، سه گیت روی یک خط راست، پد فرود «H» (L1) در z = −5.8. فلش‌ها دستورهای base_u14.py هستند.

تمرین U19 (configs/stages/practice_u19_demo_v1.json)

نمای بالای U19

نمای بالای مسیر تمرینی U19: پنج گیت (G03 تا G05 چرخیده و تنگ‌شده‌اند)، دو زون، و تنها پد فرود «H» یعنی L1 در (−2.4, 5.4)، ۲٫۲ متر بعد از سمت خروجی آخرین گیت G05. خط‌چین = مسیر برگشت base_u19.py (تست نشده). (شکل هنوز جای قدیمی پد پشت START را نشان می‌دهد.)

پد فرود انتخاب‌شده

تصویر مرجع: پد فرود اعلام‌شده یک نوار روشن (سبز) دور خود دارد.

هندسهٔ گیت‌ها

نمای جانبی ارتفاع گیت‌ها

نمای جانبی: دهانهٔ گیت کوتاه از 0.60 تا 1.20 متر (مرکز 0.90)، گیت بلند از 1.20 تا 1.80 متر (مرکز 1.50). بعد از takeoff() پهپاد در حدود 0.80 متر هاور می‌کند. تگ AprilTag زیر دهانه است – هرگز به سمت تگ پرواز نکنید.

ابعاد گیت

مرجع: ابعاد گیت از نقشهٔ مسابقه.

نقشهٔ گیت فیزیکی

مرجع: نقشهٔ ابعاد گیت فیزیکی که گیت‌های شبیه‌ساز از آن پیروی می‌کنند.

گیت‌های تنگ‌شده با مانع

مرجع: گیت‌های G03 تا G05 در U19 با یک نوار، یک پنل یا یک میلهٔ مورب داخل دهانه «تنگ» شده‌اند.

دوربین پهپاد چه می‌بیند

فریم دوربین از پد شروع

فریم واقعی دوربین (960 × 720) روی پد START: گیت G01 روبه‌رو با تگ AprilTag زیر دهانه.

فریم دوربین در حال هاور

فریم دوربین بلافاصله بعد از تیک‌آف (≈ 0.8 متر): دهانهٔ گیت کوتاه حالا جلوی دوربین است.

فریم دوربین نزدیک گیت ۱

فریم دوربین نزدیک G01: تگ روی پایه، زیر لبهٔ پایین است؛ دهانه همان قاب بنفش بالای آن است.

تشخیص AprilTag

خروجی examples/camera_apriltag_viewer.py که شناسه‌های تگ tag36h11 (۱ و ۵) را از پد شروع رسم کرده است.

۴. دستورها، یکی‌یکی

همهٔ این‌ها متدهای کلاس djitellopy.Tello هستند. دستورهای حرکتی مسدودکننده هستند: تا پهپاد ok برنگرداند برنمی‌گردند (DJITelloPy تا ۷ ثانیه صبر می‌کند). واحدها: سانتی‌متر، درجه، درصد.

متد ربات چه می‌کند واحد / بازه
Tello() کلاینت ساخته می‌شود (آدرس 192.168.10.1، پورت UDP 8889) – هنوز چیزی ارسال نمی‌شود –
connect() دستور command را می‌فرستد و حالت SDK را فعال می‌کند. اگر پاسخی نیاید خطا می‌دهد –
get_battery() درصد باتری ٪ (۰ تا ۱۰۰)
get_height() ارتفاع نسبت به نقطهٔ تیک‌آف (از جریان state) سانتی‌متر
get_distance_tof() فاصلهٔ سنسور ToF رو به پایین تا زمین سانتی‌متر
get_yaw() زاویهٔ سر پهپاد نسبت به جهت روشن‌شدن درجه، −180 تا 180
takeoff() موتورها روشن می‌شوند، بالا می‌رود و در ≈ ۸۰ سانتی‌متر هاور می‌کند –
move_forward(x) / move_back(x) در راستای بدنه مستقیم می‌رود و بعد هاور می‌کند سانتی‌متر، ۲۰ تا ۵۰۰
move_left(x) / move_right(x) حرکت جانبی سانتی‌متر، ۲۰ تا ۵۰۰
move_up(x) / move_down(x) حرکت عمودی سانتی‌متر، ۲۰ تا ۵۰۰
rotate_clockwise(d) / rotate_counter_clockwise(d) درجا می‌چرخد درجه، ۱ تا ۳۶۰
set_speed(s) سرعت پیمایشی که دستورهای move_* استفاده می‌کنند سانتی‌متر بر ثانیه، ۱۰ تا ۱۰۰
send_rc_control(lr, fb, ud, yaw) جوی‌استیک مجازی – پایین توضیح داده شده هر کدام −100 تا 100
streamon() / streamoff() شروع / توقف جریان ویدیو (UDP 11111) –
get_frame_read().frame آخرین فریم دیکدشده به‌صورت آرایهٔ NumPy با فرمت RGB و ابعاد 720 × 960 × 3 (قبل از اولین فریم None است) –
land() پایین می‌آید و موتورها را خاموش می‌کند –
end() اگر هنوز در پرواز است فرود می‌آید، ویدیو را قطع و سوکت‌ها را می‌بندد. همیشه در finally صدا بزنید –

مقادیر خارج از بازه، قبل از ارسال در خود DJITelloPy خطا می‌دهند – دقیقاً مثل پهپاد واقعی. حرکت بلندتر از حدود ۳۰۰ سانتی‌متر ممکن است از مهلت ۷ ثانیه‌ای پاسخ DJITelloPy بگذرد؛ آن را تقسیم کنید.

send_rc_control – جوی‌استیک

محورهای بدنه و کانال‌های rc

محورهای بدنه: fb مثبت = جلو (جهت دوربین)، lr مثبت = راست، ud مثبت = بالا، yaw مثبت = ساعتگرد.

کوچک‌ترین برنامه

from djitellopy import Tello

t = Tello()
t.connect()
print(t.get_battery(), "%", t.get_height(), "cm", t.get_distance_tof(), "cm")
t.takeoff()            # حدود ۸۰ سانتی‌متر
t.move_up(20)          # حدود ۱۰۰ سانتی‌متر
t.move_forward(100)    # ۱ متر مستقیم جلو
t.rotate_clockwise(90)
t.land()
t.end()

سنسورهای Tello و دستورهای خواندن آن‌ها (حدود ۱۵ دقیقه)

تا وقتی برنامهٔ شما از پهپاد سؤال نپرسد، Tello «کور» پرواز می‌کند. هر سنسوری که در ادامه می‌آید یک قطعهٔ واقعی روی پهپاد واقعی است و شبیه‌ساز همان قطعه را با همان واحدها مدل می‌کند (godot/scripts/physics/tello_sensors.gd)؛ پس هر چه این‌جا یاد می‌گیرید روی سخت‌افزار هم کار می‌کند.

سنسورهای Tello از نمای کنار

نمای کنار یک Tello و سنسورهایش. دوربین جلو (آبی) رو به جلو نگاه می‌کند، فاصله‌سنج ToF (قرمز) یک پرتو باریک مادون‌قرمز مستقیم به پایین می‌فرستد، دوربین VPS (سبز) ناحیهٔ وسیعی از کف را می‌بیند، IMU و بارومتر داخل بدنه هستند و باتری عقب است. محورهای بدنه: x جلو، y راست، z پایین.

مقدارها چطور به شما می‌رسند. پهپاد حدود ۱۰ بار در ثانیه (~10 Hz) یک خط متنی روی پورت UDP 8890 پخش می‌کند. DJITelloPy آخرین خط را نگه می‌دارد و همهٔ متدهای get_*() زیر فقط یک فیلد از همان خط را می‌خوانند؛ پس فوری برمی‌گردند ولی ممکن است تا ~۱۰۰ میلی‌ثانیه قدیمی باشند. متدهای query_*() یک سؤال می‌فرستند (battery?، tof?، ...) و منتظر جواب می‌مانند؛ کندترند ولی تازه. برای شروع: داخل حلقه‌ها get_*()، و query_*() فقط گاه‌به‌گاه.

یک خط واقعی که از شبیه‌ساز روی زمین ضبط شده (artifacts/test_reports/phase1_raw_wire.json، کلید state_sample):

pitch:0;roll:0;yaw:0;vgx:-2;vgy:-1;vgz:0;templ:48;temph:51;tof:10;h:0;bat:95;baro:31.04;time:0;agx:-2.59;agy:-2.62;agz:-995.33;

get_current_state() همین خط را به‌صورت دیکشنری Python می‌دهد:

s = t.get_current_state()
print(s["tof"], s["h"], s["bat"], s["yaw"])   # مثلاً 10 0 95 0

قطعه‌کدهای زیر فرض می‌کنند t یک Tello() متصل است و بالای فایل import time دارید.

۱. فاصله‌سنج رو به پایین (ToF / مادون‌قرمز)

d = t.get_distance_tof()          # سانتی‌متر
if d == 6553:
    print("بدون بازتاب - خیلی بالا یا چیزی زیر پهپاد نیست")
elif d < 60:
    t.move_up(30)                 # اگر کف نزدیک‌تر از ۶۰ سانتی‌متر است بالا برو

۲. بارومتر (فشارسنج)

base = t.get_barometer()          # سانتی‌متر، قبل از تیک‌آف
t.takeoff()
print("با بارومتر حدود", t.get_barometer() - base, "سانتی‌متر بالا رفت")   # ~ ۸۰ تا ۹۰، نویزی

فقط برای اختلاف‌ها از آن استفاده کنید، هرگز برای ارتفاع مطلق. داخل سالن tof / h را ترجیح دهید.

۳. ارتفاع ترکیبی h

t.takeoff()
while t.get_height() < 100:       # تا ۱ متر بالا برو، بعد بایست
    t.send_rc_control(0, 0, 30, 0)
    time.sleep(0.05)
t.send_rc_control(0, 0, 0, 0)

۴. IMU – ژیروسکوپ و وضعیت (pitch، roll، yaw)

start = t.get_yaw()
t.rotate_clockwise(90)
turned = (t.get_yaw() - start + 180) % 360 - 180   # پیچش 180/−180 را درست می‌کند
print("چرخید", turned, "درجه")                      # ~ ۹۰

۵. IMU – شتاب‌سنج (agx، agy، agz)

ax, ay, az = t.get_acceleration_x(), t.get_acceleration_y(), t.get_acceleration_z()
print(f"{ax:.0f} {ay:.0f} {az:.0f} milli-g")       # مثلاً -1  2  -999 در سکون
if abs(az) < 800:
    print("کج‌شدن شدید یا سقوط آزاد")

۶. تخمین سرعت (vgx، vgy، vgz)

t.send_rc_control(0, 50, 0, 0)
time.sleep(1.0)
print("سرعت جلو", t.get_speed_x(), "cm/s")         # ~ ۴۷
t.send_rc_control(0, 0, 0, 0)                      # ترمز

۷. دوربین VPS رو به پایین (فقط داخلی)

۸. باتری

if t.get_battery() < 20:
    raise SystemExit("اول شارژ کنید")
t.takeoff()

۹. دما

print(t.get_temperature(), "C")                    # مثلاً 49.5

۱۰. زمان کار موتور

t.takeoff(); time.sleep(3)
print("موتورها", t.get_flight_time(), "ثانیه کار کردند")   # ~ ۳ یا ۴

۱۱. دوربین جلو

t.streamon()
fr = t.get_frame_read()
while fr.frame is None:
    time.sleep(0.05)
h, w, _ = fr.frame.shape            # 720 960 3
print(fr.frame[360, 480])           # RGB پیکسل وسط

۱۲. سیگنال Wi‑Fi

زمین در برابر هاور: اعداد کنار هم

از artifacts/test_reports/phase2_correlations.json (یک اجرا، همان پهپاد):

فیلد روی زمین هاور بعد از takeoff() حرکت رو به جلو (rc fb=50)
tof (cm) 10 93 93
h (cm) 0 83 82
baro (m) 31.06 31.93 31.95
pitch / yaw (deg) 0 / 0 0 / 0 −5 / 60
vgx (cm/s) −2 1 47
agz (0.001 g) −999 −1002 −988
bat (%) 95 95 95
time (s) 0 3 5

کدام سنسور برای کدام کار

کار از این استفاده کنید نه از این
هم‌راستا شدن با گیت دوربین جلو (get_frame_read().frame) – جای گیت در تصویر vgx/vgy (سرعت را می‌گویند، نه جای گیت را)
نگه‌داشتن یا تغییر ارتفاع get_distance_tof() / get_height() همراه send_rc_control(0,0,ud,0) get_barometer() (می‌لغزد)
چرخش به اندازهٔ زاویهٔ مشخص get_yaw() قبل و بعد، یا rotate_clockwise() فقط دوربین
توقف / ترمز send_rc_control(0, 0, 0, 0) و صبر تا get_speed_x() نزدیک ۰ شود «حرکت معکوس» با move_back
تشخیص لغزش در هاور get_speed_x()، get_speed_y() غیر صفر در حالی که استیک‌ها وسط‌اند –
تصمیم به پرواز یا نه get_battery() ≥ 20، get_temperature() < 65 –
مطمئن‌شدن از روی زمین بودن get_height() == 0 و get_distance_tof() == 10 baro

۵. همین حالا مسیر U14 را پرواز دهید

python examples\base_u14.py

این فایل مسیر را به‌صورت لیست (دستور، مقدار) با یک کامنت برای هر خط دارد. مسیر همان مسیر تأییدشده در artifacts/demo/RESULT.md است:

up 20 → forward 300 (G01) → forward 300 (G02) → up 50 → forward 300 (G03) → forward 65 → down 60 → land

نتیجهٔ اجرای تأییدشده: GATE_VALID G01, G02, G03، LANDING_VALID L1، ATTEMPT_SUCCEEDED. توجه کنید که پرواز حلقه‌باز در مسیر ۱۰ متری حدود ± 0.3 متر خطا دارد، پس فرود در هر اجرا تضمین نمی‌شود – یکی از دو اجرای تمیز ۰٫۲۹ متر جلوتر نشست. بهتر کردن این موضوع (با تله‌متری و دوربین) کار شماست.

برای U19 از examples\base_u19.py شروع کنید: گیت‌های G01 + G02 + ZONE_1 همان مسیر دموی منتشرشده است (up 20, forward 300, up 50, forward 300, forward 70)؛ برگشت به پد H (rotate_clockwise 180, forward 300, forward 300, forward 100, down 60, forward 50, land) فقط نقطهٔ شروع است – تست نشده.

۶. قوانین داوری (آن‌طور که در شبیه‌ساز پیاده شده)

قانون امتیازدهی

امتیاز = B (بهترین زونی که در یک تلاش معتبر رسیده‌اید) − P (تعداد تلاش‌های ناموفق)؛ تکمیل کامل مسیر ۲۵ امتیاز دارد.

خواندن پنل داور

در زمین کلید Esc را بزنید تا پنل داور / لاگ رویدادها باز شود. رویدادهایی که می‌بینید:

رویداد معنی
PAD_SELECTED پد فرود هدف اعلام شد (مراحل رسمی U19 ممکن است این کار را بعد از تیک‌آف انجام دهند)
GATE_VALID G0x گیت درست عبور شد
GATE_TOUCH G0x:rim به قاب خوردید → تلاش ناموفق، ۱+ جریمه
ZONE_ENTER / ZONE_VALID وارد زون امتیازی شدید / حساب شد
LANDING_VALID L1 کاملاً داخل پد هدف فرود آمدید
LANDING_INVALID … بیرون یا نیمه‌بیرون پد فرود آمدید
ATTEMPT_SUCCEEDED / ATTEMPT_FAILED حکم نهایی تلاش
BOUNDARY_EXIT از حجم پرواز زمین خارج شدید
INFRASTRUCTURE_OVERLOAD کامپیوتر خیلی کند است؛ نتایج آن اجرا قابل اعتماد نیست

۷. مشکلات رایج

علامت علت / راه‌حل
connect() خطای «Did not receive a response» / timeout می‌دهد شبیه‌ساز هنوز وارد زمین نشده؛ آدرس 192.168.10.1 وجود ندارد (tools\setup_network.ps1 را اجرا کنید)؛ فایروال؛ برنامهٔ دیگری پهپاد را کنترل می‌کند
پاسخ error است دستور رد شده: مقدار خارج از بازه، move در حالی که در پرواز نیستید، takeoff وقتی در پروازید، باتری کم؛ در U19 دیده شده که forward 300 وقتی دو شبیه‌ساز روی یک پورت بودند error برگردانده
«Cannot bind UDP 192.168.10.1:8889» (در شبیه‌ساز) آدرس وجود ندارد یا یک نمونهٔ دیگر از شبیه‌ساز باز است – آن را ببندید؛ نمونهٔ دوم باعث می‌شود پاسخ‌ها به‌جای ok اکو شوند (مثلاً «up 50»)
KeyError یا پاسخ عجیب داخل DJITelloPy پاسخ دیرهنگام دستور قبلی روی کامپیوتر پرفشار؛ برنامه‌های دیگر را ببندید، گرافیک را کم کنید
ویدیو نمی‌آید (frame همیشه None است) بعد از streamon() ۲ تا ۳ ثانیه صبر کنید؛ نصب بودن av، وجود ffmpeg و قانون فایروال برای UDP 11111 را بررسی کنید؛ اولین فریم ممکن است 400 × 300 باشد و بعد 960 × 720 شود
پهپاد خودش فرود می‌آید ۱۵ ثانیه بدون هیچ دستور (watchdog) – چیزی بفرستید، مثلاً get_battery() یا send_rc_control
اجرای tools\doctor.py روی کامپیوتر شبیه‌ساز تشخیص وضعیت شبکه و پورت‌ها را چاپ می‌کند

۸. Map Creator (ساخت مسیر خودتان)

در صفحهٔ انتخاب دسته کلید M را بزنید تا Map Creator باز شود. نقشه‌های ذخیره‌شده در این مسیر قرار می‌گیرند:

%APPDATA%\Godot\app_userdata\FIRA Air Simulator\stages\

و کنار مسیرهای تمرینی پیش‌فرض در لیست مسیرها ظاهر می‌شوند. فایل‌های JSON موجود در configs/stages/ مرجع فرمت هستند (واحد متر، height_config برابر low یا high).

۹. زاویه‌های دوربین تماشاگر

در زمین کلید C را بزنید تا بین حالت‌ها بچرخید، یا روی دکمه‌های پایین صفحه کلیک کنید: Follow Smooth, Chase Low, Orbit Free, Gate Focus, Trackside, Overhead, Crane/Dolly, Landing Focus, Auto Director, True Tello FPV. در حالت Orbit با درگ / چرخ ماوس دوربین را بچرخانید. «True Tello FPV» همان تصویری است که برنامهٔ شما دریافت می‌کند.

۱۰. قدم بعدی