Functions SDK

A function is a C# class that Proxus compiles and runs on the edge gateways you choose. It sees the values the gateway reads, can change or add to them, and can save values, call other systems and send notifications. This page describes the programming interface. How to create, build and deploy a function in the hub is in Functions.

The shape of a function

A function is one class that derives from FunctionBase and passes the three constructor arguments on unchanged. The gateway creates it once when the function is deployed and stops it when it is removed or redeployed.

using System;
using Proxus.Common;
using Proxus.Common.Messages;
using Proxus.SDK.BaseFunctions;

namespace Proxus.Functions {

// Adds a calculated tag to every reading of the case packers and warns when the motor current is high.
public sealed class PackerPowerFunction(object sys, object log, object config) : FunctionBase(sys, log, config) {

    private const double CurrentLimit = 45.0;          // A
    private const string ChannelName = "Shift supervisors";
    private DateTime _lastWarning = DateTime.MinValue;

    protected override void OnStarted() {
        // Receive the readings of every device on this gateway. Use device IDs instead of "*" to narrow it.
        Subscriptions?.Add(new SubscriptionContext {
            Type = typeof(TransportData),
            Topics = ["*"]
        });

        // Write a heartbeat to the function log every minute.
        ExecuteScheduledTask(TimeSpan.FromMinutes(1), () => LogInformation("PackerPowerFunction is running"));

        base.OnStarted();
    }

    protected override void OnMessageReceive(FunctionContext ctx) {
        if (ctx.Message is not TransportData data) return;

        var deviceName = data.GetMetaDataValueByKey("DeviceName") ?? ctx.Topic;
        if (!deviceName.StartsWith("LYS_PACKER_", StringComparison.Ordinal)) return;

        var current = data.GetPayloadValueByName<double>("MotorCurrent");
        if (current <= 0) return;

        // A new tag on the same reading: it is stored and published like a tag read from the machine.
        var powerKw = Math.Round(400 * current * Math.Sqrt(3) * 0.85 / 1000, 2);
        data.SetPayloadValue("MotorPower", powerKw, "kW");

        if (current > CurrentLimit && DateTime.UtcNow - _lastWarning > TimeSpan.FromMinutes(10)) {
            _lastWarning = DateTime.UtcNow;
            LogWarning($"{deviceName}: motor current {current} A is above {CurrentLimit} A");
            SendNotification(ChannelName, $"{deviceName}: motor current {current} A is above {CurrentLimit} A");
        }
    }
}
}

Rules that follow from how the gateway runs functions:

• Add your subscriptions in OnStarted, then call base.OnStarted(). The base method connects the subscriptions, so a subscription added after it receives nothing.
• OnMessageReceive is called for each reading, before the reading is stored, sent to outbound targets or run through pipelines. A payload you add or change on the TransportData object goes on with the reading.
• Readings that a function itself produced (BackToPipeline, Save) are not delivered to functions again, so a function cannot loop on its own output.
• Keep OnMessageReceive short. Start long work (HTTP calls, database queries) as a task and do not wait for it.

Lifecycle

FunctionContext has Topic (for device data, the device ID) and Message (the object received, usually a TransportData).

Subscriptions

Subscriptions?.Add(new SubscriptionContext {
    Type = typeof(TransportData),
    Topics = ["69", "70"],       // device IDs, or "*" for every device on the gateway
    EdgeGateways = ["2"]         // optional: also receive what gateway 2 publishes with PublishToEdgeGateways
});

Reading and changing a reading

A reading is a TransportData: a list of Payload (one per tag) and a list of MetaData (facts about the reading, such as DeviceId, DeviceName, Enterprise, Site, Area, ProcessCell, EquipmentModule).

Payload has Key, Value (text), NumericValue, Type, Unit and Time.

Sending data on

The MQTT helpers connect to the broker given by the overridable properties MqttBrokerHost (default "localhost"), MqttBrokerPort (1883), MqttBrokerUser and MqttBrokerPassword (empty). Override them to reach another broker, or set MqttBrokerUser to the gateway's MasterToken to use the built-in one.

Devices, notifications and databases

Timers

Timers started with these methods are stopped for you when the function stops.

Logging and failures

LogTrace, LogDebug, LogInformation, LogWarning, LogError and LogCritical each take (object message, bool asJson = false). The lines appear under Logs on the function and in System logs, prefixed with the class name.

Two settings in the [UserFunctions] section of the gateway's configuration limit a misbehaving function:

There is no time or memory limit per call. A function that blocks or loops holds up the gateway's processing of the devices it subscribes to, so keep the work in OnMessageReceive small.

What the compiler offers

Your code can use the .NET base library (collections, LINQ, tasks, HttpClient, sockets, JSON, XML), the Proxus types above, MQTT client types and ML.NET. There is no package manager: a library outside this set cannot be referenced.

For safety, code that uses these namespaces is refused when it is built, with the message Blacklisted namespace used: <name>. Reason: ...:

Build errors are listed as <code> (line <n>, column <n>): <message>.

Templates

Templates on the function screen starts a function from one of these:

What's next

• Functions: create, build, deploy and read the logs of a function in the hub.
• Pipelines and rules: when a function is the right tool and when a pipeline or rule is.
• Troubleshoot automation: compile and deploy errors.