Skip to content

Control Changes

App to App

Control Changes can be sent from one Kelvin SmartApp to another.

This can also operate even if the edge device does not have any Internet connection.

The only stipulation is that the Kelvin SmartApp™ that produces the control change object and the Kelvin SmartApp™ or Connector that consumes the control change object are hosted on the same Cluster and have local communications if they are hosted on different Nodes.

Examples

"Basic Usage"

To set this up, the app.yaml file of the Kelvin SmartApp™ that produces the control change object must define the output Data Stream with the control_change key.

app:
  type: kelvin
  kelvin:

    outputs:
    - data_type: number
      name: motor_speed_set_point
      control_change: true

Then you can produce a Control Change to be sent to another Kelvin SmartApp™.

This is a simple Control Change example.

Read the Control Change Produce page to see all the types of Control Changes you are produce.

from datetime import timedelta

from kelvin.application import KelvinApp
from kelvin.message import ControlChange
from kelvin.krn import KRNAssetDataStream

(...)

# Create and Publish a Control Change
await app.publish(
    ControlChange(
        resource=KRNAssetDataStream("my-motor-asset", "motor_speed_set_point"),
        payload=1000,
        expiration_date=timedelta(minutes=5)
    )
)

and the Kelvin SmartApp™ that consumes the control change object must define the input Data Stream with the control_change key.

app:
  type: kelvin
  kelvin:

    inputs:
    - data_type: number
      name: motor_speed_set_point
      control_change: true

Then you can consume a Control Change that has been sent by another Kelvin SmartApp™.

async def on_control_change(cc: AssetDataMessage) -> None:

    """Callback when a Control Change is received."""
    print("Received Control Change: ", cc)

You can also see the control change status with this code;

from kelvin.message import ControlChangeStatus

(...)

async def on_control_status(cc_status: ControlChangeStatus) -> None:
    """Callback when a Control Status is received."""
    print("Received Control Status: ", cc_status)

If the consumer is a Connector, then this key is automatically set using the Kelvin Connector setup process. It will automatically receive the control change object directly from the Kelvin SmaartApp™ without requiring any connection to the Kelvin Cloud.

Event Callbacks

Concepts Made Simple

A callback in Python is like a WhatsApp notification. Imagine you’re waiting for a message from a friend, but instead of constantly checking your phone, you let WhatsApp notify you when the message arrives. You only get alerted when the specific event—your friend’s message—actually happens.

In Python, a callback works similarly. Instead of constantly checking for updates, the program waits until a certain event occurs, and when it does, the callback function (like the WhatsApp notification) is triggered to perform a specific action.

Event Callbacks are functions that are triggered when certain events happen, such as new time series data is received or a control change is initiated.

Video Tutorial

You can watch this Event Callback video tutorial which will show you how to program and test it on you local machine with the Kelvin test data generator Python script.

Copy the code in the Video Tutorial

In the following chapters after the video tutorial you can see and copy all the scripts shown in the video tutorial.

Control Change Data Event

When any new control change is initiated, a callback event is created.

Detailed Explanation of Parameters

Response Parameters

  • id: UUID('db18aaaf-9a70-4c3e-babb-b7571867871f')

    • Description: A unique random generated UUID as the key id for the control change object.

  • type: KMessageTypeData('data', 'pt=number')

    • Options: number, boolean, string
    • Description: The format of the data to expect.

  • trace_id: UUID('db18aaaf-9a70-4c3e-babb-b7571867871f')

  • timestamp: datetime.datetime(2024, 10, 28, 11, 51, 44, 601689, tzinfo=datetime.timezone(datetime.timedelta(seconds=25200), '+07'))

    • Description: The time of recording of the time series data in the local computer's timezone.

  • resource: KRNAssetDataStream(asset='test-asset-1', data_stream='sa-rw-number')

    • Description: The Asset and Data Stream names associated with the control change.

  • payload: The actual value in the declared type key format.

The full code is given here for the main.py script.

Detailed Code Explanations

Click on the for details about the code

main.py
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
import asyncio # (1)!

from kelvin.application import KelvinApp # (2)!
from kelvin.message.primitives import AssetDataMessage # (3)!

async def on_control_change(msg: AssetDataMessage): # (4)!
    # Get Asset and Value
    asset = msg.resource.asset
    value = msg.payload

    print("Received Control Message: ", msg)
    print(f"Asset: {asset}, Value: {value}")

async def main() -> None:  # (5)!

    # Initialize the SmartApp
    app = KelvinApp()

    # Define the function to call when event callback is triggered
    app.on_control_change = on_control_change

    # Connect the SmartApp with the Kelvin Platform
    await app.connect()

    # Force the Application to run forever
    while True:
        await asyncio.sleep(1)

if __name__ == "__main__":
    asyncio.run(main())
  1. The asyncio module is used to ensure the program is running in asynchronous mode. This allows code, especially that which typically waits such as I/O-bound operations, to effectively execute in parallel thereby making the most efficient use of processor time.
  2. The KelvinApp class is used to initlize and connect the Kelvin SmartApp™ to the Kelvin Platform.
  3. The AssetDataMessage is a class representing the structure and properties of the asset data messages which will be held in an instance called msg.
  4. The on_control_change callback function is triggered automatically whenever a new control change object is initiated to an Asset associated with the Kelvin SmartApp™. It serves as an event handler to process incoming control change data in real time, ensuring that relevant review, actions or data updates occur immediately upon receipt.
  5. The main function initializes the Kelvin SmartApp™, connects it to the Kelvin Platform, and configures an event callback to execute a specific function whenever a new control change is initiated for an asset associated with the Kelvin SmartApp™.

When you run this Python script, the following output will be view in the terminal or logs;

Output from Program
Received Control Message:  id=UUID('44ba34f7-6689-464f-9804-7bcc0e347f68') type=KMessageTypeData('data', 'pt=number') trace_id=None source=None timestamp=datetime.datetime(2024, 10, 28, 14, 29, 41, 553346, tzinfo=datetime.timezone(datetime.timedelta(seconds=25200), '+07')) resource=KRNAssetDataStream(asset='test-asset-1', data_stream='sa-cc-number') payload=20.0

Asset: test-asset-1, Value: 20.0

Data Generator for Local SmartApp Testing

Easily test your SmartApp locally on your computer.

Comprehensive documentation is available for the Generator Tool. Click here to learn how to use this event callback script with the Test Generator on the "Test a SmartApp" ⟹ "Generator" page.