`apds9960` --- مُشغّل مستشعر القرب والإيماءات واللون#

توفّر هذه الوحدة مُشغّلاً لمستشعر Broadcom/Avago APDS9960 الرقمي للقرب والضوء المحيط ولون RGB والإيماءات عبر I2C. يكشف المُشغّل عن عناصر تحكم بالتمكين/التعطيل لكل ميزة، وقراءات قنوات خام (الصافية، R، G، B، القرب)، وآلة حالة لفك ترميز الإيماءات برمجياً تُصنّف إيماءات التمرير لأعلى/لأسفل/يسار/يمين وإيماءات الاقتراب/الابتعاد من ذاكرة FIFO المكوّنة من 4 ثنائيات ضوئية على الشريحة.

مثال على الاستخدام:

import time
from machine import I2C, Pin
from apds9960 import uAPDS9960 as APDS9960

bus = I2C(1, scl=Pin("P15"), sda=Pin("P14"))
sensor = APDS9960(bus)

sensor.enableLightSensor()
sensor.enableProximitySensor()

while True:
    r = sensor.readRedLight()
    g = sensor.readGreenLight()
    b = sensor.readBlueLight()
    c = sensor.readAmbientLight()
    p = sensor.readProximity()
    print(r, g, b, c, p)
    time.sleep_ms(100)

الأصناف#

class apds9960.APDS9960(bus: machine.I2C, address: int = 0x39, valid_id: list = [0xAB, 0x9C, 0xA8, -0x55])#

ينشئ نسخة من مُشغّل APDS9960.

bus هو كائن ناقل I2C مُهيّأ يُستخدم للتواصل مع المستشعر. يُصدر الصنف الأساسي استدعاءات بنمط SMBus من نوع read_byte_data وwrite_byte_data وread_i2c_block_data؛ ومن أجل machine.I2C في MicroPython استخدم uAPDS9960 بدلاً منه.
address هو عنوان I2C المكوّن من 7 بتات للجهاز. القيمة الافتراضية هي APDS9960_I2C_ADDR (0x39).
valid_id هو قائمة بالقيم المقبولة التي يُعيدها سجل المعرّف الخاص بالشريحة. القيمة الافتراضية هي APDS9960_DEV_ID.

يقرأ المُنشئ معرّف الجهاز ويُطلق ADPS9960InvalidDevId إذا لم يكن موجوداً في valid_id. ثم يُعطّل كل ميزة، ويبرمج قيم ATIME/WTIME/PPULSE الافتراضية، ويطبق الإعدادات الافتراضية لقيادة LED، وكسب القرب، وكسب ALS، وعتبات القرب، وعتبات الضوء المحيط، والاستمرارية، وتهيئة محرك الإيماءات (عتبات الدخول/الخروج، وGCONF1، وكسب الإيماءات، وقيادة LED للإيماءات، وزمن انتظار الإيماءات، وإزاحات الإيماءات، وGPULSE، وGCONF3، وتمكين مقاطعة الإيماءات).

وضع التشغيل والتحكم بالطاقة#

getMode() → int#: تُعيد القيمة الخام لسجل ENABLE، التي تُرمّز الميزات الممكَّنة حالياً (الطاقة، ALS، القرب، الانتظار، مقاطعة ALS، مقاطعة القرب، الإيماءات).

setMode(mode: int, enable: bool = True) → None#: تُمكّن أو تُعطّل ميزة فردية في سجل ENABLE. يجب أن يكون mode واحداً من قيم APDS9960_MODE_* (APDS9960_MODE_POWER ..\ APDS9960_MODE_ALL). عندما يكون mode هو APDS9960_MODE_ALL، تُفعَّل أو تُعطَّل جميع البتات دفعة واحدة. تُطلق ADPS9960InvalidMode للقيم خارج النطاق.

enablePower() → None#: تُشغّل طاقة APDS9960 (تضبط بت PON في ENABLE).

disablePower() → None#: تُطفئ طاقة APDS9960 (تمسح بت PON في ENABLE).

مستشعر الضوء المحيط / RGB#

enableLightSensor(interrupts: bool = True) → None#: تستعيد كسب ALS الافتراضي، وتُهيّئ بت تمكين مقاطعة ALS، وتُشغّل طاقة الجهاز، وتُمكّن محرك الضوء المحيط/اللون.

disableLightSensor() → None#: تُعطّل مقاطعة ALS وتوقف محرك الضوء المحيط/اللون.

readAmbientLight() → int#: تقرأ مستوى الضوء المحيط للقناة الصافية كقيمة غير موقّعة مكوّنة من 16 بت.

readRedLight() → int#: تقرأ مستوى القناة الحمراء كقيمة غير موقّعة مكوّنة من 16 بت.

readGreenLight() → int#: تقرأ مستوى القناة الخضراء كقيمة غير موقّعة مكوّنة من 16 بت.

readBlueLight() → int#: تقرأ مستوى القناة الزرقاء كقيمة غير موقّعة مكوّنة من 16 بت.

مستشعر القرب#

enableProximitySensor(interrupts: bool = True) → None#: تستعيد كسب القرب الافتراضي وقيادة LED، وتُهيّئ بت تمكين مقاطعة القرب، وتُشغّل طاقة الجهاز، وتُمكّن محرك القرب.

disableProximitySensor() → None#: تُعطّل مقاطعة القرب وتوقف محرك القرب.

readProximity() → int#: تقرأ مستوى القرب كقيمة غير موقّعة مكوّنة من 8 بتات.

محرك الإيماءات#

enableGestureSensor(interrupts: bool = True) → None#: تُعيد ضبط حالة الإيماءات، وتضبط WTIME وعدد نبضات الإيماءة، وتعزز LED إلى 300%، وتُهيّئ بت تمكين مقاطعة الإيماءات، وتدخل آلة حالة الإيماءات، وتُشغّل طاقة الجهاز، وتُمكّن أوضاع الانتظار والقرب والإيماءات.

disableGestureSensor() → None#: تُعيد ضبط حالة الإيماءات، وتُعطّل مقاطعة الإيماءات وآلة الحالة، وتوقف محرك الإيماءات.

isGestureAvailable() → bool#: تُعيد True إذا كان بت GVALID في سجل حالة الإيماءات مضبوطاً، مما يشير إلى أن بيانات FIFO للإيماءات جاهزة للقراءة.

readGesture() → int#: تُفرّغ ذاكرة FIFO للإيماءات، وتُشغّل فاكّ ترميز الإيماءات الموجود على اللوحة، وتُعيد واحداً من ثوابت الاتجاه APDS9960_DIR_*. تُعيد APDS9960_DIR_NONE إذا لم يكن المحرك قيد التشغيل، أو لم تتوفر بيانات صالحة، أو لم تُحلّ البيانات إلى إيماءة معروفة.

resetGestureParameters() → None#: تمسح المخزن المؤقت الداخلي لـ FIFO الإيماءات، والفروق (deltas)، والعدّادات، وعدّادات الاقتراب/الابتعاد، والحالة، وآخر حركة مفكوكة الترميز.

processGestureData() → bool#: تعالج عيّنات U/D/L/R الخام من FIFO المخزّنة حالياً لتحديث فروق U/D وL/R وعدّادات الاقتراب/الابتعاد. تُعيد True إذا اكتُشف حدث اقتراب أو ابتعاد، وFalse فيما عدا ذلك.

decodeGesture() → bool#: تحوّل أعداد U/D وL/R الحالية والفروق المتراكمة إلى اتجاه يُخزَّن في الحقل الداخلي gesture_motion_. تُعيد True عند التعرّف على اتجاه، وFalse فيما عدا ذلك.

عتبات القرب#

getProxIntLowThresh() → int#: تُعيد العتبة المنخفضة لمقاطعة القرب (سجل PILT).

setProxIntLowThresh(threshold: int) → None#: تضبط العتبة المنخفضة لمقاطعة القرب.

getProxIntHighThresh() → int#: تُعيد العتبة المرتفعة لمقاطعة القرب (سجل PIHT).

setProxIntHighThresh(threshold: int) → None#: تضبط العتبة المرتفعة لمقاطعة القرب.

getProximityIntLowThreshold() → int#: اسم بديل لـ getProxIntLowThresh().

setProximityIntLowThreshold(threshold: int) → None#: اسم بديل لـ setProxIntLowThresh().

getProximityIntHighThreshold() → int#: اسم بديل لـ getProxIntHighThresh().

setProximityIntHighThreshold(threshold: int) → None#: اسم بديل لـ setProxIntHighThresh().

قيادة LED والكسب والتعزيز#

getLEDDrive() → int#: تُعيد قوة قيادة LED المستخدمة للقرب وALS. مُرمّزة كواحدة من قيم APDS9960_LED_DRIVE_* (0 = 100 mA، 1 = 50 mA، 2 = 25 mA، 3 = 12.5 mA).

setLEDDrive(drive: int) → None#: تضبط قوة قيادة LED المستخدمة للقرب وALS. drive هو واحد من قيم APDS9960_LED_DRIVE_*.

getProximityGain() → int#: تُعيد كسب مستقبِل القرب. مُرمّز كواحد من قيم APDS9960_PGAIN_* (0 = 1x، 1 = 2x، 2 = 4x، 3 = 8x).

setProximityGain(drive: int) → None#: تضبط كسب مستقبِل القرب. drive هو واحد من قيم APDS9960_PGAIN_*.

getAmbientLightGain() → int#: تُعيد كسب مستشعر الضوء المحيط. مُرمّز كواحد من قيم APDS9960_AGAIN_* (0 = 1x، 1 = 4x، 2 = 16x، 3 = 64x).

setAmbientLightGain(drive: int) → None#: تضبط كسب مستشعر الضوء المحيط. drive هو واحد من قيم APDS9960_AGAIN_*.

getLEDBoost() → int#: تُعيد تعزيز تيار LED. مُرمّز كواحد من قيم APDS9960_LED_BOOST_* (0 = 100%، 1 = 150%، 2 = 200%، 3 = 300%).

setLEDBoost(boost: int) → None#: تضبط تعزيز تيار LED. boost هو واحد من قيم APDS9960_LED_BOOST_*.

تعويض كسب القرب وقناع الثنائيات الضوئية#

getProxGainCompEnable() → bool#: تُعيد True إذا كان تعويض كسب القرب ممكَّناً.

setProxGainCompEnable(enable: bool) → None#: تُمكّن أو تُعطّل تعويض كسب القرب.

getProxPhotoMask() → int#: تُعيد القناع المكوّن من 4 بتات للثنائيات الضوئية المعطّلة للقرب. تُربط البتات على النحو 3=UP و2=DOWN و1=LEFT و0=RIGHT؛ حيث 1 يُعطّل ثنائياً ضوئياً و0 يُمكّنه.

setProxPhotoMask(mask: int) → None#: تضبط القناع المكوّن من 4 بتات للثنائيات الضوئية المعطّلة للقرب (انظر الترميز أعلاه).

تهيئة الإيماءات#

getGestureEnterThresh() → int#: تُعيد عتبة القرب المطلوبة للدخول إلى وضع الإيماءات.

setGestureEnterThresh(threshold: int) → None#: تضبط عتبة القرب المطلوبة للدخول إلى وضع الإيماءات.

getGestureExitThresh() → int#: تُعيد عتبة القرب المطلوبة للخروج من وضع الإيماءات.

setGestureExitThresh(threshold: int) → None#: تضبط عتبة القرب المطلوبة للخروج من وضع الإيماءات.

getGestureGain() → int#: تُعيد كسب الثنائي الضوئي المستخدم أثناء وضع الإيماءات. مُرمّز كواحد من قيم APDS9960_GGAIN_* (0 = 1x، 1 = 2x، 2 = 4x، 3 = 8x).

setGestureGain(gain: int) → None#: تضبط كسب الثنائي الضوئي المستخدم أثناء وضع الإيماءات.

getGestureLEDDrive() → int#: تُعيد تيار قيادة LED المستخدم أثناء وضع الإيماءات. مُرمّز كواحد من قيم APDS9960_LED_DRIVE_*.

setGestureLEDDrive(drive: int) → None#: تضبط تيار قيادة LED المستخدم أثناء وضع الإيماءات.

getGestureWaitTime() → int#: تُعيد زمن الانتظار منخفض الطاقة بين عمليات كشف الإيماءات. مُرمّز كواحد من قيم APDS9960_GWTIME_* (0 = 0 ms .. 7 = 39.2 ms).

setGestureWaitTime(time: int) → None#: تضبط زمن الانتظار منخفض الطاقة بين عمليات كشف الإيماءات.

getGestureMode() → bool#: تُعيد True إذا كانت آلة حالة الإيماءات قيد التشغيل حالياً.

setGestureMode(enable: bool) → None#: تدخل آلة حالة الإيماءات أو تخرج منها.

عتبات مقاطعة الضوء المحيط#

getLightIntLowThreshold() → int#: تُعيد العتبة المنخفضة المكوّنة من 16 بت المستخدمة لمقاطعة الضوء المحيط.

setLightIntLowThreshold(threshold: int) → None#: تضبط العتبة المنخفضة المكوّنة من 16 بت المستخدمة لمقاطعة الضوء المحيط.

getLightIntHighThreshold() → int#: تُعيد العتبة المرتفعة المكوّنة من 16 بت المستخدمة لمقاطعة الضوء المحيط.

setLightIntHighThreshold(threshold: int) → None#: تضبط العتبة المرتفعة المكوّنة من 16 بت المستخدمة لمقاطعة الضوء المحيط.

تمكين المقاطعات ومسحها#

getAmbientLightIntEnable() → bool#: تُعيد True إذا كانت مقاطعات الضوء المحيط ممكَّنة.

setAmbientLightIntEnable(enable: bool) → None#: تُمكّن أو تُعطّل مقاطعات الضوء المحيط.

getProximityIntEnable() → bool#: تُعيد True إذا كانت مقاطعات القرب ممكَّنة.

setProximityIntEnable(enable: bool) → None#: تُمكّن أو تُعطّل مقاطعات القرب.

getGestureIntEnable() → bool#: تُعيد True إذا كانت مقاطعات الإيماءات ممكَّنة.

setGestureIntEnable(enable: bool) → None#: تُمكّن أو تُعطّل مقاطعات الإيماءات.

clearAmbientLightInt() → None#: تمسح مقاطعة ضوء محيط معلّقة.

clearProximityInt() → None#: تمسح مقاطعة قرب معلّقة.

class apds9960.uAPDS9960(bus: machine.I2C, address: int = 0x39, valid_id: list = [0xAB, 0x9C, 0xA8, -0x55])#: صنف فرعي في MicroPython من APDS9960. واجهة برمجة تطبيقات عامة مطابقة، لكن الوصول إلى السجلات الأساسي يستخدم استدعاءات readfrom_mem وwriteto_mem بنمط machine.I2C بدلاً من الطرق بنمط SMBus. هذا هو الصنف الذي يُستخدم على أهداف OpenMV / MicroPython.

الاستثناءات#

exception apds9960.ADPS9960InvalidDevId(id: int, valid_ids: list)#: صنف فرعي من ValueError. يُطلقه مُنشئ APDS9960 عندما لا تكون القيمة المقروءة من سجل المعرّف الخاص بالشريحة موجودة في القائمة valid_id.

exception apds9960.ADPS9960InvalidMode(mode: int)#: صنف فرعي من ValueError. تُطلقه APDS9960.setMode() عندما يكون وسيط mode خارج النطاق APDS9960_MODE_POWER..\ APDS9960_MODE_ALL.

الثوابت#

عنوان I2C ومعرّفات الجهاز#

apds9960.APDS9960_I2C_ADDR: int#: عنوان I2C الافتراضي المكوّن من 7 بتات لـ APDS9960 (0x39).

apds9960.APDS9960_DEV_ID: list#: القائمة الافتراضية لقيم سجل معرّف الجهاز الصالحة ([0xAB, 0x9C, 0xA8, -0x55]).

ضبط الإيماءات#

apds9960.APDS9960_GESTURE_THRESHOLD_OUT: int#: الحد الأدنى لمقدار العيّنة (لكل ثنائي ضوئي) الذي يستخدمه فاكّ ترميز الإيماءات عند البحث عن أولى/آخر عيّنات FIFO ضمن النطاق.

apds9960.APDS9960_GESTURE_SENSITIVITY_1: int#: عتبة على فروق U/D وL/R المتراكمة، التي فوقها يلتزم فاكّ الترميز باتجاه تمرير.

apds9960.APDS9960_GESTURE_SENSITIVITY_2: int#: عتبة على فروق U/D وL/R لكل خطوة، التي تحتها يعتبر فاكّ الترميز العيّنة مرشحة للاقتراب/الابتعاد بدلاً من التمرير.

apds9960.APDS9960_TIME_FIFO_PAUSE: int#: عدد المللي ثانية التي تنام فيها حلقة الإيماءات بين عمليات تفريغ FIFO.

أوضاع الميزات#

تُمرَّر هذه القيم إلى APDS9960.setMode().

apds9960.APDS9960_MODE_POWER: int#: بت تشغيل الطاقة (0).

apds9960.APDS9960_MODE_AMBIENT_LIGHT: int#: بت تمكين محرك الضوء المحيط/اللون (1).

apds9960.APDS9960_MODE_PROXIMITY: int#: بت تمكين محرك القرب (2).

apds9960.APDS9960_MODE_WAIT: int#: بت تمكين حالة الانتظار (3).

apds9960.APDS9960_MODE_AMBIENT_LIGHT_INT: int#: بت تمكين مقاطعة الضوء المحيط (4).

apds9960.APDS9960_MODE_PROXIMITY_INT: int#: بت تمكين مقاطعة القرب (5).

apds9960.APDS9960_MODE_GESTURE: int#: بت تمكين محرك الإيماءات (6).

apds9960.APDS9960_MODE_ALL: int#: قيمة حارسة (7) تُخبر APDS9960.setMode() بتمكين أو تعطيل كل بت في سجل ENABLE دفعة واحدة.

تيارات قيادة LED#

apds9960.APDS9960_LED_DRIVE_100MA: int#: قيادة LED بتيار 100 mA (0).

apds9960.APDS9960_LED_DRIVE_50MA: int#: قيادة LED بتيار 50 mA (1).

apds9960.APDS9960_LED_DRIVE_25MA: int#: قيادة LED بتيار 25 mA (2).

apds9960.APDS9960_LED_DRIVE_12_5MA: int#: قيادة LED بتيار 12.5 mA (3).

كسب القرب (PGAIN)#

apds9960.APDS9960_PGAIN_1X: int#: كسب قرب 1x (0).

apds9960.APDS9960_PGAIN_2X: int#: كسب قرب 2x (1).

apds9960.APDS9960_PGAIN_4X: int#: كسب قرب 4x (2). الافتراضي الذي يطبقه المُنشئ.

apds9960.APDS9960_PGAIN_8X: int#: كسب قرب 8x (3).

كسب الضوء المحيط (AGAIN)#

apds9960.APDS9960_AGAIN_1X: int#: كسب ALS بمقدار 1x (0).

apds9960.APDS9960_AGAIN_4X: int#: كسب ALS بمقدار 4x (1). الافتراضي الذي يطبقه المُنشئ.

apds9960.APDS9960_AGAIN_16X: int#: كسب ALS بمقدار 16x (2).

apds9960.APDS9960_AGAIN_64X: int#: كسب ALS بمقدار 64x (3).

كسب الإيماءات (GGAIN)#

apds9960.APDS9960_GGAIN_1X: int#: كسب إيماءات 1x (0).

apds9960.APDS9960_GGAIN_2X: int#: كسب إيماءات 2x (1).

apds9960.APDS9960_GGAIN_4X: int#: كسب إيماءات 4x (2). الافتراضي الذي يطبقه المُنشئ.

apds9960.APDS9960_GGAIN_8X: int#: كسب إيماءات 8x (3).

تعزيز LED#

apds9960.APDS9960_LED_BOOST_100: int#: تعزيز LED بنسبة 100% (0).

apds9960.APDS9960_LED_BOOST_150: int#: تعزيز LED بنسبة 150% (1).

apds9960.APDS9960_LED_BOOST_200: int#: تعزيز LED بنسبة 200% (2).

apds9960.APDS9960_LED_BOOST_300: int#: تعزيز LED بنسبة 300% (3). يُطبَّق تلقائياً بواسطة APDS9960.enableGestureSensor().

أزمنة انتظار الإيماءات#

apds9960.APDS9960_GWTIME_0MS: int#: 0 ms (0).

apds9960.APDS9960_GWTIME_2_8MS: int#: 2.8 ms (1). الافتراضي الذي يطبقه المُنشئ.

apds9960.APDS9960_GWTIME_5_6MS: int#: 5.6 ms (2).

apds9960.APDS9960_GWTIME_8_4MS: int#: 8.4 ms (3).

apds9960.APDS9960_GWTIME_14_0MS: int#: 14.0 ms (4).

apds9960.APDS9960_GWTIME_22_4MS: int#: 22.4 ms (5).

apds9960.APDS9960_GWTIME_30_8MS: int#: 30.8 ms (6).

apds9960.APDS9960_GWTIME_39_2MS: int#: 39.2 ms (7).

اتجاهات الإيماءات#

تُعيد APDS9960.readGesture() هذه القيم.

apds9960.APDS9960_DIR_NONE: int#: لم تُكتشف أي إيماءة (0).

apds9960.APDS9960_DIR_LEFT: int#: تمرير يساري (1).

apds9960.APDS9960_DIR_RIGHT: int#: تمرير يميني (2).

apds9960.APDS9960_DIR_UP: int#: تمرير لأعلى (3).

apds9960.APDS9960_DIR_DOWN: int#: تمرير لأسفل (4).

apds9960.APDS9960_DIR_NEAR: int#: حدث اقتراب (5).

apds9960.APDS9960_DIR_FAR: int#: حدث ابتعاد (6).

apds9960.APDS9960_DIR_ALL: int#: قيمة حارسة (7) تُستخدم داخلياً لتمثيل "أي اتجاه".

حالات الإيماءات#

قيم الحالة الداخلية المُبلَّغ عنها عبر آلة حالة الإيماءات.

apds9960.APDS9960_STATE_NA: int#: لا حالة (0).

apds9960.APDS9960_STATE_NEAR: int#: اكتُشفت حالة اقتراب (1).

apds9960.APDS9960_STATE_FAR: int#: اكتُشفت حالة ابتعاد (2).

apds9960.APDS9960_STATE_ALL: int#: قيمة حارسة (3) تُستخدم داخلياً لتمثيل "أي حالة".

apds9960 --- مُشغّل مستشعر القرب والإيماءات واللون#