عرض مصدر Arduino/advanced io/tone

<noinclude>{{DISPLAYTITLE:الدالة <code>tone()‎</code> في  أردوينو}}</noinclude>
تولِّد الدالة <code>tone()‎</code> موجةً مربَّعةً بتردد محدَّد (وبنسبة 50% لدورة العمل [duty cycle]) على رجل معيَّنة. يمكن تحديد فترة زمنية معيَّنة تُولَّد خلالها الموجة فقط أو ستستمر عملية توليد الموجة إلى أن تستدعى الدالة <code>[[Arduino/advanced io/notone|noTone()‎]]</code>. يمكن ربط الرجل التي ستُولَّد عليها الموجة بطنَّان إجهادي (piezo buzzer) أو أي مكبر صوت لتشغيل النغمات الناتجة عن الموجة المولَّدة.

يمكن توليد نغمة واحدة فقط على إحدى الأرجل، لذا إن كان هنالك نغمة تعمل على رجل معيَّنة واستدعيت الدالة <code>tone()‎</code> على رجل أخرى، فلن يكون لهذا الاستدعاء أي تأثير. أمَّا إن استدعيت الدالة على نفس الرجل التي تعمل عليها النغمة آنذاك، فسيعاد ضبط تردد النغمة التي يجري توليدها.

سيتداخل استعمال الدالة <code>tone()‎</code> مع الخرج PWM على الرجل 3 والرجل 11 (على جميع اللوحات باستثناء لوحات Mega).

ليس بالإمكان توليد نغمات بتردد أقل من 21 هرتز. لتفاصيل تقنية أوسع، اطلع على [https://github.com/bhagman/Tone#ugly-details هذه] الصفحة.

==البنية العامة==
<syntaxhighlight lang="arduino">
tone(pin, frequency)

tone(pin, frequency, duration)
</syntaxhighlight>
==المعاملات==
===<code>pin</code>===
[[Arduino/int|عددٌ صحيحٌ]] يشير إلى الرجل المراد توليد الموجة (النغمة) عليها.

=== <code>frequency</code> ===
[[Arduino/unsignedint|عددٌ صحيحٌ عديم الإشارة]] (unsigned int) يحدِّد تردُّد النغمة بالهرتز.

=== <code>duration</code> ===
[[Arduino/unsignedlong|عددٌ طويلٌ عديم الإشارة]] (unsigned long) يحدِّد مدة عمل النغمة بالميلي ثاينة، وهو معامل اختياري.

==القيم المعادة==
لا يعاد أي شيء.

== أمثلة ==
مثال على استعمال الدالة <code>tone()‎</code> لتوليد موجة مربعة بتردد معين على الرجل 3:<syntaxhighlight lang="arduino">
unsigned int freq = 1000;
void setup() {
  tone(3, freq);     // على الرجل 3 freq توليد موجبة مربعة بالتردد
}

void loop() {
  // وهنا وتكرار تنفيذها tone لا حاجة لوضع الدالة 
}
</syntaxhighlight>

==ملاحظات وتحذيرات==
إن أردت تشغيل نغمات مختلفة على أرجل مختلفة، فأنت بحاجة إلى استدعاء الدالة <code>[[Arduino/advanced io/notone|noTone()‎]]</code> على الرجل التي تعمل عليها النغمة آنذاك قبل استدعاء الدالة <code>tone()‎</code> على الرجل التالية.
==انظر أيضًا==
* الدالة <code>[[Arduino/advanced io/notone|noTone()‎]]</code>: توقف توليد موجةٍ مربَّعةٍ على رجل معيَّنة أُنشئَت باستعمال الدالة <code>[[Arduino/advanced io/tone|tone()‎]]</code>.
* الدالة <code>[[Arduino/advanced io/pulsein|pulseIn()‎]]</code>: تحسب طول نبضةٍ (إمَّا <code>HIGH</code> أو <code>LOW</code>) على رجل محدَّدة.
* الدالة <code>[[Arduino/advanced io/pulseinlong|pulseInLong()‎]]</code> هي دالةٌ بديلةٌ محسَّنةٌ للدالة <code>[[Arduino/advanced io/pulsein|pulseIn()‎]]</code>، إذ يمكنها التعامل مع نبضات ومقاطعات طويلة متأثرة بحالات مختلفة.
* الدالة <code>[[Arduino/advanced io/shiftin|shiftIn()‎]]</code>: تزيح بايتًا من البيانات من رجل محدَّدة إلى متغيِّر مقدار بتٍّ واحدٍ في كل مرة تتغير فيها حالة النبضة على رجل أخرى إلى <code>HIGH</code>.
* الدالة <code>[[Arduino/advanced io/shiftout|shiftOut()‎]]</code>: تزيح بايتًا من البيانات إلى رجل محدَّدة مقدار بتٍّ واحدٍ في كل مرة تتغير فيها حالة النبضة على رجل أخرى إلى <code>HIGH</code>.
* مثال عملي: تشغيل لحن باستعمال الدالة <code>tone()‎</code>.
* مثال عملي: إنشاء نغمة تتبع باستعمال الدالة <code>tone()‎</code>.
* مثال عملي: إنشاء لوحة مفاتيح بسيطة مع استعمال الدالة <code>tone()‎</code>.
* مثال عملي: تشغيل نغمات متعددة على عدة مخرجات باستعمال الدالة <code>tone()‎</code>.
* درس: تعديل عرض النبضة (PWM).

==مصادر==
* [https://www.arduino.cc/reference/en/language/functions/advanced-io/tone/ صفحة الدالة tone()‎ في توثيق أردوينو الرسمي.]
[[تصنيف: Arduino]]
[[تصنيف: Arduino Function]]
[[تصنيف: Arduino I/O]]
[[تصنيف: Arduino Advanced I/O]]