Skip to main content

C# Edge SDK Manual

October 21, 2024

Environment

Installing the NuGet package for your project​

dotnet add package EdgeSync360.EdgeHub.Edge.DotNet.SDK

EdgeAgent

Constructor (EdgeAgentOptions options)​

New EdgeAgent object.

EdgeAgentOptions options = new EdgeAgentOptions()
{
    ConnectType = ConnectType.DCCS,                         // Connection type (DCCS, MQTT). The default is DCCS.
    DCCS = new DCCSOptions()                                // If ConnectType is DCCS, the following options must be entered:
    {
        CredentialKey = "", // Credential Key
        APIUrl = ""          // DCCS API Url
    },
    MQTT = new MQTTOptions()                                // If ConnectType is MQTT, the following options must be entered:
    {
        HostName = "127.0.0.1",
        Port = 1883,
        Username = "admin",
        Password = "admin",
        ProtocolType = Protocol.TCP
    },
    AzureIoTHub = new AzureIoTHubOptions()                  // if ConnectType is AzureIoTHub, the following options must be entered:
    {
        HostName = "",
        SASToken = ""
    },
    UseSecure = false,
    AutoReconnect = true,
    ReconnectInterval = 1000,
    NodeId = "5095cf13-f005-4c81-b6c9-68cf038e2b87",        // Get from portal
    Type = EdgeType.Gateway,                                // Configure the edge type as Gateway or Device. The default is Gateway.
    DeviceId = "SmartDevice1",                              // If the type is Device, the DeviceId must be entered. 
    Heartbeat = 60000,                                      // The default is 60 seconds.
    DataRecover = true                                      // Configure whether to recover data when disconnected.
};
EdgeAgent edgeAgent = new EdgeAgent(options);

Azure IoT Hub​

Due to the connection limit of the Azure IoT Hub SDK, the C# SDK can only connect to the Azure IoT Hub using a SASToken. Therefore, you can only connect to the Edge Hub using a SCADA device.

Event​

EdgeAgent has three subscription events.

  • Connected: When EdgeAgent is connected to the IoTHub.
  • Disconnected: When EdgeAgent is disconnected from the IoTHub.
  • MessageReceived: When EdgeAgent receives an MQTT message from the cloud. The message types are as follows:
    • WriteValue: Change the tag value from the cloud.
    • WriteConfig: Change the config from the cloud.
    • ConfigAck: Response to a config upload from the edge to the cloud.
edgeAgent.Connected += edgeAgent_Connected;
edgeAgent.Disconnected += edgeAgent_Disconnected;
edgeAgent.MessageReceived += edgeAgent_MessageReceived;

private void edgeAgent_Connected(object sender, EdgeAgentConnectedEventArgs e)
{
    // Connected
    Console.WriteLine("Connect success!");
}

private void edgeAgent_Disconnected(object sender, DisconnectedEventArgs e)
{
    // Disconnected
    Console.WriteLine("Disconnected.");
}

private void edgeAgent_MessageReceived(object sender, MessageReceivedEventArgs e)
{
    switch (e.Type)
    {
        case MessageType.WriteValue:
            WriteValueCommand wvcMsg = (WriteValueCommand) e.Message;
            foreach (var device in wvcMsg.DeviceList)
            {
                Console.WriteLine("DeviceId: {0}", device.Id);
                foreach (var tag in device.TagList)
                {
                    Console.WriteLine("TagName: {0}, Value: {1}", tag.Name, tag.Value.ToString() );
                }
            }
            break;
        case MessageType.WriteConfig:
            break
        case MessageType.ConfigAck:
            ConfigAck cfgAckMsg = (ConfigAck) e.Message;
            Console.WriteLine("Upload Config Result: {0}", cfgAckMsg.Result.ToString() );
            break;
    }
}

Connect()​

Connect to the IoTHub. When successfully connected, a connected event will be triggered.

edgeAgent.Connect();

Disconnect()​

Disconnect from the IoTHub. When successfully disconnected, a disconnected event will be triggered.

edgeAgent.Disconnect();

UploadConfig(ActionType action, EdgeConfig edgeConfig)​

Upload Node/Device/Tag Config with Action Type (Create/Update/Delete).

EdgeConfig config = new EdgeConfig();
// set node condig
// set device config
// set tag config
bool result = _edgeAgent.UploadConfig( ActionType.Create, config ).Result;

Node Config:

config.Node = new EdgeConfig.NodeConfig();

Device Config:

EdgeConfig.DeviceConfig device = new EdgeConfig.DeviceConfig()
{
    Id = "Device1",
    Name = "Device1",
    Type = "Smart Device 1",
    Description = "Device 1"
};

Analog Tag Config:

EdgeConfig.AnalogTagConfig analogTag = new EdgeConfig.AnalogTagConfig()
{
    Name = "Volt",
    Description = "Volt",
    ReadOnly = false,
    ArraySize = 0
    SpanHigh = 1000,
    SpanLow = 0,
    EngineerUnit = "V",
    IntegerDisplayFormat = 4,
    FractionDisplayFormat = 2,
    SendWhenValueChanged = true		// Data will only be sent when the value changed
};

Discrete Tag Config:

EdgeConfig.DiscreteTagConfig discreteTag = new EdgeConfig.DiscreteTagConfig()
{
    Name = "DTag",
    Description = "DTag" + j,
    ReadOnly = false,
    ArraySize = 0
    State0 = "0",
    State1 = "1",
    State2 = "",
    State3 = "",
    State4 = "",
    State5 = "",
    State6 = "",
    State7 = "",
    SendWhenValueChanged = true		// Data will only be sent when the value changed
};

Text Tag Config:

EdgeConfig.TextTagConfig textTag = new EdgeConfig.TextTagConfig()
{
    Name = "Text",
    Description = "Text",
    ReadOnly = false,
    ArraySize = 0,
    SendWhenValueChanged = true		// Data will only be sent when the value changed
};

Block Config​

Create block config:

EdgeConfig.AnalogTagConfig analogTag = new EdgeConfig.AnalogTagConfig()
{
    Name = "ATag",
    Description = "ATag",
    ReadOnly = false,
    ArraySize = 0,
    SpanHigh = 1000,
    SpanLow = 0,
    EngineerUnit = "V",
    IntegerDisplayFormat = 4,
    FractionDisplayFormat = 2,
    SendWhenValueChanged = true     // Data will only be sent when the value changed
};

EdgeConfig.DiscreteTagConfig discreteTag = new EdgeConfig.DiscreteTagConfig()
{
    Name = "DTag",
    Description = "DTag",
    ReadOnly = false,
    ArraySize = 0,
    State0 = "0",
    State1 = "1",
    SendWhenValueChanged = true     // Data will only be sent when the value changed
};

EdgeConfig.TextTagConfig textTag = new EdgeConfig.TextTagConfig()
{
    Name = "TTag",
    Description = "TTag",
    ReadOnly = false,
    ArraySize = 0,
    SendWhenValueChanged = true     // Data will only be sent when the value changed
};

var blockConfig = new EdgeConfig.BlockConfig("Pump");
blockConfig.AnalogTagList.Add(analogTag);
blockConfig.DiscreteTagList.Add(discreteTag);
blockConfig.TextTagList.Add(textTag);

This block config contain 3 tag, and the block type is Pump, using this block config create two block:

device.AddBlock("Pump01", blockConfig);
device.AddBlock("Pump02", blockConfig);

This will add 6 tag to your device, the first 3 tag will have a prefix of Pump01 and the last 3 tag will have a prefix of Pump02, for example:

SendData(EdgeData data)​

Send the tag value to the cloud.

Random random = new Random();
EdgeData data = new EdgeData();
for (int i = 1; i  T is defined according to the tag type (Analog: double, Discrete: int, Text: string).

```c#
// analog array tag
Dictionary dicVal = new Dictionary();
dicVal.Add("0", 0.5);    // The tag index is 0 and the value is 0.5
dicVal.Add("1", 1.42);    // The tag index is 1 and the value is 1.42
dicVal.Add("2", 2.89);    // The tag index is 2 and the value is 2.89
EdgeData.Tag aTag = new EdgeData.Tag()
{
    DeviceId = "Device1",
    TagName = "ATag",
    Value = dicVal
};

// discrete array tag
Dictionary dicVal = new Dictionary();
dicVal.Add("0", 0);    // The tag index is 0 and the value is 0
dicVal.Add("1", 1);    // The tag index is 1 and the value is 1
dicVal.Add("2", 2);    // The tag index is 2 and the value is 2
EdgeData.Tag dTag = new EdgeData.Tag()
{
    DeviceId = "Device1",
    TagName = "DTag",
    Value = dicVal
};

// text array tag
Dictionary dicVal = new Dictionary();
dicVal.Add("0", "zero");    // The tag index is 0 and the value is "zero"
dicVal.Add("1", "one");    // The tag index is 1 and the value is "one"
dicVal.Add("2", "two");    // The tag index is 2 and the value is "two"
EdgeData.Tag tTag = new EdgeData.Tag()
{
    DeviceId = "Device1",
    TagName = "TTag",
    Value = dicVal
};

Send the tag values in batch to the cloud.

HashSet dataset = new HashSet();
for ( int n = 1; n <= 10; n++ )
{
    Random random = new Random();
    EdgeData data = new EdgeData();
    for ( int i = 1; i <= 1; i++ )
    {
        for ( int j = 1; j <= 5; j++ )
        {
            EdgeData.Tag aTag = new EdgeData.Tag()
            {
                DeviceId = "Device" + i,
                TagName = "ATag" + j,
                Value = random.NextDouble()
            };
            EdgeData.Tag dTag = new EdgeData.Tag()
            {
                DeviceId = "Device" + i,
                TagName = "DTag" + j,
                Value = j % 2
            };
            EdgeData.Tag tTag = new EdgeData.Tag()
            {
                DeviceId = "Device" + i,
                TagName = "TTag" + j,
                Value = "TEST " + j.ToString()
            };
            data.TagList.Add( aTag );
            data.TagList.Add( dTag );
            data.TagList.Add( tTag );
        }
    }
    dataset.Add( data );
}
bool result = edgeAgent.SendData( dataset ).Result;

SendDeviceStatus (EdgeDeviceStatus deviceStatus)​

Send the device status to the cloud when the status changes.

EdgeDeviceStatus deviceStatus = new EdgeDeviceStatus();
for (int i = 1; i <= 2; i++)
{
    EdgeDeviceStatus.Device device = new EdgeDeviceStatus.Device()
    {
        Id = "Device" + i,
        Status = Status.Online
    };
    deviceStatus.DeviceList.Add(device);
}
deviceStatus.Timestamp = DateTime.Now;
bool result = edgeAgent.SendDeviceStatus(deviceStatus).Result;

Property​

Property NameData TypeDescription
IsConnectedbooleanConnection status (read only)

Sample Code

Release Note

  • [1.0.2] - 2024-10-21
    • Add
      • Support Azure IoT Hub device connection which is created from EdgeHub
  • [1.0.1] - 2024-09-09
    • Add
      • Support BlockType that is defined in WISE-PaaS MQTT v1.0.16
  • [1.0.0] - 2024-08-08
    • Add
      • EdgeSync360 EdgeHub EdgeSDK Project initialized, derived from WISE-PaaS DataHub EdgeSDK

Release Note (Archived: WISE-PaaS DataHub EdgeSDK)

  • [1.1.3] - 2021-09-09
    • Added
      • Support send data in batch for high frequency data
  • [1.1.2] - 2021-07-27
    • Updated
      • Remove the strategy of splitting a huge data message into several smaller packets.
    • Removed
      • DataManipulate function.
  • [1.1.1] - 2020-12-14
    • Fixed
      • Custom timestamp SendData() is invalid
  • [1.1.0] - 2020-10-19
    • Added
      • Patameter “SendWhenValueChanged”: If it is true, data will only be sent when the value changed
    • Removed
      • Deprecate time sync function
  • [1.0.12] - 2020-10-15
    • Added
      • UpdateData() for History data manipulation
      • SendData() supports a message contains tag values with multi-timestamp
    • Removed
      • Remove deprecation properties of AnalogTagConfig
  • [1.0.11] - 2020-04-30
    • Added
      • Use NLog for error logging
    • Removed
      • Remove deprecation properties of NodeConfig and DeviceConfig
  • [1.0.9] - 2020-02-11
    • Updated
      • Upgrade related packages
  • [1.0.8] - 2020-02-11
    • Added
      • Add “Delsert” action to the UploadConfig function. Let the cloud directly apply the uploaded config by force.
      • Add a “RetentionPolicyName” property to the DeviceConfig class
    • Updated
      • Remove the “ID”, “Name”, and “Description” properties of the EdgeConfig.NodeConfig class
  • [1.0.7] - 2018-10-02
    • Updated
      • EdgeData Property
      • Split a huge data message into a couple of smaller packages (a data message contains 100 tags at most)
      • Redesign the message object class of MessageReceived
  • [1.0.6] - 2018-08-01
    • Added
      • “IsConnected” property
  • [1.0.5] - 2018-08-01
    • Added
      • Automatic reconnection mechanism
    • Fixed
      • Adjust Connect() and Disconnect() to async function
  • [1.0.4] - 2018-05-15
    • Fixed
      • Cannot use customize time in SendData()
  • [1.0.3] - 2018-05-14
    • Added
      • Support a DCCS connection mechanism
  • [1.0.2] - 2018-03-22
    • Added
      • Support data recovery
  • [1.0.1] - 2018-02-22
  • [1.0.0] - 2017-02-20

On this page ...

Is this helpful?