Skip to content

Instantly share code, notes, and snippets.

@ltrademark

ltrademark/ReadMe.md

Last active December 28, 2022 21:15
Show Gist options
  • Save ltrademark/c389bfc3dda83b8c42643ed3451ee54e to your computer and use it in GitHub Desktop.
Save ltrademark/c389bfc3dda83b8c42643ed3451ee54e to your computer and use it in GitHub Desktop.
Download ZIP
Flipperzero: How to make Screen Animations
Raw
ReadMe.md

Flipper zero Badgeles

How To Make & compile Animations

Making screen animations on the flipper is pretty straight forward once you understand some basics. As far as i've tried, there are no frame limitations to compiling an animation, however, for the sake of the aesthetic, and screen hardware on the flipper zero, 12fps is often best. I've also found that 8fps with around 26 total frames is a pretty cozy workspace.

Disclaimer: This has only been done & tested on a Windows Machine, so the compilation method is set in Powershell.

Getting Started

You will need the following:

  • Animation Frames
  • File batch renaming tool
    • You can use PowerRename from Windows PowerToys, or use something like Ant Renamer. Both do the same thing, the PowerToys suite has a lot more than just renamers.
  • A cloned version of the Flipper Repository
  • Powershell
  • qFlipper for Flipper file management

Before getting any visuals together, it would be best to set-up your working environment. To do this, lets start by git cloneing (or just downloading) the Flipper Repository to any directory of your choosing. Once you have the repo locally, navigate over to assets/dolphin/external. Here you'll likely see some default animations already on the FlipperZero, and you'll notice a particular naming scheme. The quick of it is that the L1, L2, L3 Denote a level your flipper can attain. Although this title does not dictate what level your animation is assignable to, it's more for you to know at a quick glance. The Second part being a custom name identifier, often seperated with _ for spaces. Lastly the dimensions of your animation. Again, all this is for your purposes of identifying, the actual level, and dimensions, are either set in the manifest, or meta text files.

In external, you'll create a folder with a similar scheme as the other folders. For starting purposes, you can start with an L1, with 128x64 dimensions. Inside this folder is where you will place your assets.

Animation Frames

For your Animation frames, you can often start from one of two avenues: making your own frame-by-frame animation by hand, with whatever graphics software of your choice, OR you convert an existing GIF into seperated frames to work with. When you Save these frames to a folder, make sure to use the following naming scheme: Frame_[ number sequence, starting with 0 ].[ png|jpg ].

⚠️ For Converting GIFs into seperate frames, I found ezGif to be a simple solution.

Once you have your assets, you need to create a file in your current directory, called meta.txt

Animation Configuration

Here is an example of what a meta.txt config could look like:

Filetype: Flipper Animation
Version: 1

Width: 128
Height: 64
Passive frames: 13
Active frames: 2
Frames order: 0 1 0 2 3 3 4 0 1 5 6 1 1 7 8
Active cycles: 2
Frame rate: 2
Duration: 3600
Active cooldown: 5

Bubble slots: 1

Slot: 0
X: 5
Y: 28
Text: Predictable twist
AlignH: Right
AlignV: Bottom
StartFrame: 14
EndFrame: 16

These configuration paraeters dictate how you want your animation to behaves. Here's a breakdown on what these keys mean in relation to your animation:

  • Width

    • This is the width of your animation frame. The max is usually 128 (in pixels, but you omit the unit) since that is the size of the flipper display.

  • Height

    • This, like the width, is the height of the animation frame. The max height is 64.

  • Passive frames

    • These are the sum of frames which will look on your flipper while idle. Often this sum startes as the beginning of your Frame Order.

  • Active frames

    • When you interact with your Flipper, or simply wake the device, this sequence will play, and is often noted after your passive frames in your Frame Order.

  • Frames order

    • In order to better establish you Passive and Active Frames, it may be easier to note a Frame order first. The format for frame order is simply the Frame name ID (the number in the filename after 'Frame_'), followed by a space.

    Here is a visual breakdown of a Frames Order example of an animation with 5 passive frames, and 10 active frames: [0 1 2 0 1] [2 3 4 5 6 7 8 9 10 11].

  • Active cycles

    • If you are using Active Frames, this is the number of times it will loop your Active Frames before going back to the Passive Frames and looping those again. If you are just using Passive Frames, you can leave this at 1 and you’re good. The default value for this is 1

  • Frame rate

    • This is pretty self explanatory, but like mentioned above, its usually best to keep this at 12. You may, however, use something like 2, but anything faster than 24 will look distorted.

  • Duration

    • This one is a little tricky, but you can use this tool to calculate the duration value. Usually for a 26 frame animation at 8fps, the duration will be 3250. This value is in milliseconds.

  • Active cooldown

    • Number of seconds after entering Passive Mode before the Active Frames can be triggered again. If you set it at 30, once your Active Cycles concludes, it will take this number of seconds before they can play again from Passive Mode. For example, if you Active animation just looped back to Passive Frames, it will take 30 seconds before you can trigger the Active Frame sequence again.

Bubble Slots (Optional)

If you're not including any speech bubbles, set this value to 0.

However if you ARE including some speech bubbles, include the amount bubbles you will list below. Bubbles these have their own included parameters:

  • Slot
    • You can have multiple bubble slots which separate different sets of bubbles. For now, you can only have ONE speech bubble in your passive frames, so if you plan to have speech bubbles during both passive and active frames, you’ll need at least 2 slots. Bubbles in the same slot will play in order (unless you’re trying to put more than 1 bubble in a passive sequence which won’t work at this time) based on your start and end times.
  • X & Y
    • This position is relative to the top left corner of the bubble. It's advisable that using 0 as either value will produce bad results.
  • Text
    • Pretty self explanatory. This can be passed as a string without quotes, even if you need to add line breaks, you can do so by calling \n when you need to break.
  • AlignH
    • Each bubble has a "tail", and can be positioned in a few ways. Here we choose where we would place that tail horizontally. The accepted values are: [Left, Center, Right]
  • AlignV
    • Here we decide where that tail would live vetically. The accepted values are: [Top, Center, Bottom]
  • StartFrame
    • Choose when your bubble shows up in your animation. You can reference the values you made in Frames Order.
  • EndFrame
    • Choose when your bubble disappears from the screen.

Manifest

Last but not least, you will now neet to add your animation as an entry in the manifext.txt located on the root of the /external directory which all your assets live in. You'll notice that the files for all the other default animations are listed here, so if you get lost in what things mean, or how to note a value, you can reference an existing entry. Suffice it to say, your entry will look a little something like this:

Name: [ THE NAME OF YOUR FOLDER ]
Min butthurt: 0
Max butthurt: 5
Min level: 1
Max level: 3
Weight: 5

And a quick explainer of what some of those parameters mean:

  • Min butthurt & Max butthurt
    • Butthurt levels go from 1-14. When Flipper is angry it will change its level of butthurt. If you want your animation to play regardless of Flipper’s butthurt level, you can include all the levels.
  • Min level & Max level
    • Your flipper has the capacity to "level up" through completing various tasks, like cloning, or utilizing various utilities thereof. The stock firmware has a max level of 3, however unofficial firmwares, such as RogueMaster has a max level of 30.
  • Weight
    • 4The Weight is how likely your animation is to show up. The higher the number the more likely your animation is to show up when Flipper randomly chooses which animation to play next. Currently we’re not quite sure that the max weight is, but higher is better.

As for placement, It doesnt matter at this point, since you wont be using that manifest when moving it over to your device.

Compiling Everything

Once your animation files are ready, and you have an entry in the manifest, we can now start compiling these files. The flipper executable in the repo converts the image frames into a binary format for the flipper to read. To start, navigate back to the root of the flipper repository, and open Powershell here. If you dont have the option to do so from your context menu, you can just open up Powershell and type Set-Location "[ WHEREVER YOU CLONED THE REPO ]\flipperzero-firmware", and that will set your directory as such. Now all thats left is to run the following command:

./fbt icons proto dolphin_internal dolphin_ext resources

If everything goes well (which it might not. see Troubleshooting), starting at the repo root, you will find your freshly-compiled folder in flipperzero-firmware/assets/resources/dolphin. This directory will contain a manifext.txt as well as the folder you created in /external.

Migrate to your flipper

Connect your flipper to your PC, and open up qFlipper. Click on the file tab on the top (3rd, or last tap),and naviage to sdcard > dolphin. Now you can drag your compiled folder into the directory inside qFlipper. Now inside qFlipper, scroll to the bottom, and find the manifext.txt file. Right-click and select download, and choose a location to place it in. Now navigate to that saved location, and copy your manifext entry into the one you just downloaded from the flipper. If I have an L1, I'll just scroll until I see the last L1, make a break and place it right after. Save the file, and drag it back into the dolphin directory on qFlipper. The dragged file will overwrite the existing one without any prompts, so if it seems like nothing just happened, something did happen.

Once you're done, unplug your Flipper, and reboot it. You can do so by holding the ( ↩ ) button and the ( ◀ ) at the same time for less than 3 seconds. You should now be able to see your new animation in one of your Flipper's screen idle cycles.

Troubleshooting

There's a highly likely chance that the compilation failed on your first try. IF that happens, however, fret not; It's more than likely and issue with either the meta.txt file, or manifext.txt.

Some common issues may include, but arent limited to:

  • Meta.txt
    • Invalid values on some of the parameters. Usually around the passive/active frames and the frame order.
    • Make sure your active & passive frames are a sum of your frame order. If you have bubbles included, make sure those start and end frame coincide with your frame order as well.
    • Active cycles breaks a bubbles endFrame value.
  • Manifest.txt
    • probably a type in the name. Make sure your folder name and the name param in the manifext match.
    • certain param value exceed allowed value (i.e. level or butthurt too high)

🔗ix.io Hyperlink

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment