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, and 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 the behaviour can be described with files, and 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
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. Packing that folder is done with the Component Pack CLI in the SDK. Refer to How to create a Custom Component to attach optional files, and to Using a Custom Component for the component once it is there. For the dashboard itself, refer to the Dashboard visual editor. A DLL plugin is covered on Developing Plugins.

The DBC file and the dashboard sit in the component, and the Component Engine under it manages them. Component metadata names the DBC file, the dashboard, and the main script for a pack. The main script reads the settings map. Menu actions name the action scripts. The firmware scripts named in the firmware actions read the firmware map.

Custom Component Component metadata DBC file Dashboard Main script Settings map Actions Action scripts Menu actions Firmware Firmware scripts Firmware map Firmware actions Component Engine Script Map Configuration metadata DBC Dashboard
The Component Engine sits under the component. It manages the DBC file and the dashboard, and it runs the scripts. Component metadata names the DBC file, the dashboard, and the main script for a pack. The main script reads the settings map. The dashboard binds signals from the DBC file. Firmware actions name the firmware scripts. 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.