From 78139609125c9343ba57d08741d9cd24c40cf772 Mon Sep 17 00:00:00 2001 From: Alex4386 Date: Mon, 3 Jun 2024 01:04:15 +0900 Subject: [PATCH] docs: add docs --- KICKSTART.md | 69 ++++++++++++++++++++++++++++++++++++++++ README.md | 69 +++++++++++++++++----------------------- icons/DolphinWait.png | Bin 0 -> 480 bytes icons/dolphin_71x25.png | Bin 1188 -> 0 bytes src/scenes/about/main.c | 4 ++- src/scenes/list.h | 3 +- 6 files changed, 103 insertions(+), 42 deletions(-) create mode 100644 KICKSTART.md create mode 100644 icons/DolphinWait.png delete mode 100644 icons/dolphin_71x25.png diff --git a/KICKSTART.md b/KICKSTART.md new file mode 100644 index 0000000..d60fb3f --- /dev/null +++ b/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 ` 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). diff --git a/README.md b/README.md index 0404591..385d121 100644 --- a/README.md +++ b/README.md @@ -1,68 +1,57 @@

Flipper Zero: Application Template

## 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. Update `application.fam` with your application's information. +4. Continue on [Setup Build environment](#setup-build-environment). +5. Change `AppID` ## Build Status + -* **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 | -|:-------------:|:-------------:| +- **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 - ``` + ```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 - ``` + - 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 - ``` + ```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. +> 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. -## 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`. - - -### How to use `SceneManager` with this project? -This template implements `SceneManager`, A "Scene" based framework for programming flipper zero GUIs. - -Here is how you can add/modify scenes in this repository: -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). +### 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**) diff --git a/icons/DolphinWait.png b/icons/DolphinWait.png new file mode 100644 index 0000000000000000000000000000000000000000..a69397db3c1b1a957c38ac65bd368f81f197bce0 GIT binary patch literal 480 zcmV<60U!Q}P)~OCkwVHRVN*7NEshiw)61Z8+%f zFWBkB3$p=VnlyMfeffIe+Ar|T<{l5{OLxAVUiAMA7kBx@8pdl{PK0B_`c&mzHCa1z z$w@yVzz|FdR?S@hH!c1e(h>%x!Jg+0WLtX9d(-5Q-lt+vdm_R`jDeh+_s>S^v|4QR zqK=x?sqVOh9vZHBKs(35i@A1V9D_wxzM^QHNCj(cmaRZLmb+jM5on`f&e%;2dHJP^?;L)GsdO%B$ ziQ}QeyBpTi*b${?4PB=B45t;FwPV-wi=Pv5@&2m>=AEPcM2E535SQXxH{dYOSYU78 z!{>@0thMe?`~Yxk0*Jy7c3}Vj03CEiSaefwW^{L9a%BKOY;|s7aA9d~bT4pjXDwrI WWMyOZLm3_b0000TWAzl7@kEf7@I;~nks=zCO(*wx$f*`#%yF}XLqwDyN&A>qX;^elkAYpoN;E7 zT_ad+1+A!okV0Py4WTxu1Va$ocu7nty*w!DqxewhOYlKo`cO5bXEwXhhv>kWbN(~m z_uv2drZ1mqY}nO+VOV3fM=78^gVxT_7W6*!a_R}%LS7*wW3%^LR*YCPxa}3AQ3{SH>$uMGA5P2T2Jp{6c<6W*XAQqH#%^s2xM9KFZk*3S#GF1*!&>f^% zK@ez$qdAU52+})Y`)Y->z4mn_H8l$Gbk}rz6WVy7R@LB$pCFLS>#V-n3T8~@-t~m;fvub zaw?2&QUafr!$gg1Y?8kkH}Y;SU2Q?+5*@V5TkW&nn$=s>o55hv8Yf7xu#|2!_;DXYyRGERL7p5^$ #include "../../main.h" #include "main.h" +#include #define THIS_SCENE About @@ -20,11 +21,12 @@ void About_on_draw(Canvas* canvas, void* context) { canvas_clear(canvas); canvas_set_bitmap_mode(canvas, true); + canvas_draw_icon(canvas, 2, 3, &I_DolphinWait); canvas_set_font(canvas, FontPrimary); canvas_draw_str(canvas, 67, 11, "f0-template"); canvas_set_font(canvas, FontSecondary); canvas_draw_str(canvas, 72, 20, "by Alex4386"); - canvas_draw_line(canvas, 54, 25, 124, 25); + canvas_draw_line(canvas, 68, 25, 124, 25); canvas_draw_str(canvas, 71, 39, "Protected by"); canvas_set_font(canvas, FontPrimary); canvas_draw_str(canvas, 61, 51, "Fantasy Seal"); diff --git a/src/scenes/list.h b/src/scenes/list.h index 8a101d3..8f7bec4 100644 --- a/src/scenes/list.h +++ b/src/scenes/list.h @@ -7,7 +7,8 @@ * Use it as following: * 1. Define the scene via SCENE_ACTION macro. (e.g. SCENE_ACTION(Home)) * 2. Implement the scene handlers in the corresponding file. - * (_on_enter, _on_event, _on_exit, _get_view, _alloc) + * _on_enter, _on_event, _on_exit, _get_view, _alloc, _free + * e.g. Home -> Home_on_enter should be implemented * 3. Include the scene in the list of scenes in main.h. */