Resources

• 1: What's new
• 2: Installation guide
• 3: Design guide
• 3.1: Gauges
• 3.2: Images
• 3.3: Indicators
• 4: Roadmap
• 4.1: Known issues
• 5: Controls
• 6: Scenes
• 7: Materials
• 8: Colors

1 - What's new

To download the latest version and get started, see the installation guide.

You can follow the development roadmap to see what features are planned for the upcoming releases and if there are any known issues.

What’s new in 0.1.0

• Sepiana 0.1.0 is the first public release of the Sepiana dashboard.
• Early access: This version is intended for testing the release process and providing a starting point for documentation. It is not production-ready and may contain bugs.
• Distributed as a Windows executable only (no installers or packages yet).
• The official documentation site, sepiana.com, is now live.

Key features:

• Create dashboards within a single “Atelier” scene.
• Change the dashboard’s base material and color.
• Add and configure gauges:
  • Connect gauges to Home Assistant data sources.
  • Customize gauge frame material, color, and face.
• Adjust camera settings, including position, focal length, and angle.
• Select scene lighting conditions from preset values.

2 - Installation guide

The app is currently in an early development phase with very limited functionality and somewhat complex setup process. This is only for testing purposes and not intended for general use.

System requirements

You need the following

• Windows computer with a decent CPU/GPU
  • The app is created with a moderate gaming PC with Nvidia RTX 3060 GPU, so it should run on similar or better hardware.
• Home Assistant instance with real-time data access enabled

The app is created using Unreal Engine 5 and its performance may vary based on your hardware. If your computer can run modern Windows games, it should be able to run the app.

Install the app

Windows

1. Download the app the app for your platform
2. Extract the downloaded ZIP file to a folder of your choice e.g. C:\Sepiana
   • On Windows, you can use the built-in ZIP extraction tool or a third-party tool like 7-Zip.
3. Open the extracted folder and verify that you have the following files:
   • Sepiana.exe executable file (Windows)
   • /Engine folder
   • /Sepiana folder

4. Download the example configuration files from the GitHub repository and extract them to the C:\Sepiana\Config folder.
   • Alternatively, you can create your own configuration file from scratch, see the design guide for more information.
5. Create a shortcut to the Sepiana.exe file on your desktop or start menu for mandatory configuration parameters to be set up before running the app.
   • On Windows, right-click on the Sepiana.exe file and select Send to -> Desktop (create shortcut).
   • Edit the shortcut properties to add the -Config= parameter to the target field, e.g. C:\Sepiana\Sepiana.exe -Config=C:\Sepiana\Config\AtelierDemo.json
   • This will allow you to run the app with the specified configuration file and you can create as many configurations and shortcuts as you like.

Configure the app

The app requires a connection to a Home Assistant instance to display data. You can configure the connection and dashboard visualization settings as a JSON file in the app’s configuration folder. See the design guide for more information on how to create and configure the JSON file.

Setup Home-Assistant to allow access to real-time data

1. Install Home Assistant on your server or local machine.
2. Home Assistant has the Websocket API available by default, but you need to create a long-lived access token so that the app can connect to your stream.
   • Go to your Home Assistant user profile page (click on your user icon in the bottom left corner).
   • Go to “Security tab” and scroll down to the “Long-Lived Access Tokens” section.
   • Click on “Create Token” and give it a name (e.g., “Sepiana Access Token”).
   • Put that token in some safe place, as you will need to copy it to the app’s configuration file later.
   • In case of connectivity issues, please check the Home Assistant documentation.

Create Sepiana JSON file

1. Create a new JSON file in the app’s configuration folder (e.g., C:\Sepiana\Config\MyDashboard.json).
2. Use the example configuration files from Github as a template or create new file from scratch.
3. Learn how to create your own configuration file by following the design guide.

Run the app

1. Start the app from the shortcut you created earlier, or run the Sepiana.exe file with the -Config= parameter in the command line.
   • For example, C:\Sepiana\Sepiana.exe -Config=C:\Sepiana\Config\AtelierDemo.json

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

3.1 - Gauges

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.

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.

Full Gauge

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.

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.

3.2 - Images

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.3 - Indicators

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.

4 - Roadmap

This roadmap is a living document that will be updated when there is something to update. The roadmap is subject to change based on user feedback, technical challenges, and other factors. Share your feedback and ideas - you may have the power to change the content for the upcoming releases.

Runtime features

• support for macOS (Apple Silicon)
• Autoupdate functionality to ensure that users are always using the latest version of the app

Scene

• Add more interesting scene as the base for the dashboard.
• Ability to change scene light conditions (day/night, direction etc.)

Dashboard

• Different shapes for the dashboard, so that user can choose the shape that fits their design.

Gauge

• Ability to set GlassModel and GlassMaterial for gauges
• Add gauge decoration elements like screws, bolts.

Image

• Ability to add images to the dashboard
• Ability to set image size and position

Indicator

• Ability to add indicators to the dashboard
  • Show Home Assistant binary state (on/off) as a simple LED light

Camera

• Ability to set static camera positions in configuration file, so that the app can switch between different camera angles with some shortcuts or some other mechanism.
• Reconfigure camera control to use same controls as typically used in-game photomodes.
• Add screencapture button or shortcode to take screenshots of the dashboard
• Camera shake effect for more realistic feel
• Add camera effects like bloom, vignette, etc.

Toggle

• Ability to add toggle switches to the dashboard, so that the app can use Home Assistant API to control connected devices. This is probably something that will be done “when everything else is done” as it requires more complex Home Assistant API integration.

4.1 - Known issues

This page lists known issues with Sepiana. Please, send a bug report when you find a bug or an issue that is not listed here.

5 - Controls

Mouse controller

• Left click - Focus on the visualisation element

Keyboard controller

• ESC - Exit the app
• W, A, S, D - Move the camera
• Q, E - Move the camera up and down
• I - Zoom in
• O - Zoom out
• L - Switch between different light modes

Gamepad controller

6 - Scenes

All Sepiana scenes are premade with a purpose to be used as a theme and environment for your dashboards. At the moment it is not possible to create your own scenes or modify existing ones.

Atelier

The Atelier scene is designed to provide a cozy and creative workspace environment for inspiration. It features warm lighting, wooden textures, and various artistic elements that inspire creativity.

Available dashboard identifiers

• s-square
• s-landscape
• m-square
• l-portrait

7 - Materials

Sepiana supports a variety of materials that can be used to create a unique and visually appealing dashboard. These materials can be combined with any color to create a custom look and feel.

“Aluminium”

The “Aluminium” material is a smooth and shiny material that mimics the look of brushed aluminium. It is often used for dials, switches, and other metallic elements.

“CarPaint”

The “CarPaint” material is a highly reflective and glossy material that mimics the look of classic car paint.

“Chrome”

The “Chrome” material is a highly reflective and shiny material that mimics the look of chrome plating. It is often used for dials, switches, and other metallic elements.

“Leather”

The “Leather” material is a textured material that mimics the look and feel of leather.

“Plastic”

The “Plastic” material is a smooth and glossy material that mimics the look of plastic.

8 - Colors

Note: The colors listed below are examples collected using AI-based methods and may not be accurate. The colors below are examples of colors used in classic cars from the 1960s to the 1970s. The hex codes are provided for reference, but they may not match the exact color used in the car. You are not limited to these colors, and you can use any color you like in your designs. The colors are provided as a reference for inspiration and to help you create a visually appealing dashboard.