وضع المفسّر التفاعلي في MicroPython (المعروف باسم REPL)

يغطي هذا القسم بعض خصائص وضع المفسّر التفاعلي في MicroPython. والمصطلح الشائع لهذا الوضع هو REPL (حلقة قراءة-تقييم-طباعة) والذي سيُستخدم للإشارة إلى هذه المطالبة التفاعلية.

ملاحظة

تُتيح كاميرات OpenMV Cam هذا الـ REPL عبر منفذ USB التسلسلي (CDC). وهو ذو صلة فقط عندما تتصل بالكاميرا مباشرةً باستخدام محاكي طرفية تسلسلية (أو أداة مثل التحكم عن بُعد في MicroPython: mpremote). لا يستخدم OpenMV IDE الـ REPL — بل يتواصل مع الكاميرا عبر بروتوكول تصحيح أخطاء منفصل لتشغيل البرامج النصية ونقل الملفات وبث مخزن الإطارات. كل ما هو موصوف في هذه الصفحة ينطبق على جلسات الطرفية المباشرة فقط.

المسافة البادئة التلقائية

عند كتابة عبارات Python التي تنتهي بنقطتين (مثل if وfor وwhile) فإن المطالبة ستتغير إلى ثلاث نقاط (...) وستُزاح المؤشر بمقدار 4 مسافات. وعند الضغط على مفتاح الإدخال، سيستمر السطر التالي عند نفس مستوى المسافة البادئة للعبارات العادية أو عند مستوى إضافي من المسافة البادئة حيثما كان ذلك مناسبًا. وإذا ضغطت على مفتاح المسافة الخلفية فإنه سيتراجع عن مستوى واحد من المسافة البادئة.

إذا كان المؤشر في أقصى البداية، فإن الضغط على RETURN سينفّذ عندئذٍ الشيفرة التي أدخلتها. ويوضح ما يلي ما ستراه بعد إدخال عبارة for (تُظهر الشرطة السفلية مكان استقرار المؤشر):

>>> for i in range(30):
...     _

وإذا أدخلت بعد ذلك عبارة if، فسيُوفَّر مستوى إضافي من المسافة البادئة:

>>> for i in range(30):
...     if i > 3:
...         _

الآن أدخل break متبوعًا بـ RETURN ثم اضغط على BACKSPACE:

>>> for i in range(30):
...     if i > 3:
...         break
...     _

وأخيرًا اكتب print(i)، واضغط على RETURN، ثم اضغط على BACKSPACE واضغط على RETURN مرة أخرى:

>>> for i in range(30):
...     if i > 3:
...         break
...     print(i)
...
0
1
2
3
>>>

لن تُطبَّق المسافة البادئة التلقائية إذا كان السطران السابقان كله مسافات. وهذا يعني أنه يمكنك إنهاء إدخال عبارة مركّبة بالضغط على RETURN مرتين، ثم سيؤدي الضغط الثالث إلى الإنهاء والتنفيذ.

الإكمال التلقائي

أثناء كتابة أمر في الـ REPL، إذا كان السطر المكتوب حتى الآن يطابق بداية اسم شيء ما، فإن الضغط على TAB سيُظهر الأشياء المحتملة التي يمكن إدخالها. على سبيل المثال، استورد أولًا الوحدة machine بإدخال import machine والضغط على RETURN. ثم اكتب m واضغط على TAB ومن المفترض أن يتوسّع إلى machine. أدخل نقطة . واضغط على TAB مرة أخرى. ينبغي أن ترى شيئًا مثل:

>>> machine.
__name__        info            unique_id       reset
bootloader      freq            rng             idle
sleep           deepsleep       disable_irq     enable_irq
Pin

ستتوسّع الكلمة قدر الإمكان حتى تتعدد الاحتمالات. على سبيل المثال، اكتب machine.Pin.PULL واضغط على TAB فسيتوسّع إلى machine.Pin.PULL_. وسيُظهر الضغط على TAB مرة ثانية التوسّعات الممكنة:

>>> machine.Pin.PULL_
PULL_DOWN       PULL_UP
>>> machine.Pin.PULL_

مقاطعة برنامج قيد التشغيل

يمكنك مقاطعة برنامج قيد التشغيل بالضغط على Ctrl-C. وسيؤدي ذلك إلى إطلاق استثناء KeyboardInterrupt الذي سيعيدك إلى الـ REPL، شريطة ألا يعترض برنامجك استثناء KeyboardInterrupt.

على سبيل المثال:

>>> for i in range(1000000):
...     print(i)
...
0
1
2
3
...
6466
6467
6468
Traceback (most recent call last):
  File "<stdin>", line 2, in <module>
KeyboardInterrupt:
>>>

وضع اللصق

إذا أردت لصق بعض الشيفرة في نافذة الطرفية، فإن ميزة المسافة البادئة التلقائية ستُفسد الأمور. على سبيل المثال، إذا كان لديك شيفرة Python التالية:

def foo():
    print('This is a test to show paste mode')
    print('Here is a second line')
foo()

وحاولت لصق هذا في الـ REPL العادي، فسترى عندئذٍ شيئًا مثل هذا:

>>> def foo():
...         print('This is a test to show paste mode')
...             print('Here is a second line')
...             foo()
...
Traceback (most recent call last):
  File "<stdin>", line 3
IndentationError: unexpected indent

إذا ضغطت على Ctrl-E، فستدخل وضع اللصق، الذي يُعطّل أساسًا ميزة المسافة البادئة التلقائية، ويُغيّر المطالبة من >>> إلى ===. على سبيل المثال:

>>>
paste mode; Ctrl-C to cancel, Ctrl-D to finish
=== def foo():
===     print('This is a test to show paste mode')
===     print('Here is a second line')
=== foo()
===
This is a test to show paste mode
Here is a second line
>>>

يسمح وضع اللصق بلصق الأسطر الفارغة. ويُترجَم النص الملصوق كما لو كان ملفًا. ويؤدي الضغط على Ctrl-D إلى الخروج من وضع اللصق وبدء عملية الترجمة.

إعادة التعيين البرمجية

ستؤدي إعادة التعيين الناعمة إلى إعادة تعيين مفسّر Python، لكنها تحاول ألا تعيد تعيين الطريقة التي تتصل بها بكاميرا OpenMV Cam (USB).

يمكنك إجراء إعادة تعيين برمجية من الـ REPL بالضغط على Ctrl-D، أو من شيفرة Python الخاصة بك بتنفيذ:

machine.soft_reset()

على سبيل المثال، إذا أعدت تعيين كاميرا OpenMV Cam ونفّذت أمر dir()، فسترى شيئًا مثل هذا:

>>> dir()
['__name__']

الآن أنشئ بعض المتغيرات وكرّر أمر dir():

>>> i = 1
>>> j = 23
>>> x = 'abc'
>>> dir()
['j', 'x', '__name__', 'i']
>>>

الآن إذا أدخلت Ctrl-D، وكرّرت أمر dir()، فسترى أن متغيراتك لم تعد موجودة:

MPY: sync filesystems
MPY: soft reboot
MicroPython v1.25.0 on 2025-05-15; OpenMV Cam H7 with STM32H743
Type "help()" for more information.
>>> dir()
['__name__']
>>>

لمزيد من المعلومات حول أنواع إعادة التعيين وعملية بدء التشغيل، راجع تسلسل إعادة التعيين والإقلاع.

المتغير الخاص _ (الشرطة السفلية)

عند استخدام الـ REPL، قد تُجري حسابات وترى النتائج. يُخزّن MicroPython نتيجة العبارة السابقة في المتغير _ (الشرطة السفلية). لذا يمكنك استخدام الشرطة السفلية لحفظ النتيجة في متغير. على سبيل المثال:

>>> 1 + 2 + 3 + 4 + 5
15
>>> x = _
>>> x
15
>>>

الوضع الخام ووضع اللصق الخام

الوضع الخام (المعروف أيضًا بالـ REPL الخام) ليس شيئًا يستخدمه الشخص عادةً. فهو مُخصّص للاستخدام البرمجي ويتصرّف أساسًا مثل وضع اللصق مع إيقاف الصدى، ومع تحكّم اختياري في التدفّق.

يُدخَل الوضع الخام باستخدام Ctrl-A. ثم ترسل شيفرة python الخاصة بك، متبوعةً بـ Ctrl-D. وسيُؤكَّد الـ Ctrl-D بعبارة 'OK' ثم ستُترجَم شيفرة python وتُنفَّذ. وسيُرسَل أي خرج (أو أخطاء) مرة أخرى. وسيؤدي إدخال Ctrl-B إلى مغادرة الوضع الخام والعودة إلى الـ REPL العادي (المعروف أيضًا بالودود).

وضع اللصق الخام هو وضع إضافي ضمن الـ REPL الخام يتضمن تحكّمًا في التدفّق، ويُترجِم الشيفرة أثناء استقبالها. وهذا يجعله أكثر متانة للنقل عالي السرعة للشيفرة إلى الجهاز، كما أنه يستخدم قدرًا أقل من RAM عند الاستقبال لأنه لا يحتاج إلى تخزين نسخة طبق الأصل من الشيفرة قبل الترجمة (على عكس الوضع الخام القياسي).

يستخدم وضع اللصق الخام البروتوكول التالي:

  1. ادخل الـ REPL الخام كالمعتاد عبر ctrl-A.

  2. اكتب 3 بايتات: b"\x05A\x01" (أي ctrl-E ثم "A" ثم ctrl-A).

  3. اقرأ 2 بايت لتحديد ما إذا كان الجهاز قد دخل وضع اللصق الخام:

    • إذا كانت النتيجة b"R\x00" فإن الجهاز يفهم الأمر لكنه لا يدعم اللصق الخام.

    • إذا كانت النتيجة b"R\x01" فإن الجهاز يدعم اللصق الخام وقد دخل هذا الوضع.

    • خلاف ذلك، ينبغي أن تكون النتيجة b"ra" ولا يدعم الجهاز اللصق الخام، وينبغي قراءة السلسلة b"w REPL; CTRL-B to exit\r\n>" وتجاهلها.

  4. إذا كان الجهاز في وضع اللصق الخام فتابع، وإلا فارجع إلى الوضع الخام القياسي.

  5. اقرأ 2 بايت، وهذا هو مقدار الزيادة في حجم نافذة التحكّم في التدفّق (بالبايت) مُخزّنًا كعدد صحيح غير موقّع ذي 16 بت بترتيب البايت الصغير الطرف. وينبغي تعيين القيمة الأولية لمتغير حجم-النافذة-المتبقي إلى هذا الرقم.

  6. اكتب الشيفرة إلى الجهاز:

    • ما دامت هناك بايتات لإرسالها، اكتب ما يصل إلى ما يعادل حجم-النافذة-المتبقي من البايتات، وأنقص حجم-النافذة-المتبقي بعدد البايتات المكتوبة.

    • إذا كان حجم-النافذة-المتبقي يساوي 0، أو كان هناك بايت في انتظار القراءة، فاقرأ بايتًا واحدًا. وإذا كان هذا البايت b"\x01" فزِد حجم-النافذة-المتبقي بمقدار الزيادة في حجم النافذة من الخطوة 5. وإذا كان هذا البايت b"\x04" فإن الجهاز يريد إنهاء استقبال البيانات، وينبغي كتابة b"\x04" إلى الجهاز وعدم إرسال مزيد من الشيفرة بعد ذلك. (ملاحظة: إذا كان هناك بايت في انتظار القراءة من الجهاز فلا حاجة إلى قراءته والتصرّف بناءً عليه فورًا، فالجهاز سيستمر في استهلاك البايتات الواردة ما دام حجم-النافذة-المتبقي أكبر من 0.)

  7. عند كتابة كل الشيفرة إلى الجهاز، اكتب b"\x04" للإشارة إلى نهاية البيانات.

  8. اقرأ من الجهاز حتى يُستقبَل b"\x04". عند هذه النقطة يكون الجهاز قد استقبل وترجم كل الشيفرة التي أُرسِلت وهو ينفّذها.

  9. يُخرِج الجهاز أي محارف تُنتجها الشيفرة المُنفَّذة. وعندما (إن) تنتهي الشيفرة سيُخرَج b"\x04"، متبوعًا بأي استثناء لم يُلتقَط، متبوعًا مرة أخرى بـ b"\x04". ثم يعود إلى الـ REPL الخام القياسي ويُخرِج b">".

على سبيل المثال، بدءًا من سطر جديد في الـ REPL العادي (الودود)، إذا كتبت:

b"\x01\x05A\x01print(123)\x04"

فسيستجيب الجهاز عندئذٍ بشيء مثل:

b"\r\nraw REPL; CTRL-B to exit\r\n>R\x01\x80\x00\x01\x04123\r\n\x04\x04>"

وبتقسيم ذلك عبر الزمن يبدو الأمر هكذا:

# Step 1: enter raw REPL
write: b"\x01"
read: b"\r\nraw REPL; CTRL-B to exit\r\n>"

# Step 2-5: enter raw-paste mode
write: b"\x05A\x01"
read: b"R\x01\x80\x00\x01"

# Step 6-8: write out code
write: b"print(123)\x04"
read: b"\x04"

# Step 9: code executes and result is read
read: b"123\r\n\x04\x04>"

في هذه الحالة يكون مقدار الزيادة في حجم نافذة التحكّم في التدفّق هو 128 وهناك ما يعادل نافذتين من البيانات متاحًا فورًا في البداية، واحدة من قيمة مقدار الزيادة في حجم النافذة الأولية وواحدة من القيمة الصريحة b"\x01" التي تُرسَل. وهذا يعني أنه يمكن كتابة ما يصل إلى 256 بايت للبدء قبل الانتظار أو التحقق من المزيد من محارف التحكّم في التدفّق الواردة.

تستخدم الأداة التحكم عن بُعد في MicroPython: mpremote الـ REPL الخام، بما في ذلك وضع اللصق الخام، لتنفيذ شيفرة Python على كاميرات OpenMV Cam.