Skip to content

Theme options

Jump to bottom
V0rT3x edited this page Oct 26, 2024 · 31 revisions

Fancygotchi Theme Configuration Guide

This document provides detailed instructions on how to structure and configure theme options for Fancygotchi plugins. It covers the required folder architecture, configuration files, and customizable options available for theme developers.

Theme Folder Structure

The theme folder must adhere to the following structure:


theme folder name (e.g.: cyber)
├── config folder
│   ├── [config-h.toml] or [config.toml]
│   ├── [config-v.toml]
│   └── resolutions folder (e.g.: 320x240)
│       ├── [config-h.toml]
│       └── [config-v.toml]
├── img folder
│   ├── bg folder 
│   │   ├── [background images files]
│   │   ├── [animated background gif images files]
│   │   └── [foreground images files]
│   ├── boot folder
│   │   └── [boot animation images file]
│   ├── face folder 
│   │   └── [face images files]
│   ├── friend_face folder 
│   │   └── [friend face images files]
│   ├── menu folder 
│   │   └── [menu images files]
│   ├── widgets folder 
│   │   └── widget folder (e.g.: bluetooth)   
│   │       └── [widget images files]
│   └── icons folder
│       └── [favicon.png]
├── fonts folder
│   └── [fonts files]
├── script folder
│   └── [scripts files .py or .sh]
├── [style.css]
└── [info.json]
  • Theme folder name: It is used as theme reference for the theme manager.
  • Configuration folder: The theme selector first checks for configuration files in the main config folder of the theme.
    • If there's only one .toml file in this folder, it uses that for all orientations.
    • If there are specific 'config-v.toml' and 'config-h.toml' files, it selects the appropriate one based on the rotation (vertical or horizontal).
    • If neither of the above cases apply, it looks for a configuration file in a size-specific folder (e.g., '800x480').
    • Within the resolution folder:
      • If there's only one .toml file, it uses that for both orientations.
      • If there are multiple files, it selects based on the orientation ('config-v.toml' or 'config-h.toml').
      • If no matching configuration file is found in any of these locations, it falls back to the default theme settings.
    • config-h.toml: This is the horizontal theme configuration file (for rotation 0 or 180).
    • config-v.toml: This is the vertical theme configuration file (for rotation 90 or 270).

Here's a non-exhaustive list of compatible displays and resolutions for Pwnagotchi:

  • Img folder: It contain all image used by the theme. It can contain, background, foreground, faces, icons or any customs images for the theme.
    • Icons folder: It can contain a favicon.png image used to customize the web browser favourite icon. It can contain custom icons for the theme.
    • Bg folder:
      • Contains background and foreground images files for all the resolutions.
      • Includes animated background gif images
    • Boot folder:
      • Contains the images files for the boot animation. The frames images type can be jpg, jpeg, bmp or png. The frames need to be numbered (e.g.: frame001, frame002, etc) or a single animated gif can be use instead of a set of frames.
    • Face folder:
      • Stores face images files used for the main Pwnagotchi face.
    • Friend_face folder:
      • Contains friend face images files for representing other Pwnagotchi devices.
    • Widgets folder:
      • Includes subfolders for each widget.
      • Each widget subfolder contains specific image files for that widget.
  • Fonts folder: It contain the custom fonts files for the theme.
  • style.css: This css file is use to change the web UI style.
  • info.json: This json file is use for the theme description. It can contain credit or any useful information about the theme configuration. Here an example of the info file:
{
  "author": "Author Name", 
  "version": "1.0.0", # The version of the theme
  "display": "displayhatmini", # Compatible displays with the theme
  "plugins": "memtemp.py, bt-tether.py", # List of pre-configured plugins
  "notes": "memtemp.py needs to be put in vertical mode" # Useful information about the theme
}

General options

This start with [theme.options].

  • screen_mode: Sets the default screen mode. Currently supports 'screen_saver' and 'terminal' mode. The 'auxiliary' mode is not available yet.

  • screen_saver: Defines what to display in screen saver mode. Default is 'show_logo' which displays the Fancygotchi logo.

  • second_screen_fps: Controls the refresh rate (frames per second) for the secondary screen. Default is 1 FPS.

  • second_screen_webui: Enable/disable second screen on the web UI. Default is False.

  • bg_fg_select: Controls background/foreground selection mode. Set to manu for manual selection. In manual mode, the image name should be specified. If the auto mode, the program will check for a fg.png or bg.png image in the theme image folder.

  • bg_mode: Controls how background images are displayed. Available modes:

    • normal: Display at original size
    • stretch: Stretch to fill screen
    • fit: Scale to fit while maintaining aspect ratio
    • fill: Fill screen, may crop image
    • center: Center image on screen
    • tile: Repeat image in a tiled pattern

  • fg_mode: Controls how foreground elements are displayed. Uses same modes as bg_mode:

    • normal: Display at original size
    • stretch: Stretch to fill screen
    • fit: Scale to fit while maintaining aspect ratio
    • fill: Fill screen, may crop image
    • center: Center image on screen
    • tile: Repeat image in a tiled pattern

  • fg_image (WIP): Foreground image name.

  • bg_color: Background colour. The colour can be a name colour, hexadecimal or RGBA colour tuple.

    • colour name (e.g.: 'lime')
    • hexadecimal colour (e.g.: '#FFFFFF')
    • RGBA tupple (e.g: [0,0,0,0])
      • [0,0,0,0] = fully transparent
      • [0,0,0,255] = full opacity

  • bg_image: Background image name.

  • bg_anim_image: Animated background gif name.

  • boot_animation: This is to enable or disable the boot animation. The boot animation colour mode is defined by the color_mode = ['P','P'] option and its orientation is defined by the Fancygotchi rotation in the /etc/pwnagotchi/config.toml (main.plugins.Fancygotchi.rotation = 0)

    • boot_max_loops: This is to adjust how many time the animation will be repeated.
    • boot_total_duration: This is to adjust how long the animation should take.

  • font_sizes: Font sizes in this order: [Bold, BoldSmall, Medium, Huge, BoldBig, Small]

  • Fonts options:

    • If a file extension is provided, the font file will be sourced from inside the theme's fonts folder.
    • If there is no file extension specified, the system's default font files will be used.
    • If the configuration value is an empty bracket, the default fonts will be used.

  • font: The UI general font.

  • font_bold: The UI general bold font.

  • status_font: The status font.

  • font_awesome: The font awesome file use for UI icons.

  • label_spacing: General label space.

  • size_offset: Status font offset.

  • cursor: Cursor symbol.

  • friend_bars: Friend bar gauge symbol.

  • friend_no_bars: Friend missing bar gauge symbol.

  • main_text_color = ['color1', 'color2']: The main text colour configuration determines the colour that will be applied to all widget elements.

    • If more than one colour is specified in the list, the text colour will cycle through the colours in the list.

  • color_mode = ['P','P']:

    • The first input in the list specifies the color mode for web images.
    • The second input in the list specifies the color mode for hardware output.
    • It accepts PIL colour mode values:
      1. 1: 1-bit pixels, black and white, stored with one pixel per byte.
      2. L: 8-bit pixels, grayscale.
      3. P: 8-bit pixels, mapped to any other mode using a color palette.
      4. RGB: 3x8-bit pixels, true color.
      5. RGBA: 4x8-bit pixels, true color with transparency mask.
      6. CMYK: 4x8-bit pixels, color separation.
      7. YCbCr: 3x8-bit pixels, color video format.
      8. LAB: 3x8-bit pixels, Lab color space.
      9. HSV: 3x8-bit pixels, Hue, Saturation, Value color space.
      10. I: 32-bit signed integer pixels.
      11. F: 32-bit floating-point pixels.

Default theme option configuration

[theme.options]
boot_animation = false
boot_max_loops = 1
boot_total_duration = 1
screen_mode = "screen_saver"
screen_saver = "show_logo"
second_screen_fps = 1
second_screen_webui = false
bg_fg_select = "manu"
bg_mode = "normal"
fg_mode = "normal"
fg_image = ''
bg_color = 'black'
bg_image = ''
bg_anim_image = ''
font_sizes = [10, 8, 10, 25, 25, 9]
font = 'DejaVuSansMono'
font_bold = 'DejaVuSansMono-Bold'
status_font = 'DejaVuSansMono'
font_awesome = ''
size_offset = 5
label_spacing = 9
cursor = '❤'
friend_bars = '▌'
friend_no_bars = '│'
main_text_color = ['lime']
color_mode = ['P', 'P']

Theme options example from cyber theme

[theme.options]
stealth_mode = false
fg_image = ''#'320x240hs.png'
bg_color = 'black'
bg_image = "320x240e-t-g.png"
bg_anim_image = "320x240matrix.gif"
# Bold, BoldSmall, Medium, Huge, BoldBig, Small
font_sizes = [10, 8, 10, 55, 25, 9]
font = 'DejaVuSansMono'
font_bold = 'DejaVuSansMono-Bold.ttf'
status_font = 'DejaVuSansMono'
font_awesome = 'font-awesome-solid.otf'
label_spacing = 9
size_offset = 5

cursor = '❤'
friend_bars = '>'#'▌'
friend_no_bars = '│'

# if the full color or animated full color is enabled
# the main color will have priority on all text color
main_text_color = []

# To define which type of image will be saved 
# 1, L, P, RGB, RGBA, LAB,...
color_mode = ['P', 'P']

Development options

This start with [theme.dev].

  • refresh: Specifies the frequency at which animated background frame the theme will refresh.

    • -1: The theme refresh is turned off.
    • 0 or positive integer: The theme will refresh every specified number of frames.

  • log: Determines whether prompt logging is enabled.

    • true: Prompt logging is enabled.
    • false: Prompt logging is disabled.

  • debug: Determines if the messages log are shown in the regular log or only in debug mode.

    • true: Debug mode is enabled, log only appear in the debug log.
    • false: Warning mode is enabled, log is appearing in the regular log as warnings.
[theme.dev]
# Which frame the theme will refresh
refresh = -1

# if prompt log or not
log = true

# Show log
# true = debug
# false = warning
debug = false

Widget options:

This start with [theme.widgets]. If there is no custom widgets options, Fancygotchi will use the default value front the pwnagotchi UI and allocate defaults value for custom options.

General widget options

Every widget can have those basic options.

  • position = []:
    • [x,y] for Text, LabeledValue and bitmap.
      • Numeric values are treated as direct pixel positions
      • Negative values are interpreted as offsets from the right or bottom edge
      • String expressions are evaluated using the keyword mapping and safe evaluation. A math formula can be used ((),+,-,/,*)

        • top, bottom edges of the screen for the y axis.

        • right, left edges of the screen for the x axis.

        • center of the screen for x and y axis.

        • height for the screen's height.

        • width for the screen's width.

        • h for the widget's height.

        • w for the widget's width.

        • Example of a complex positioning: position = ["center - w/2", "bottom - h - 5"]

        • If one value need "", every values need to have "" as well.

    • [x,y,w,h] for Line, rect and filledrect.
      • The x and y represent the top-left corner of an element.
      • The w (width) and h (height) define the element's dimensions (It handles percentage-based dimensions, converting them to pixel values based on the screen width and height).
  • color = []: The color configuration determines the colour that will be applied to this widget elements.
    • If more than one colour is specified in the list, the text colour will cycle through the colours in the list.
  • z_axis: This option is used to sort widget on the canvas.
    • Higher z-axis values place elements on top of those with lower values.
    • Widgets with negative z-axis values are removed from the drawing list.
    • When stealth mode is enabled, widgets with z-axis values below 100 are not drawn.

Text & LabeledValue

  • text_font: A custom font can be use for this specific widget.
  • text_font_size: A custom font size can be use for this specific widget.
  • size_offset: A custom font offset can be use for this specific widget.
  • icon: true or false
    • for Text: It will can be used to enable the custom face image, the custom friend_face image (WIP) or a random custom aps image (WIP).
    • for LabaledValue: It will be use to enable the custom label icon (for images or font awesome icons). The label will be used as reference for the custom icon source. (If an image is used, the label should contain the image name from the /themes/theme_name/img/widgets/widget_name/: label = "image.png". If font awesome is used, the label should contain the character reference: label = "f293")
  • icon_color: If it is enabled, the icon will be tinted with the color.
  • invert: It it is enabled, the icon colour will be inverted.
  • alpha: If it is enabled, the light to white will become transparent.
  • mask: If it is enabled, the visible layer of the image will become a one colour mask.
  • refine: The factor used for zoom and mask cut.
  • zoom: The factor used to resize the icon image.
    • 1: The image stay at the same size.
    • under 1: The image is smaller.
    • over 1: The image is bigger.
  • image_type: The image extension use. By default it is png.

Text

  • wrap: If the text need to wrap or will be cut.
  • max_length: Define the text length of the widget.

Blank Text widget configuration:

# custom text
[theme.widgets.widget_name]
position = [0, 0]
color = ["#000000", "#FFFFFF"]
z_axis = 0
text_font = ""
text_font_size = 0
size_offset = 0
icon = false
icon_color = false
alpha = false
mask = false
refine = 150
zoom = 1
image_type = "png"
wrap = false
max_length = 0

LabeledValue

  • label: This option is used to customize the label. It can be a text, an icon name (e.g.: label = "image.png"), or a font_awesomesymbol code (e.g.:label = "f293"`).
  • label_font: A custom font can be use for this specific widget label.
  • label_font_size: A custom font size can be use for this specific widget label.
  • label_spacing: Spacing between the label and the text of this specific widget. The value can be negative.
  • label_line_spacing: Vertical spacing between the label and the text of this specific widget. The value can be negative.
  • f_awesome: If it is enabled, the label will use font_awesome. The symbol code is contained into the label value (e.g.: label = "f293"). The icon option need to be enabled to use the font awesome feature.
  • f_awesome_size: A custom font awesome size can be use for this specific widget label.

Blank LabeledValue widget configuration:

# custom labeled_value
[theme.widgets.widget_name]
position = [0, 0]
color = ["#000000"]
z_axis = 0
text_font = ""
text_font_size = 0
size_offset = 0
icon = false
icon_color = false
alpha = false
mask = false
refine = 150
zoom = 1
image_type = "png"
label = ""
label_font = ""
label_font_size = 0
label_spacing = 0
label_line_spacing = 0
f_awesome = false
f_awesome_size = 0

Line

  • width: The line width.

Blank Line widget configuration:

# custom line
[theme.widgets.widget_name]
position = [0, 0, 0, 0]
color = ["#000000"]
z_axis = 0
width = 1

Bitmap

  • icon: If it is enabled, it will used a theme custom image instead of the original widget image.
    • The widget image subfolder can contain one image or multiple pair of images named with a number followed A and B. (e.g.: 1A.png and 1B.png)
      • If only one image is provided, that image will be used regardless of the active image state in the pwnagotchi.
      • If multiple images are provided, it need to respect the system logic.
        • Reference Image (A version):
          • The A version (e.g., 1A.png) serves as the reference image.
          • It corresponds to the original image from the defined widget in pwnagotchi.
          • Used to determine which custom B image should be loaded.
        • Custom Image (B version):
          • The B version (e.g., 1B.png) is the custom image provided by the theme.
          • It replaces the original widget image when the corresponding state is active.
        • Multiple States:
          • The system supports multiple numbered states (2A, 2B, 3A, 3B, etc.).
          • Each state pair (A and B) follows the same principle as the 1A and 1B images.
  • icon_color: If it is enabled, the icon will be tinted with the color.
  • alpha: If it is enabled, the light to white will become transparent.
  • invert: It it is enabled, the icon colour will be inverted.
  • mask: If it is enabled, the visible layer of the image will become a one colour mask.
  • refine: The factor used for zoom and mask cut.
  • zoom: The factor used to resize the icon image.
    • 1: The image stay at the same size.
    • under 1: The image is smaller.
    • over 1: The image is bigger.

Blank Bitmap widget configuration:

# custom bitmap
[theme.widgets.widget_name]
position = [0, 0]
color = ["#000000"]
z_axis = 0
icon = false
icon_color = false
alpha = false
mask = false
refine = 150
zoom = 1

rect

Rect has no special options.

Blank Rect widget configuration:

# custom rect
[theme.widgets.widget_name]
position = [0, 0, 0, 0]
color = ["#000000"]
z_axis = 0

filledrect

Filledrect has no special options.

Blank Filledrect widget configuration:

# custom filled_rect
[theme.widgets.widget_name]
position = [0, 0, 0, 0]
color = ["#000000"]
z_axis = 0
Clone this wiki locally