Skip to content

Make your first Custom Component

This tutorial adds a Custom Component named Hello.

Download the Hello component pack

Unzip the pack, then attach the files in the steps that follow. The pack includes a DBC file so this path can bind a CAN signal. It also includes firmware files so the component can show an Output Limit field. A Custom Component does not need a DBC file or firmware files. At the end the component publishes a count tag, lists a Temperature message, shows those values on its page, has Connect / Disconnect in the menu, and shows an Output Limit firmware field. The path takes about 20 minutes.

What you need

  • Profinity 2.3 running, with an active profile.
  • A Desktop, Server, or Enterprise licence, which includes Custom Plugins and Scripting. Refer to Licensing.
  • The Modify components, View tags, View firmware, Modify firmware, and Allow firmware actions permissions. Refer to Roles and permissions.
  • Scripting enabled on the Application Config tab of System Configuration.

Scripts run with application permissions

A script runs inside Profinity with the same operating system permissions as the application, so review any script before running it.

Add the component

To add the component:

  1. Select ADD COMPONENT in the side menu.
  2. Select Custom Component.
  3. Enter Hello as the Name.
  4. Select ADD COMPONENT.

The component appears in the side menu and opens its starter dashboard.

Add a DBC file

A DBC file names the CAN messages the component can decode. This example uses a DBC file. A Custom Component does not need one.

  1. Create a file named hello.dbc that contains this DBC:

    VERSION ""

NS_ :

BS_:

BU_: Sensor

BO_ 256 Temperature: 8 Sensor
 SG_ Value : 0|16@1+ (0.1,0) [0|150] "C" Vector__XXX

    The file describes one message named Temperature with one signal named Value.

  2. On the Hello dashboard, select the three bar icon at the top right to open the settings.

  3. Select the Pack files tab.
  4. Set Upload DBC File (Optional) to hello.dbc.
  5. Select SAVE.

The component menu includes Messages and Signals and Edit DBC File.

Add the main script

A main script is a long-running service that publishes tags for the component.

  1. Create a file named scripts/hello.py that contains this Python:

    import time

_run_count = 0

def on_start():
    global _run_count
    _run_count = 0
    return True

def run():
    global _run_count
    while not Profinity.ScriptCancelled:
        _run_count = _run_count + 1
        Profinity.Tags.SetValue("count", _run_count)
        time.sleep(1)
    return True

    The script publishes a tag named count under the component once a second.

  2. Open the settings from the three bar icon.

  3. Select the Scripts tab.
  4. Set Main Script (Optional) to scripts/hello.py.
  5. Turn on Auto Start Main Script.
  6. Select SAVE.

Profinity starts the main script because Auto Start Main Script is on. Select TAG UTILITIES in the side menu to open the Tag Explorer, expand Hello, and find count. The value increases once a second.

Add a dashboard

The dashboard is the component's page. This file binds count from the main script and DBC/Temperature/Value from the DBC file.

  1. Create a file named hello.yaml that contains this dashboard:

    version: "2.3"
dashboard:
    items:
        - row:
            direction: vertical
            items:
            - group:
                class: statscontainer
                items:
                    - pill:
                        icon:
                            image: IbmWatsonKnowledgeStudio
                        items:
                        - pillgroup:
                            items:
                            - value:
                                label: COUNT
                                precision: 0
                                bind:
                                  - target: value
                                    source: count
                            - value:
                                label: TEMPERATURE
                                precision: 1
                                bind:
                                  - target: value
                                    source: DBC/Temperature/Value

  2. Open the settings from the three bar icon.

  3. Select the Pack files tab.
  4. Set Upload Dashboard (Optional) to hello.yaml.
  5. Select SAVE.

The Hello page shows COUNT updating once a second. TEMPERATURE stays empty until a CAN frame for that message arrives.

Add menu actions

actions.yaml adds items to the component menu. This file adds Connect / Disconnect for the main script.

  1. Create a file named actions.yaml that contains this YAML:

    version: "2.3"
menuActions:
  - id: connect
    displayName: Connect / Disconnect
    icon: Start
    kind: mainScriptToggle

  2. Open the settings from the three bar icon.

  3. Select the Pack files tab.
  4. Set Actions YAML file (Optional) to actions.yaml.
  5. Select SAVE.

The Hello menu includes Connect / Disconnect.

Add firmware

A firmware map adds firmware fields on the component. The load and save scripts are named in firmware.yaml. Refer to Firmware actions. This example uses a firmware map and firmware scripts. A Custom Component does not need them.

  1. Create a file named firmware_map.yaml that contains this YAML:

    version: "2.3"
sections:
  - id: limits
    displayName: Limits
    categories:
      - id: output
        displayName: Output
        fields:
          outputLimit:
            name: Output Limit
            type: UINT16
            default: 100
            units: "%"
            min: 0
            max: 100
            index: 0x10

  2. Create a file named scripts/load_firmware.py that contains this Python:

    Profinity.FirmwareSettings.SetValue("outputLimit", 80)
print("Firmware settings loaded")

  3. Create a file named scripts/save_firmware.py that contains this Python:

    value = Profinity.FirmwareSettings.GetValue("outputLimit")
print(value)

  4. Copy the scripts folder into the Hello folder under components in the active profile. The profile sits in the profiles folder of the artefacts directory.

  5. Create a file named firmware.yaml that contains this YAML:

    version: "2.3"
loadScript: scripts/load_firmware.py
saveScript: scripts/save_firmware.py

  6. Open the settings from the three bar icon.

  7. Select the Pack files tab.
  8. Set Firmware Map YAML file (Optional) to firmware_map.yaml.
  9. Set Firmware Actions YAML file (Optional) to firmware.yaml.
  10. Select SAVE.

The settings show a Limits tab with Output Limit at 100. On Firmware Utilities, select LOAD SETTINGS. Output Limit changes to 80.

Next steps