قالب Flipper Zero Zig

قالب حديث وجاهز للإنتاج لتطوير تطبيقات Flipper Zero باستخدام لغة البرمجة Zig. يوفر هذا المشروع نظام بناء مبسّط يدمج Zig مع مجموعة تطوير Flipper Zero SDK، مما يتيح للمطورين كتابة تطبيقات آمنة من حيث النوع والذاكرة لمنصة Flipper Zero.

نظرة عامة

يسد هذا القالب الفجوة بين نظام البناء القوي وميزات لغة Zig ومجموعة تطوير برمجيات Flipper Zero الثابتة. يتعامل مع التكامل المعقد بين التجميع المشترك لـ Zig مع معمارية ARM Cortex-M4 ومجموعة تطوير Flipper SDK، مما يوفر نقطة انطلاق نظيفة للتطبيقات المخصصة.

الميزات الرئيسية

• دعم أصلي لـ Zig: كتابة تطبيقات Flipper بالكامل بلغة Zig، والاستفادة من ضمانات السلامة في وقت التجميع وقابلية التشغيل التفاعلي مع لغة C
• خط أنابيب بناء آلي: تكامل سلس مع ufbt (أداة بناء غير رسمية) لتجميع ملفات FAP
• تطوير عبر المنصات: يعمل على macOS و Linux ومنصات أخرى مدعومة من Zig
• تكامل SDK: مسارات تضمين وخيارات مترجم مهيأة مسبقاً لمجموعة تطوير Flipper الكاملة (هدف F7)
• إعداد تفاعلي: سكريبت تهيئة موجه لتخصيص بيانات التطبيق الوصفية
• إطلاق سريع: أوامر مدمجة للبناء والتجميع والنشر على أجهزة Flipper

البنية المعمارية

يستخدم القالب عملية بناء من مرحلتين:

1. مرحلة بناء Zig: تجميع مصدر Zig إلى ملفات كائن ARM Cortex-M4 (app.o)

   • الهدف: معمارية thumb مع نموذج وحدة معالجة مركزية cortex-m4
   • واجهة ABI: eabihf (واجهة ثنائية التطبيقات المضمنة، فاصلة عائمة صلبة)
   • التحسين: ReleaseSmall لتقليل حجم الملف الثنائي

2. مرحلة تجميع UFBT: ربط ملفات الكائن مع SDK وتجميعها بتنسيق .fap

   • تتم معالجتها بواسطة سلسلة أدوات بناء Flipper الرسمية
   • تنتج حزم تطبيقات قابلة للنشر

المتطلبات الأساسية

الأدوات المطلوبة

• Zig: الإصدار 0.15.1 أو أحدث (تحميل)
• UFBT: أداة بناء Flipper غير رسمية (دليل التثبيت)
• Python 3: مطلوب لتشغيل أوامر ufbt
• مجموعة تطوير Flipper Zero SDK: تتم إدارتها تلقائياً بواسطة ufbt (يتم تثبيتها إلى ~/.ufbt)

الإعداد الخاص بالمنصة

macOS

القالب مهيأ مسبقاً لـ macOS ARM64 مع مسار سلسلة أدوات ARM:

~/.ufbt/toolchain/arm64-darwin/arm-none-eabi/include

إذا كنت على منصة مختلفة، قد تحتاج إلى تعديل مسار arm_libc_include في build.zig:31 ليتوافق مع موقع سلسلة الأدوات الخاصة بك.

التثبيت

1. تثبيت UFBT:

   root@kitploit:~

   python3 -m pip install --upgrade ufbt
   ufbt update
   

2. استنساخ أو تنزيل هذا القالب:

   root@kitploit:~

   git clone https://github.com/yourusername/flipper-template.git
   cd flipper-template
   

3. تهيئة مشروعك:

   root@kitploit:~

   zig build init
   

   سيطالبك هذا السكريبت التفاعلي بـ:

   • معرف التطبيق (مثل my_custom_app)
   • اسم العرض (يظهر في قائمة Flipper)
   • الوصف
   • اسم المؤلف
   • رابط مستودع GitHub

الاستخدام

بناء التطبيق

تجميع مصدر Zig إلى ملف كائن:

zig build

ينتج هذا zig-out/bin/app.o مع كل كود التطبيق المُجمّع.

إنشاء حزمة FAP

بناء وتجميع التطبيق بالكامل:

zig build fap

يقوم هذا بتشغيل خط الأنابيب بالكامل:

1. تجميع مصدر Zig إلى ملف كائن
2. استدعاء ufbt للربط مع SDK
3. إنشاء ملف .fap في دليل dist/

النشر على Flipper

تشغيل التطبيق مباشرة على جهاز Flipper Zero متصل:

zig build launch

يقوم هذا بالبناء والتجميع ونقل التطبيق عبر USB، ثم تشغيله تلقائياً.

هيكل المشروع

flipper-template/
├── application.fam       # بيان تطبيق Flipper (بيانات وصفية، نقاط دخول)
├── build.zig            # تكوين نظام بناء Zig
├── build.zig.zon        # بيان حزمة Zig
├── icon.png             # أيقونة التطبيق (مستحسن 10×10 بكسل)
├── setup.sh             # سكريبت تهيئة المشروع التفاعلي
├── src/
│   └── root.zig         # كود مصدر التطبيق الرئيسي
└── zig-out/             # نتائج البناء (تم إنشاؤها)
    └── bin/
        └── app.o        # ملف الكائن المُجمّع

الملفات الرئيسية

• src/root.zig: نقطة الدخول التي تحتوي على دالة start() ومنطق التطبيق
• application.fam: إعدادات خاصة بـ Flipper (معرف التطبيق، الفئة، التبعيات، حجم المكدس)
• build.zig: يحدد أهداف التجميع، مسارات SDK، وأوامر البناء

دليل التطوير

هيكل التطبيق الأدنى

يتضمن القالب مثال "Hello World" يوضح واجهات برمجة تطبيقات Flipper الأساسية:

// استيراد دوال Flipper SDK
const flipper = @cImport({
    @cInclude("furi.h");
    @cInclude("gui/gui.h");
    @cInclude("gui/canvas.h");
    @cInclude("gui/view_port.h");
});

// نقطة دخول التطبيق (يجب أن تسمى "start")
export fn start(_: ?*anyopaque) callconv(.{ .arm_aapcs = .{} }) i32 {
    // تهيئة منفذ عرض واجهة المستخدم الرسومية
    const gui = flipper.furi_record_open("gui");
    const view_port = flipper.view_port_alloc();

    // إعداد الاستدعاءات وواجهة المستخدم
    // ... (راجع src/root.zig للتنفيذ الكامل)

    // حلقة الأحداث
    _ = flipper.furi_thread_flags_wait(1, flipper.FuriFlagWaitAny, flipper.FuriWaitForever);

    return 0;
}

تكامل SDK

يقوم نظام البناء بتكوين مسارات التضمين تلقائياً لـ:

• SDK الأساسي: FURI (واجهة وقت تشغيل Flipper العالمية)
• HAL: طبقة تجريد الأجهزة لـ STM32WB55
• المكتبات القياسية: mbedTLS، nanopb، mlib
• مكتبات البروتوكول: Sub-GHz، NFC، RFID، الأشعة تحت الحمراء
• واجهات برمجة التطبيقات الطرفية: GPIO، SPI، I2C، UART

جميع الرؤوس متاحة عبر @cImport() في كود Zig الخاص بك.

ملاحظات حول اصطلاحات الاستدعاء

تستخدم مجموعة تطوير Flipper SDK اصطلاحات استدعاء ARM AAPCS:

• AAPCS: استدعاء إجراء ARM القياسي (مثل نقطة دخول start())
• AAPCS-VFP: مع دعم الفاصلة العائمة/المتجه (مثل الاستدعاءات)

تأكد من أن الدوال المُصدّرة تطابق اصطلاح الاستدعاء المتوقع:

export fn start(_: ?*anyopaque) callconv(.{ .arm_aapcs = .{} }) i32
export fn draw_callback(canvas: ?*Canvas, ctx: ?*anyopaque) callconv(.{ .arm_aapcs_vfp = .{} }) void

التعامل مع استيرادات SDK

تحتوي بعض رؤوس SDK على تراكيب لا يستطيع مترجم C الخاص بـ Zig معالجتها (مثل الاتحادات مع أنواع غير شفافة في input/input.h). في هذه الحالات، قم بتعريف الدوال الخارجية يدوياً:

extern fn view_port_input_callback_set(
    view_port: ?*flipper.ViewPort,
    callback: ?*const fn (?*anyopaque, ?*anyopaque) callconv(.{ .arm_aapcs_vfp = .{} }) void,
    context: ?*anyopaque
) callconv(.{ .arm_aapcs = .{} }) void;

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

أخطاء البناء

المشكلة: unable to find header 'furi.h'

• السبب: لم يتم تثبيت SDK الخاص بـ UFBT أو مسار ~/.ufbt غير صحيح
• الحل: قم بتشغيل ufbt update لتثبيت رؤوس SDK

المشكلة: undefined reference to 'view_port_alloc'

• السبب: لم يتم ربط ملف الكائن بشكل صحيح مع SDK
• الحل: استخدم zig build fap بدلاً من zig build لإكمال الربط

مشاكل النشر

المشكلة: No Flipper device found

• السبب: الجهاز غير متصل أو في وضع DFU
• الحل: اتصل عبر USB وتأكد من فتح الجهاز في القائمة الرئيسية

المشكلة: تعطل التطبيق عند التشغيل

• السبب: تجاوز سعة المكدس أو اصطلاح استدعاء غير صحيح
• الحل: قم بزيادة stack_size في application.fam أو تحقق من توقيعات الدوال

الإعدادات المتقدمة

خيارات المترجم

قم بتعديل addFlipperDefines() في build.zig لضبط وحدات الماكرو الخاصة بالمعالج الأولي:

obj.root_module.addCMacro("FAP_VERSION", "\\\"1.0\\\"");
obj.root_module.addCMacro("CUSTOM_DEFINE", "value");

إعدادات التحسين

قم بتغيير مستوى التحسين في build.zig:11:

const optimize = b.standardOptimizeOption(.{
    .preferred_optimize_mode = .ReleaseFast,  // أو .ReleaseSmall، .Debug
});

البنية المستهدفة

القالب يستهدف STM32WB55 الخاص بـ Flipper Zero (ARM Cortex-M4F). لنقله إلى أجهزة ARM أخرى، قم بتعديل build.zig:4-9:

const target = b.resolveTargetQuery(.{
    .cpu_arch = .thumb,
    .cpu_model = .{ .explicit = &std.Target.arm.cpu.cortex_m4 },
    .os_tag = .freestanding,
    .abi = .eabihf,
});

المساهمة

المساهمات مرحب بها! يهدف هذا القالب إلى تبسيط تطوير Zig لـ Flipper Zero. إذا واجهت مشاكل توافق مع SDK أو لديك اقتراحات لتحسين عملية البناء، يرجى فتح مشكلة أو طلب سحب.

مجالات التحسين

• دعم مسارات أدوات Windows
• الكشف التلقائي عن إصدار SDK
• التكامل مع كتالوج تطبيقات Flipper
• تجريدات إضافية لواجهة SDK

الموارد

• توثيق مطوري Flipper Zero
• مستودع UFBT
• مرجع لغة Zig
• مرجع واجهة برمجة تطبيقات Flipper SDK

الترخيص

هذا المشروع مرخص بموجب رخصة MIT - راجع ملف LICENSE للحصول على التفاصيل.

الشكر والتقدير

• فريق Flipper Devices على سلسلة أدوات UFBT
• مجتمع Zig على دعم التجميع المشترك لـ ARM
• المساهمين في مجموعة تطوير Flipper Zero SDK

ملاحظة: هذا قالب غير رسمي ولا تابع لشركة Flipper Devices Inc. اختبر التطبيقات جيداً دائماً قبل النشر على الأجهزة الإنتاجية.