← صفحه لیگ Chovgan

آموزش از صفر: لیگ Chovgan

این آموزش برای کسی است که تا حالا ربات برنامه‌نویسی نکرده. همه‌ی کدها Python هستند و در خود شبیه‌ساز CHOVGAN 1.0.0 اجرا و آزمایش شده‌اند. قدم‌به‌قدم جلو می‌رویم:

  1. ربات را با فرمان‌های ساده خط‌به‌خط تکان می‌دهیم: forward(2)، turn_left(90).
  2. می‌بینیم زیر این فرمان‌ها چیست: دو موتور.
  3. همه‌ی حسگرها را می‌خوانیم.
  4. با قطب‌نما دقیق می‌چرخیم، با GPS به هر نقطه می‌رویم و با سونار به چیزی نمی‌خوریم.
  5. توپ را به سمت دروازه هل می‌دهیم و ربات‌ها با هم حرف می‌زنند.
  6. در آخر تیم کامل چهار نفره را می‌خوانیم و عوض می‌کنیم.

برای هر درس یک جلسه‌ی کلاس در نظر گرفته شده است. طرح درس جلسه‌به‌جلسه در صفحه‌ی لیگ هست.


۰. داخل این بسته چیست

Chovgan-BaseCode.zip
├── team_name.txt          نام تیم، در یک خط
├── chovgan_team/          کد تیم شما (همین پوشه به شبیه‌ساز داده می‌شود)
│   ├── robot.py           راه‌انداز. عدد LESSON این‌جاست
│   ├── lessons.py         درس‌های ۱ تا ۸
│   ├── chovgan_robot.py   کلاس مشترک: حسگرها، موتورها و فرمان‌های ساده
│   ├── utils.py           توابع کمکی تیم کامل
│   ├── robot1.py          دروازه‌بان
│   ├── robot2.py          مدافع
│   ├── robot3.py          مهاجم اول
│   └── robot4.py          مهاجم کناری
├── img/                   تصویرهای این آموزش
├── README.md
└── TUTORIAL-FA.md         همین آموزش

۱. نصب و اولین مسابقه

  1. از صفحه‌ی لیگ، CHOVGAN-1.0.0-windows-x86_64.zip را بگیرید، راست‌کلیک کنید و Extract All بزنید، مثلاً در C:\CHOVGAN. داخل پوشه چیزی را جابه‌جا نکنید. CHOVGAN.exe باید کنار پوشه‌های python و sdk بماند. Python را لازم نیست جدا نصب کنید؛ داخل شبیه‌ساز هست.

  2. CHOVGAN.exe را باز کنید. اگر ویندوز پنجره‌ی آبی «Windows protected your PC» نشان داد، More info و بعد Run anyway.

منوی اصلی شبیه‌ساز

  1. همین بسته (Chovgan-BaseCode.zip) را هم کنار دستتان باز کنید، مثلاً در Documents\chovgan_base.

  2. اولین مسابقه، بدون تغییر کد: Competition را بزنید، رده‌ی خود را انتخاب کنید و نام دو تیم را بنویسید. در مرحله‌ی STRATEGY برای هر دو تیم روی Select team ZIP… بزنید و همین Chovgan-BaseCode.zip را بدهید. زیر نام تیم باید VALID بیاید. بعد READY و شروع.

مرحله‌ی STRATEGY با دو تیم VALID

بدون کد، ربات حرکت نمی‌کند. تا هر دو تیم کد VALID نداشته باشند، مسابقه و تمرین شروع نمی‌شوند. ربات‌ها هیچ حرکت خودکار یا تصادفی ندارند؛ هر حرکتی که می‌بینید از کد Python شماست.

چرخه‌ی کار با کد

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

  1. فایل را در VS Code یا Notepad++ ویرایش و ذخیره کنید.
  2. پوشه‌ی chovgan_team و فایل team_name.txt را با هم انتخاب کنید، راست‌کلیک، Send to → Compressed (zipped) folder.
  3. ZIP تازه را در شبیه‌ساز بدهید. برای درس‌ها از Training → Movement استفاده کنید (پایین‌تر).

ZIP باید chovgan_team/ و team_name.txt را مستقیم در سطح اول داشته باشد، نه داخل یک پوشه‌ی دیگر.


۲. ربات و زمین

هر تیم چهار ربات دارد. شبیه‌ساز فایل chovgan_team/robot.py را برای هر ربات جداگانه اجرا می‌کند. اسم ربات (B1 تا B4 برای آبی، Y1 تا Y4 برای زرد) می‌گوید کدام بازیکن است. در کد، self.number همان عدد ۱ تا ۴ است.

نقشه‌ی زمین

حسگرهای ربات


۳. درس‌ها را کجا اجرا کنیم: Training → Movement

برای درس‌ها مسابقه لازم نیست. از منوی اصلی Training و بعد کاشی Movement را بزنید. با Import ZIP فایل ZIP تیم را بدهید و Start بزنید.

صفحه‌ی Training

خروجی print ربات‌ها را در منوی مکث (Esc) و بعد Controller status می‌بینید. اگر رباتی خطا بدهد (CRASHED)، متن خطا همان‌جاست.

پنل Controller status

برای اجرای هر درس: در chovgan_team/robot.py عدد LESSON را عوض کنید، ذخیره کنید، ZIP بسازید و Reload code بزنید.

LESSON = 1          # 0 = تیم کامل مسابقه، 1 تا 8 = درس‌ها

اگر توپ از زمین بیرون برود، شبیه‌ساز بازی را برای شروع مجدد متوقف می‌کند و ربات‌ها را سر جایشان می‌گذارد. در این لحظه ربات‌ها حرکت نمی‌کنند. این ایراد کد شما نیست.


۴. درس ۱: ربات را خط‌به‌خط تکان بده (LESSON = 1)

این ساده‌ترین راه حرکت دادن ربات است. هر خط یک کار انجام می‌دهد و تا تمام نشود خط بعدی اجرا نمی‌شود:

class Lesson1Commands(ChovganRobot):
    def run(self):
        self.wait(0.5)              # نیم ثانیه صبر: حسگرها اولین عددشان را بگیرند
        self.turn_to(180)           # رو به -x، جایی که خالی است
        self.forward(2)             # ۲ ثانیه جلو
        self.turn_left(90)          # ۹۰ درجه به چپ
        self.forward(1.5)
        self.turn_right(90)         # ۹۰ درجه به راست
        self.backward(1)            # ۱ ثانیه عقب
فرمان چه می‌کند
forward(t) t ثانیه مستقیم جلو. با قطب‌نما جهتش را نگه می‌دارد تا کج نرود. سرعت پیش‌فرض ۵
forward(t, speed=8) همان، با سرعت ۸ (بیشینه ۱۰)
backward(t) t ثانیه مستقیم عقب
turn_left(d) d درجه در جا به چپ
turn_right(d) d درجه در جا به راست
turn_to(h) در جا بچرخ تا رو به جهت h باشی: ۰ = ‎+x، ۹۰ = ‎+y، ۱۸۰ = ‎-x، ‎-90 = ‎-y
drive_to(x, y) با GPS به نقطه‌ی (x, y) زمین برو و بایست (درس ۵)
wait(t) t ثانیه بایست
stop() هر دو موتور صفر

چرا فقط ربات ۳ حرکت می‌کند؟ بالای lessons.py عدد MOVER = 3 است. در درس‌های ۱، ۲ و ۴ فقط همین ربات حرکت می‌کند و بقیه می‌ایستند تا ربات‌ها به هم نخورند. برای دیدن ربات دیگر، عدد را عوض کنید.

تمرین‌ها: - forward(2) را forward(4) کنید. ربات چقدر دورتر می‌رود؟ - ربات یک مستطیل بکشد و به جای اولش برگردد. - یک print بگذارید که بعد از هر حرکت جای ربات را چاپ کند: print(self.name, self.position()).


۵. درس ۲: زیر فرمان‌ها چیست؟ دو موتور (LESSON = 2)

forward و turn_left در واقع به دو موتور عدد می‌دهند. ربات دو موتور دارد: چپ و راست. هر کدام سرعتی بین ‎-10 و ‎+10 می‌گیرد. سرعت ۱۰ حدود ۱۴ متر بر ثانیه است.

موتور چپ موتور راست نتیجه
‎+5 ‎+5 مستقیم جلو
‎-4 ‎-4 عقب
‎-3 ‎+3 چرخش در جا به چپ
‎+3 ‎-3 چرخش در جا به راست
‎+6 ‎+3 قوس به راست
self.left.setVelocity(5)     # موتور چپ
self.right.setVelocity(5)    # موتور راست: هر دو برابر = جلو
self.tick()                  # ۳۲ میلی‌ثانیه جلو برو

حلقه‌ی اصلی. شبیه‌ساز زمان را قدم‌به‌قدم جلو می‌برد. هر self.tick() یک قدم ۳۲ میلی‌ثانیه‌ای است (داخلش robot.step(32) صدا زده می‌شود و همه‌ی حسگرها تازه می‌شوند). موتور تا وقتی عدد تازه نگیرد، با همان سرعت می‌ماند. فرمان‌های درس ۱ همین حلقه را برایتان می‌چرخانند.

در Lesson2Motors یک جدول PLAN هست. هر ردیف تا یک زمان مشخص اجرا می‌شود:

PLAN = [               # (تا چند ثانیه، موتور چپ، موتور راست، توضیح)
    (2.0,  5.0,  5.0, "forward"),
    (3.5, -3.0,  3.0, "turn left on the spot"),
    (5.5,  6.0,  3.0, "arc to the right"),
    ...
]

تمرین: در Robot Lab بخش Turning Test را امتحان کنید. بعد یک ردیف به PLAN اضافه کنید که ربات یک دایره‌ی کامل بزند.

Robot Lab


۶. درس ۳: همه‌ی حسگرها (LESSON = 3)

ربات حرکت نمی‌کند و هر ثانیه همه‌ی حسگرها را چاپ می‌کند. خروجی واقعی از آزمایش ما:

B1 t=1.0s gps=(2.0, 1.0) heading=88.7 sonar[front=10.0 back=3.2 left=10.0 right=1.5] ball 2.2m at +67.1deg -> (-0.0,1.9) attack_x=-52.5
فرمان چه می‌دهد واحد
self.position() GPS: جای ربات (x, y) متر
self.heading_deg() قطب‌نما: جهت ربات. ۰ = ‎+x، ۹۰ = ‎+y درجه، بین ‎-180 و ‎+180
self.distance("front") سونار جلو: فاصله تا نزدیک‌ترین ربات، توپ یا مانع. back، left، right هم هست متر، تا ۱۰
self.ball_distance() فاصله‌ی توپ متر
self.ball_angle() زاویه‌ی توپ نسبت به دماغه. ۰ = جلو، مثبت = چپ درجه
self.ball_position() جای توپ در زمین متر
self.attack_x x دروازه‌ای که باید به آن حمله کنیم متر

فاصله‌ی توپ از کجا می‌آید؟ گیرنده‌ی توپ «قدرت سیگنال» می‌دهد که برابر ۱ / فاصله² است. پس:

dist = 1.0 / math.sqrt(strength)          # قدرت 0.04 یعنی 5 متر

اگر توپ هنوز دیده نشده، این فرمان‌ها None برمی‌گردانند. پیش از استفاده بررسی کنید: if self.ball is not None:.

نام‌های خام دستگاه‌ها، اگر خواستید خودتان مستقیم بخوانید:

"gps"  "compass"  "ball receiver"  "supervisor receiver"  "team emitter"  "team receiver"
"distancesensor front"  "distancesensor back"  "distancesensor left"  "distancesensor right"
"left wheel motor"  "right wheel motor"

تمرین: یک جدول بکشید: هر حسگر، عددی که دیدید، واحد، کاربرد. بعد در Robot Lab → Open live sensor practice همان عددها را زنده ببینید.


۷. درس ۴: قطب‌نما و چرخش دقیق (LESSON = 4)

turn_to(h) ربات را رو به یک جهت مطلق می‌چرخاند، هر جا که الان رو کرده باشد. این‌طوری کار می‌کند:

err = target - heading                 # خطای زاویه، همیشه بین -180 و +180 (کوتاه‌ترین راه)
turn = 4.0 * err - 1.2 * rate          # P: هرچه خطا بیشتر، تندتر.  D: اگر خیلی تند می‌چرخیم، ترمز
self.set_motors(-turn, turn)           # چپ منفی، راست مثبت = چرخش به چپ
# وقتی خطا زیر 3 درجه و ربات تقریباً ایستاده باشد، تمام است

درس ۴ با چهار جهت اصلی یک مربع می‌کشد:

for heading in (180, -90, 0, 90):
    self.turn_to(heading)
    self.forward(1.5)

نتیجه‌ی آزمایش ما: ۱۷۷.۱، ‎-90.4، ‎-2.9 و ۸۷.۱ درجه. خطای هر چرخش زیر ۳ درجه. چون هر ضلع جهت مطلق دارد، خطای چرخش‌ها روی هم جمع نمی‌شود. با turn_left چهار بار پشت سر هم، جمع می‌شد.

تمرین: در chovgan_robot.py ضریب 4.0 تابع turn_to را 1.0 و بعد 10 کنید. چه فرقی می‌کند؟


۸. درس ۵: GPS و رفتن به یک نقطه (LESSON = 5)

drive_to(x, y) ربات را با GPS و قطب‌نما به هر نقطه‌ی زمین می‌برد:

want = math.atan2(ty - y, tx - x)              # نقطه‌ی هدف در چه جهتی است
err = want - heading                            # چقدر باید بچرخم
turn = 4.0 * err
forward = 7.0 if abs(err) < 0.6 else 1.0        # اول رو به نقطه، بعد برو
# نزدیک نقطه آرام، در 1.5 متری بایست

در درس ۵ هر ربات روی خط y خودش، بین دو نقطه در نیمه‌ی خودی گشت می‌زند:

home = -self.attack_sign            # نیمه‌ی خودی: سمت مخالف دروازه‌ی حریف
self.drive_to(home * 13, y)
self.drive_to(home * 31, y)

نتیجه‌ی آزمایش ما: هر چهار ربات به همه‌ی نقطه‌ها رسیدند و بعد از نیمه، خودشان سمت درست را گشت زدند.

تمرین: هر چهار ربات یک خط روی خط وسط زمین (x = 0) بسازند.


۹. درس ۶: سونار و جلوگیری از برخورد (LESSON = 6)

if self.distance("front") > 3.0:
    self.set_motors(5, 5)                       # راه باز است
    self.tick()
elif self.distance("left") >= self.distance("right"):
    self.turn_left(60)                          # سمت چپ بازتر است
else:
    self.turn_right(60)

ربات‌های دیگر و توپ هر دو مانع حساب می‌شوند. در آزمایش ما ربات‌ها در فاصله‌ی ۲ تا ۳ متری ربات جلویی ایستادند و به سمت بازتر چرخیدند.

تمرین: SAFE را ۱.۵ و ۵ کنید. اگر پشت ربات هم بسته بود (distance("back")) چه کند؟


۱۰. درس ۷: توپ را به سمت دروازه هل بده (LESSON = 7)

ربات فرمان «شوت» ندارد. توپ را با راندن ربات به سمت آن هل می‌دهیم. اگر مستقیم به توپ بزنیم، توپ هر طرف که رو کرده‌ایم می‌رود، حتی به دروازه‌ی خودی. پس سه قدم:

bx, by = self.ball_position()                                   # ۱. توپ کجاست
to_goal = math.atan2(0 - by, self.attack_x - bx)                # جهت توپ → دروازه‌ی حریف
behind = (bx - 4 * math.cos(to_goal), by - 4 * math.sin(to_goal))
self.drive_to(*behind)                                          # ۲. برو ۴ متر پشت توپ
self.turn_to(math.degrees(to_goal))                             # ۳. رو به دروازه
self.forward(1.5, speed=10)                                     #    و هل بده

فقط ربات ۳ این درس را بازی می‌کند. تمرین: عدد ۴ را ۲ و ۶ کنید و در Training → Shooting امتحان کنید.


۱۱. درس ۸: پیام تیمی (LESSON = 8)

اگر هر چهار ربات دنبال توپ بروند، دور توپ گیر می‌کنند. در این درس:

self.team_emitter.send(json.dumps({"robot": self.name, "dist": mine}))   # به هم‌تیمی‌ها بگو
for msg in self.inbox:                                                   # پیام‌های رسیده
    distances[msg["robot"]] = msg["dist"]
closest = all(mine <= d for d in others)                                 # آیا من نزدیک‌ترینم؟

فقط نزدیک‌ترین ربات سراغ توپ می‌رود و دروازه‌بان هیچ‌وقت نامزد نیست. پیام فقط به سه هم‌تیمی می‌رسد و حریف نمی‌شنود. با json هر دیکشنری را می‌شود فرستاد. در آزمایش ما در ۴۰ ثانیه حدود ۲۰۰۰ پیام رد و بدل شد.


۱۲. تیم کامل (LESSON = 0)

فایل نقش چه می‌کند
robot1.py دروازه‌بان ۵ متر جلوی دروازه‌ی خودی می‌ماند و با توپ چپ و راست می‌رود. اگر توپ نزدیک شد آن را دور می‌کند
robot2.py مدافع وسط نیمه‌ی خودی می‌ماند. اگر توپ نزدیک‌تر از ۹ متر شد، سراغش می‌رود
robot3.py مهاجم اول پشت توپ می‌رود و آن را به سمت دروازه‌ی حریف هل می‌دهد. اگر ربات ۴ نزدیک‌تر است، پشت توپ منتظر می‌ماند
robot4.py مهاجم کناری همان هل دادن. اگر ربات ۳ نزدیک‌تر است، ۸ متر جلوتر از توپ و آن طرف زمین منتظر توپ برگشتی می‌ماند

یک مسابقه با کد پایه

نتیجه‌ی آزمایش ما: مقابل تیم تمرینی ایستا ۱ بر ۰ برد و مقابل تیم تمرینی رسمی شبیه‌ساز ۰ بر ۱ باخت. یعنی کار می‌کند، ولی جای بهتر شدن دارد. این کار شماست.

اولین تغییرهای پیشنهادی

  1. سرعت: در robot3.py عدد drive(self.left, self.right, 10.0, turn) را ببینید. ۱۰ بیشترین سرعت است.
  2. دروازه‌بان جلوتر یا عقب‌تر: GOAL_OFFSET در robot1.py.
  3. مدافع جسورتر: STRENGTH_ENGAGE در robot2.py. عدد کوچک‌تر یعنی از دورتر سراغ توپ می‌رود (قدرت ۰.۰۱۲ یعنی حدود ۹ متر، چون ۱/√۰.۰۱۲ ≈ ۹).
  4. از درس‌ها استفاده کنید: فرمان‌های ساده (drive_to، turn_to، distance) در همه‌ی بازیکن‌ها هست، چون همه از ChovganRobot ارث می‌برند.

۱۳. U14: تابلوی مربی (Coach Board)

در رده‌ی U14 مربی می‌تواند پیش از مسابقه و در جریان آن از Coach Board برنامه را عوض کند: ATTACK، BALANCED یا DEFEND.

تابلوی مربی

شبیه‌ساز این را به‌صورت پیام chovgan.coach.plan.v1 می‌فرستد و کد پایه آن را در self.coach_playbook نگه می‌دارد:

if self.coach_playbook == "DEFEND":
    self.drive_to(-self.attack_sign * 20, 0)     # در نیمه‌ی خودی بمان

در U19 تابلوی مربی وجود ندارد و این پیام هرگز نمی‌آید. پس همین کد در هر دو رده بی‌خطر است.


۱۴. تمرین بدون شبیه‌ساز (اختیاری)

این بسته را می‌شود مستقیم در شبیه‌ساز بارگذاری کرد، چون فقط فایل‌های مجاز دارد. ران‌تایم تمرینی بیرون از شبیه‌ساز از ماژول‌هایی استفاده می‌کند که داخل شبیه‌ساز بسته‌اند، پس جداست: Chovgan-LocalPractice.zip را از صفحه‌ی لیگ بگیرید، باز کنید و پوشه‌ی chovgan_team خودتان را جای پوشه‌ی داخل آن بگذارید. با Python 3.10 یا جدیدتر بزنید:

python local_runtime/run_local.py --realtime

فیزیک آن ساده‌تر از شبیه‌ساز است. برای امتحان سریع یک ایده خوب است، اما نتیجه‌ی واقعی را همیشه در خود شبیه‌ساز ببینید.


۱۵. تحویل کد

  1. LESSON = 0 باشد.
  2. chovgan_team/ و team_name.txt را با هم ZIP کنید. آموزش و تصویرها لازم نیست، ولی اگر بمانند هم ایرادی ندارد.
  3. یک بار در Competition → STRATEGY بارگذاری کنید و مطمئن شوید VALID است.
  4. محل و مهلت تحویل در کانال کمیته فنی اعلام می‌شود.

۱۶. مشکلات رایج

پیام معنی و راه‌حل
MISSING_ENTRYPOINT chovgan_team/robot.py در سطح اول ZIP نیست. ZIP را باز کنید و ببینید داخل یک پوشه‌ی اضافه نیفتاده باشد
IMPORT_ERROR ماژولی خارج از فهرست مجاز. os، sys، socket و کتابخانه‌های بیرونی مثل numpy بسته‌اند. math، json، random و collections آزادند
UNSUPPORTED_EXTENSION فقط فایل‌های .py، .json، .md، .txt و .png مجازند. عکس .jpg را حذف کنید
UNKNOWN_DEVICE نام دستگاه در getDevice اشتباه است. نام‌ها را از درس ۳ کپی کنید
PYTHON_SYNTAX_ERROR خطای نگارشی. شماره‌ی خط در پیام هست
ربات CRASHED در Controller status متن خطا همان‌جاست. معمولاً None: توپ هنوز دیده نشده و ball_distance() عدد نیست
ربات‌ها به هم می‌خورند همه در یک ردیف شروع می‌کنند. اول با turn_to رو به جای خالی کنید، یا فقط یک ربات را حرکت دهید
ربات چند لحظه حرکت نمی‌کند توپ بیرون رفته و شبیه‌ساز در حال شروع مجدد است
نیمه‌ی دوم ربات‌ها به دروازه‌ی خودی حمله می‌کنند به‌جای عدد ثابت از self.attack_x استفاده کنید

سؤال‌ها را در کانال کمیته فنی بپرسید.