machine --- الدوال المتعلقة بالعتاد

تحتوي وحدة machine على دوال محددة متعلقة بالعتاد على لوحة معينة. تتيح معظم الدوال في هذه الوحدة تحقيق وصول مباشر وغير مقيّد إلى كتل العتاد في النظام والتحكم فيها (مثل وحدة المعالجة المركزية والمؤقتات والنواقل، إلخ).

الوصول إلى الذاكرة

تكشف الوحدة عن ثلاثة كائنات قابلة للفهرسة تُستخدم للوصول الخام إلى الذاكرة. يتصرّف كل منها مثل مصفوفة متفرقة مفهرسة بعنوان البايت: value = memN[addr] للقراءة، وmemN[addr] = value للكتابة. العنوان هو دائمًا عنوان بايت، بغض النظر عن عرض الوصول.

machine.mem8

مُوصِّل ذاكرة قابل للفهرسة بعرض 8 بتات. mem8[addr] يقرأ قيمة int في النطاق 0-255 من البايت عند addr ؛ وmem8[addr] = value يكتب البتات الثمانية المنخفضة من value . يجب أن يكون addr محاذيًا إلى بايت واحد (أي عنوان).

machine.mem16

مُوصِّل ذاكرة قابل للفهرسة بعرض 16 بت (نصف كلمة). mem16[addr] يقرأ قيمة int في النطاق 0-65535؛ وmem16[addr] = value يكتب البتات الستة عشرة المنخفضة. يجب أن يكون addr محاذيًا إلى بايتين.

machine.mem32

مُوصِّل ذاكرة قابل للفهرسة بعرض 32 بت (كلمة). mem32[addr] يقرأ قيمة int في النطاق 0-0xFFFFFFFF؛ وmem32[addr] = value يكتب البتات الاثنتين والثلاثين المنخفضة. يجب أن يكون addr محاذيًا إلى 4 بايتات.

مثال على الاستخدام (السجلات خاصة بمتحكم دقيق من نوع STM32H7 -- على OpenMV Cam H7 / H7 Plus / Pure Thermal يكون دبوس الترويسة P0 موصولًا بـ PB15):

import machine
from micropython import const

GPIOB = const(0x58020400)
GPIO_BSRR = const(0x18)
GPIO_IDR = const(0x10)

# set P0 (PB15) high via the GPIOB bit-set/reset register
machine.mem32[GPIOB + GPIO_BSRR] = 1 << 15

# read P0 (PB15) directly out of the GPIOB input-data register
value = (machine.mem32[GPIOB + GPIO_IDR] >> 15) & 1

الدوال المتعلقة بإعادة التعيين

machine.reset() → None

يعيد التعيين الصلب للجهاز بطريقة مشابهة للضغط على زر RESET الخارجي.

machine.soft_reset() → None

ينفّذ إعادة تعيين ناعمة للمفسّر، إذ يحذف جميع كائنات Python ويعيد تعيين كومة Python.

machine.reset_cause() → int

الحصول على سبب إعادة التعيين. انظر الثوابت لمعرفة القيم المُرجعة الممكنة.

machine.bootloader(value: int | None = None, /) → NoReturn

إعادة تعيين الكاميرا إلى محمّل إقلاع DFU / التنزيل التسلسلي الخاص بها، جاهزة لإعادة وميضها ببرنامج ثابت جديد. لا يعود هذا الاستدعاء أبدًا؛ تُعاد تهيئة اللوحة مباشرة إلى محمّل الإقلاع.

يُقبل الوسيط value لأجل التوافق بين المنافذ ولكنه يُتجاهل على كل لوحة مدعومة من OpenMV.

الدوال المتعلقة بالمقاطعات

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

import machine

# Disable interrupts
state = machine.disable_irq()

# Do a small amount of time-critical work here

# Enable interrupts
machine.enable_irq(state)

machine.disable_irq() → int

تعطيل طلبات المقاطعة. يُرجع حالة IRQ السابقة التي ينبغي اعتبارها قيمة مبهمة. ينبغي تمرير هذه القيمة المُرجعة إلى دالة enable_irq() لاستعادة المقاطعات إلى حالتها الأصلية، قبل استدعاء disable_irq() .

machine.enable_irq(state: int) → None

إعادة تفعيل طلبات المقاطعة. ينبغي أن يكون المعامل state هو القيمة التي أُرجعت من أحدث استدعاء لدالة disable_irq() .

الدوال المتعلقة بالطاقة

machine.freq(hz: int | None = None, /) → int | tuple[int, ...]

إرجاع ترددات ساعة المتحكم الدقيق (MCU).

على منافذ STM32 (كل OpenMV Cam M4/M7/H7/H7+/PT/N6 والمتغيرات التي تحمل علامة Arduino التجارية) تكون القيمة المُرجعة صفًا (tuple) من السواعات الداخلية بوحدة Hz. على STM32N6 (OpenMV Cam N6) يكون الصف (CPUCLK, SYSCLK, HCLK, PCLK1, PCLK2, PCLK4, PCLK5) ؛ وعلى كاميرات STM32 الأخرى يكون (SYSCLK, HCLK, PCLK1, PCLK2) .

على منفذ mimxrt (OpenMV Cam RT1062) ومنفذ alif (OpenMV Cam AE3) تكون القيمة المُرجعة عددًا صحيحًا واحدًا -- تردد وحدة المعالجة المركزية بوحدة Hz.

استدعاء freq(hz) لضبط الساعة يطلق NotImplementedError على كل لوحة مدعومة من OpenMV.

machine.idle() → None

يحجب الساعة عن وحدة المعالجة المركزية، وهو مفيد لتقليل استهلاك الطاقة في أي وقت خلال فترات قصيرة أو طويلة. تواصل الطرفيات عملها ويُستأنف التنفيذ بمجرد إطلاق أي مقاطعة، أو على أبعد تقدير بعد ميلي ثانية واحدة من إيقاف وحدة المعالجة المركزية مؤقتًا.

يُوصى باستدعاء هذه الدالة داخل أي حلقة مُحكمة تتحقق باستمرار من تغيّر خارجي (أي الاستقصاء). سيقلّل ذلك من استهلاك الطاقة دون التأثير بشكل كبير على الأداء. ولتقليل استهلاك الطاقة أكثر فانظر الدوال lightsleep() وtime.sleep() وtime.sleep_ms() .

machine.sleep() → None

ملاحظة

هذه الدالة مهملة، استخدم lightsleep() بدلًا منها دون وسائط.

machine.lightsleep(time_ms: int | None = None, /) → None

إيقاف التنفيذ والدخول في حالة منخفضة الطاقة مع الاحتفاظ الكامل بذاكرة RAM والطرفيات. تُحجب ساعة المتحكم الدقيق؛ وعندما تعود الدالة، يُستأنف التنفيذ من النقطة التي استُدعيت عندها lightsleep() مع بقاء كل نظام فرعي عاملًا.

إذا حُدّد time_ms فهو أقصى مدة للسبات بالميلي ثانية. مع أو بدون مهلة، قد يُستأنف التنفيذ مبكرًا إذا أُطلق أي مصدر إيقاظ مُهيّأ (مقاطعة Pin ، أو منبّه RTC ، أو مقاطعة طرفية مفعّلة، ...). يجب إعداد مصادر الإيقاظ قبل الاستدعاء.

توفير الطاقة أكثر تواضعًا من deepsleep() لكن الاستيقاظ فوري ولا تُفقد أي حالة.

machine.deepsleep(time_ms: int | None = None, /) → NoReturn

إيقاف التنفيذ والدخول في أعمق حالة منخفضة الطاقة متاحة. قد تُفقد محتويات ذاكرة RAM وحالة الطرفيات واتصالات الشبكة جميعها. وعندما يستيقظ المتحكم الدقيق فإنه يُقلع من بداية البرنامج النصي الرئيسي، على نحو مشابه للتشغيل من حالة إيقاف الطاقة أو إعادة التعيين الصلبة؛ عندئذٍ يُرجع reset_cause() القيمة DEEPSLEEP_RESET حتى يستطيع البرنامج النصي التمييز بين استيقاظ السبات العميق وأسباب إعادة التعيين الأخرى.

إذا حُدّد time_ms فإن المتحكم الدقيق يجدول استيقاظًا بعد ذلك العدد من الميلي ثواني (أو أبكر، إذا أُطلق مصدر إيقاظ مُهيّأ آخر أولًا). لا تمرّر شيئًا للسبات حتى يُطلق مصدر إيقاظ خارجي.

لا يعود هذا الاستدعاء أبدًا -- عالج التنفيذ المُستأنف في أعلى البرنامج النصي الرئيسي، مشروطًا بـ reset_cause() .

دوال متنوعة

machine.unique_id() → bytes

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

يعتمد الطول على عائلة المتحكم الدقيق -- 12 بايت على STM32، و8 بايتات على منفذي mimxrt وalif. إذا كان تطبيقك يحتاج إلى معرّف ثابت الطول، فقم بتقطيع القيمة المُرجعة أو تجزئتها.

machine.time_pulse_us(pin: Pin, pulse_level: int, timeout_us: int = 1000000, /) → int

قياس عرض نبضة واحدة على pin وإرجاع مدتها بالميكروثانية.

يجب تهيئة pin كدخل رقمي.

pulse_level هو قطبية النبضة المراد توقيتها: 1 لنبضة مرتفعة، 0 لنبضة منخفضة.

تعمل الدالة على مرحلتين. أولًا، إذا لم يكن الدبوس عند pulse_level بالفعل، فإنها تنتظر انتقال الدبوس إلى pulse_level (بداية النبضة). ثم تقيس المدة التي يبقى فيها الدبوس عند pulse_level قبل أن ينتقل عائدًا (نهاية النبضة). تُرجع المدة المقيسة بالميكروثانية.

يحدّ timeout_us كل مرحلة على حدة (بحيث يستمر الاستدعاء في أسوأ الحالات حتى 2 * timeout_us). عند انتهاء المهلة تُرجع الدالة قيمة سالبة تحدد أي مرحلة انتهت مهلتها:

• -2 -- انتهت المهلة أثناء انتظار الحافة الأمامية (لم يبلغ الدبوس pulse_level أبدًا).

• -1 -- انتهت المهلة أثناء انتظار الحافة الخلفية (كانت النبضة أطول من timeout_us).

machine.bitstream(pin: Pin, encoding: int, timing: tuple, data: bytes, /) → None

يرسل data عن طريق التذبذب البتي (bit-banging) على الدبوس المحدد pin. يحدّد الوسيط encoding كيفية ترميز البتات، وtiming هو مواصفة توقيت خاصة بالترميز.

الترميزات المدعومة هي:

• 0 لتعديل مدة النبضة من نوع "مرتفع منخفض". سيرسل هذا البتين 0 و1 كنبضات موقّتة، بدءًا من البت الأكثر أهمية. يجب أن يكون timing صفًا رباعيًا من النانوثواني بالصيغة (high_time_0, low_time_0, high_time_1, low_time_1). على سبيل المثال، (400, 850, 800, 450) هي مواصفة التوقيت لمصابيح WS2812 RGB LED عند 800kHz.

تعتمد دقة التوقيت على العتاد؛ تنتج المتحكمات الدقيقة الأسرع نبضات أكثر إحكامًا (عادةً عشرات النانوثواني).

ملاحظة

للتحكم في شرائط WS2812 / NeoPixel، انظر وحدة neopixel للحصول على واجهة برمجية عالية المستوى.

الثوابت

تُرجع الثوابت أدناه من قِبل reset_cause() وتحدد سبب آخر إعادة تعيين للمتحكم الدقيق. متاحة على منفذي STM32 وmimxrt؛ ولا يكشف منفذ alif (OpenMV Cam AE3) حاليًا عن ثوابت سبب إعادة التعيين، ويُرجع reset_cause() الخاص به دائمًا 0 .

machine.PWRON_RESET: int

إعادة تعيين سببها تطبيق الطاقة على الشريحة. منفذا STM32 وmimxrt.

machine.WDT_RESET: int

إعادة تعيين سببها انتهاء مؤقت المراقبة. منفذا STM32 وmimxrt.

machine.SOFT_RESET: int

إعادة تعيين سببها soft_reset() (أُعيد تشغيل مفسّر Python دون إعادة تعيين عتادية). منفذا STM32 وmimxrt.

machine.HARD_RESET: int

إعادة تعيين سببها تأكيد دبوس NRST (زر إعادة التعيين الخارجي). منافذ STM32 فقط.

machine.DEEPSLEEP_RESET: int

إعادة تعيين سببها الاستيقاظ من السبات العميق. منافذ STM32 فقط.

الفئات

• class Pin -- التحكم في دبابيس الإدخال/الإخراج
• class Signal -- التحكم في أجهزة الإدخال/الإخراج الخارجية واستشعارها
• الفئة LED -- تحكم محمول في مؤشر LED المدمج على اللوحة
• class ADC -- التحويل من التماثلي إلى الرقمي
• الفئة PWM -- تعديل عرض النبضة (pulse-width modulation)
• class UART -- ناقل اتصالات تسلسلية ثنائي الاتجاه
• class SPI -- بروتوكول ناقل واجهة الطرفيات التسلسلية (جانب وحدة التحكم)
• class SoftSPI -- ناقل SPI مُحاكى برمجيًا
• الصنف I2C -- بروتوكول تسلسلي ثنائي الأسلاك
• الصنف SoftI2C -- ناقل I2C مُحاكى برمجياً
• الصنف I2CTarget -- جهاز هدف I2C
• الفئة I2S -- بروتوكول ناقل الصوت بين الدوائر المتكاملة (Inter-IC Sound)
• الفئة CAN -- بروتوكول شبكة منطقة التحكم (Controller Area Network)
• class RTC -- ساعة الوقت الحقيقي
• class Timer -- مؤقت دوري / أحادي الطلقة افتراضي
• class WDT -- مؤقت المراقبة (watchdog)
• class SDCard -- مشغّل بطاقات SD / MMC
• class Counter -- عدّاد النبضات
• class Encoder -- مُرمِّز تربيعي