Gauges

Learn how to design and implement gauges in Sepiana, including frame models, materials, and face images.

Gauges are the primary visual elements in Sepiana, allowing you to display real-time data from your Home Assistant instance. This guide will help you understand how to create and configure gauges for your dashboard.

  {
    "FrameModel": "Frame-A-100mm",
    "FrameMaterial": "Aluminium",
    "FrameColor": "#ffffff",
    "Face": "percentage_full_0_100_30_330.png",
    "Value": "sensor.home_assistant_core_cpu_percent",
    "TextUp": "HA CPU",
    "X": 150,
    "Y": 100,
    "Recessed": 10
  }

FrameModel

The FrameModel defines the type of gauge frame to use. This defines the shape and size of the bezel that holds the gauge face and glass. The frame models are predefined in the app. The face image will scale to fit the frame size.

  • “Frame-A-100mm”: 100mm diameter, simplified round frame.
  • “Frame-A-50mm”: 50mm diameter, simplified round frame.

For now the app supports only predefined frame models with predefined sizes. This is to ensure that the gauges fit well on the dashboard and to maintain a consistent look and feel. More dynamic frame models may be added in the future if that doesn’t complicate the design too much and still allows for a consistent look and feel.

FrameMaterial

See available materials in the materials section.

FrameColor

The FrameColor is a hexadecimal color value (e.g., #FF0000 for red) that defines the color of the frame. This allows you to customize the appearance of the gauge to match your dashboard’s theme.

Face

All face textures are .png files 2048x2048 pixels in size. The application handles the image files as a texture, so you can draw anything you like that fits into your dashboard design. The app doesn’t use alpha channels, so the images can be saved as 8-bit PNG files without transparency. The app doesn’t enforce 2048x2048 size, but it is recommended to use this size for consistency and to avoid scaling issues.

Creating your own gauge face might seem daunting, but it can be as simple as using templates. The template is a .svg file that you can edit in any vector graphics editor (e.g., Inkscape, Adobe Illustrator). The template includes guidelines for the gauge face, such as the range and degree markings.

The tricky part is to understand the naming convention for the face images. The image name is structured as follows:

<name> _ <type> _ <min> _ <max> _ <start> _ <end>.png

Where:

  • <name>: A descriptive name for the gauge face (this is just a filename, so can be anything you like to keep your files organized).

  • <type>: The type of gauge face, which must be one of the following:

    • “full”: Analog gauge with a full circle.

  • <min>: The minimum value of the gauge range. (integer)

  • <max>: The maximum value of the gauge range. (integer)

  • <start>: The starting degree of the gauge (0-360).

  • <end>: The ending degree of the gauge (0-360).

  • “example_full_0_100_0_360.png”: A gauge dial with a 0…100 range and 0-360 degrees.

  • “example_full_-30_40_60_330.png”: A gauge dial with a -30…40 range and 60-330 degrees.

It is critical to use the correct naming convention for the face images, as the app uses this information to render and rotate the pointer. If the naming convention is not followed, the gauge will not display correct values.

Full Gauge

Full 0°-360° gauge has a complete circle face and can display values in the range of 0-360 degrees. The pointer will rotate around the center of the gauge face.

Value

The Value field is the Home Assistant entity that the gauge will display. It must be a sensor entity that provides a numerical value. The app will automatically update the gauge when the value changes.

TextUp, TextDown

The TextUp and TextDown fields are optional text labels that can be displayed on the gauge. These texts can be used to provide additional context or information about the gauge value.

For the best quality, you should add your texts directly to the face image, so that you can control the font, size, and position of the text. The app will render the texts using the default font and size, which may not match the style of your face image.

Recessed

The Recessed field defines how much the gauge is recessed into the dashboard. This is measured in millimeters and can be used to create a more realistic look for the gauge. A value of 0 means the gauge is surface-mounted, while a positive value indicates how deep the gauge is recessed into the dashboard.

You can use negative values to create a surface-mounted gauge that is slightly raised above the dashboard surface, but be aware that this may not look good with all frame models.