This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Design guide

Learn how to design your own dashboard, create custom gauges, and configure the app’s settings.

Use the following pages to learn how to design your own dashboard, create custom gauges, and configure the app’s settings.

Best practices

Pen and paper

The app doesn’t yet have a built-in design editor, so you will need to create your dashboard configuration in a text editor (JSON configuration file). Before you start configuring JSON files, take a pen and a paper and draft a rought layout of your planned dashboard. This will help you to visualize the layout and placement of elements before you start configuring.

Pen and paper

For example, if the demo board is 1000 x 500 millimeters (or 1000 x 500 pixels if you prefer that unit). This means that you can place elements anywhere on the board, but you should keep in mind the size and placement of each element. A standard gauge is 100 x 100 millimeters, so you can fit 10 gauges side by side on the board on a single row.

Sepiana configuration file is a JSON file that contains all the information about the dashboard, including the gauges, their positions, and other settings.

You must manually create and maintain this configuration file (and make backups!). The app does not - at least for now - provide a graphical user interface for editing the configuration.

We will gradually add in-app editing options, but dont’ hold your breath, as we must first implement the basics and get the app to beta-level functionality.

Folder structure

You can create a folder structure to organize your dashboards and their configuration files. This will help you to keep track of your designs and make it easier to manage multiple dashboards.

You can use a separate folder for each dashboard, which contains the configuration file and the gauge face images. This may result in duplicate gauge face images if you use the same images in multiple dashboards, but it keeps the dashboard configuration files separate and easy to manage.

Application folder/
├── Your dashboard A/
│   ├── Config.json
│   └── Gauges/
├── Your dashboard B/
│   ├── Config.json
│   └── Gauges/
├── Your dashboard C/
│   ├── Config.json
│   └── Gauges/

Or you can use a single folder for all your dashboards and reuse the gauge face images across multiple dashboards. This will result in a single configuration file for each dashboard, but it may be harder to manage if you have many dashboards.

Application folder/
└── Dashboards/
    ├── Config A.json
    ├── Config B.json
    ├── Config C.json
    └── Gauges/

Backup, backup, backup

Take backups of your configuration file along with the face images and other resources. The app shouldn’t corrupt the files as they are handled as read-only, but as the app is still in early development - and you may want to create and try different designs - it is a good idea to take backups of your configuration file and resources. This way you can always revert to a previous version if something goes wrong.

Design elements

The Sepiana dashboard is built using various design elements that can be combined to create a visually appealing and functional interface. Each element serves a specific purpose and can be customized to fit your needs. Below is a list of the main design elements available in Sepiana:

Element Description
Level Level is the base or scene to where other elements can be attached. As an example, a plank board of plane or an empty surface on a car dashboard.
Gauges Gauge is the most important visualization element for numerical data. This is your traditional analog gauge to show values in clear and visually interesting ways.
Indicators Indicator is a visual element that shows the state (true/false, on/off) of a device or a system.
Images Image is a visual element that can be used to display a logo, a picture, or any other visual content. It can be used to enhance the visual appeal of the dashboard or to provide additional context to the data being displayed.

Note that texts are part of elements (where supported) and are not separate elements. Texts can be used to provide additional context to the data being displayed, and their placement is specific to the element. See element specifications for supported texts and placements.

Units

All measurement units are in millimeters - in case you don’t speak metric system, you can think millimeters as pixels (the end result will be the same).

Coordinates

Sepiana uses a coordinate system where the origin (0,0) is the center point of the dashboard. The X and Y coordinates are used to position the gauges, indicators, toggles, and images on the dashboard. The coordinate always denotes the position of the element’s center point, so you can use negative values to position the element to the left or below the center point.

Example configuration file

The file is structured as follows:

{
  "Version": "1.0",
  "HomeAssistant": {
    "Url": "ws://0.0.0.0:8123/api/websocket",
    "Token": "eyJhbG.............PuEn0wJw"
  },
  "Scene": {
    "Name": "Atelier",
    "Description": "A collection of dashboards showcasing various materials and gauges in an old-school atmosphere."
  },
  "Dashboards": [
    {
      "Identifier": 1,
      "Name": "IT Room",
      "Description": "Show various CPU, memory, and temperature metrics from the Home Assistant and Unifi system.",
      "Theme": {
        "AccentColor": "#d4001a",
        "BoardMaterial": "Aluminium",
        "BoardColor": "#ccddee"
      },
      "Gauges": [
        {
          "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": "Frame-A-100mm",
          "FrameMaterial": "Aluminium",
          "FrameColor": "#ffffff",
          "Face": "percentage_full_0_100_30_330.png",
          "Value": "sensor.unifi_cpu_utilization_2",
          "TextUp": "Unifi CPU",
          "X": 0,
          "Y": 100,
          "Recessed": 20
        },
        {
          "FrameModel": "Frame-A-100mm",
          "FrameMaterial": "Aluminium",
          "FrameColor": "#ffffff",
          "Face": "percentage_full_0_100_30_330.png",
          "Value": "sensor.synology_cpu_utilization_total",
          "TextUp": "Synology CPU",
          "X": -150,
          "Y": 100,
          "Recessed": 20
        },
        {
          "FrameModel": "Frame-A-50mm",
          "FrameMaterial": "Chrome",
          "FrameColor": "#ffffff",
          "Face": "percentage_full_0_100_30_330.png",
          "Value": "sensor.home_assistant_core_memory_percent",
          "TextUp": "HA Mem",
          "X": 150,
          "Y": 0,
          "Recessed": 0
        },
        {
          "FrameModel": "Frame-A-50mm",
          "FrameMaterial": "Chrome",
          "FrameColor": "#ffffff",
          "Face": "percentage_full_0_100_30_330.png",
          "Value": "sensor.unifi_memory_utilization_2",
          "TextUp": "Unifi Mem",
          "X": 0,
          "Y": 0,
          "Recessed": 10
        },
        {
          "FrameModel": "Frame-A-50mm",
          "FrameMaterial": "Chrome",
          "FrameColor": "#ffffff",
          "Face": "percentage_full_0_100_30_330.png",
          "Value": "sensor.synology_memory_usage_real",
          "TextUp": "Synology Mem",
          "X": -150,
          "Y": 0,
          "Recessed": 10
        },
        {
          "FrameModel": "Frame-A-50mm",
          "FrameMaterial": "Chrome",
          "FrameColor": "#ffffff",
          "Face": "temperature-w-0-100_full_0_100_30_330.png",
          "Value": "sensor.unifi_cpu_temperature",
          "TextUp": "Unifi Temp",
          "X": 0,
          "Y": -60,
          "Recessed": 10
        },
        {
          "FrameModel": "Frame-A-50mm",
          "FrameMaterial": "Chrome",
          "FrameColor": "#ffffff",
          "Face": "temperature-w-0-100_full_0_100_30_330.png",
          "Value": "sensor.synology_temperature",
          "TextUp": "Synology Temp",
          "X": -150,
          "Y": -60,
          "Recessed": 10
        }
      ]
    }
  ]
}

Configuration file structure

Version

The Version field indicates the version of the configuration file format. This helps in maintaining compatibility with future updates.

HomeAssistant

The HomeAssistant object contains the connection details for your Home Assistant instance:

  • Url: The WebSocket URL of your Home Assistant instance (e.g., ws://IP.ADDRESS.HERE:8123/api/websocket).
  • Token: Your long-lived access token for Home Assistant. You can create this token in your Home Assistant user profile under the “Security” tab.

Scene

The Scene object contains the name and description of the scene. This is used to provide context for the dashboards and can be displayed in the app. The name must match the available scene name in the app as it will be used to load the 3D scene/map.

  • Name: The name of the scene (e.g., “Atelier”). At the moment “Atelier” is the only available scene, but more scenes will be added in the future.
  • Description: A brief description of the scene (e.g., “A collection of dashboards showcasing various materials and gauges in an old-school atmosphere.”).

Dashboards

The Dashboards array contains all the dashboards you want to create. Each dashboard can have multiple gauges, indicators, toggles, and images.

Dashboard designs are transferrable between different levels, so you can create a dashboard in the default level and then move it to another level later.

Identifier

The Identifier field is a unique identifier for the dashboard within the scene. This is used to differentiate between multiple dashboards in the scene. The identifier must match the available dashboard identifier in the app as it will be used to load the dashboard design, and assign to correct dashboard placeholder.

To make your dashboard designs easily transferable between different levels, use the identifiers listed below. Each identifier corresponds to a specific dashboard size, ensuring your design will fit properly in any supported scene.

Identifier Width (mm) Height (mm) Aspect Ratio Aspect Ratio Description
s-square 500 500 1:1 Square
s-landscape 1000 500 2:1 Landscape
s-portrait 500 1000 1:2 Portrait
m-square 1000 1000 1:1 Square
m-landscape 1500 1000 3:2 Landscape
m-portrait 1000 1500 2:3 Portrait
l-square 1500 1500 1:1 Square
l-landscape 2000 1500 4:3 Landscape
l-portrait 1500 2000 3:4 Portrait
xl-square 2000 2000 1:1 Square
xl-landscape 2500 2000 5:4 Landscape
xl-portrait 2000 2500 4:5 Portrait

These identifiers may not be available in all scenes, so you should check the available identifiers in the scene design. Technically a scene may have multiple dashboard with the same size - in that case the scene design will inform the postfix to use in the identifier, e.g. s-square-2, s-square-3, etc.

Note that you can always use smaller design on a larger dashboard because the app will automatically center the design on the dashboard. Larger designs on a smaller dashboard will cause visualisation elements to float in the air (the app doesn’t enforce correct sizing - at least not yet).

Name

The Name field is a descriptive name for the dashboard. This is used to identify the dashboard in the app - and it may be displayed on the dashboard itself.

Description

The Description field is a brief description of the dashboard. This can be used to provide additional context or information about the dashboard. Description is not shown on the dashboard, but it may be shown in menus.

Theme

The Theme object contains the theme settings for the dashboard. This allows you to customize the look and feel of your dashboard.

AccentColor

The AccentColor field is the primary accent color of the dashboard in hexadecimal format (e.g., 0xFF0000 for red). For now, the color is used only in gauge pointer, but in the future it may be used in other elements as well.

BoardMaterial

The BoardMaterial field defines the material of the dashboard board. See available materials in the materials section.

BoardColor

The color of the dashboard material in hexadecimal format. This allows you to change the color of the dashboard material (if applicable for the material) to match your preferences. You can find some inspiring colors in the colors guide.

Gauges

Gauges: An array of gauge objects, each representing a gauge on the dashboard. See gauge design guide for more details on how to create and configure gauges.

Images

Images: An array of image objects, each representing an image on the dashboard. See images design guide for more details on how to create and configure images.

Indicators

Indicators: An array of indicator objects, each representing an indicator on the dashboard. See indicators design guide for more details on how to create and configure indicators.

1 - 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.

2 - Images

Learn how to design and implement images in Sepiana, including image formats and usage.

Images are not yet available. This page serves as a placeholder on how to design and implement images in Sepiana.

Images are visual elements that can be used to display stickers, logos, pictures in your dashboard. They can enhance the visual appeal of the dashboard or provide additional context to the data being displayed.

Image format

Images must be in Alphatransparent PNG format. The recommended size is 2048x2048 pixels, but the app does not enforce this size or aspect ratio. You can use any size that fits your design, but keep in mind that larger images may affect performance.

3 - Indicators

Learn how to design and implement indicators in Sepiana, including their visual representation and usage.

Indicators are not yet available, and needs further design how indicators should look like and how they should behave. The current design assumption is that indicators are simple on/off LED lights that shows binary value/state from Home Assistant.

This page serves as a placeholder for future documentation on how to design and implement indicators in Sepiana.

Indicators are visual elements that represent the state of a device or system, typically in a binary manner (true/false, on/off). They can be used to provide quick visual feedback about the status of various components in your dashboard.