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 इंटरऑपरेबिलिटी का लाभ उठाते हुए
• स्वचालित बिल्ड पाइपलाइन: FAP फ़ाइलों को पैकेज करने के लिए ufbt (अनऑफिशियल बिल्ड टूल) के साथ सहज एकीकरण
• क्रॉस-प्लेटफ़ॉर्म डेवलपमेंट: macOS, Linux और Zig द्वारा समर्थित अन्य प्लेटफ़ॉर्म पर कार्य करता है
• SDK एकीकरण: पूर्ण Flipper SDK (F7 टार्गेट) के लिए प्री-कॉन्फ़िगर्ड इन्क्लूड पाथ और कंपाइलर फ़्लैग्स
• इंटरैक्टिव सेटअप: ऐप मेटाडेटा को कस्टमाइज़ करने के लिए गाइडेड इनिशियलाइज़ेशन स्क्रिप्ट
• क्विक लॉन्च: Flipper डिवाइसों पर बिल्ड, पैकेज और डिप्लॉय करने के लिए अंतर्निहित कमांड

आर्किटेक्चर

टेम्पलेट दो-चरणीय बिल्ड प्रक्रिया का उपयोग करता है:

1. Zig बिल्ड चरण: Zig सोर्स को ARM Cortex-M4 ऑब्जेक्ट फ़ाइलों (app.o) में कंपाइल करता है

   • टार्गेट: cortex-m4 CPU मॉडल के साथ thumb आर्किटेक्चर
   • ABI: eabihf (एम्बेडेड एप्लिकेशन बाइनरी इंटरफ़ेस, हार्ड फ्लोट)
   • ऑप्टिमाइज़ेशन: न्यूनतम बाइनरी आकार के लिए ReleaseSmall

2. UFBT पैकेज चरण: ऑब्जेक्ट फ़ाइलों को SDK के साथ लिंक करता है और .fap प्रारूप में पैकेज करता है

   • आधिकारिक Flipper बिल्ड टूलचेन द्वारा संभाला जाता है
   • डिप्लॉय करने योग्य एप्लिकेशन पैकेज तैयार करता है

आवश्यक शर्तें

आवश्यक उपकरण

• Zig: संस्करण 0.15.1 या उसके बाद (डाउनलोड)
• UFBT: अनऑफिशियल Flipper बिल्ड टूल (इंस्टॉलेशन गाइड)
• Python 3: ufbt कमांड चलाने के लिए आवश्यक
• Flipper Zero SDK: ufbt द्वारा स्वचालित रूप से प्रबंधित (~/.ufbt में इंस्टॉल होता है)

प्लेटफ़ॉर्म-विशिष्ट सेटअप

macOS

टेम्पलेट ARM टूलचेन पाथ के साथ ARM64 macOS के लिए प्री-कॉन्फ़िगर्ड है:

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

यदि आप किसी भिन्न प्लेटफ़ॉर्म पर हैं, तो आपको अपने टूलचेन स्थान से मेल खाने के लिए build.zig:31 में arm_libc_include पाथ को समायोजित करने की आवश्यकता हो सकती है।

स्थापना

1. UFBT इंस्टॉल करें:

   python3 -m pip install --upgrade ufbt
   ufbt update
   

2. इस टेम्पलेट को क्लोन या डाउनलोड करें:

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

3. अपना प्रोजेक्ट इनिशियलाइज़ करें:

   zig build init
   

   यह इंटरैक्टिव स्क्रिप्ट आपसे निम्नलिखित पूछेगी:

   • ऐप ID (जैसे, my_custom_app)
   • प्रदर्शन नाम (Flipper मेनू में दिखाया जाता है)
   • विवरण
   • लेखक का नाम
   • GitHub रिपॉज़िटरी URL

उपयोग

एप्लिकेशन बनाना

Zig सोर्स को ऑब्जेक्ट फ़ाइल में कंपाइल करें:

zig build

यह सभी कंपाइल किए गए एप्लिकेशन कोड के साथ zig-out/bin/app.o बनाता है।

FAP पैकेज बनाना

पूर्ण एप्लिकेशन को बिल्ड और पैकेज करें:

zig build fap

यह पूर्ण पाइपलाइन चलाता है:

1. Zig सोर्स को ऑब्जेक्ट फ़ाइल में कंपाइल करता है
2. SDK के साथ लिंक करने के लिए ufbt चलाता है
3. dist/ निर्देशिका में .fap फ़ाइल उत्पन्न करता है

Flipper पर डिप्लॉय करना

कनेक्टेड Flipper Zero पर सीधे एप्लिकेशन लॉन्च करें:

zig build launch

यह ऐप को USB के माध्यम से बिल्ड, पैकेज और ट्रांसफर करता है, फिर इसे स्वचालित रूप से प्रारंभ करता है।

प्रोजेक्ट संरचना

flipper-template/
├── application.fam       # Flipper app manifest (metadata, entry points)
├── build.zig            # Zig build system configuration
├── build.zig.zon        # Zig package manifest
├── icon.png             # App icon (10x10px recommended)
├── setup.sh             # Interactive project initialization script
├── src/
│   └── root.zig         # Main application source code
└── zig-out/             # Build artifacts (generated)
    └── bin/
        └── app.o        # Compiled object file

मुख्य फ़ाइलें

• src/root.zig: start() फ़ंक्शन और एप्लिकेशन लॉजिक वाला एंट्री पॉइंट
• application.fam: Flipper-विशिष्ट कॉन्फ़िगरेशन (ऐप ID, श्रेणी, निर्भरताएँ, स्टैक आकार)
• build.zig: कंपाइलेशन टार्गेट, SDK पाथ और बिल्ड कमांड परिभाषित करता है

विकास गाइड

न्यूनतम एप्लिकेशन संरचना

टेम्पलेट में एक "Hello World" उदाहरण शामिल है जो मुख्य Flipper APIs को प्रदर्शित करता है:

// Import Flipper SDK functions
const flipper = @cImport({
    @cInclude("furi.h");
    @cInclude("gui/gui.h");
    @cInclude("gui/canvas.h");
    @cInclude("gui/view_port.h");
});

// Application entry point (must be named "start")
export fn start(_: ?*anyopaque) callconv(.{ .arm_aapcs = .{} }) i32 {
    // Initialize GUI viewport
    const gui = flipper.furi_record_open("gui");
    const view_port = flipper.view_port_alloc();

    // Set up callbacks and UI
    // ... (see src/root.zig for complete implementation)

    // Event loop
    _ = 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, Infrared
• पेरिफेरल APIs: GPIO, SPI, I2C, UART

सभी हेडर आपके Zig कोड में @cImport() के माध्यम से उपलब्ध हैं।

कॉलिंग कन्वेंशन नोट्स

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 हेडर में ऐसे कंस्ट्रक्ट होते हैं जिन्हें Zig का C ट्रांसलेटर प्रोसेस नहीं कर सकता (जैसे, 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'

• कारण: UFBT SDK इंस्टॉल नहीं है या ~/.ufbt पाथ गलत है
• समाधान: SDK हेडर इंस्टॉल करने के लिए ufbt update चलाएँ

समस्या: undefined reference to 'view_port_alloc'

• कारण: ऑब्जेक्ट फ़ाइल SDK के साथ ठीक से लिंक नहीं हुई है
• समाधान: लिंकिंग पूरा करने के लिए zig build के बजाय zig build fap का उपयोग करें

डिप्लॉयमेंट समस्याएँ

समस्या: No Flipper device found

• कारण: डिवाइस कनेक्ट नहीं है या DFU मोड में है
• समाधान: USB के माध्यम से कनेक्ट करें और सुनिश्चित करें कि डिवाइस मुख्य मेनू पर अनलॉक है

समस्या: ऐप लॉन्च पर क्रैश होता है

• कारण: स्टैक ओवरफ़्लो या गलत कॉलिंग कन्वेंशन
• समाधान: application.fam में stack_size बढ़ाएँ या फ़ंक्शन सिग्नेचर सत्यापित करें

उन्नत कॉन्फ़िगरेशन

कंपाइलर फ़्लैग्स

प्रीप्रोसेसर मैक्रोज़ समायोजित करने के लिए build.zig में addFlipperDefines() संशोधित करें:

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

ऑप्टिमाइज़ेशन सेटिंग्स