SIGCORE UC / DEVELOPERS

.NET API Reference

Use the SigCoreCommon.SigCoreSystem class to communicate with a SigCore UC controller from C# applications.

C# / .NETSource: SigCoreSystem.csDeveloper reference

Overview

SigCoreSystem is the primary application-facing class for connecting to a controller, reading digital and analog inputs, operating outputs, working with PID controllers, and reading or updating configuration. Its asynchronous methods return Task or Task<T>.

The examples below use the SigCoreCommon namespace and a reference to the SigCoreCommon library. Most value-reading methods are request/response operations. Output and configuration setters generally send commands without an applied-state acknowledgment, so read the state back when confirmation matters.

Channel numbering: the Control Panel uses zero-based API channel indices. For example, physical relay R1 is channel 0.

Device address: use the hostname when available, such as SCUC-000019.local, with a reachable IP address as a fallback. The default Core TCP port is 7020.

Getting started

Create a SigCoreSystem, attach event handlers, and call StartAsync(). Use Stop() or dispose the object to end the session.

using System;
using System.Threading.Tasks;
using SigCoreCommon;

class Program
{
    static async Task Main()
    {
        using var device = new SigCoreSystem();
        device.ConnectionStateChanged += state =>
            Console.WriteLine($"Connection: {state}");
        device.DigitalInChanged += values =>
            Console.WriteLine($"DI1: {values[0]}");

        await device.StartAsync("SCUC-000019.local");
        bool input = await device.GetDInAsync(0);
        Console.WriteLine($"DI1 is {input}");

        // Example only: command relay R1 if it is safe to do so.
        // await device.SetRelayAsync(0, true);

        device.Stop();
    }
}

StartAsync() completes after an initial successful connection, handshake, and subscription send. It automatically attempts to reconnect after a lost managed connection. For UI programs, event callbacks may arrive on a non-UI thread, so marshal UI updates to the correct thread.

This sample is based on the public method signatures. It has not been compiled or tested against a connected device as part of this documentation pass.

Connection

For applications that keep a device connection open, prefer managed StartAsync() and monitor ConnectionStateChanged.

StartAsync

public Task StartAsync( string ip, int port = 7020, int timeoutMs = 5000)

Preferred for long-lived connections. Waits for the first successful handshake and subscribe send; thereafter attempts reconnection automatically.

Stop

public void Stop()

Stops managed reconnection and closes the session.

ConnectAsync

public Task<ConnectStatus> ConnectAsync( string ip, int port = 7020, int timeoutMs = 5000)

One-shot connection, without managed reconnection. If using this, call SubscribeAsync separately to receive alerts.

Close

public void Close()

Stops managed reconnect behavior and closes the transport.

Dispose

public void Dispose()

Operation provided by SigCoreSystem.

PingAsync

public async Task<bool> PingAsync(int timeoutMs = 1000)

Performs a connectivity health check with the device using a ping/pong exchange.

Digital inputs

GetDInAsync

public Task<bool> GetDInAsync(uint channel)

Returns the debounced logical digital input state.

Request/response operations can throw TimeoutException if the server does not respond.

GetDInConfigAsync

public Task<DInConfigPayload> GetDInConfigAsync(uint channel)

Retrieves the configuration for a digital input channel.

Request/response operations can throw TimeoutException if the server does not respond.

SetDInConfigAsync

public async Task SetDInConfigAsync(DInConfigPayload config)

Updates the configuration for a digital input channel.

A completed send is not an applied-configuration verification. Read back the corresponding configuration if confirmation is needed.

Relay outputs

GetRelayAsync

public Task<bool> GetRelayAsync(uint channel)

Returns true for an energized relay; false for de-energized.

Request/response operations can throw TimeoutException if the server does not respond.

SetRelayAsync

public async Task SetRelayAsync(uint channel, bool state)

Sends a relay command; completion does not independently confirm physical state. Use GetRelayAsync or RelayChanged for feedback.

GetRelayConfigAsync

public Task<RelayConfigPayload> GetRelayConfigAsync(uint channel)

Returns a RelayConfigPayload with channel settings.

Request/response operations can throw TimeoutException if the server does not respond.

SetRelayConfigAsync

public async Task SetRelayConfigAsync(uint channel, RelayConfigPayload config)

Updates the configuration for a relay output channel.

A completed send is not an applied-configuration verification. Read back the corresponding configuration if confirmation is needed.

Analog inputs

GetAnalogInputAsync

public Task<double> GetAnalogInputAsync(uint channel)

Returns the channel’s analog reading in configured engineering units.

Request/response operations can throw TimeoutException if the server does not respond.

GetAInConfigAsync

public Task<AInConfigPayload> GetAInConfigAsync(uint channel)

Retrieves the configuration for an analog input channel.

Request/response operations can throw TimeoutException if the server does not respond.

SetAInConfigAsync

public async Task SetAInConfigAsync(AInConfigPayload config)

Updates the configuration for an analog input channel.

A completed send is not an applied-configuration verification. Read back the corresponding configuration if confirmation is needed.

Analog outputs

GetAOutValueAsync

public Task<double> GetAOutValueAsync(uint channel)

Retrieves the current value of an analog output channel.

Request/response operations can throw TimeoutException if the server does not respond.

SetAOutValueAsync

public async Task SetAOutValueAsync(uint channel, double value)

Sends an output command; completion does not independently confirm physical output.

GetAOutConfigAsync

public Task<AOutConfigPayload> GetAOutConfigAsync(uint channel)

Retrieves the configuration for an analog output channel.

Request/response operations can throw TimeoutException if the server does not respond.

SetAOutConfigAsync

public async Task SetAOutConfigAsync(AOutConfigPayload config)

Updates the configuration for an analog output channel.

A completed send is not an applied-configuration verification. Read back the corresponding configuration if confirmation is needed.

PID control

GetPIDCurValAsync

public Task<(double setPoint, double processVariable, double output, double tolerance, bool autoMode, double deviation)> GetPIDCurValAsync(uint channel)

Returns a tuple: setPoint, processVariable, output, tolerance, autoMode, deviation.

Request/response operations can throw TimeoutException if the server does not respond.

GetPIDConfigAsync

public Task<PidConfigPayload> GetPIDConfigAsync(uint channel)

Retrieves the configuration for a PID controller channel.

Request/response operations can throw TimeoutException if the server does not respond.

SetPIDConfigAsync

public async Task SetPIDConfigAsync(PidConfigPayload config)

Updates the configuration parameters for a PID controller channel.

A completed send is not an applied-configuration verification. Read back the corresponding configuration if confirmation is needed.

SetPIDSPAsync

public async Task SetPIDSPAsync(uint channel, double sp)

Sets the PID setpoint for the specified channel.

A completed send is not an applied-configuration verification. Read back the corresponding configuration if confirmation is needed.

SetPIDOutputAsync

public async Task SetPIDOutputAsync(uint channel, double output)

Sets the PID manual output value for the specified channel.

A completed send is not an applied-configuration verification. Read back the corresponding configuration if confirmation is needed.

SetPIDTolAsync

public async Task SetPIDTolAsync(uint channel, double tol)

Sets the PID tolerance value for the specified channel.

A completed send is not an applied-configuration verification. Read back the corresponding configuration if confirmation is needed.

SetPIDAutoAsync

public async Task SetPIDAutoAsync(uint channel, bool auto)

Enables or disables automatic PID control mode.

A completed send is not an applied-configuration verification. Read back the corresponding configuration if confirmation is needed.

SetPIDRampTimeAsync

public async Task SetPIDRampTimeAsync(uint channel, double rampTime)

Sets the PID ramp time in seconds.

A completed send is not an applied-configuration verification. Read back the corresponding configuration if confirmation is needed.

SetPIDRampTargetAsync

public async Task SetPIDRampTargetAsync(uint channel, double rampTarget)

Sets the PID ramp target value.

A completed send is not an applied-configuration verification. Read back the corresponding configuration if confirmation is needed.

SetPIDRampAsync

public async Task SetPIDRampAsync(uint channel, bool ramp)

Enables or disables PID ramping behavior.

A completed send is not an applied-configuration verification. Read back the corresponding configuration if confirmation is needed.

ResetPIDAsync

public async Task ResetPIDAsync(uint channel)

Resets the PID controller error state for the specified channel.

Logging

GetLoggingConfigAsync

public Task<LoggerConfigPayload> GetLoggingConfigAsync()

Retrieves the current logging configuration for the device.

Request/response operations can throw TimeoutException if the server does not respond.

SetLoggingConfigAsync

public Task SetLoggingConfigAsync(LoggerConfigPayload config)

Updates the device logging configuration.

A completed send is not an applied-configuration verification. Read back the corresponding configuration if confirmation is needed.

Device and network

GetGlobalConfigAsync

public Task<SystemConfigPayload> GetGlobalConfigAsync()

Retrieves the current global system configuration from the device.

Request/response operations can throw TimeoutException if the server does not respond.

SetGlobalConfigAsync

public async Task SetGlobalConfigAsync(SystemConfigPayload config)

Updates the global system configuration for the device.

A completed send is not an applied-configuration verification. Read back the corresponding configuration if confirmation is needed.

GetNetworkConfigAsync

public Task<NetworkSettingsPayload> GetNetworkConfigAsync()

Retrieves the current network configuration of the device.

Request/response operations can throw TimeoutException if the server does not respond.

SetNetworkConfigAsync

public async Task SetNetworkConfigAsync(NetworkSettingsPayload payload)

Updates the network configuration for the device.

A completed send is not an applied-configuration verification. Read back the corresponding configuration if confirmation is needed.

GetStatusAsync

public async Task<JObject> GetStatusAsync()

Retrieves the current runtime status information from the device.

RestartAsync

public async Task RestartAsync()

Initiates a restart of the device.

Shutdown

public async Task Shutdown()

Initiates a graceful shutdown of the device.

FactoryReset

public async Task<JObject> FactoryReset( string serialNo, string rev, string ver, string host, string sysName, string manifestURL, string sigUrl, string url, string signature)

Waits for a device response (30-second request timeout). This operation changes factory identity/settings; it is not a normal application workflow.

Subscriptions

Managed connections created with StartAsync() subscribe automatically. Subscribe explicitly only when using the one-shot connection API.

SubscribeAsync

public Task SubscribeAsync()

Requests the initial state snapshot and subsequent change alerts. Completion means the subscribe message was sent, not that the snapshot arrived.

Events and properties

Events are emitted for server alerts and connection changes. Event callbacks may run on non-UI threads.

Member	Type	Use
`IsConnected`	`bool`	Underlying TCP connection state; not a full managed-session readiness test.
`ConnectionState`	`SigCoreConnectionState`	Connection lifecycle including Connecting, Handshaking, Subscribing, Connected, Reconnecting and Faulted.
`ReconnectDelay`	`TimeSpan`	Delay between managed connection attempts; defaults to one second.
`IsCommander`	`bool`	Public flag exposed by the client; commander authority and enforcement should be checked against the server implementation.
`DigitalInChanged`	`Action<bool[]>`	Device alert notifying the subscriber of a change.
`AnalogInChanged`	`Action<double[]>`	Device alert notifying the subscriber of a change.
`RelayChanged`	`Action<uint, bool>`	Device alert notifying the subscriber of a change.
`AnalogOutChanged`	`Action<uint, double, bool>`	Device alert notifying the subscriber of a change.
`PIDSPChanged`	`Action<uint, double>`	Device alert notifying the subscriber of a change.
`PIDPVChanged`	`Action<uint, double>`	Device alert notifying the subscriber of a change.
`PIDOutputChanged`	`Action<uint, double>`	Device alert notifying the subscriber of a change.
`PIDTolChanged`	`Action<uint, double>`	Device alert notifying the subscriber of a change.
`PIDDevChanged`	`Action<uint, double>`	Device alert notifying the subscriber of a change.
`PIDAutoChanged`	`Action<uint, bool>`	Device alert notifying the subscriber of a change.
`PIDRampTimeChanged`	`Action<uint, double>`	Device alert notifying the subscriber of a change.
`PIDRampTargetChanged`	`Action<uint, double>`	Device alert notifying the subscriber of a change.
`PIDRampChanged`	`Action<uint, bool>`	Device alert notifying the subscriber of a change.
`LoggerStatusChanged`	`Action<string, bool>`	Device alert notifying the subscriber of a change.
`ConnectionWarning`	`Action<string>`	Connection warning message.
`ConnectionStateChanged`	`Action<SigCoreConnectionState>`	Connection lifecycle transition.

ConnectStatus can be Connected, TcpFailed, ProtocolRejected, or Timeout. SigCoreConnectionState also includes Disconnected.

Configuration payloads

Configuration methods accept and return typed payload objects from SigCoreCommon.Payloads. The following types appear in the public methods of SigCoreSystem; individual property declarations belong to their respective source classes.

Payload	Used for
`DInConfigPayload`	Digital input label, debounce and inversion
`RelayConfigPayload`	Relay label, startup and fail-safe behavior
`AInConfigPayload`	Analog input range, units, averaging, and calibration
`AOutConfigPayload`	Analog output mode, units, and scaling
`PidConfigPayload`	PID loop configuration and tuning
`LoggerConfigPayload`	Logging destination and configuration
`SystemConfigPayload`	Device-wide settings
`NetworkSettingsPayload`	Ethernet, Wi-Fi and hostname settings

Refer to the corresponding Get...ConfigAsync and Set...ConfigAsync methods above for usage. No separate payload-class reference is included in this edition.

Validation notes

This reference documents the application-facing members of SigCoreSystem. Public message-dispatch handlers and transport callbacks are implementation-facing and are intentionally excluded from the application method catalog.

Before publication, compile the sample against the distributed SigCoreCommon library and confirm channel limits, payload member validation, server-side commander permissions, and the device response to rejected commands. These details cannot be fully validated from the interface file alone.

Factory reset behavior: although an older source comment calls it fire-and-forget, the present implementation waits for a result, with a 30-second timeout.