Flipper Zero Zig 템플릿

Zig 프로그래밍 언어를 사용하여 Flipper Zero 애플리케이션을 개발하기 위한 최신 프로덕션 환경에 적합한 템플릿입니다. 이 프로젝트는 Zig를 Flipper Zero SDK와 통합하는 간소화된 빌드 시스템을 제공하여 개발자가 Flipper Zero 플랫폼용 타입 안전(type-safe) 및 메모리 안전(memory-safe) 애플리케이션을 작성할 수 있게 합니다.

개요

이 템플릿은 Zig의 강력한 빌드 시스템과 언어 기능을 Flipper Zero 펌웨어 개발 키트와 연결합니다. Zig의 ARM Cortex-M4 크로스 컴파일과 Flipper SDK 간의 복잡한 통합을 처리하여 맞춤형 애플리케이션을 위한 깔끔한 시작점을 제공합니다.

주요 기능

• 네이티브 Zig 지원: Flipper 애플리케이션을 전적으로 Zig로 작성하며, 컴파일 타임 안전성 보장과 C 상호 운용성을 활용합니다
• 자동화된 빌드 파이프라인: FAP 파일 패키징을 위한 ufbt(비공식 빌드 도구)와의 원활한 통합
• 크로스 플랫폼 개발: macOS, Linux 및 Zig가 지원하는 기타 플랫폼에서 동작
• SDK 통합: 전체 Flipper SDK(F7 대상)에 대한 사전 구성된 include 경로 및 컴파일러 플래그
• 대화형 설정: 앱 메타데이터를 사용자 지정하기 위한 안내형 초기화 스크립트
• 빠른 실행: 빌드, 패키징 및 Flipper 기기 배포를 위한 내장 명령

아키텍처

이 템플릿은 2단계 빌드 프로세스를 사용합니다:

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 설치:

   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
   

   이 대화형 스크립트는 다음 항목을 입력하라는 메시지를 표시합니다:

   • 앱 ID (예: my_custom_app)
   • 표시 이름(Flipper 메뉴에 표시됨)
   • 설명
   • 작성자 이름
   • GitHub 저장소 URL

사용 방법

애플리케이션 빌드

Zig 소스를 오브젝트 파일로 컴파일:

zig build

이렇게 하면 컴파일된 모든 애플리케이션 코드가 포함된 zig-out/bin/app.o가 생성됩니다.

FAP 패키지 생성

전체 애플리케이션을 빌드하고 패키징:

zig build fap

이 명령은 전체 파이프라인을 실행합니다:

1. Zig 소스를 오브젝트 파일로 컴파일
2. ufbt를 호출하여 SDK와 링크
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 경로 및 빌드 명령 정의

개발 가이드

최소 애플리케이션 구조

이 템플릿은 핵심 Flipper API를 보여주는 "Hello World" 예제를 포함합니다:

// 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 통합

빌드 시스템은 다음 항목에 대한 include 경로를 자동으로 구성합니다:

• 코어 SDK: FURI(Flipper Universal Runtime Interface)
• HAL: STM32WB55용 하드웨어 추상화 계층
• 표준 라이브러리: mbedTLS, nanopb, mlib
• 프로토콜 라이브러리: Sub-GHz, NFC, RFID, 적외선(Infrared)
• 주변 장치 API: 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 경로가 올바르지 않음
• 해결 방법: ufbt update를 실행하여 SDK 헤더를 설치

문제: 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");

최적화 설정

build.zig:11에서 최적화 수준 변경:

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

대상 아키텍처

이 템플릿은 Flipper Zero의 STM32WB55(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,
});

기여

기여는 언제나 환영합니다! 이 템플릿은 Flipper Zero용 Zig 개발을 간소화하는 것을 목표로 합니다. SDK 호환성 문제가 발생하거나 빌드 프로세스 개선을 위한 제안이 있다면 이슈 또는 풀 리퀘스트를 열어 주세요.

개선 영역

• Windows 툴체인 경로 지원
• 자동 SDK 버전 감지
• Flipper 애플리케이션 카탈로그와의 통합
• 추가 SDK 래퍼 추상화

리소스

• Flipper Zero 개발자 문서
• UFBT 저장소
• Zig 언어 참조
• Flipper SDK API 참조

라이선스

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 LICENSE 파일을 참조하세요.

감사의 말

• UFBT 툴체인을 제공한 Flipper Devices 팀
• ARM 크로스 컴파일 지원을 제공한 Zig 커뮤니티
• Flipper Zero SDK에 기여한 기여자들

참고: 이 템플릿은 비공식 템플릿이며 Flipper Devices Inc.와 관련이 없습니다. 프로덕션 기기에 배포하기 전에 항상 애플리케이션을 철저히 테스트하세요.