Skip to content

Custom Components

Profinity provides four ways to create a custom component, from a simple dashboard through to a compiled C# plugin:

  • A Dashboard Component bound only to tags that already exist.
  • A Custom Component built from files and scripts in a profile.
  • That same Custom Component packed, so another installation can add it by name.
  • A full plugin written in C#, compiled against the Profinity SDK, and installed through Components & Plugins.

Once any of them is in a profile, it is monitored, graphed, logged, and used by rules and scripts in the same way as a built-in component.

A Dashboard Component is enough when the page only needs existing tags. A Custom Component is enough when files can describe the behaviour. A packed Custom Component is that same component made installable on another system. A dynamic-link library (DLL) plugin is used when files and scripts are not enough.

flowchart LR
    DC["Dashboard Component"] ~~~ CC["Custom Component"] ~~~ Pack["Packed Custom Component"] ~~~ Plugin["C# plugin"]
The four ways to create a custom component

Comparison

Dashboard Component Custom Component Packed Custom Component C# plugin
Built from Dashboard YAML Files and scripts in a profile The same files, plus component_metadata.yaml An assembly compiled by the author
Typical use A screen of existing tags A new component in one profile The same component on other installations When files and scripts are not enough
CAN database (DBC), scripts, and maps None Optional Optional As the assembly implements them

To make a first Custom Component, follow Make your first Custom Component. This section is the reference for a Custom Component: the files that make one up, including component_metadata.yaml, which names a pack. To pack that folder, use the Component Pack CLI in the SDK. Refer to Using a Custom Component to add one to a profile and attach optional files. For the dashboard itself, refer to the Visual Editor. For a DLL plugin, refer to Developing Plugins.

Component metadata names the DBC file, the dashboard, and the main script for a pack. The main script reads the settings map, and the dashboard binds signals from the DBC file. Menu actions name the action scripts. The firmware scripts named in the firmware actions read the firmware map. Profinity manages the DBC file and the dashboard, and runs the scripts.

flowchart TB
    subgraph Component["Custom Component"]
        Meta["Component metadata"] --> DBC["DBC file"]
        Meta --> Dashboard
        Meta --> Main["Main script"]
        DBC --> Dashboard
        Main --> Settings["Settings map"]
    end
Component metadata names the DBC file, the dashboard, and the main script. The dashboard binds signals from the DBC file, and the main script reads the settings map
flowchart LR
    subgraph Actions["Menu actions"]
        Menu["actions.yaml"] --> ActionScripts["Action scripts"]
    end
    subgraph Firmware["Firmware"]
        FirmwareActions["Firmware actions"] --> FirmwareScripts["Firmware scripts"] --> Map["Firmware map"]
    end
Menu actions name the action scripts. Firmware actions name the firmware scripts, and those scripts read the firmware map
  • Custom Component files lists every file, which ones a pack requires, and which upload field holds each one.
  • DBC, dashboard, and rules covers the CAN database, the component page, and tag rules.
  • Settings covers settings_map.yaml, the extra fields on the settings dialog.
  • Main script covers the service that publishes the component's tags.
  • Menu actions covers actions.yaml, including Connect / Disconnect.
  • Firmware maps covers firmware_map.yaml, the firmware fields on the component.
  • Firmware actions covers firmware.yaml, which names the load, save, and other firmware scripts.
  • Component metadata covers component_metadata.yaml, which names the pack in the catalogue.
  • Component Pack CLI covers the profinity-component-pack commands that pack and install that folder.