تعلّم

دالة map() في Arduino، على مِقبض يمكنك تدويره

مبتدئ

أو تصفّح كل الدروس.

  • 526قطعة على المنضدة
  • 46لوحة تعمل الآن
  • 1.00xزمن حقيقي، على كل لوحة
Arduino Uno: مِقبض على A0 يخفّض إضاءة LED على الطرف 9مباشر0.000 s 0.00x
اضغط لفتحه في المحرر
تحوّل map() مدى المقبض من 0 إلى 1023 إلى مدى LED من 0 إلى 255. وتطبع الشاشة التسلسلية القيمتين معًا.

map(value, fromLow, fromHigh, toLow, toHigh) re-scales a number from one range to another. Its most common job is the line map(analogRead(A0), 0, 1023, 0, 255), which turns a knob’s reading into an LED brightness: 0 stays 0, 1023 becomes 255, and everything in between lands in proportion.

الدائرة أعلاه هي ذلك بالضبط: مقاوم متغيّر على A0 وLED على الطرف 9 في لوحة Uno. اضغط «تشغيل» ودوّر المقبض. مع المقبض في المنتصف تطبع الشاشة التسلسلية قراءة 511 وإضاءة 127. أدره إلى أقصاه فتطبع 1023 و255، وأعده إلى أقصاه الآخر فتطبع 0 و0، وتتبع LED ذلك.

هذا هو المكسب السريع. وبقية هذه الصفحة عن الأمور الأربعة التي تفعلها map() وتفاجئ الناس: أنها تقرّب للأسفل، وأنها لا تحدّ من القيمة، وأنها لا مانع لديها من العدّ تنازليًا، وأنها تعمل بالأعداد الصحيحة فقط. جرّبنا كل واحدة على Uno في Mokxi، والأرقام أدناه هي ما طُبع.

تريد النسخة خطوة بخطوة؟ الدرس «قراءة جهد» يتناول هذا مع نقاط تحقق.

افتح الدرس

الكود، والأرقام الخمسة

The first number is the value to convert. The next two are the range it comes from, and the last two are the range you want. So map(reading, 0, 1023, 0, 255) reads as "reading, which runs from 0 to 1023, scaled to run from 0 to 255". For a servo you would write map(reading, 0, 1023, 0, 180), and the knob at 512 gives 90 degrees.

يطبع الكود فقط عندما تتحرك القراءة بأكثر من 8، فلا يملأ مقبض ثابت الشاشة. غيّر الرقم 255 الأخير إلى 50 واضغط «تشغيل» مرة أخرى: لن تتجاوز إضاءة LED وهجًا خافتًا أبدًا، لأن المقبض بأكمله يُحوَّل الآن إلى مدى 0 إلى 50.

firmware/uno/examples/sfpot (الكود الذي يعمل أعلاه)
const int KNOB = A0;
const int LED = 9;

int shown = -1;

void setup() {
  pinMode(LED, OUTPUT);
  Serial.begin(9600);
  Serial.println("Mokxi Uno: knob on A0, LED on pin 9");
}

void loop() {
  int reading = analogRead(KNOB);
  int brightness = map(reading, 0, 1023, 0, 255);
  analogWrite(LED, brightness);
  if (abs(reading - shown) > 8) {
    shown = reading;
    Serial.print("reading ");
    Serial.print(reading);
    Serial.print("  brightness ");
    Serial.println(brightness);
  }
  delay(20);
}

افتح هذا الكود في المحررالكود وحده: يضع المحرر اللوحة والقطع التي يستطيع قراءتها من الكود.

كيف تعمل map() من الداخل

لا يوجد فيها شيء خفي. map() هي سطر واحد من حساب الأعداد الصحيحة، ويطبعها مرجع Arduino كاملة. اطرح أسفل المدى الأول، واضرب في حجم المدى الثاني، واقسم على حجم المدى الأول، وأضف أسفل المدى الثاني.

ترجمنا تلك الدالة باسم آخر وقارنّاها بدالة map() المدمجة لكل قراءة من 0 إلى 1023، نحو 0 إلى 255، و0 إلى 180، و255 إلى 0. تطابقت كل الإجابات. ومعرفة الصيغة تفسّر كل مفاجأة أدناه: القسمة تلقي بالباقي، ولا شيء في أي مكان يتحقق من أن الإجابة داخل المدى.

map()، كما يعطيها مرجع Arduino
long map(long x, long in_min, long in_max, long out_min, long out_max) {
  return (x - in_min) * (out_max - out_min) / (in_max - in_min) + out_min;
}

تقرّب للأسفل، فالقيمة العليا نادرة

قسمة الأعداد الصحيحة تلغي الكسر. map(512, 0, 1023, 0, 255) تساوي 127.6 على آلة حاسبة و127 على اللوحة. وmap(1022, 0, 1023, 0, 255) تساوي 254.75، وتقول اللوحة 254. قراءة 1023 بالضبط هي وحدها التي تعطي 255.

أحصينا ذلك بتشغيل كل قراءة من 0 إلى 1023 عبر map() على Uno. خمس قراءات تعطي 0، ومعظم النواتج تحصل كل واحدة منها على أربع قراءات، وتحصل 255 على واحدة. على مقاوم متغيّر حقيقي، مع ضجيج بسيط على المزلق، ستندر جلوس LED عند الإضاءة الكاملة. وهذا مقبول عادة. وعندما لا يكون كذلك، اقسم على أربعة بدلًا من ذلك: reading / 4، وهي نفسها map(reading, 0, 1024, 0, 256). عندها يحصل كل ناتج من 0 إلى 255 على أربع قراءات بالضبط، وتعطي 512 الناتج 128، وتعطي 1023 الناتج 255، ولا 256 أبدًا.

لا تحدّ من القيمة: استخدم constrain()

لا مانع لديها من إعطاء إجابة خارج المدى الذي أعطيتها إياه. لنقل إنك عايرت حساس إضاءة ووجدت أنه يقرأ 200 في الظلام و800 في ضوء النهار، فكتبت map(reading, 200, 800, 0, 100) للحصول على نسبة مئوية. في شمس ساطعة يقرأ 900، فيقول الكود 116 بالمئة. أعطها 1200 على مدى 0 إلى 1023 فتحصل على 299، وهي ليست إضاءة وُلدت analogWrite() لتستقبلها.

الحل نداء واحد إضافي. constrain(map(reading, 200, 800, 0, 100), 0, 100) أعطت 100 للقراءة نفسها 900. أبقِ الدالتين معًا كلما يمكن للمدخل أن يتجاوز الطرفين اللذين قستهما، وهذا يحدث دائمًا مع أي حساس حقيقي.

حوّل، ثم حدّد
void setup() {
  Serial.begin(9600);
  int reading = 900;
  Serial.println(map(reading, 200, 800, 0, 100));
  Serial.println(constrain(map(reading, 200, 800, 0, 100), 0, 100));
}

void loop() {
}

افتح هذا الكود في المحررالكود وحده: يضع المحرر اللوحة والقطع التي يستطيع قراءتها من الكود.

تنازليًا وتحت الصفر

بدّل الرقمين الأخيرين ويعمل المدى في الاتجاه المعاكس. map(300, 0, 1023, 255, 0) أعطت 181، أي أن تدوير المقاوم المتغيّر للأعلى يخفّض سطوع LED. هذا هو الحل السهل لمقاوم متغيّر موصّل بالمقلوب، أو لحساس ضوء يجب أن يضيء مصباحًا عند حلول الظلام.

Negative numbers work too. map(512, 0, 1023, -40, 125) gave 42, which is how a sensor’s 0 to 5 V output becomes -40 to 125 degrees. Below zero, the rounding goes toward zero rather than down: map(-10, 0, 1023, 0, 255) gave -2, not -3.

لماذا تستخدم map() نوع long، ولماذا تختفي الأعداد العشرية

جرّب الحساب بنفسك مع int وستحصل على نتيجة خاطئة. على لوحة Uno يكون int من 16 بت ولا يتّسع لأكثر من 32767. int a = 1000; ثم a * 180 / 1023 طبع -16، لأن 180000 لا تتّسع فالتفّت قبل القسمة. أما map(1000, 0, 1023, 0, 180) فطبع 175، لأن map() تنفّذ الضرب في long من 32 بت.

تقبل map() الأعداد الصحيحة فقط. map(2.7, 0, 10, 0, 100) طبع 20، لأن 2.7 اقتُطعت إلى 2 عند الدخول، وقد حذّرت لوحة البناء: implicit conversion from 'double' to 'long' changes value from 2.7 to 2. لاستخدام الأعداد العشرية، اكتب الصيغة نفسها مع float. النسخة أدناه طبعت 27.00 للقيمة 2.7، و2.50 لقراءة قدرها 512 محوَّلة إلى مدى من 0 إلى 5 فولت.

دالة map() للأعداد العشرية
float mapFloat(float x, float inMin, float inMax, float outMin, float outMax) {
  return (x - inMin) * (outMax - outMin) / (inMax - inMin) + outMin;
}

void setup() {
  Serial.begin(9600);
  Serial.println(mapFloat(2.7, 0, 10, 0, 100));
  Serial.println(mapFloat(512, 0, 1023, 0, 5));
}

void loop() {
}

افتح هذا الكود في المحررالكود وحده: يضع المحرر اللوحة والقطع التي يستطيع قراءتها من الكود.

افتح هذه الدائرة في المحرر. لوحة Arduino Uno: مقاوم متغيّر على A0 يتحكم في سطوع LED على الطرف 9، موصولة كما تعمل في أعلى هذه الصفحة. غيّر قطعة أو قيمة وشغّلها مرة أخرى.

افتح الدائرة

الأسئلة

هل تقيّد map() في Arduino النتيجة؟

لا. القيمة الخارجة عن المدى الأول تعطي جوابًا خارج المدى الثاني: قراءة قدرها 900 محوَّلة من 200 إلى 800 على مدى 0 إلى 100 تعطي 116. لفّها داخل constrain()، كما في constrain(map(x, 200, 800, 0, 100), 0, 100).

لماذا لا تصل map(x, 0, 1023, 0, 255) إلى 255 تقريبًا أبدًا؟

لأن map() تقرّب نحو الأسفل، فلا تعطي 255 إلا عند قراءة 1023 بالضبط. خمس قراءات تعطي 0 ومعظم المخرجات تحصل على أربع قيم. اقسم القراءة على 4 بدلًا من ذلك إذا أردت أن يحصل كل مستوى سطوع على الحصة نفسها من المقاوم المتغيّر.

هل تقبل map() الأعداد العشرية؟

لا. معاملاتها وجوابها من نوع long، فتتحول 2.7 إلى 2 قبل أن تبدأ. اكتب الصيغة نفسها بمعاملات float، كما تفعل الدالة mapFloat() في هذه الصفحة، عندما تحتاج إلى الكسور.

كيف أعكس مدًى باستخدام map()؟

بدّل الرقمين الأخيرين: map(reading, 0, 1023, 255, 0) تعطي 255 عند أسفل المقاوم المتغيّر و0 عند أعلاه. ويمكن عكس المدى الأول بالطريقة نفسها.

ما الفرق بين map() و constrain()؟

تغيّر map() مقياس العدد. أما constrain() فتترك المقياس كما هو وتمنع العدد من تجاوز الحدّين اللذين تعطيهما له. وغالبًا ما تُستخدمان معًا، map() أولًا.

ما هي صيغة دالة map() في Arduino؟

(value - fromLow) * (toHigh - toLow) / (fromHigh - fromLow) + toLow، تُحسب بأعداد صحيحة ويُرمى الباقي. لذا map(1000, 0, 1023, 0, 100) تساوي 97 و map(512, 0, 1023, 0, 100) تساوي 50، وهذا ما طبعته لوحة Uno هنا.

المصادر

من أين جاءت الحقائق في هذه الصفحة

ابنِ هذا على أرض الواقع

افتح المحرر وغيّر قيمة وشاهد الرقم يتحرك معها. لا شيء لتثبّته ولا حاجة إلى حساب.