Design guide

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.

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.

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:

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.

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.

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.

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.