YOSHIMITSU · مرجع واجهة برمجة التطبيقات

النينجا الهرمسي كمكتبة: رسم تخطيطي واحد مرتاح، هدفان، ست وضعيات، ووحدة التحكم المحمية بـ 極光 التي تدير العرش.

البنية

YOSHIMITSU هي مكتبة يعلوها رسم تخطيطي رفيع. النواة كلها تعيش في src/Yoshimitsu.h؛ وكل قيمة افتراضية تعيش في src/Yoshimitsu_Loadout.h كقيم _DEFAULT (أطراف، توقيتات، مستويات بوابات). الرسم التخطيطي — yoshimitsu.ino أو نسخة examples/Yoshimitsu_Default/ — يحمل فقط إعدادك* وأي تجاوزات تعرّفها قبل التضمين. حدّث المكتبة دون إعادة لمس رسمك.

اكتشاف الهدف تلقائي: ARDUINO_ARCH_RP2040 يختار مسار RP2040-Tiny (Servo.h، تبديل الوضعية بنقرات RESET)، وARDUINO_ARCH_ESP32/ARDUINO_ARCH_ESP32S3 يختار مسار ESP32-S3 (ESP32Servo.h، USB أصلي). أي شيء آخر يفشل عند الترجمة بخطأ #error واضح.

graph TB
  SKETCH["yoshimitsu.ino
the relaxed sketch — config only"]
  LOADOUT["Yoshimitsu_Loadout.h
the starting loadout · *_DEFAULT"]
  CORE["src/Yoshimitsu.h
the whole core"]
  STANCES["six stances
KINCHO · MANJI · FLEA
MEDITATION · NSS · BACK"]
  CONSOLE["USB-serial console
極光-gated admin"]
  CRSF["CRSF RX"]
  BRIDGE["MUSHIN bridge
無心 no-mind protocol"]
  PWM["servo PWM
wing L/R · crest"]
  SKETCH --> CORE
  LOADOUT --> CORE
  CRSF --> CORE
  BRIDGE --> CORE
  CONSOLE --> CORE
  CORE --> STANCES
  STANCES --> PWM

الوضعيات الست

كل وضعية هي قيمة تعداد Stance (0–5) تُختار وقت التشغيل — بأمر USB، أو زر GPIO0 (ESP32-S3)، أو نقرات RESET (RP2040-Tiny).

الوضعية	الوظيفة
KINCHO	الصدّ — محوّل CRSF→PWM؛ قنوات الراديو تتحول إلى ميكروثوانٍ للماكينة.
MANJI_DRAGONFLY	التحليق — المحوّل بالإضافة إلى PID الجيروسكوبي Zephyrus المحلي على القمّة.
FLEA	الرفع — أداة دورة طاقة تُسقط المستقبِل في محمّل الإقلاع ثم MEDITATION.
MEDITATION	رأس الإسفنج — وماض جيب؛ USB↔UART جسر شفاف نقي لأداة esptool.
NSS	منضدة بلا سيف — تشغيل مباشر للماكينة (SERVO i us)، دون راديو.
BACK_TURNED	المرآة — سكون خادع؛ صدى UART لا يلتفت أبداً إلى الوراء.

بوابات وقت الترجمة

كل ما هو اختياري يُزال نظيفاً عند التعطيل — لا بايتات ميتة ولا مراجع معلّقة. تجاوز أيّاً منها في رسمك قبل التضمين.

• JIGUANG — الراوي / المدير (1 = حاضر في كل مكان، 0 = صفر بايتات من 極光 تُترجم).
• YOSHI_GYRO — مسار الجيروسكوب Zephyrus MPU6050.
• YOSHI_RGB — شفق WS2812B المدمج (لون الوضعية الدائم الإضاءة).
• JIGUANG_PROMPT — سلسلة موجه وحدة تحكم الإدارة (الافتراضي "極光")؛ أعد تسميتها في الرسم.
• BOARD_CUSTOM — قدّم أطرافك الخاصة CUSTOM_RP2040_*_DEFAULT / CUSTOM_S3_*_DEFAULT.

واجهة برمجة تطبيقات وحدة التحكم

تبقى أوامر الوضعيات مفتوحة: KINCHO وMANJI وFLEA وMEDITATION وNSS وBACK وPOSE n، بالإضافة إلى STATUS وSERVO i us وHELP. أوامر الإدارة مقفلة خلف الموجه: اكتب 極光 أولاً، ثم DOC أو SETUP أو JIGUANG أو MUTE أو CRSF أو SCORE أو ELRS أو LEGEND أو BRIDGE أو ADMIN أو MUSHIN.

極光 DOC يطبع كتالوج الأكواد السرية؛ 極光 SETUP يطبع معالج التأمل (الوضعية، مستوى الصوت، حالة MUSHIN، طاقة المستقبِل). السطر بلا موجه الذي يصيب أمراً مقفلاً يجيب «العرش محروس» ويعود.

MUSHIN 無心 — بروتوكول اللاعقل

جسر ذاكرة العضلات (الروح→العضلة) يتحدث إطاراً من 4 حقول عبر السلكين نفسهما اللذين يستخدمهما الومّاض. يُقلع مسلّحاً ويُحفظ في الذاكرة الومضية.

[0x9B][len][type][payload][xor]
  0x01  INTENT    n × uint16 µs per servo
  0x02  ANNOUNCE  1 Hz keepalive
  0x03  TELEMETRY gyro rate + correction

النشر

ثبّت مجلد sketches/yoshimitsu كمكتبة Arduino ثم افتح ملف → أمثلة → Yoshimitsu → Yoshimitsu_Default. ومّض مرة واحدة؛ بعدها تكون التحديثات عبر git pull أو إصدار جديد — ويبقى الرسم دون مساس.

استكشاف الأخطاء وإصلاحها

• YOSHIMITSU targets ESP32-S3 or RP2040 only — لوحتك ليست أيّاً منهما؛ تحقق من أدوات → اللوحة أو عرّف BOARD_CUSTOM.

• أمرٌ يجيب «العرش محروس» — إنه أمر إدارة؛ اكتب 極光 أولاً.

• ينتهي esptool بمهلة في MEDITATION — تأكد من أن طرفي UART للجسر (BRIDGE_RX_PIN/BRIDGE_TX_PIN) يطابقان توصيلاتك.