hobdrive-docs

HobDrive Layout Specification

Index

English

Russian

This document collects the layout tags, attributes and options used by HobDrive UI layout files.

Table of Contents

• HobDrive Layout Specification
  • Layout Contract
  • Top-level tags
  • Layout Files and Load Order
  • section
    • Section Visibility in the App
  • Layout containers
  • item
    • Item Actions
  • Special item types
  • Decorators and nested elements
    • image decorator
    • progress decorator
    • tile decorator
    • padding decorator
    • crop decorator
    • visible / visibility decorator
    • filter decorator
    • break decorator
  • Layout-level attributes and features from changelog
  • Sensor and expression features
  • Sensor lists and autogenerated panels
  • Conditional expressions
  • Interpolation in Expressions
  • Grid sizing hints
  • Other useful attributes and behaviors (from changelog and examples)
  • Widget and decorator attributes (observed in user.layout)
  • Appendix — common attributes quick reference
  • Try it — ready templates

Layout Contract

• Inputs: XML-like layout files (tags: ui, section, grid, item, union, stack-vertical, stack-horizontal, etc.)
• Output: Rendered UI screens in HobDrive; conditional visibility and decorators influence on runtime behavior
• Error modes: invalid attributes are ignored or fallback to defaults; missing sensors show as empty/unavailable
• Success criteria: layout renders and respects conditional if attributes, grid placement, decorators and widget attributes

Top-level tags

• ui — root element for a layout file. Contains section elements and other layout constructs.

• include — allows embedding another layout file or fragment. Attributes:

  • file — relative path to the included layout (e.g., file="default-tripcomp.layout").
  • if — optional condition which controls whether the included file is processed (same expression syntax as section if).
  • Includes are evaluated when the file is loaded and are commonly used to compose main layouts from reusable fragments (trip computer, HUD, dashkits).

Example:

<include file="default-tripcomp.layout" if='${!sexists("GasTrigger")}'/>

Layout Files and Load Order

The regular HobDrive interface is assembled from the app’s standard layout files and user overrides.

Typical standard files:

• default-landscape.layout — top-level layout and common config parameters;
• default-hobd.layout — base HobDrive sections;
• included files such as default-tripcomp.layout, default-dashb3.layout, and ECU-specific layout files.

User files:

• user1.layout — the screen created by the Your Screen dialog in main screen settings;
• user.layout — manual user sections and overrides;
• user.gauge — user settings for sensor appearance;
• override* directories — isolated override sets, including installed DashKits.

Standard default-*.layout and default*.gauge files should not be edited directly: they may be replaced by an app update. Use user.layout, user1.layout, user.gauge, or a DashKit for your own changes.

user.gauge is different from user.layout: HobDrive can automatically change it from the sensor appearance settings dialog. Manual editing is possible, but requires care to avoid conflicts with settings made through the interface.

section

Defines a logical screen/page block. Common attributes:

• name — human-readable section name (used in UI lists).
• title — displayed title. If omitted, name is used.
• fixed — true/false (whether the section is fixed in navigation). fixed="true" makes the section part of the main screen panel.
• optional — true/false. optional="true" keeps the section as an extra screen: it does not enter the main swipe sequence, but can be opened through the Screens menu.
• order — numeric section priority. 0 means natural order. Negative values place the section before regular screens, positive values after unnumbered screens.
• if — conditional expression (a sensor name or expression). Section is shown only if condition evaluates truthy. Examples: if="Oxygen_b1s1", if="PortraitLayout", if="Renault_01_11103.ControlModuleVoltage".
• class — CSS-like class used by system to apply predefined behaviors (e.g., SensorList).
• ns — namespace for sensor filtering when using SensorList.
• exclude — regex to exclude sensor IDs in generated sensor lists.
• title-height — height of the title/top padding area for the section.
• maximize-focus — (from changelog) true/false removes optional controls when focused.
• controls — autohide or other values to control UI button visibility.
• volatile — hint for temporary/service sections.

Example:

<section name="GPS">
  ...
</section>

<section name="Fuel Trims" if="STFT1">
  ...
</section>

Navigation example:

<section name="My Diagnostics" title="Diagnostics" optional="true" order="2" if="STFT1">
  <grid rows="," cols=",">
    <item id="STFT1"/>
    <item id="LTFT1"/>
  </grid>
</section>

Section Visibility in the App

At runtime, a section has an Optional state.

• fixed="true" sets Optional=false: the screen enters the main panel and is available by swiping.
• optional="true" keeps the screen as an extra screen.
• User main screen settings can override optional and order; they are saved in configuration as LayoutSection_<SectionName>_Optional and LayoutSection_<SectionName>_Order.
• Sections whose names start with @ are used as service actions in the menu.

If a section should be available only for a specific sensor, ECU, or orientation, use if.

Common conditions:

<section name="Only ATF" if="ATFTemp">
  ...
</section>

<section name="Portrait Tools" if="PortraitLayout">
  ...
</section>

<section name="Landscape Tools" if="LandscapeLayout">
  ...
</section>

config elements

• config — declare UI-configurable options that appear in settings dialogs. Typical attributes:
  • id — unique identifier accessible from layout expressions (e.g., ${Layout_ECUFuel}).
  • type — bool, int, string, etc.
  • default — default value.
  • title, descr — text shown in UI; localized variants like title-ru, descr-ru are supported.

Example:

<config id="Layout_ECUFuel" type="bool" default="false"
        title="Use Fuel Level data from ECU"
        descr="If enabled - fuel level will be shown from ECU. Otherwise - estimated from fuel consumption"
        title-ru="Показывать уровень топлива из ЭБУ"
        descr-ru="Если включено - уровень топлива будет браться из ЭБУ. Иначе - показывается оценочный уровень топлива"/>

Layout containers

• grid — places child items into a table-like grid.
• Attributes: rows, cols — comma-separated size hints. Example: rows=",," cols=",35".
• rows and cols can include numeric heights/widths or empty entries for flexible sizing.

• grids can be nested.

• stack-vertical / stack-horizontal — stack items vertically/horizontally; columns may be used.
  • Example: <stack-vertical columns="${LandscapeLayout ? 2 : 1}">
• union — allows compositing several alternate layouts into same area (used in TPMS layout).
  • Use union when multiple mutually-exclusive sub-layouts should occupy the same grid area; each child typically contains its own grid.
• switch — selects one of its child elements to show based on an index expression. Useful for small cycling lists or conditional items.
  • Attributes:
    • index — an expression or integer selecting which child to show (0-based). Can reference sensor values via svalue(...) or any TinyExe expression.
    • interval — when present, index may be evaluated periodically using this interval (milliseconds) to cycle children.
    • if — optional condition to entirely enable the switch.
  • Children are typical items (or nested grids); when index resolves to a child index that child is displayed.

Example (cycle temperature sensors every 4 seconds):

<switch if='${Layout_RollTemp = true}' index='$${ svalue("DateTime") / 4000 }'>
  <item id="ATFTemp" .../>
  <item id="CVTTemp" .../>
  <item id="EngineOilTemp" .../>
</switch>

item

Represents a widget in a grid or stack. Common attributes and usages:

• id — sensor or special control identifier. Examples: RPM, Latitude, ControlModuleVoltage.
• type — button, static, etc. Defaults to a sensor/value widget when omitted.
• text — for buttons or static items, visible text.
• action — for button: action string such as invoke(FAN_ON) or run(...).
• size — visual size hint: micro, small, normal, large, huge, extralarge or numeric.
• precision — number of decimal digits or special tags like 6fixed.
• inherit — refers to a decorator or style name, e.g., inherit="_ColoredOnOff" or _MB_Battery.
• colspan / rowspan — span cells in the grid.
• description — extra attribute used to style or position small descriptive labels (e.g., description="aside").
• period — update period in milliseconds (e.g., period='5000' on ControlModuleVoltage).
• wrap — filter expression for smoothing or prediction: examples from changelog:
  • wrap="predict(50,0.7)"
  • wrap="smooth(400,100,5)"
  • wrap="average(30)"

• custom attributes: text-values, custom-units, colored-descr, text-evaluator (see changelog entries where used)

• onclick — item-level click handler (navigates or runs named actions). Examples: onclick="NewFueling", onclick="Go(Efficiency)".
• actions — comma-separated list of actions available in sensor info dialog. Example: actions="SetupOdometer".
• units — visual placement of unit text: units="below", units="aside" or units="hidden".
• interval — an update interval used for dynamic UI behaviour or internal timers (different from sensor period).
• decorator-XXX — special syntax to enable decorators.

Example usages:

<item id="FuelLevel" if='${Layout_ECUFuel != true}' inherit="_FuelIndicator, _EditAction" onclick="NewFueling"/>
<item id="Odometer" if="${Layout_ECU_Odometer != true}" actions="SetupOdometer" size="large" inherit="_EditAction"/>

Item Actions

Actions can be attached to items through onclick, ondoubleclick, onhold, action, and actions.

Examples:

<item id="FuelLevel" onclick="NewFueling"/>
<item id="Speed" onhold="SensorInformation"/>
<item type="button" text="Min" action="Minimize"/>
<item id="Speed" actions="SetupOdometer, Minimize, Shutdown"/>
<item id="EfficiencyPercentage" onclick="Go(Efficiency)"/>

Common actions:

• ChangeLiterCost — fuel liter cost dialog;
• FuelCalibration — tank volume calibration dialog;
• SensorInformation — sensor information;
• NewFueling — new refueling entry;
• NewMaintenance — new maintenance entry;
• Minimize — hide the app;
• Shutdown — exit;
• VehicleSettings — vehicle settings;
• PortSettings — connection settings;
• ExtraSettings — system settings;
• EditSensorsLayout — sensor edit mode;
• CorrectionInformation — consumption correction information;
• Go(ScreenName) or go(ScreenName) — navigate to a screen;

• run(...) — run an external action/command if supported by the platform.

• type specifics and chart attributes:
  • type="chart" — renders a chart for the sensor; common chart attributes: chart='line', time-scale, min-limit, max-limit, cover-description.
  • border-opacity — visual border control (used on charts/gauges in dashkits).
  • custom-description / description / custom-units — allow custom labels and units.
• item extradata access:
  • id="sensor[extradata]" — render additional data stored with a sensor (e.g., TripTime[fillup]).

Examples:

Special item types

• type=”button” — clickable button. Use action=”invoke(NAME)” to call ECU/service action.
• type=”static” — static text block. E.g. type="static" size="micro"
• gauge / chart / image decorators — declared either as item with nested decorators or in gauge/theme files; can accept decorators.

Decorators and nested elements

item may contain nested decorators. Example syntax:

<item id="Speed">
  <image image-zorder="bottom" image-path="images/dashboard-svgrepo-com.svg" image-scale="0.5"/>
  <image image-zorder="bottom" image-path="images/arrow.png" image-scale="0.5"/>
</item>

The modern nested form is more convenient for new layouts because all decorator parameters are kept next to the item.

The older attribute syntax decorator-* is also supported and is common in existing gauge and layout files:

<item id="Speed"
      decorator-i1="image"
      i1-image-zorder="bottom"
      i1-image-path="images/gauges/without_arrow_circle.png"
      decorator-i2="image"
      i2-image-zorder="bottom"
      i2-image-path="images/gauges/arrow.png"
      i2-image-rotate='$${ Sensor_Value - 45 }'
      i2-image-scale="1"/>

The identifier after decorator- is arbitrary (i1, bg, pad, action, and so on). Decorator attributes use the same prefix: i1-image-path, pad-padding, action-image-align.

The overlay order of old-style decorators is determined by sorting their identifiers. For predictable order, numeric or alphabetical prefixes are convenient: d1, d2, d3.

image decorator

Attributes: image-zorder, image-path, image-scale, image-width, image-height, image-align, image-aspect, image-rotate, image-rotate-align (can contain dynamic expressions).

Many attributes can accept dynamic expressions such as image-rotate='$${ Sensor_Value - 45 }'.

The image-path is usually relative to the HobDrive resource folder or the current DashKit. Use PNG or SVG for transparency.

Dynamic image example:

<item id="RPM">
  <image image-zorder="bottom"
         image-path='images/gauges/rpms/$${ceiling(Sensor_Value/1000*2)}.png'
         image-align="hcenter,bottom"
         image-scale="0.8"/>
</item>

progress decorator

<item id="Speed" decorator-10="touch-progress"/>

This is a system decorator, used to draw dynamic line on press.

tile decorator

<item id="Speed" decorator-10="tile"/>

Draws a tile behind the gauge.

padding decorator

Padding decorator is used to “pad” space in iitem. Values are for TOP, RIGHT, BOTTOM, LEFT.

You can use percentage values.

<item id="Speed">
    <padding padding="0 0 0 120"/>
</item>

crop decorator

Crop decorator cuts (hides) part of the previously rendered widget.

<item id="Test" border-opacity="1" type='roundbar' red-green="150,0">
  <crop crop="10% 10% 10% 10%"/>
</item>

visible / visibility decorator

This decorator just enables/disables drawing in runtime. You can use dynamic $$ evaluation.

<item id="AT_R" visibility='$${Sensor_Value}'/>

filter decorator

The filter decorator is a powerful tool for applying visual effects and transformations to UI elements. It supports both draw effects (visual filters) and matrix transformations (geometric changes).

Attributes

• effect — semicolon-separated list of filter functions to apply. Each filter is a function call with parameters.
• mode — controls when the filter is applied in the rendering pipeline:
  • before — applies filter before rendering the target element, then renders the element normally
  • in (default) — applies filter to the target element only
  • after — renders the target element first, then applies filter
• interval — optional; update interval in milliseconds for dynamic filter expressions (using $${} syntax)

Draw Effects

These filters modify the visual appearance without changing geometry. Multiple filters can be chained with semicolons.

blur(radiusX, radiusY)

• Applies Gaussian blur to the element
• radiusX — horizontal blur radius in pixels
• radiusY — vertical blur radius in pixels
• Example: effect="blur(2,2)" — applies 2px blur in both directions

drop-shadow(dx, dy, sigmaX, sigmaY)

• Creates a drop shadow effect
• dx — horizontal shadow offset in pixels
• dy — vertical shadow offset in pixels
• sigmaX — horizontal blur sigma
• sigmaY — vertical blur sigma (optional, defaults to sigmaX if omitted)
• Shadow color is black
• Example: effect="drop-shadow(5,5,3,3)" — shadow offset 5px right and down with 3px blur

transparent(alpha)

• Adjusts element transparency
• alpha — opacity reduction (0.0 = fully transparent, 1.0 = no change)
• Example: effect="transparent(0.5)" — makes element 50% more transparent

dilate(radiusX, radiusY)

• Expands bright areas (morphological dilation)
• radiusX — horizontal dilation radius in pixels
• radiusY — vertical dilation radius in pixels
• Example: effect="dilate(2,2)" — expands bright areas by 2px

erode(radiusX, radiusY)

• Shrinks bright areas (morphological erosion)
• radiusX — horizontal erosion radius in pixels
• radiusY — vertical erosion radius in pixels
• Example: effect="erode(2,2)" — erodes bright areas by 2px

brightness(factor)

• Adjusts brightness of the element
• factor — brightness multiplier (0.0 = black, 1.0 = original, >1.0 = brighter)
• Example: effect="brightness(1.5)" — increases brightness by 50%

contrast(factor)

• Adjusts contrast of the element
• factor — contrast multiplier (0.0 = gray, 1.0 = original, >1.0 = higher contrast)
• Example: effect="contrast(1.3)" — increases contrast by 30%

invert()

• Inverts colors (negative effect)
• No parameters
• Example: effect="invert()" — creates color negative

sepia()

• Applies sepia tone (warm brownish tint)
• No parameters
• Example: effect="sepia()" — vintage photo effect

grayscale()

• Converts to grayscale (luminance-based)
• No parameters
• Uses standard luminance weights (R: 0.2126, G: 0.7152, B: 0.0722)
• Example: effect="grayscale()" — black and white effect

saturate(amount)

• Adjusts color saturation
• amount — saturation change (-1.0 = desaturate, 0.0 = no change, >0.0 = more saturated)
• Example: effect="saturate(0.5)" — increases saturation by 50%
• Example: effect="saturate(-0.3)" — reduces saturation by 30%

colorfilter(r, g, b)

• Tints the element with a specific color while preserving brightness
• r — red component (0-255)
• g — green component (0-255)
• b — blue component (0-255)
• Converts image to grayscale then applies color tint
• Example: effect="colorfilter(255,100,50)" — orange tint

remove-black()

• Makes black pixels transparent (useful for removing black backgrounds)
• No parameters
• Alpha channel becomes proportional to pixel brightness
• Example: effect="remove-black()" — removes black background from images

Matrix Transformations

Important: Matrix transformations (rotate, offset, zoom) modify geometry and should not be mixed with draw effects in the same filter. Use separate <filter> decorators if you need both.

rotate(angle, [pivotX, pivotY])

• Rotates the element
• angle — rotation angle in degrees
• pivotX — optional; horizontal pivot point (percentage or pixels, default: 50%)
• pivotY — optional; vertical pivot point (percentage or pixels, default: 50%)
• Example: effect="rotate(45)" — rotates 45° around center
• Example: effect="rotate(90,0%,0%)" — rotates 90° around top-left corner
• Dynamic example: effect="rotate($${Sensor_Value})" — rotates based on sensor value

offset(dx, dy)

• Translates (moves) the element
• dx — horizontal offset (percentage or pixels)
• dy — vertical offset (percentage or pixels)
• Example: effect="offset(10,20)" — moves 10px right, 20px down
• Example: effect="offset(50%,0)" — moves 50% of width to the right

zoom(scale) or zoom(scaleX, scaleY, [pivotX, pivotY])

• Scales the element
• scale — uniform scale factor (1.0 = original size)
• OR:
• scaleX — horizontal scale factor
• scaleY — vertical scale factor
• pivotX — optional; horizontal scaling center (percentage or pixels)
• pivotY — optional; vertical scaling center (percentage or pixels)
• Example: effect="zoom(1.5)" — scales to 150% around center
• Example: effect="zoom(2,1)" — doubles width only
• Example: effect="zoom(0.5,0.5,0%,0%)" — scales to 50% from top-left corner

Usage Examples

Simple blur effect:

<item id="Speed">
  <filter effect="blur(2,2)"/>
</item>

Multiple chained effects:

<item id="Temperature">
  <filter effect="grayscale();saturate(0.5);brightness(1.2)"/>
</item>

Dynamic rotation based on sensor value:

<item id="Compass">
  <filter effect="rotate($${Sensor_Value},50%,50%)" interval="100"/>
</item>

Mode usage with multiple decorators:

<item id="Speed" type="chart" chart='line'>
  <break/>
  <image image-zorder="bottom" image-path="images/ui/arrow.png"/>
  <filter effect="rotate($${180+Sensor_Value%360},50%,50%)" mode="in" interval="100"/>
  <filter effect="blur(1,1)" mode="after"/>
  <padding padding="0 0 0 120"/>
</item>

Color tinting:

<item id="Warning">
  <filter effect="colorfilter(255,0,0)"/>  <!-- Red tint -->
</item>

Best Practices

• Chain multiple draw effects in a single filter using semicolons for better performance
• Don’t mix matrix transformations with draw effects in the same effect attribute
• Use interval attribute only when you have dynamic $${} expressions that need periodic updates
• Use mode="in" (default) for most cases; use mode="before" or mode="after" for special layering needs
• Pair <break/> decorator before filters when you want to apply effects only to subsequent decorators, not the base element

break decorator

You can use break to abort overlaying of other decorators. Break means drawing pipeline starts from empty.

In this example break is used to apply filters only to the image decorator. not to the original content of “Speed” gauge (value and chart).

<item id="Speed" type="chart" chart='line'>
  <break/>
  <image image-zorder="bottom" image-path="images/ui/arrow-circle-right.png" image-scale="0.6"/>
  <filter effect="rotate($${180+Sensor_Value%360},50%,50%)" mode="in" interval="100"/>
  <filter effect="blur(1,1)"/>
  <padding padding="0 0 0 120"/>
</item>

Layout-level attributes and features from changelog

• if — conditional rendering for section or item. Can use sensor names, boolean flags like PortraitLayout, LandscapeLayout, or compound expressions.
• ignore-gauges in section — ignores global gauge attributes for all elements inside the section.
• gauge local definitions — gauge definitions can be declared inside section to scope them locally.
• swap-direction on gauges: swap-direction="true" to change direction of bar or roundbar.
• horizontal-offset in roundbar.
• break decorator — <break/> splits rendering into independent stages.
• maximize-focus, controls="autohide" — useful for dash panels.
• time-scale — used in charts to compress/expand time axis.
• text-evaluator — advanced gauge attribute (returns arbitrary dynamic text), used in tank/description rendering.

Additional attributes and behaviors observed in layout files and changelogs:

• optional / volatile on section (controls visibility rules in some hosts).
• period on item — refresh period in milliseconds.
• precision — numeric formatting or special formats (e.g., 6fixed).
• colspan / rowspan — grid spanning.

Example of a chart item with filters and custom description:

Sensor and expression features

• Sensors can be referenced directly by id in if attributes or as item ids.
• TinyExe helpers and eval expressions available in ecuxml. Variables and functions accessible include: Pi, E, PositiveInfinity, NegativeInfinity and other globals from themes or gauge definitions.
• Filters for sensors (wrap) as above.

TinyExe / eval example (from changelogs):

image-rotate='$${ Sensor_Value - 45 }'

Sensor formatted access example:

<item id="TripTime[fillup]"/> — uses extradata from sensor history APIs.

Sensor lists and autogenerated panels

• section with class="SensorList" and ns="<namespace>" generates a screen listing sensors for a namespace. Use exclude regex to filter out unwanted sensor IDs. Example:

Conditional expressions

• The if attribute can be a simple sensor presence test (e.g., if="STFT1") or a full expression referencing theme variables, day/night flags, layout flags, and sensor values. Example seen: if="SY_ABS_TEVES.ABS_ControlModuleVoltage, Chery_A21_ABS_TRW.ABS_ControlModuleVoltage"

Notes: if can contain comma-separated identifiers which act as OR conditions in practice (layout files often list multiple sensors/namespaces separated by commas).

Interpolation in Expressions

In addition to unadorned expressions, two interpolation styles are available:

• ${ } interpolation: Evaluated once when the layout is built. Use this form for static computations or one-time assignments. Applicable for any attributes.

• $${ } interpolation: Evaluated dynamically, making it suitable for values that update over time (e.g., animations or periodic sensor updates). Only applicable to the selected elements/attributes:

  • text-evaluator, switch[index], visibility, image-rotate, image-path, crop

These forms allow embedding TinyExe expressions within attribute values to achieve either static or dynamic evaluation as needed.

Grid sizing hints

• rows and cols accept comma separated values. Empty entries are flexible cells, numbers provide fixed size hints. Example: rows="30,,," cols="30,,30".

You can nest grid elements to create complex responsive regions.

Other useful attributes and behaviors (from changelog and examples)

• period on item — sets refresh period for the widget.
• precision — formatting precision or special tags like 6fixed.
• description="aside" — places descriptive text aside.
• inherit — reuses widget styling (colors/formatting) from theme or other definitions.
• text-values and custom-units allow mapping numeric values to textual labels or alternate unit systems.
• min-limit / max-limit — clamp values for charts.

Widget and decorator attributes (observed in user.layout)

• type (examples): bar, roundbar, chart, text, static — many visual widgets are selected via type on the item.

• cache-interval — UI cache/refresh hint (milliseconds or unit) used to control smoothing/plotting; frequently used on chart and gauge-like widgets. Example: cache-interval="6".

• red-green — color threshold list; comma-separated numbers indicating color boundaries (interpretation depends on widget). Examples: red-green="100,5", red-green="10,120,150".

• bars-count — number of bars or segments used by bar/roundbar widgets. Example: bars-count="10".

• transparent — true/false whether background is transparent for the widget.

• border-width / border-opacity — visual border control. Example: border-width="3", border-opacity="1".

• colored-value — whether value text is colored according to thresholds: colored-value="true".

• fade-coeff — visual fading coefficient used on charts/gauges to control trail transparency: fade-coeff="0.8".

• width-compression — compress drawing horizontally: width-compression="0.9".

• item-size / item-width / item-height / item-spacing — sizing controls for roundbars and similar widgets (absolute/logical units). Example: item-size="25", item-width="10", item-height="10", item-spacing="20".

• small-radius-delta / small-radis-delta (typo variants observed) — small radius adjustments used for roundbars.

• start-angle / end-angle / radius / vertical-offset — roundbar geometry attributes to control arc start/end and offset.

• item-width/item-height vs item-size — some widgets use item-size while others use width/height pair.

• corn-angle / middle-angle — additional roundbar geometry attributes (observed in test layouts).

• decorator-p (padding) and p-padding — decorator shorthand for padding decorator. Example: decorator-p="padding" p-padding="10 10 10 10".

• decorator-i / decorator-iN pattern — numbered decorators for multiple images on a single item. Use decorator-i1="image" and i1-image-path, i1-image-rotate, i1-image-zorder, i1-image-rotate-align, etc. The unnumbered decorator-i="image" with nested <image> elements is also supported.

  Examples: ```xml

- rotate / scale attributes on nested `<image>` decorators — `rotate` can contain dynamic TinyExe expressions and `scale` applies an image scale.

- custom-units — used on `DateTime` to show time variants: `custom-units="time12"`, `time`, `timesec`, `datetime`, `seconds`.

- border-opacity used on static/test items to preview borders: `border-opacity="1"`.

- numeric `size` on `item` — static items can use numeric `size` values (e.g., `size="72"`, `size="32"`) besides named sizes (`small`, `normal`, `large`).


Common `type` values seen in dashkits:

- `type="text"` — textual rendering of a sensor with `text-values` mapping.
- `type="chart"` — time-series chart for sensor.
- `type="button"` — user-invokable action.

Example: `text-values` and `type=text` usage in dashb3 kits:

`<item id="RPM" wrap="predict(50, 0.7)" text-values="0:" type="text" description="hidden">`

## Advanced: ecuxml and sensor definitions
- sensor definitions and `eval` expressions live in ecuxml files. Key features mentioned across changelogs:
  - `<eval>` expressions for computed sensors
  - `base-data` / `base-raw` for raw bytes
  - functions `get(offset)`, `get_word()` etc.
  - `text` tag with offset/length for string sensors

## Best practices and tips
- Use `if` broadly to keep layout files modular; layout files are only loaded for relevant ECUs, but `if` helps avoid rendering empty sections.
- Use `SensorList` sections for generic sensor browsing screens and `exclude` to filter noisy sensors.
- Prefer nested decorators for complex visuals; they are simpler and localized.
- Use `wrap` filters on noisy sensors (GPS, speed, MAF) for smoother rendering.
- Keep gauges local to section when possible using `ignore-gauges` and local `gauge` declarations to reduce global side-effects.

## DashKit Packages

A DashKit is a folder with metadata, layout files, and resources that HobDrive can download from GitHub and install into the user directory as a separate override.

Official repository: [hobdrive/hobdrive-dashkits](https://github.com/hobdrive/hobdrive-dashkits).

Template for your own packages: [hobdrive/template-dashkits](https://github.com/hobdrive/template-dashkits).

Minimal structure:

```text
community/my-dashkit/
  info.json
  user.layout
  images/
  README.md

info.json:

{
  "name": "My DashKit",
  "version": "1.0.0",
  "description": "Custom dashboard for HobDrive",
  "author": "Your Name"
}

Supported info.json fields:

• name — package name;
• version — version;
• author — author;
• description — description;
• exclude — additional files/folders that should not be downloaded during installation;
• repo, branch, path, url, localPath — service fields that HobDrive adds or uses after download.

The user.layout inside a DashKit uses the same syntax as a regular user user.layout. Images can be placed nearby in images/ and referenced from image-path.

When installing, HobDrive creates a local folder like:

override-<DashKitName>-<repo>-<branch>/

This folder is read as a user override. Therefore, a DashKit can add its own user.layout, images, themes, and other resources without changing the app’s standard files.

In the app, DashKits are opened through Settings -> Dash Panel Settings. The source is specified as a GitHub owner/repo and branch/ref; defaults are hobdrive/hobdrive-dashkits, main.

Appendix — common attributes quick reference

• section: name, title, fixed, optional, order, if, class, ns, exclude, title-height, maximize-focus, controls, volatile
• grid: rows, cols
• item: id, type, text, action, onclick, ondoubleclick, onhold, actions, size, precision, inherit, colspan, rowspan, description, period, wrap
• decorators: image (image-path, image-scale, image-zorder, image-rotate, image-width/image-height), padding, tile, touch-progress, crop, filter, break

Try it — ready templates

Copy these minimal examples into a skin file to try the patterns.

GPS panel (minimal)

<ui>
  <section name="GPS">
    <grid rows=",," cols=",,">
      <item id='Latitude' precision='6fixed' size="normal"/>
      <item id='Longitude' precision='6fixed' size="normal"/>
      <item id='GPSSpeed' precision='1' />
    </grid>
  </section>
</ui>

Fan control (buttons + inherit)

<ui>
  <section name="FAN" fixed="false" if="PortraitLayout">
    <grid rows=",," cols="">
      <item id="FAN_Status" inherit="_ColoredOnOff" size='large'/>
      <item type="button" text="Fan On" action="invoke(FAN_ON)" size='extralarge' />
      <item type="button" text="Fan Off" action="invoke(FAN_OFF)" size='extralarge' />
    </grid>
  </section>
</ui>

Hybrid summary example

<ui>
  <section name="Hybrid">
    <grid rows="30,,," cols="30,,30">
      <item id="Efficiency_Battery" size='huge' />
      <item id="FuelEconomy_NoBattery" size='huge' />
      <item id="BatteryCurrent" />
      <item id="SoC" />
    </grid>
  </section>
</ui>