class SDCard -- مشغّل بطاقات SD / MMC

تشغّل الفئة SDCard فتحة بطاقات SD / MMC على كاميرات OpenMV التي تحتوي على واحدة. ينفّذ المشغّل واجهة vfs.AbstractBlockDev بحيث يمكن تمريره مباشرة إلى vfs.mount()

import machine
import vfs

sd = machine.SDCard()
vfs.mount(sd, "/sd")

ملاحظة

يقوم برنامج OpenMV الثابت بتركيب بطاقة SD تلقائيًا عند الإقلاع، لذا فإن معظم البرامج النصية لا تُنشئ كائن SDCard مباشرة على الإطلاق -- بل تقرأ وتكتب عبر المسار المركّب تلقائيًا فحسب. أنشئ واحدًا يدويًا فقط عندما تحتاج إلى نقطة تركيب غير افتراضية أو إلى وصول خام على مستوى الكتل عبر readblocks() / writeblocks() / ioctl().

على OpenMV Cam M7 / H7 / H7 Plus / Pure Thermal / N6 تُشغَّل الفتحة بواسطة وحدة التحكم SDMMC المدمجة في STM32 في وضع SD بأربع بتات. على OpenMV Cam RT1062 تُشغَّل الفتحة بواسطة وحدة التحكم USDHC في i.MX RT، أيضًا في وضع SD بأربع بتات. لا حاجة إلى أي وسائط لتعدد الدبابيس على أي لوحة OpenMV حالية -- يعرف المشغّل توصيلات اللوحة.

غير متاح على OpenMV Cam AE3 (منفذ alif).

المُنشئات

class machine.SDCard(id: int = 1) → SDCard

تُعيد المثيل المفرد SDCard لفتحة SD المحددة بواسطة id. يُقبل id للتوافق بين المنافذ لكن المنافذ المدعومة من OpenMV تعرض فتحة واحدة فقط؛ مرّر 1 أو احذفه.

على STM32 لا يأخذ المُنشئ أي وسائط على الإطلاق؛ وعلى mimxrt يُقبل الوسيط id لكن 1 فقط هو الصالح.

الطرق

present() → bool

تُعيد True إذا كانت هناك بطاقة مكتشَفة حاليًا في الفتحة، وFalse خلاف ذلك.

على اللوحات التي توصّل إشارة كشف البطاقة تعكس الطريقة تلك الإشارة في الزمن الحقيقي، بحيث يمكن استطلاعها بعد إنشاء كائن SDCard للتفاعل مع الإدخال / الإزالة الساخنة. على اللوحات التي لا تملك إشارة كشف البطاقة تُثبَّت القيمة عند وقت الإنشاء -- فهي تُبلغ عن نتيجة استكشاف CMD0 الأولي الذي قام به المشغّل عند إنشاء الكائن، ولن تكون البطاقة المُدخَلة ساخنًا بعد ذلك مرئية حتى يُعاد إنشاء الكائن (أو يُستدعى init() على mimxrt).

info() → tuple[int, int, int]

تُعيد صفًا ثلاثيًا يصف البطاقة المُدخَلة حاليًا:

  • [0] num_blocks -- السعة الإجمالية بكتل سعة كل منها 512 بايت. اضرب في 512 للحصول على السعة الخام بالبايت.

  • [1] block_size -- دائمًا 512 لبطاقات SD. مُدرَجة بحيث يمكن للمستدعين إجراء num_blocks * block_size بشكل قابل للنقل.

  • [2] card_type -- نوع البطاقة الذي يُبلغ عنه ناقل SD أثناء مصافحة التهيئة CMD8 / OCR. القيم النموذجية هي 0 (SDSC -- السعة القياسية) و0x40 (SDHC / SDXC -- السعة العالية / الموسّعة) و0x80 (MMC).

مفيد للتحقق السليم من التعرّف على البطاقة، أو لعرض أرقام المساحة الحرة نسبةً إلى السعة الإجمالية.

power(state: bool, /) → None

تشغّل أو تطفئ خط طاقة فتحة البطاقة. يعرض برنامج STM32 الثابت الطريقة لكن لا توجد OpenMV Cam حالية تتحكم في مصدر طاقة SD، لذا فإن الاستدعاء فعليًا بلا تأثير. أُبقي عليه للتوافق مع التعليمات البرمجية المكتوبة أصلًا للوحات STM32 المرجعية في MicroPython الأصلية. منفذ STM32 فقط.

read(block_num: int, /) → bytes

تقرأ كتلة واحدة سعتها 512 بايت من البطاقة وتُعيدها ككائن bytes مخصَّص حديثًا.

هذه هي قراءة الكتلة الواحدة القديمة التي يشحنها منفذ STM32. ينبغي للتعليمات البرمجية الجديدة استخدام readblocks() بدلًا منها -- فتلك الطريقة تعمل على كل منفذ OpenMV، ويمكنها قراءة أي عدد من الكتل المتجاورة في عملية نقل واحدة، وتتجنب التخصيص لكل استدعاء بالكتابة في مخزن مؤقت يوفّره المستدعي. منفذ STM32 فقط.

write(block_num: int, data: bytes, /) → None

تكتب كتلة واحدة سعتها 512 بايت إلى البطاقة. يجب أن يكون data بطول 512 بايت بالضبط.

هذه هي كتابة الكتلة الواحدة القديمة التي يشحنها منفذ STM32؛ ينبغي للتعليمات البرمجية الجديدة استخدام writeblocks() بدلًا منها، فهي تعمل على كل منفذ OpenMV ويمكنها كتابة أي عدد من الكتل المتجاورة لكل استدعاء. منفذ STM32 فقط.

readblocks(block_num: int, buf: bytearray) → None
readblocks(block_num: int, buf: bytearray, offset: int) → None

تقرأ بيانات خام محاذاة للكتل من البطاقة إلى buf. نقطة دخول جهاز الكتل القياسية vfs.AbstractBlockDev التي تستخدمها طبقة نظام الملفات.

الصيغة البسيطة (readblocks(block_num, buf)): تقرأ كتلًا كاملة بدءًا من فهرس الكتلة block_num. يجب أن يكون len(buf) مضاعفًا لحجم كتلة SD (512 بايت).

الصيغة الموسّعة (readblocks(block_num, buf, offset)): تقرأ len(buf) بايت -- ليس بالضرورة عددًا كاملًا من الكتل -- بدءًا من البايت offset داخل الكتلة block_num. تستخدمها littlefs وأنظمة الملفات الأخرى القابلة للعنونة بالبايت.

writeblocks(block_num: int, buf: bytes | bytearray) → None
writeblocks(block_num: int, buf: bytes | bytearray, offset: int) → None

تكتب بيانات خام محاذاة للكتل من buf إلى البطاقة. نقطة دخول جهاز الكتل القياسية vfs.AbstractBlockDev التي تستخدمها طبقة نظام الملفات.

الصيغة البسيطة (writeblocks(block_num, buf)): تكتب كتلًا كاملة بدءًا من فهرس الكتلة block_num. يجب أن يكون len(buf) مضاعفًا لحجم كتلة SD (512 بايت). تُكتب كل كتلة متأثرة بالكامل من جديد.

الصيغة الموسّعة (writeblocks(block_num, buf, offset)): تكتب len(buf) بايت -- ليس بالضرورة عددًا كاملًا من الكتل -- بدءًا من البايت offset داخل الكتلة block_num. تستخدمها littlefs وأنظمة الملفات الأخرى القابلة للعنونة بالبايت.

ioctl(cmd: int, arg: int) → int | None

نقطة دخول التحكم القياسية vfs.AbstractBlockDev. تستدعيها طبقة نظام الملفات عند التركيب/الفك وعند كل مزامنة. قيم cmd المعترَف بها هي:

  • 1 -- التهيئة. تُعيد 0 عند النجاح.

  • 2 -- إلغاء التهيئة. تُعيد 0 عند النجاح.

  • 3 -- مزامنة أي عمليات كتابة معلّقة. تُعيد 0 (يكتب مشغّل SDMMC بشكل متزامن، ولا شيء لتفريغه).

  • 4 -- تُعيد عدد الكتل على الجهاز.

  • 5 -- تُعيد حجم الكتلة الواحدة (دائمًا 512).

  • 6 -- مسح كتلة (بلا تأثير على SD، أُبقي عليه لعقد vfs.AbstractBlockDev).

  • 7 -- تُعيد ما إذا كان الجهاز يدعم مسح الكتل (0 على SD).

لا يستخدم المستدعون المباشرون هذه الطريقة عادةً -- يوزّع مشغّل نظام الملفات كل الرموز القياسية تلقائيًا بمجرد تركيب SDCard.

init(*args, **kwargs) → None

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

deinit() → None

تُلغي تهيئة واجهة SD، محرِّرةً وحدة التحكم SDMMC/USDHC ودبابيس الإدخال/الإخراج التي طالبت بها. يصبح كائن SDCard غير صالح للاستخدام حتى يُستدعى init() مرة أخرى. استخدمها قبل إعادة كتابة البطاقة من واجهة أخرى، أو لقطع الطاقة عن الفتحة في تطبيق يعمل بالبطارية. منفذ mimxrt فقط.