Initial commit

.github/scripts/change_ver.sh

@@ -0,0 +1,25 @@
+#!/bin/bash
+
+# Check if $TAG_NAME is set
+if [ -z "$TAG_NAME" ]; then
+    echo "Error: \$TAG_NAME must be set"
+    exit 1
+fi
+
+# Extract the version from $TAG_NAME
+version="${TAG_NAME##v}"
+
+# Loop through all files in the current directory
+for file in *; do
+    # Check if the file is a regular file
+    if [ -f "$file" ]; then
+        # Make a temporary copy of the file
+        cp "$file" "$file.tmp"
+
+        # Perform the replacement
+        sed "s/fap_version=\"[0-9]*\.[0-9]*\"/fap_version=\"$version\"/" "$file.tmp" > "$file"
+
+        # Remove the temporary file
+        rm "$file.tmp"
+    fi
+done

.github/scripts/renamer.sh

@@ -0,0 +1,28 @@
+#!/bin/bash
+
+# Check if $DIST_DIR and $FILE_SUFFIX are set
+if [ -z "$FILE_SUFFIX" ] || [ -z "$DIST_FILE" ]; then
+    echo "Error: \$DIST_DIR and \$FILE_SUFFIX must be set"
+    exit 1
+fi
+
+# $DIST_FILE
+DIST_FILE=$(echo "$DIST_FILE" | head -n 1)
+DIST_DIR=$(dirname "$DIST_FILE")
+
+# Loop through files in $DIST_DIR
+for file in "$DIST_DIR"/*; do
+    # Check if the item is a regular file
+    if [ -f "$file" ]; then
+        # Extract the filename and extension
+        filename=$(basename "$file")
+        extension="${filename##*.}"
+        name="${filename%.*}"
+
+        # Construct the new filename
+        new_filename="${name}-${FILE_SUFFIX}.${extension}"
+
+        # Rename the file
+        mv "$file" "$DIST_DIR/${new_filename}"
+    fi
+done

.github/workflows/lint.yml

@@ -0,0 +1,17 @@
+name: Lint
+on:
+    - push
+    - pull_request
+
+jobs:
+    all:
+        runs-on: ubuntu-latest
+        name: Lint
+        steps:
+          - name: Checkout
+            uses: actions/checkout@v4
+          - name: Linting
+            uses: flipperdevices/flipperzero-ufbt-action@v0.1.3
+            with:
+                sdk-channel: release
+                task: lint

.github/workflows/nightly.yml

@@ -0,0 +1,41 @@
+name: Nightly
+on:
+    push:
+        branches:
+            - main
+
+jobs:
+    all:
+        runs-on: ubuntu-latest
+        name: Nightly Build for ${{ matrix.name }}
+        strategy:
+            matrix:
+                include:
+                  - name: (Official) Release channel
+                    sdk-ident: official_release
+                    sdk-channel: release
+                  - name: (Unleashed) Release channel
+                    sdk-ident: unleashed_release
+                    sdk-index-url: https://up.unleashedflip.com/directory.json
+                    sdk-channel: release
+                  - name: (Official) Dev channel
+                    sdk-ident: official_dev
+                    sdk-channel: dev
+                  - name: (Unleashed) Development channel
+                    sdk-ident: unleashed_dev
+                    sdk-index-url: https://up.unleashedflip.com/directory.json
+                    sdk-channel: dev
+        steps:
+          - name: Checkout
+            uses: actions/checkout@v4
+          - name: Build for ${{ matrix.name }}
+            uses: flipperdevices/flipperzero-ufbt-action@v0.1.3
+            id: build-app
+            with:
+                sdk-channel: ${{ matrix.sdk-channel }}
+                sdk-index-url: ${{ matrix.sdk-index-url }}
+          - name: Upload app artifacts
+            uses: actions/upload-artifact@v3
+            with:
+                name: ${{ github.event.repository.name }}-${{ steps.build-app.outputs.suffix }} (${{ matrix.sdk-ident }})
+                path: ${{ steps.build-app.outputs.fap-artifacts }}

.github/workflows/release.yml

@@ -0,0 +1,56 @@
+name: Build Release
+on:
+    release:
+        types: [created]
+
+jobs:
+    all:
+        runs-on: ubuntu-latest
+        name: Build Release for ${{ matrix.name }}
+        strategy:
+            matrix:
+                include:
+                  - name: (Official) Release channel
+                    sdk-ident: official_release
+                    sdk-channel: release
+                  - name: (Unleashed) Release channel
+                    sdk-ident: unleashed_release
+                    sdk-index-url: https://up.unleashedflip.com/directory.json
+                    sdk-channel: release
+                  - name: (Official) Dev channel
+                    sdk-ident: official_dev
+                    sdk-channel: dev
+                  - name: (Unleashed) Development channel
+                    sdk-ident: unleashed_dev
+                    sdk-index-url: https://up.unleashedflip.com/directory.json
+                    sdk-channel: dev
+        steps:
+          - name: Checkout
+            uses: actions/checkout@v4
+          - name: Change Version to ${{ github.event.release.tag_name }}
+            run: |
+                chmod +x ./.github/scripts/change_ver.sh
+                ./.github/scripts/change_ver.sh
+            env:
+                TAG_NAME: ${{ github.event.release.tag_name }}
+          - name: Build for ${{ matrix.name }}
+            uses: flipperdevices/flipperzero-ufbt-action@v0.1.3
+            id: build-app
+            with:
+                sdk-channel: ${{ matrix.sdk-channel }}
+                sdk-index-url: ${{ matrix.sdk-index-url }}
+          - name: Rename Built files for ${{ matrix.name }}
+            run: |
+                chmod +x ./.github/scripts/renamer.sh
+                ./.github/scripts/renamer.sh
+            env:
+                FILE_SUFFIX: ${{ matrix.sdk-ident }}-${{ steps.build-app.outputs.suffix }}
+                DIST_FILE: ${{ steps.build-app.outputs.fap-artifacts }}
+          - name: Upload packages to release
+            uses: svenstaro/upload-release-action@v2
+            with:
+                repo_token: ${{ secrets.GITHUB_TOKEN }}
+                file: ./dist/*
+                tag: ${{ github.ref }}
+                overwrite: true
+                file_glob: true

.gitignore

@@ -0,0 +1,6 @@
+dist/*
+.vscode
+.clang-format
+.editorconfig
+.env
+.ufbt

CHANGELOG.md

@@ -0,0 +1,5 @@
+v1.0:
+ * The first release of the plugin
+
+v0.5:
+ * this is the example of the changelog

KICKSTART.md

@@ -0,0 +1,69 @@
+# Getting Started with `f0-template`
+
+Welcome on your path to creating Flipper Zero Application!  
+Here are the few stuff to get started!
+
+## Before you begin
+
+### Change `AppID`
+
+1. Open [application.fam](applciation.fam).
+2. head to `appid="demo_app"` and change it to your own.
+3. Open [./src/scenes/about/main.c](src/scenes/about/main.c).
+4. Update `#include <demo_app_icons.h>` into `#include <{app_id}_icons.h>`.  
+   If there is intelliSense error for missing variable, try rebuilding application.
+
+## Developer Resources
+
+Here are the resources for developing applications for Flipper Zero:
+
+- [Flipper Zero Firmware Docs](https://developer.flipper.net/flipperzero/doxygen/)
+  - [`struct` list](https://developer.flipper.net/flipperzero/doxygen/annotated.html) ([index](https://developer.flipper.net/flipperzero/doxygen/classes.html))
+- [Flipper Zero code examples](https://github.com/m1ch3al/flipper-zero-dev-tutorial)
+- [Lopaka, Graphics Editor for Embedded Devices](https://lopaka.app/)  
+  Note that Flipper Zero has screen dimension of `128x64`.
+
+## Directory Structure
+
+`f0-template` consists of following directories
+
+- `.github` - Reserved for GitHub Actions
+- `icons` - For generating `Icon` (Sprites) for use in GUI elements
+- `screenshots` - When uploaded to store, these are the Screenshots available from store page
+- `src` - Where the C source is located
+  - `src/main.c` - Where the main entrypoint is available.
+  - `src/scenes` - Scene definitions for Scene Manager - Refer to [Using SceneManager](#using-scenemanager)
+- `application.fam` - Flipper Zero's application manifest file - Refer to [this docs](https://developer.flipper.net/flipperzero/doxygen/app_manifests.html)
+- `CHANGELOG.md` - When uploaded to store, these are the changelog available from store page
+- `icon.png` - The Application Icon which is shown next to application name in Apps menu.
+
+### `icons`
+
+> [!WARNING]  
+> alpha channel of PNG is **NOT** supported.
+> Make sure that background is white!
+
+This directory is for generating `Icon` struct which can be used for drawing sprites in flipper zero `Canvas`.  
+It can be used as following:
+
+1. Put your `PNG` files into icons.
+2. Build (`ufbt build` or anything triggers build job) at least once before use.
+3. Import `{app_id}_icons.h`.
+4. On `draw_callback`, draw Icon by calling `canvas_draw_icon(canvas, loc_x, loc_y, &I_{png_filename});`
+5. Done!
+
+### Using `SceneManager`
+
+This template implements `SceneManager`, A "Scene" based framework for programming flipper zero GUIs.
+
+#### Creating Scenes
+
+The Scenes are defined via using macro: `SCENE_ACTION`. By default, the `f0-template` provides two example scenes
+
+1. Goto [`./src/scenes/list.h`](/src/scenes/list.h).
+2. Add your own scene by using macro: `SCENE_ACTION`.
+   (e.g. If you want to make new scene called `Store`, You should type `SCENE_ACTION(Store)`)
+3. Implement `_on_enter`, `_on_event`, `_on_exit`, `_get_view`, `_alloc`, `_free` accordingly. Refer to [`./src/scenes/home/main.c`](/src/scenes/home/main.c) for more info.  
+   (F0 doesn't make sure the precendence of `_on_exit` and `_free`. Please make sure those two are independent by checking each other's free'd state)
+4. Add headers to export those functions.
+5. Include your header in [`./src/scenes/import.h`](/src/scenes/import.h).

README.md

@@ -0,0 +1,57 @@
+<h1 align="center">Flipper Zero: Application Template</h1>
+
+## How to use this template
+
+1. Setup the repository by clicking the `Use this template` button on the top of the repository. Fill in the data if needed.
+2. Update `README.md`'s upstream url with your repository's url.
+3. Add `LICENSE` file with your own license.
+4. Continue on [Setup Build environment](#setup-build-environment).
+5. Change `AppID`
+
+## Build Status
+
+<!-- Replace the https://github.com/Alex4386/f0-template to your own repo after using template! -->
+
+- **Latest Release**: [Download](https://github.com/Alex4386/f0-template/releases/latest)
+- **Latest Nightly**: [Download](https://github.com/Alex4386/f0-template/actions/workflows/nightly.yml) _(GitHub Login Required)_
+
+|                                           Nightly Build                                           |                                           Release Build                                           |
+| :-----------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------: |
+| ![Nightly Build](https://github.com/Alex4386/f0-template/actions/workflows/nightly.yml/badge.svg) | ![Release Build](https://github.com/Alex4386/f0-template/actions/workflows/release.yml/badge.svg) |
+
+## Setup Build environment
+
+### Build Instruction
+
+1. Install `ufbt`:
+   ```bash
+   pip3 install ufbt
+   ```
+2. Clone this repository and enter the repository root.
+3. Run `ufbt update` to update the SDK for your flipper
+   - If you are using custom firmware, You should switch SDK. Here is the example for `unleashed` firmware:
+     ```bash
+     ufbt update --index-url=https://up.unleashedflip.com/directory.json
+     ```
+   - If you want to use different release channel, You can run update to that channel too. Here is the example for `dev` channel (`dev`, `rc`, `release` are supported):
+     ```bash
+     ufbt update --channel=dev
+     ```
+4. Run `ufbt` in the repository root:
+   ```bash
+   ufbt
+   ```
+5. Compiled binary is now available at `./dist/` directory.
+
+### Setup Visual Studio Code
+
+> [!WARNING]
+> This command will overwrite your `.vscode` directory and `.gitignore` on your root directory.
+> **Make sure to backup your changes before running this command.**
+
+1. Suppose your build environment is ready.
+2. Run `ufbt vscode_dist` to generate Visual Studio Code config.
+
+### What Next?
+
+See [KICKSTART.md](KICKSTART.md) to see how to start building and setting up the repo for the first time! (This includes changing `AppID` and required steps to make your app **WORK**)

application.fam

@@ -0,0 +1,32 @@
+# Please refer to:
+# https://developer.flipper.net/flipperzero/doxygen/app_manifests.html
+
+App(
+    appid="demo_app",  # Must be unique
+    name="Demo Application",  # Displayed in UI
+    apptype=FlipperAppType.EXTERNAL,
+    entry_point="entrypoint",
+    stack_size=2 * 1024, # size of memory stack it will allocate
+
+    # source code settings
+    sources=[            # Due to limitation of the fbt,
+      "src/*.c*",        # you need to specify nested directories
+      "src/*/*.c*",      # manually since it doesn't support
+      "src/*/*/*.c*"     # recurse globbing such as "src/**/*.c*"
+    ], 
+
+    # Dependencies
+    requires=[
+
+    ],
+
+    # FAP Settings
+    fap_category="Tools",
+    fap_description="A simple app for demonstration",
+    fap_version="1.0",  # (major, minor)
+    fap_icon="icon.png",  # 10x10 1-bit PNG
+    fap_author="Alex4386",
+    fap_weburl="https://github.com/Alex4386/f0-template",
+    fap_icon_assets="icons",  # Image assets to compile for this application
+                              # available as {appid}_icons.h in the source code
+)

icons/.gitkeep

@@ -0,0 +1 @@
+Drop 

src/handler.c

@@ -0,0 +1,19 @@
+#include "main.h"
+
+bool scene_handler_event_forwarder(void* context, uint32_t event_id) {
+    App* app = (App*)context;
+    if(app == NULL || app->scene_manager == NULL) {
+        return false;
+    }
+
+    return scene_manager_handle_custom_event(app->scene_manager, event_id);
+}
+
+bool scene_handler_navigation_forwarder(void* context) {
+    App* app = (App*)context;
+    if(app == NULL || app->scene_manager == NULL) {
+        return false;
+    }
+
+    return scene_manager_handle_back_event(app->scene_manager);
+}