Main Module

The main dash module.

Provides factory functions for creating UI nodes, color utilities, multi-page management, and access to resource tables (fonts, images, telemetry) defined in the dashboard JSON configuration.

Every dash script must call dash.update() in its main loop to process input, run telemetry hooks, update timers, and render the frame.

local page = dash.Page()
page:set_background_color(0xFF000000)

local label = dash.Label(page, {
    x = 10, y = 10,
    text = "Hello, World!",
    font = dash.font.montserrat_24,
    text_color = 0xFFFFFFFF
})

while true do
    label:set_text(string.format("Uptime: %ds", dash.uptime() // 1000))
    dash.update()
end
dash.telemetry: Telemetries

Table of all telemetry objects. Keys are telemetry names, e.g. dash.telemetry.engine_rpm. Available telemetry depends on the connected simulation.

dash.font: table<string, any>

Table of all font handles defined in the dashboard JSON "fonts" section, e.g. dash.font.montserrat_24.

dash.image: table<string, any>

Table of all image handles defined in the dashboard JSON "images" section, e.g. dash.image.background.

dash.rgba(r: integer, g: integer, b: integer, a?: integer): (color: integer)

Create an ARGB color integer from individual components.

local red = dash.rgba(255, 0, 0, 255)       -- fully opaque red
local semi = dash.rgba(255, 255, 255, 128)   -- 50% transparent white
Parameters:

  • r (integer) – red component (0-255)

  • g (integer) – green component (0-255)

  • b (integer) – blue component (0-255)

  • a? (integer) – alpha component (0-255, 255 = opaque) (default: 255)

Returns:

color (integer) – color value in 0xAARRGGBB format

dash.rgb(r: integer, g: integer, b: integer): (color: integer)

Create an RGB color integer with full opacity. Equivalent to dash.rgba(r, g, b, 255).

local white = dash.rgb(255, 255, 255)  -- 0xFFFFFFFF
Parameters:

  • r (integer) – red component (0-255)

  • g (integer) – green component (0-255)

  • b (integer) – blue component (0-255)

Returns:

color (integer) – color value in 0xAARRGGBB format (always 0xFFRRGGBB)

dash.color(color: (integer | string)): (color: integer)

Convert a color value to an ARGB32 integer. Accepts an integer (passed through as-is) or a hex color string.

Supported string formats:

  • "#RGB" – each digit is expanded, e.g. "#F00" becomes 0xFFFF0000

  • "#ARGB" – 4 digits with alpha, e.g. "#8F00" becomes 0x88FF0000

  • "#RRGGBB" – 6 digits, full opacity

  • "#AARRGGBB" – 8 digits with explicit alpha

local c1 = dash.color(0xFFFF0000)   -- integer pass-through
local c2 = dash.color("#FF0000")    -- red, full opacity
local c3 = dash.color("#80FF0000")  -- red, 50% opacity
Parameters:

color ((integer | string)) – ARGB32 integer or hex color string

Returns:

color (integer) – color value in 0xAARRGGBB format

dash.update()

Update the dash display. Must be called repeatedly in the main loop to process input, run telemetry update hooks, advance timers, and render the current frame.

while true do
    -- update logic here
    dash.update()
end
dash.uptime(): (uptime: integer)

Get the time elapsed since the dash started.

Returns:

uptime (integer) – uptime in milliseconds

dash.get_page(index: integer): (page: dash.Page)

Get a page by its index. Pages are numbered starting from 1 in the order they were created.

Parameters:

index (integer) – page index (1-based)

Returns:

page (dash.Page) – the page at the given index

dash.get_current_page(): (page: dash.Page)

Get the currently active page.

Returns:

page (dash.Page) – the current page

dash.get_current_page_index(): (index: integer)

Get the index of the currently active page.

Returns:

index (integer) – current page index (1-based)

dash.change_page(index: integer)

Switch to a different page.

Parameters:

index (integer) – page index to switch to (1-based)

Dash Objects

class dash.Params

Base parameters for all dash object creation functions. These parameters are common to every node type and are inherited by all type-specific parameter classes.

Coordinate system: (0,0) is at the top-left corner of the parent. X increases to the right, Y increases downward. All coordinates and sizes are in pixels.

x: integer?

X coordinate relative to parent (default: 0)

y: integer?

Y coordinate relative to parent (default: 0)

width: integer?

width in pixels (default: 100)

height: integer?

height in pixels (default: 100)

align: string?

alignment within parent (default: “default”). One of “default”, “top_left”, “top_mid”, “top_right”, “bottom_left”, “bottom_mid”, “bottom_right”, “center_left”, “center_right”, “center”.

class dash.Object

Common base class for all dash node types (Page, Box, Label, Image, etc.). Every node inherits these methods. Type-specific methods are documented in each subclass.

Node tree: nodes form a parent-child hierarchy. Each node’s position is relative to its parent. Visibility is inherited – hiding a parent hides all its children.

Coordinate system: (0,0) is the top-left corner of the parent node. X increases rightward, Y increases downward.

set_position(self, x: integer, y: integer)

Set position relative to parent.

Parameters:

  • x (integer) – X coordinate in pixels

  • y (integer) – Y coordinate in pixels

get_position(self): (x: integer, y: integer)

Get position relative to parent.

Returns:

  • x (integer) – X coordinate

  • y (integer) – Y coordinate

get_x(self): (x: integer)

Get X position relative to parent.

Returns:

x (integer) – X coordinate

get_y(self): (y: integer)

Get Y position relative to parent.

Returns:

y (integer) – Y coordinate

set_size(self, w: integer, h: integer)

Set size.

Parameters:

  • w (integer) – width in pixels

  • h (integer) – height in pixels

resize(self, w: integer, h: integer, align?: string)

Resize this node while keeping a specified anchor point fixed. Unlike set_size, which only changes width/height and leaves the position unchanged, resize adjusts the position so that the chosen alignment point stays at the same screen coordinate. When called without an alignment argument, defaults to "top_left" (equivalent to set_size).

-- Shrink bar height while keeping bottom-left corner in place
bar:resize(bar:get_width(), new_height, "bottom_left")

-- Grow box from center
box:resize(200, 200, "center")

Alignment names are the same as for align_in_parent:

  • "top_left", "top_center" (or "top"), "top_right"

  • "center_left" (or "left"), "center", "center_right" (or "right")

  • "bottom_left", "bottom_center" (or "bottom"), "bottom_right"

Parameters:

  • w (integer) – new width in pixels

  • h (integer) – new height in pixels

  • align? (string) – alignment anchor point to keep fixed (default: "top_left")

get_size(self): (width: integer, height: integer)

Get size.

Returns:

  • width (integer) – width in pixels

  • height (integer) – height in pixels

get_width(self): (width: integer)

Get width.

Returns:

width (integer) – width in pixels

get_height(self): (height: integer)

Get height.

Returns:

height (integer) – height in pixels

set_visible(self, visible: boolean)

Set visibility. When a node is hidden, all its children are also hidden.

Parameters:

visible (boolean) – true to show, false to hide

get_visible(self): (visible: boolean)

Get visibility state.

Returns:

visible (boolean) – true if visible

set_parent(self, parent: dash.Object)

Re-parent this node to a different parent.

Parameters:

parent (dash.Object) – new parent node

get_parent(self): (parent: dash.Object)

Get the parent node.

Returns:

parent (dash.Object) – parent node

get_children(self): (children: dash.Object[])

Get all direct child nodes.

Returns:

children (dash.Object[]) – array of child nodes

set_telemetry_update_hook(
    self,
    update_rate: integer,
    callback: function,
    telemetryhandle: Telemetry,
    telemetryhandle2?: Telemetry,
    telemetryhandle3?: Telemetry,
    telemetryhandle4?: Telemetry,
    telemetryhandle5?: Telemetry
)

Register a telemetry update hook. The callback is invoked at the specified rate (times per second) whenever any of the watched telemetry values has changed. Up to 5 telemetry handles can be watched in a single hook.

The callback receives no arguments – read the telemetry values inside the callback using the handles you already have.

local rpm = dash.telemetry.engine_rpm
label:set_telemetry_update_hook(30, function()
    label:set_text(string.format("%d", rpm:value()))
end, rpm)

-- Watch multiple telemetry values
local speed = dash.telemetry.speed
local gear = dash.telemetry.transmission_gear
label:set_telemetry_update_hook(10, function()
    label:set_text(string.format("G%d %d km/h", gear:value(), speed:value()))
end, speed, gear)
Parameters:

  • update_rate (integer) – maximum check rate in Hz (times per second)

  • callback (function) – function called when any watched telemetry changes

  • telemetryhandle (Telemetry) – first telemetry handle to watch

  • telemetryhandle2? (Telemetry) – second telemetry handle (optional)

  • telemetryhandle3? (Telemetry) – third telemetry handle (optional)

  • telemetryhandle4? (Telemetry) – fourth telemetry handle (optional)

  • telemetryhandle5? (Telemetry) – fifth telemetry handle (optional)

align_in_parent(
    self,
    align: string,
    offset_x?: integer,
    offset_y?: integer
)

Align this node within its parent using a 9-point alignment grid. Sets position so that the chosen anchor point on this node matches the same anchor point on the parent, plus an optional pixel offset. For labels, also sets text alignment to match.

box:align_in_parent("center")
box:align_in_parent("bottom_right", -10, -10)

Alignment names:

  • "top_left", "top_center" (or "top"), "top_right"

  • "center_left" (or "left"), "center", "center_right" (or "right")

  • "bottom_left", "bottom_center" (or "bottom"), "bottom_right"

Parameters:

  • align (string) – alignment name (see list above)

  • offset_x? (integer) – horizontal pixel offset (default: 0)

  • offset_y? (integer) – vertical pixel offset (default: 0)

anchor_to(
    self,
    target: dash.Object,
    target_anchor: string,
    self_anchor: string,
    x_offset?: integer,
    y_offset?: integer
)

Position this node relative to a sibling using anchor points. Computes position so that self_anchor on this node is placed at target_anchor on the target node, plus an optional pixel offset. This is a one-time computation (not reactive to later changes).

-- Place label directly below a box with 5px gap
label:anchor_to(box, "bottom_left", "top_left", 0, 5)

-- Center label2 on top of label1
label2:anchor_to(label1, "center", "center")

Anchor names are the same as for align_in_parent.

Parameters:

  • target (dash.Object) – sibling node to anchor to (must share the same parent)

  • target_anchor (string) – anchor point on the target node

  • self_anchor (string) – anchor point on this node

  • x_offset? (integer) – horizontal pixel offset (default: 0)

  • y_offset? (integer) – vertical pixel offset (default: 0)

destroy(self): (count: integer)

Destroy this node and all its children. The node and its entire subtree are removed from the scene.

Returns:

count (integer) – total number of nodes destroyed (including children)

extend(self, defaults?: dash.Params): (class: table)

Create a new class derived from this node type. Supports OOP-style inheritance. Works on built-in types (e.g. dash.Box:extend()) and on previously extended classes for multi-level inheritance.

The optional defaults table provides default creation parameters for instances. Defaults are chained: child defaults fall through to parent defaults, so you only need to specify overrides.

If the derived class defines an init(self, parent, props) method, it is called automatically after the underlying C node is created. Use it to set up custom state and telemetry hooks.

Instances are created by calling the class table like a constructor: MyWidget(parent, props).

-- Define a custom widget
local TelemetryLabel = dash.Label:extend({
    font = dash.font.Bold_24,
    text_color = 0xFF00FF00
})

function TelemetryLabel:init(parent, props)
    self._telemetry = props.telemetry
    self._format = props.format or "%d"
    self:set_telemetry_update_hook(
        props.update_rate or 30,
        self.update,
        props.telemetry
    )
    self:update()
end

function TelemetryLabel:update()
    self:set_text(string.format(self._format, self._telemetry:value()))
end

-- Create an instance
local rpm = TelemetryLabel(page, {
    x = 10, y = 10,
    telemetry = dash.telemetry.engine_rpm,
    format = "%d RPM"
})
Parameters:

defaults? (dash.Params) – default creation parameters for instances of this class

Returns:

class (table) – a callable class table for creating instances

class dash.Page: dash.Object
class ctor dash.Page(background_image?: integer): dash.Page

Page node – the root container for a dash layout. Created with dash.Page() or dash.Page(image). Inherits all common methods from dash.Object.

A dashboard can have multiple pages. The first page created is shown initially. Use dash.change_page(index) to switch between pages.

-- Create two pages
local page1 = dash.Page()
page1:set_background_color(0xFF000000)

local page2 = dash.Page(dash.image.page2_bg)

-- Build UI on each page
dash.Label(page1, { x=10, y=10, text="Page 1", font=dash.font.main })
dash.Label(page2, { x=10, y=10, text="Page 2", font=dash.font.main })

-- Switch pages based on button input
while true do
    if dash.wheel.get_digital_input(1) then
        dash.change_page(2)
    end
    dash.update()
end

Create a new Page node.

Parameters:

background_image? (integer) – optional background image resource from dash.image

set_background_color(self, color: (integer | string))

Set background color of the page.

Parameters:

color ((integer | string)) – ARGB32 integer (0xAARRGGBB) or hex string (“#RGB”, “#ARGB”, “#RRGGBB”, or “#AARRGGBB”)

Other members:

Inherited from dash.Object: align_in_parent(), anchor_to(), destroy(), extend(), get_children(), get_height(), get_parent(), get_position(), get_size(), get_visible(), get_width(), get_x(), get_y(), resize(), set_parent(), set_position(), set_size(), set_telemetry_update_hook(), set_visible()

class dash.Box: dash.Object
class ctor dash.Box(parent: dash.Object, params: dash.Box.Params): dash.Box

Rectangular box node with fill color, border and rounded corners. Created with dash.Box(parent, params). Inherits all common methods from dash.Object.

Boxes are commonly used as backgrounds, containers, and dynamic elements like progress bars. Fill and border colors can be changed after creation; border width and corner radius are set at creation time.

-- Simple colored box with border
local box = dash.Box(page, {
    x = 10, y = 20, width = 100, height = 50,
    background_color = 0xFFFF0000,
    border_color = 0xFF000000,
    border_width = 2,
    border_radius = 5
})

-- Progress bar using nested boxes
local bar_bg = dash.Box(page, {
    x = 10, y = 80, width = 200, height = 20,
    background_color = 0xFF333333
})
local bar_fill = dash.Box(bar_bg, {
    x = 0, y = 0, width = 200, height = 20,
    background_color = 0xFF00FF00
})
-- Update width to show 75%
bar_fill:set_size(150, 20)

Create a new Box node.

Parameters:
class Params: dash.Params

Box creation parameters. Inherits all fields from dash.Params.

background_color: (integer | string)?

fill color (default: 0xffffff). ARGB32 integer or hex string.

border_color: (integer | string)?

border color (default: 0xffffff). ARGB32 integer or hex string.

border_width: integer?

border thickness in pixels (default: 0)

border_radius: integer?

corner radius in pixels (default: 0)

Other members:

Inherited from dash.Params: align, height, width, x, y

set_fill_color(self, color: (integer | string))

Set fill color.

Parameters:

color ((integer | string)) – ARGB32 integer (0xAARRGGBB) or hex string (“#RGB”, “#ARGB”, “#RRGGBB”, or “#AARRGGBB”)

set_border_color(self, color: (integer | string))

Set border color.

Parameters:

color ((integer | string)) – ARGB32 integer (0xAARRGGBB) or hex string (“#RGB”, “#ARGB”, “#RRGGBB”, or “#AARRGGBB”)

Other members:

Inherited from dash.Object: align_in_parent(), anchor_to(), destroy(), extend(), get_children(), get_height(), get_parent(), get_position(), get_size(), get_visible(), get_width(), get_x(), get_y(), resize(), set_parent(), set_position(), set_size(), set_telemetry_update_hook(), set_visible()

class dash.Label: dash.Object
class ctor dash.Label(self, parent: dash.Object, params: dash.Label.Params)

Text label node with configurable font, color and alignment. Created with dash.Label(parent, params). Inherits all common methods from dash.Object.

Two sizing modes:

  • Auto-size (default, no width given): the bounding rectangle is computed from the rendered text metrics. The position acts as an anchor point and text_align controls which edge stays fixed when the text content changes ("left" = left edge fixed, "right" = right edge fixed, "center" = centered on position).

  • Fixed-rect (width specified): the bounding rectangle has explicit dimensions. Text is rendered within the rect according to text_align. Use long_mode to control overflow behavior.

-- Auto-size label
local label = dash.Label(page, {
    x = 5, y = 10,
    text = "Hello",
    text_color = 0xFFFF0000,
    font = dash.font.montserrat_24
})

-- Fixed-rect label with right-aligned text
local label = dash.Label(page, {
    x = 100, y = 50, width = 200,
    text = "World",
    text_color = 0xFF00FF00,
    font = dash.font.montserrat_24,
    text_align = "right"
})

-- Telemetry display using OOP inheritance
local TelemetryLabel = dash.Label:extend({
    font = dash.font.Bold_24,
    text_color = 0xFF00FF00,
    update_rate = 30
})

function TelemetryLabel:init(parent, props)
    self._telemetry = props.telemetry
    self._format = props.format or "%d"
    self:set_telemetry_update_hook(
        props.update_rate or self.update_rate,
        self.update,
        props.telemetry
    )
    self:update()
end

function TelemetryLabel:update()
    self:set_text(string.format(self._format, self._telemetry:value()))
end

local rpm_label = TelemetryLabel(page, {
    x = 10, y = 10,
    telemetry = dash.telemetry.engine_rpm,
    format = "%d RPM"
})

Construct new label node

Parameters:
class Params: dash.Params

Label creation parameters. Inherits all fields from dash.Params.

When width is omitted the label uses auto-size mode: the bounding rectangle is computed from the rendered text metrics and text_align controls which edge stays fixed when text content changes.

When width is specified the label uses fixed-rect mode: text is rendered inside the given dimensions according to text_align.

text: string?

the displayed text (default: “”)

color: (integer | string)?

text color (default: 0x000000). ARGB32 integer or hex string.

text_align: string?

horizontal text alignment (default: “left”). One of “auto”, “left”, “center”, “right”.

font: any

font handle from dash.font, e.g. dash.font.montserrat_24. Fonts are defined in the dashboard JSON configuration.

Other members:

Inherited from dash.Params: align, height, width, x, y

set_text(self, text: string)

Set displayed text.

Parameters:

text (string) – label text

get_text(self): (text: string)

Get displayed text

Returns:

text (string) – Text that was previously set in constructor or by calling set_text

set_text_color(self, color: (integer | string))

Set text color.

Parameters:

color ((integer | string)) – ARGB32 integer (0xAARRGGBB) or hex string (“#RGB”, “#ARGB”, “#RRGGBB”, or “#AARRGGBB”)

set_text_align(self, align: string)

Set horizontal text alignment. In auto-size mode, controls which edge stays fixed when text changes. In fixed-rect mode, controls text position within the bounding rect.

Parameters:

align (string) – "left", "center", or "right"

get_text_align(self): (align: string)

Get current text alignment.

Returns:

align (string) – "left", "center", or "right"

set_autosize(self, autosize: boolean)

Enable or disable auto-size mode. When true (default when created without width), the label computes its size from the rendered text. When false, the label uses explicit width/height like other node types.

Parameters:

autosize (boolean) – true for auto-size, false for fixed-rect

get_autosize(self): (autosize: boolean)

Get the current sizing mode.

Returns:

autosize (boolean) – true if auto-size, false if fixed-rect

Other members:

Inherited from dash.Object: align_in_parent(), anchor_to(), destroy(), extend(), get_children(), get_height(), get_parent(), get_position(), get_size(), get_visible(), get_width(), get_x(), get_y(), resize(), set_parent(), set_position(), set_size(), set_telemetry_update_hook(), set_visible()

class dash.Image: dash.Object
class ctor dash.Image(parent: dash.Object, params: dash.Image.Params): dash.Image

Image display node. Created with dash.Image(parent, params). Inherits all common methods from dash.Object.

Displays an image resource defined in the dashboard JSON configuration. The node shows the portion of the source image that fits within the node’s width and height. Use the source offset methods to pan within a larger image – useful for sprite sheets, scrolling textures, or clipping effects (e.g. vertical bar indicators).

Mosaic repeat: when the node is larger than the source image, the image automatically repeats in a mosaic pattern to fill the entire node area. The first tile begins at the current source offset; all subsequent tiles repeat from the image origin (0, 0). This works with both color and alpha-only images.

Images in the JSON configuration can use the default format or "format": "alpha_only" for mask images (single-channel alpha).

local img = dash.Image(page, {
    x = 10, y = 20,
    image = dash.image.background
})

-- Mosaic: repeat a 16x16 tile across a 48x48 area (3x3 mosaic)
local mosaic = dash.Image(page, {
    x = 10, y = 80, width = 48, height = 48,
    image = dash.image.tile
})

-- Vertical bar effect: clip image by adjusting source Y offset
-- and position to reveal a portion based on a value (0-100)
local bar = dash.Image(page, {
    x = 50, y = 10, width = 30, height = 200,
    image = dash.image.bar_texture
})
local pct = 75  -- percentage to show
local hidden = math.floor(200 * (100 - pct) / 100)
bar:set_source_y(-hidden)
bar:set_position(50, 10 + hidden)
bar:set_size(30, 200 - hidden)

Create a new Image node.

Parameters:
class Params: dash.Params

Image creation parameters. Inherits all fields from dash.Params.

The node displays the portion of the source image that fits within the node’s width and height. Use set_source_x/set_source_y to pan within a larger source image (for sprite sheets or scrolling effects).

Mosaic repeat: when width or height exceeds the source image dimensions, the image automatically repeats in a mosaic pattern to fill the node.

image: any

image handle from dash.image, e.g. dash.image.background. Images are defined in the dashboard JSON configuration.

Other members:

Inherited from dash.Params: align, height, width, x, y

set_image(self, image: any)

Set the displayed image. Can be used to swap the image at runtime (e.g. switching icons based on state).

Parameters:

image (any) – image handle from dash.image, e.g. dash.image.background

set_source_x(self, offset_x: integer)

Set source X offset. Shifts the origin of the source image horizontally, panning the visible region within the node.

Parameters:

offset_x (integer) – X offset in pixels

set_source_y(self, offset_y: integer)

Set source Y offset. Shifts the origin of the source image vertically, panning the visible region within the node.

Parameters:

offset_y (integer) – Y offset in pixels

get_source_x(self): (offset_x: integer)

Get source X offset.

Returns:

offset_x (integer) – current X offset in pixels

get_source_y(self): (offset_y: integer)

Get source Y offset.

Returns:

offset_y (integer) – current Y offset in pixels

set_recolor(self, color: (integer | string))

Set alpha image recolor. Sets the color used when rendering alpha-channel-only images. Has no effect on color (non-alpha) images.

Parameters:

color ((integer | string)) – ARGB32 integer (0xAARRGGBB) or hex string (“#RGB”, “#ARGB”, “#RRGGBB”, or “#AARRGGBB”)

Other members:

Inherited from dash.Object: align_in_parent(), anchor_to(), destroy(), extend(), get_children(), get_height(), get_parent(), get_position(), get_size(), get_visible(), get_width(), get_x(), get_y(), resize(), set_parent(), set_position(), set_size(), set_telemetry_update_hook(), set_visible()

class dash.Line: dash.Object
class ctor dash.Line(parent: dash.Object, params: dash.Line.Params): dash.Line

Line node drawn between two endpoints. Created with dash.Line(parent, params). Inherits all common methods from dash.Object.

The line is defined by two points with 1-based indexing (point 1 and point 2). Line color can be changed after creation; line width and rounded caps are set at creation time.

local line = dash.Line(page, {
    x1 = 0, y1 = 0, x2 = 100, y2 = 100,
    color = 0xFFFF0000,
    line_width = 3,
    rounded = true
})
-- Move endpoint dynamically
line:set_point(2, 200, 50)

Create a new Line node.

Parameters:
class Params: dash.Params

Line creation parameters. Inherits all fields from dash.Params.

The line is drawn between two endpoints (x1,y1) and (x2,y2). These coordinates are relative to the node’s own position.

x1: integer?

X coordinate of first endpoint (default: 0)

y1: integer?

Y coordinate of first endpoint (default: 0)

x2: integer?

X coordinate of second endpoint (default: 100)

y2: integer?

Y coordinate of second endpoint (default: 100)

color: (integer | string)?

line color (default: 0xffffff). ARGB32 integer or hex string.

line_width: integer?

line thickness in pixels (default: 5)

rounded: boolean?

true for rounded line caps (default: true)

Other members:

Inherited from dash.Params: align, height, width, x, y

set_line_color(self, color: (integer | string))

Set line color.

Parameters:

color ((integer | string)) – ARGB32 integer (0xAARRGGBB) or hex string (“#RGB”, “#ARGB”, “#RRGGBB”, or “#AARRGGBB”)

set_point(self, point: integer, x: integer, y: integer)

Set the coordinates of an endpoint.

Parameters:

  • point (integer) – point index: 1 (first endpoint) or 2 (second endpoint)

  • x (integer) – X coordinate

  • y (integer) – Y coordinate

get_point_x(self, point: integer): (x: integer)

Get the X coordinate of an endpoint.

Parameters:

point (integer) – point index: 1 or 2

Returns:

x (integer) – X coordinate

get_point_y(self, point: integer): (y: integer)

Get the Y coordinate of an endpoint.

Parameters:

point (integer) – point index: 1 or 2

Returns:

y (integer) – Y coordinate

Other members:

Inherited from dash.Object: align_in_parent(), anchor_to(), destroy(), extend(), get_children(), get_height(), get_parent(), get_position(), get_size(), get_visible(), get_width(), get_x(), get_y(), resize(), set_parent(), set_position(), set_size(), set_telemetry_update_hook(), set_visible()

class dash.Circle: dash.Object
class ctor dash.Circle(parent: dash.Object, params: dash.Circle.Params): dash.Circle

Circle node with configurable radius, fill and border. Created with dash.Circle(parent, params). Inherits all common methods from dash.Object.

The circle is centered within the node’s bounding box. Fill and border colors can be changed after creation; radius, border width, and background visibility are set at creation time.

Set background_visible = true to show the fill color (the fill is hidden by default).

local circle = dash.Circle(page, {
    x = 100, y = 100,
    radius = 50,
    background_color = 0xFFFF0000,
    background_visible = true,
    border_color = 0xFF000000,
    border_width = 2
})

Create a new Circle node.

Parameters:
class Params: dash.Params

Circle creation parameters. Inherits all fields from dash.Params.

The circle is centered within the node’s bounding box.

radius: integer?

radius in pixels (default: 100)

background_color: (integer | string)?

fill color (default: 0xffffff). ARGB32 integer or hex string.

background_visible: boolean?

true to show the fill (default: false)

border_color: (integer | string)?

border/outline color (default: 0xffffff). ARGB32 integer or hex string.

border_width: integer?

border thickness in pixels (default: 1)

Other members:

Inherited from dash.Params: align, height, width, x, y

set_fill_color(self, color: (integer | string))

Set fill color.

Parameters:

color ((integer | string)) – ARGB32 integer (0xAARRGGBB) or hex string (“#RGB”, “#ARGB”, “#RRGGBB”, or “#AARRGGBB”)

set_border_color(self, color: (integer | string))

Set border color.

Parameters:

color ((integer | string)) – ARGB32 integer (0xAARRGGBB) or hex string (“#RGB”, “#ARGB”, “#RRGGBB”, or “#AARRGGBB”)

Other members:

Inherited from dash.Object: align_in_parent(), anchor_to(), destroy(), extend(), get_children(), get_height(), get_parent(), get_position(), get_size(), get_visible(), get_width(), get_x(), get_y(), resize(), set_parent(), set_position(), set_size(), set_telemetry_update_hook(), set_visible()

class dash.Triangle: dash.Object
class ctor dash.Triangle(parent: dash.Object, params: dash.Triangle.Params): dash.Triangle

Triangle node defined by three vertices with optional fill and border. Created with dash.Triangle(parent, params). Inherits all common methods from dash.Object.

Vertices use 1-based indexing (point 1, 2, 3). Fill and border colors can be changed after creation; border width, background visibility, and rounded corners are set at creation time.

Set background_visible = true to show the fill color (the fill is hidden by default).

local tri = dash.Triangle(page, {
    x1 = 0, y1 = 100, x2 = 50, y2 = 0, x3 = 100, y3 = 100,
    background_color = 0xFFFF0000,
    background_visible = true,
    border_color = 0xFF000000,
    border_width = 2
})
-- Move a vertex dynamically
tri:set_point(2, 60, 10)

Create a new Triangle node.

Parameters:
class Params: dash.Params

Triangle creation parameters. Inherits all fields from dash.Params.

The triangle is defined by three vertices (x1,y1), (x2,y2), (x3,y3) relative to the node’s own position.

x1: integer?

X coordinate of first vertex (default: 0)

y1: integer?

Y coordinate of first vertex (default: 0)

x2: integer?

X coordinate of second vertex (default: 100)

y2: integer?

Y coordinate of second vertex (default: 100)

x3: integer?

X coordinate of third vertex (default: 0)

y3: integer?

Y coordinate of third vertex (default: 100)

background_color: (integer | string)?

fill color (default: 0xffffff). ARGB32 integer or hex string.

background_visible: boolean?

true to show the fill (default: false)

border_color: (integer | string)?

border/outline color (default: 0xffffff). ARGB32 integer or hex string.

border_width: integer?

border thickness in pixels (default: 1)

rounded: boolean?

true for rounded corners (default: true)

Other members:

Inherited from dash.Params: align, height, width, x, y

set_fill_color(self, color: (integer | string))

Set fill color.

Parameters:

color ((integer | string)) – ARGB32 integer (0xAARRGGBB) or hex string (“#RGB”, “#ARGB”, “#RRGGBB”, or “#AARRGGBB”)

set_border_color(self, color: (integer | string))

Set border color.

Parameters:

color ((integer | string)) – ARGB32 integer (0xAARRGGBB) or hex string (“#RGB”, “#ARGB”, “#RRGGBB”, or “#AARRGGBB”)

set_point(self, point: integer, x: integer, y: integer)

Set the coordinates of a vertex.

Parameters:

  • point (integer) – vertex index: 1, 2, or 3

  • x (integer) – X coordinate

  • y (integer) – Y coordinate

get_point_x(self, point: integer): (x: integer)

Get the X coordinate of a vertex.

Parameters:

point (integer) – vertex index: 1, 2, or 3

Returns:

x (integer) – X coordinate

get_point_y(self, point: integer): (y: integer)

Get the Y coordinate of a vertex.

Parameters:

point (integer) – vertex index: 1, 2, or 3

Returns:

y (integer) – Y coordinate

Other members:

Inherited from dash.Object: align_in_parent(), anchor_to(), destroy(), extend(), get_children(), get_height(), get_parent(), get_position(), get_size(), get_visible(), get_width(), get_x(), get_y(), resize(), set_parent(), set_position(), set_size(), set_telemetry_update_hook(), set_visible()

class dash.Graph: dash.Object
class ctor dash.Graph(parent: dash.Object, params: dash.Graph.Params): dash.Graph

Graph node that displays one or more data series as line charts. Created with dash.Graph(parent, params). Inherits all common methods from dash.Object.

Supports up to 4 lines per graph, multiple x-axis modes (fixed increment, time-based, manual), and multiple y-axis modes (fixed range, normalized, limits). Data is stored in a ring buffer; when full, the oldest values are dropped and the graph scrolls left.

local graph = dash.Graph(page, {
    x = 10, y = 10, width = 200, height = 100,
    background_color = "#000000",
    x_mode = "fixed", y_mode = "fixed",
    max_points = 50, y_min = 0, y_max = 100
})
graph:add_line("#ff0000")
graph:add_line("#00ff00")
for i = 1, 50 do
    graph:add_values(math.sin(i * 0.2) * 40 + 50,
                     math.cos(i * 0.15) * 30 + 50)
end

Create a new Graph node.

Parameters:
class Params: dash.Params

Graph creation parameters. Inherits all fields from dash.Params.

The graph displays one or more data series as line charts. Supports up to 4 lines per graph, multiple x-axis modes (fixed increment, time-based, manual), and multiple y-axis modes (fixed range, normalized, limits). Data is stored in a ring buffer; when full, the oldest values are dropped and the graph scrolls left.

max_points: integer?

maximum number of data points in the ring buffer (default: 50)

x_mode: string?

x-axis mode (default: “fixed”). One of “fixed” (auto-increment), “time” (real-time), “manual” (caller supplies x values).

y_mode: string?

y-axis mode (default: “fixed”). One of “fixed” (explicit y_min/y_max range), “normalized” (auto-scale to data), “limits” (auto-scale with limits).

y_min: number?

minimum y-axis value when y_mode is “fixed” (default: 0)

y_max: number?

maximum y-axis value when y_mode is “fixed” (default: 100)

background_color: (integer | string)?

background fill color (default: 0x00000000). ARGB32 integer or hex string.

Other members:

Inherited from dash.Params: align, height, width, x, y

add_line(self, color: (integer | string))

Add a new line to the graph. Each line is drawn independently with its own color. A graph supports up to 4 lines.

Parameters:

color ((integer | string)) – line color (ARGB32 integer or hex string, e.g. “#ff0000”)

add_values(self, ...: number)

Add data points to the graph. The number and meaning of arguments depends on the x_mode:

  • fixed / time: pass one y-value per line (y1, y2, ...).

  • manual: pass the x-value first, then one y-value per line (x, y1, y2, ...).

If the ring buffer is full, the oldest point is dropped (the graph scrolls).

-- fixed mode, 2 lines
graph:add_values(50, 80)
-- manual mode, 1 line
graph:add_values(3.5, math.sin(3.5))
Parameters:

... (number) – values (see above)

clear(self)

Clear all data from the graph.

set_y_range(self, y_min: number, y_max: number)

Set the y-axis range. Only meaningful when y_mode is “fixed”.

Parameters:

  • y_min (number) – minimum y value

  • y_max (number) – maximum y value

set_background_color(self, color: (integer | string))

Set the background color.

Parameters:

color ((integer | string)) – background color (ARGB32 integer or hex string). Use "#00000000" or 0x00000000 for a transparent background.

set_time_range(self, seconds: number)

Set the time range for time x-mode. Controls how many seconds of data are visible on the x-axis. Only used when x_mode is “time”.

Parameters:

seconds (number) – visible time range in seconds

set_x_range(self, range: number)

Set the x range for manual x-mode. Controls the visible x-axis span. Only used when x_mode is “manual”.

Parameters:

range (number) – visible x range

Other members:

Inherited from dash.Object: align_in_parent(), anchor_to(), destroy(), extend(), get_children(), get_height(), get_parent(), get_position(), get_size(), get_visible(), get_width(), get_x(), get_y(), resize(), set_parent(), set_position(), set_size(), set_telemetry_update_hook(), set_visible()

class dash.Canvas: dash.Object
class ctor dash.Canvas(parent: dash.Object, params: dash.Canvas.Params): dash.Canvas

Pixel canvas node for free-form drawing with primitive operations. Created with dash.Canvas(parent, params). Inherits all common methods from dash.Object.

The canvas provides a raw pixel buffer that can be drawn on using rectangles, circles, lines, triangles, and individual pixels.

Pixel formats:

  • RGB565 (transparent=false, default) – 16-bit opaque pixels, lower memory usage. Buffer is initially cleared to black.

  • ARGB8888 (transparent=true) – 32-bit pixels with alpha channel for transparency and blending. Buffer is initially fully transparent.

Coordinate system: (0,0) is the top-left corner of the canvas buffer. X increases rightward, Y increases downward. Drawing outside the buffer boundaries is clipped.

local canvas = dash.Canvas(page, {
    x = 10, y = 20, width = 100, height = 80,
    transparent = false
})
canvas:clear(0xFF000000)
canvas:fill_rect(5, 5, 50, 30, 0xFFFF0000)
canvas:draw_circle(50, 40, 20, 0xFF00FF00)
canvas:draw_line(0, 0, 99, 79, 0xFFFFFFFF, 2)

Create a new Canvas node.

Parameters:
class Params: dash.Params

Canvas creation parameters. Inherits all fields from dash.Params.

The canvas provides a raw pixel buffer for free-form drawing. Two pixel formats are available:

  • RGB565 (transparent=false, default) – 16-bit opaque pixels, lower memory usage. Initially cleared to black.

  • ARGB8888 (transparent=true) – 32-bit pixels with alpha channel for transparency and blending. Initially fully transparent.

transparent: boolean?

true for ARGB8888 with alpha blending, false for RGB565 opaque (default: false)

Other members:

Inherited from dash.Params: align, height, width, x, y

clear(self, color?: integer | string)

Clear the entire canvas. When called without a color, clears to black (RGB565) or fully transparent (ARGB8888) depending on the canvas pixel format.

Parameters:

color? (integer | string) – clear color. ARGB32 integer (0xAARRGGBB) or hex string (“#RGB”, “#ARGB”, “#RRGGBB”, or “#AARRGGBB”).

fill_rect(
    self,
    x: integer,
    y: integer,
    w: integer,
    h: integer,
    color: (integer | string)
)

Fill a rectangle.

Parameters:

  • x (integer) – left edge

  • y (integer) – top edge

  • w (integer) – width

  • h (integer) – height

  • color ((integer | string)) – fill color. ARGB32 integer or hex string.

draw_rect(
    self,
    x: integer,
    y: integer,
    w: integer,
    h: integer,
    color: (integer | string)
)

Draw a rectangle outline (1px wide).

Parameters:

  • x (integer) – left edge

  • y (integer) – top edge

  • w (integer) – width

  • h (integer) – height

  • color ((integer | string)) – outline color. ARGB32 integer or hex string.

draw_line(
    self,
    x1: integer,
    y1: integer,
    x2: integer,
    y2: integer,
    color: (integer | string),
    width?: integer
)

Draw a line between two points. When width > 1, draws a thick line with round caps.

Parameters:

  • x1 (integer) – start X

  • y1 (integer) – start Y

  • x2 (integer) – end X

  • y2 (integer) – end Y

  • color ((integer | string)) – line color. ARGB32 integer or hex string.

  • width? (integer) – line thickness in pixels (default: 1)

fill_circle(
    self,
    cx: integer,
    cy: integer,
    radius: integer,
    color: (integer | string)
)

Fill a circle.

Parameters:

  • cx (integer) – center X

  • cy (integer) – center Y

  • radius (integer) – radius in pixels

  • color ((integer | string)) – fill color. ARGB32 integer or hex string.

draw_circle(
    self,
    cx: integer,
    cy: integer,
    radius: integer,
    color: (integer | string),
    width?: integer
)

Draw a circle outline. When width > 1, draws a thick outline.

Parameters:

  • cx (integer) – center X

  • cy (integer) – center Y

  • radius (integer) – radius in pixels

  • color ((integer | string)) – outline color. ARGB32 integer or hex string.

  • width? (integer) – outline thickness in pixels (default: 1)

fill_triangle(
    self,
    x1: integer,
    y1: integer,
    x2: integer,
    y2: integer,
    x3: integer,
    y3: integer,
    color: (integer | string)
)

Fill a triangle defined by three vertices.

Parameters:

  • x1 (integer) – first vertex X

  • y1 (integer) – first vertex Y

  • x2 (integer) – second vertex X

  • y2 (integer) – second vertex Y

  • x3 (integer) – third vertex X

  • y3 (integer) – third vertex Y

  • color ((integer | string)) – fill color. ARGB32 integer or hex string.

fill_rounded_rect(
    self,
    x: integer,
    y: integer,
    w: integer,
    h: integer,
    radius: integer,
    color: (integer | string)
)

Fill a rounded rectangle.

Parameters:

  • x (integer) – left edge

  • y (integer) – top edge

  • w (integer) – width

  • h (integer) – height

  • radius (integer) – corner radius in pixels

  • color ((integer | string)) – fill color. ARGB32 integer or hex string.

set_pixel(self, x: integer, y: integer, color: (integer | string))

Set a single pixel.

Parameters:

  • x (integer) – X coordinate

  • y (integer) – Y coordinate

  • color ((integer | string)) – pixel color. ARGB32 integer or hex string.

set_canvas_size(self, w: integer, h: integer, transparent?: boolean)

Reallocate the pixel buffer with new dimensions. The previous buffer content is discarded. The new buffer is cleared to black (RGB565) or fully transparent (ARGB8888).

Parameters:

  • w (integer) – new width (must be > 0)

  • h (integer) – new height (must be > 0)

  • transparent? (boolean) – pixel format: true for ARGB8888, false for RGB565 (default: keep current format)

Other members:

Inherited from dash.Object: align_in_parent(), anchor_to(), destroy(), extend(), get_children(), get_height(), get_parent(), get_position(), get_size(), get_visible(), get_width(), get_x(), get_y(), resize(), set_parent(), set_position(), set_size(), set_telemetry_update_hook(), set_visible()

Telemetry Data

class Telemetry

Telemetry object representing a single telemetry value from the simulation. Telemetry objects are accessed via dash.telemetry, e.g. dash.telemetry.engine_rpm.

The available telemetry names depend on the connected simulator and its telemetry plugin. Common examples include:

  • engine_rpm – engine revolutions per minute

  • speed – vehicle speed (m/s)

  • transmission_gear – current gear number

  • throttle_input – throttle position (0-1)

  • brake_input – brake position (0-1)

  • fuel_available – remaining fuel

  • lap_time_current – current lap time

  • delta_to_best – delta to best lap time

Use valid() to check whether a telemetry value is currently available from the simulation before reading it.

local rpm = dash.telemetry.engine_rpm
if rpm:valid() then
    label:set_text(string.format("%d RPM", rpm:value()))
end

Telemetry handles can also be used with set_telemetry_update_hook for efficient change-driven updates instead of polling in the main loop.

value(self): (value: any)

Get the current value of this telemetry. The return type depends on the telemetry type: boolean for "bool", integer for "int", number for "float", or nil for "invalid".

Returns:

value (any) – the current value

name(self): (name: string)

Get the name of this telemetry.

Returns:

name (string) – the telemetry name (e.g. "engine_rpm")

valid(self): (valid: boolean)

Check if this telemetry is currently valid. A telemetry is valid when the simulation is actively providing data for it.

Returns:

valid (boolean) – true if the telemetry has a valid value

type(self): (type: string)

Get the data type of this telemetry.

Returns:

type (string) – one of "bool", "int", "float", or "invalid"

Simulation Data

dash.sim

Simulation data submodule for accessing live data from racing simulators. Accessed via dash.sim.

Provides structured access to session, player, vehicle, tire, and track data. The actual fields available on each data object depend on the simulator and its telemetry output.

All returned data objects support the get_or(field, default) method for safe field access with a fallback value.

local player = dash.sim.get_player()
local vehicle = dash.sim.get_player_vehicle()
local session = dash.sim.get_session()

-- Access fields with defaults
local car = vehicle:get_or("name", "Unknown")
local laps = session:get_or("laps_total", 0)
get_session(): (session: dash.sim.Session)

Get session data (race session info such as lap count, time, flags).

Returns:

session (dash.sim.Session) – session data table

get_participant(id: integer): (participant: dash.sim.Participant)

Get data for a specific participant in the session.

Parameters:

id (integer) – participant index (1-based)

Returns:

participant (dash.sim.Participant) – participant data table

get_player(): (player: dash.sim.Participant)

Get the local player’s data (driver info, position, lap times).

Returns:

player (dash.sim.Participant) – player data table

get_vehicle(id: integer): (vehicle: dash.sim.Vehicle)

Get data for a specific vehicle.

Parameters:

id (integer) – vehicle index (1-based)

Returns:

vehicle (dash.sim.Vehicle) – vehicle data table

get_vehicles(): (vehicles: VehiclesSimData)

Get data for all vehicles in the session.

Returns:

vehicles (VehiclesSimData) – vehicles data table

get_tire(id: integer): (tire: dash.sim.Tire)

Get data for a specific tire.

Parameters:

id (integer) – tire index (1-based)

Returns:

tire (dash.sim.Tire) – tire data table

get_tires(): (tires: TiresSimData)

Get data for all tires.

Returns:

tires (TiresSimData) – tires data table

get_track(): (track: dash.sim.Track)

Get track data (name, length, sector info).

Returns:

track (dash.sim.Track) – track data table

get_player_vehicle(): (player_vehicle: dash.sim.Vehicle)

Get the player’s vehicle data (car-specific telemetry).

Returns:

player_vehicle (dash.sim.Vehicle) – player vehicle data table

class Session: table
number_of_laps: integer

Number of laps participants must complete to finish the race

player_participant_id: integer

Id of the participant data that refers to the player on this PC

player_vehicle_id: string

ID of the vehicle that player drives. Should match the id listed in participant data.

session_name: string

User readable name of the session. Eg. “Qualifying” or “Practice 1”

session_type: string

Session type: “qualifying”, “race”, “practice”, “free_roam”, “hotlap”

track_id: string

ID of the track that is used for this session

class Participant: table
abbrev_name: string

Abbreviated name for the driver, used when character space is limited

in_current_session: boolean

True if participant is part of the currently active session

name: string

Name of the participant (driver)

on_track: boolean

Participant is currently on the track (or on pitlane). false, if participant is inside pitbox

team_name: string

Name of the team that the participant represents

tire_id: integer

Id of the tire compound currently used. Used as default when per-wheel tire ids are not specified

tire_id_lf: integer

Left front tire id

tire_id_lr: integer

Left rear tire id

tire_id_rf: integer

Right front tire id

tire_id_rr: integer

Right rear tire id

vehicle_id: string

Id of the vehicle that this participant uses

vehicle_number: integer

Car number of the participant (not necessarily unique if multiple players drive same car)

class Vehicle: table
brand: string

Brand name of the car

class_name: string

Name of the car class

engine_idle_rpm: number

Engine RPM when idle

engine_redline_rpm: number

Engine redline RPM

gearbox_backward_gears: integer

Number of backward/reverse gears the gearbox has

gearbox_forward_gears: integer

Number of forward gears the gearbox has

has_abs: boolean

Car has anti-lock brakes

has_drs: boolean

Car has drag reduction system

has_tc: boolean

Car has traction control system

model: string

Model name of the car

name: string

Name of the car

non_unique: boolean

True if this vehicle id is not uniquely identifiable. Used when adapting telemetry from a sim that does not offer a good way to identify the vehicle; a single vehicle id is used with this set to true.

Engine RPM when shifting lights should blink or otherwise indicate that RPM is too high. If between [0 - 1] then this is considered to be relative to max rpm value.

shift_light_first_rpm: number

Engine RPM when first shifting light appears. If between [0 - 1] then this is considered to be relative to max rpm value.

shift_light_last_rpm: number

Engine RPM when last shifting light is lit. If between [0 - 1] then this is considered to be relative to max rpm value.

short_name: string

Shorter name of the car

steering_wheel_rotation_deg: number

Number of degrees of rotation that the car steering wheel has from fully left to fully right

class Track: table
base_name: string

Shorter base name of the track. Might be the same as “name”

country: string

ISO 3166-1 alpha-3, three-letter country code, where the track is located

has_joker: boolean

True if the track has a rallycross-style joker lap

name: string

Full name of the track (variant)

pitlane_speed_limit: number

Speed limit in pitlane in m/s

sector_count: integer

Number of sectors in this track

track_length: number

Length of the track in meters

track_style: string

Style of the track: “circuit”, “stage”

variant: string

Track variant name

class Tire: table
hardness_order: integer

Arbitrary number defining sorting order of different compounds based on their hardness. Higher number is considered harder

name: string

Name of the tire compound

short_name: string

Short name of the tire compound

weather: string

Intended weather condition for this tire: eg. “dry”, “light_rain”, “heavy_rain”, “snow”

Submodules

dash.wheel

Wheel input submodule for reading buttons, analog axes, and touch input. Accessed via dash.wheel.

Provides access to the physical inputs on the connected wheel: analog axes (throttle, brake, clutch, etc.), digital buttons, and touch input.

Input indexing: all input indices are 1-based.

Analog values: raw analog values are unprocessed ADC readings. Processed analog values have calibration and mapping applied.

Digital inputs: raw digital inputs are the physical button states before any remapping. Processed digital inputs have user mapping applied.

-- Display all analog input values
for i = 1, dash.wheel.get_analog_input_count() do
    local val = dash.wheel.get_analog_input(i)
    local type = dash.wheel.get_analog_input_type(i)
    print(string.format("Input %d (%s): %d", i, type, val))
end
get_analog_input_count(): (count: integer)

Get the number of analog inputs.

Returns:

count (integer) – number of analog inputs available

get_analog_input(input: integer): (value: integer)

Get a processed (calibrated and mapped) analog input value.

Parameters:

input (integer) – analog input index (1-based)

Returns:

value (integer) – the processed analog value

get_raw_analog_input(input: integer): (value: integer)

Get a raw (unprocessed) analog input value. Returns the direct ADC reading before calibration or mapping.

Parameters:

input (integer) – analog input index (1-based)

Returns:

value (integer) – the raw ADC value

get_analog_input_type(input: integer): (type: string)

Get the configured type of an analog input.

Parameters:

input (integer) – analog input index (1-based)

Returns:

type (string) – one of "none", "throttle", "brake", "clutch_m", "clutch_s", "bite_point"

get_raw_digital_input_count(): (count: integer)

Get the number of raw (physical) digital inputs.

Returns:

count (integer) – number of raw digital inputs

get_raw_digital_input(input: integer): (pressed: boolean)

Get a raw digital input state (before user remapping).

Parameters:

input (integer) – digital input index (1-based)

Returns:

pressed (boolean) – true if the button is pressed

get_digital_input_count(): (count: integer)

Get the number of mapped digital inputs.

Returns:

count (integer) – number of mapped digital inputs

get_digital_input(input: integer): (pressed: boolean)

Get a mapped digital input state (after user remapping).

Parameters:

input (integer) – digital input index (1-based)

Returns:

pressed (boolean) – true if the button is pressed

get_touch_input(): (x: integer, y: integer, pressed: boolean)

Get touch input state. Returns the current touch position and press state. Coordinates are in display pixels with (0,0) at the top-left corner.

Returns:

  • x (integer) – X coordinate of touch point

  • y (integer) – Y coordinate of touch point

  • pressed (boolean) – true if the screen is currently being touched

enable_mouse_input(enable: boolean)

Enable or disable mouse input emulation. When enabled, mouse events are translated to touch input, useful for testing dashboards on a PC without a touch screen.

Parameters:

enable (boolean) – true to enable, false to disable

dash.led

LED control submodule for reading and overriding LED colors. Accessed via dash.led.

LEDs are indexed starting from 1. Colors use individual R, G, B components in the 0-255 range.

Override an LED to take control of its color from the system. Release it to return control to the default LED behavior.

-- Set first 3 LEDs to red
for i = 1, math.min(3, dash.led.get_led_count()) do
    dash.led.override_led_color(i, 255, 0, 0)
end

-- Release control back to system
for i = 1, math.min(3, dash.led.get_led_count()) do
    dash.led.release_led(i)
end
get_led_count(): (count: integer)

Get the total number of LEDs available.

Returns:

count (integer) – number of LEDs

get_led_color(index: integer): (r: integer, g: integer, b: integer)

Get the current color of an LED.

Parameters:

index (integer) – LED index (1-based)

Returns:

  • r (integer) – red component (0-255)

  • g (integer) – green component (0-255)

  • b (integer) – blue component (0-255)

override_led_color(index: integer, r: integer, g: integer, b: integer): (success: boolean)

Override the color of an LED. Takes control of the LED from the system and sets it to the given color. The override persists until release_led is called for this index.

Parameters:

  • index (integer) – LED index (1-based)

  • r (integer) – red component (0-255)

  • g (integer) – green component (0-255)

  • b (integer) – blue component (0-255)

Returns:

success (boolean) – true if the override was applied

release_led(index: integer): (success: boolean)

Release an LED color override. Returns control of the LED to the system’s default behavior.

Parameters:

index (integer) – LED index (1-based)

Returns:

success (boolean) – true if the override was released

dash.unit

Unit conversion submodule for user-preferred measurement units. Accessed via dash.unit.

Provides functions to query the user’s preferred units and convert values from SI system units to the user’s chosen units.

System (input) units: all conversion functions expect values in SI base units:

  • Speed: m/s (meters per second)

  • Distance: m (meters)

  • Temperature: celsius

  • Volume: litres

  • Pressure: kPa (kilopascals)

-- Convert and display speed in user's preferred unit
local speed_ms = dash.telemetry.speed:value()
local speed = dash.unit.convert_to_user_speed(speed_ms)
local unit_name = dash.unit.get_user_speed_unit()
label:set_text(string.format("%.0f %s", speed, unit_name))
get_user_speed_unit(): (unit: string)

Get the user’s preferred speed unit.

Returns:

unit (string) – "km/h" or "mph"

get_user_distance_unit(): (unit: string)

Get the user’s preferred distance unit.

Returns:

unit (string) – "km" or "mi"

get_user_temperature_unit(): (unit: string)

Get the user’s preferred temperature unit.

Returns:

unit (string) – "celsius", "fahrenheit", or "kelvin"

get_user_volume_unit(): (unit: string)

Get the user’s preferred volume unit.

Returns:

unit (string) – "litre" or "gallon"

get_user_pressure_unit(): (unit: string)

Get the user’s preferred pressure unit.

Returns:

unit (string) – "kPa", "bar", or "psi"

convert_to_user_speed(speed: number): (value: number)

Convert a speed value from m/s to the user’s preferred unit.

Parameters:

speed (number) – speed in m/s

Returns:

value (number) – speed in user’s unit

convert_to_user_distance(distance: number): (value: number)

Convert a distance value from meters to the user’s preferred unit.

Parameters:

distance (number) – distance in meters

Returns:

value (number) – distance in user’s unit

convert_to_user_temperature(temperature: number): (value: number)

Convert a temperature value from celsius to the user’s preferred unit.

Parameters:

temperature (number) – temperature in celsius

Returns:

value (number) – temperature in user’s unit

convert_to_user_volume(volume: number): (value: number)

Convert a volume value from litres to the user’s preferred unit.

Parameters:

volume (number) – volume in litres

Returns:

value (number) – volume in user’s unit

convert_to_user_pressure(pressure: number): (value: number)

Convert a pressure value from kPa to the user’s preferred unit.

Parameters:

pressure (number) – pressure in kPa

Returns:

value (number) – pressure in user’s unit