Go Edge SDK Manual

October 21, 2024

Environment

Installation

• Via the command line:

go get github.com/EdgeHub-Repo/dc-edge-sdk-golang

EdgeAgent

Constructor (EdgeAgentOptions options)

New EdgeAgent object.

options := agent.NewEdgeAgentOptions()                  // Set default value
options.NodeID = "" // Get from portal
options.DeviceID = ""                   // If the type is Device, the DeviceID must be entered.
options.Type = agent.EdgeType["Gateway"]                // Configure the edge as a Gateway or Device. The default setting is Gateway.
options.ReconnectInterval = 1, 				// The MQTT reconnect interval in seconds. The default setting is 1.
options.HeartBeatInterval = 60                          // The default setting is 60 seconds.
options.DataRecover = true                              // Whether to recover data when disconnected. The default setting is True.
options.ConnectType =  agent.ConnectType["DCCS"]        // Connection type (DCCS, MQTT,AzureIoTHub). The default setting is DCCS.
options.UseSecure = false
options.MQTT = &agent.MQTTOptions {                     // If connectType is MQTT, the following options must be input:
  HostName:     "127.0.0.1",
  Port:         1883,
  UserName:     "admin",
  Password:     "admin",
  ProtocolType: Protocol["TCP"],                        // MQTT protocol (TCP, WebSocket). The default setting is TCP.
}
options.DCCS = &agent.DCCSOptions {                     // If connectType is DCCS, the following options must be input:
  URL: "",                                // DCCS API URL
  Key: "",                         // Credential key
}
options.AzureIoTHubOptions = &agent.AzureIoTHubOptions {              // If connectType is AzureIoTHub, the following options must be input:
  ConnectionString : "",
}
edgeAgent := agent.NewAgent(options)

Azure IoT Hub

Due to the connection limit of the Azure IoT Hub SDK, the GO SDK can only connect to the Azure IoT Hub using a connection string. Therefore, you can only connect to the Edge Hub using a EdgeLink device.

Event

EdgeAgent has three subscription events.

• Connected: When EdgeAgent is connected to the IoTHub.
• Disconnected: When EdgeAgent is disconnected to 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.
  • ConfigAck: Response to a config upload from the edge to the cloud.

edgeAgent.SetOnConnectHandler(onConnectHandler)
edgeAgent.SetOnDisconnectHandler(onDisconnectHandler)
edgeAgent.SetOnMessageReceiveHandler(onMessageReceiveHandler)

func onConnectHandler (a agent.Agent) {
  fmt.Println("Connect success")
}
func onDisconnectHandler (a agent.Agent) {
  fmt.Println("Connect success")
}
func onMessageReceiveHandler (args agent.MessageReceivedEventArgs) {
  msgType := args.Type
  msg := args.Message

  switch msgType {
    case MessageType["WriteValue"]:  // message format: WriteDataMessage
      for _, device := range message.(agent.WriteDataMessage).DeviceList {
        fmt.Println("DeviceID:", device.ID)
        for _, tag := range device.TagList {
          fmt.Println("TagName:", tag.Name, "Value:", tag.Value)
        }
      }
    case MessageType["ConfigAck"]:  // message format: ConfigAckMessage
      fmt.Println(message.(agent.ConfigAckMessage).Result)
  }
}

Connect ()

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

edgeAgent.Connect()

Disconnect ()

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

edgeAgent.disconnect()

UploadConfig (ActionType action, EdgeConfig edgeConfig)

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

config = agent.EdgeConfig()

result = edgeAgent.UploadConfig(agent.Action["Create"], config)

Node config setting

nodeConfig = agent.NewNodeConfig()
nodeConfig.SetType(agent.EdgeType["Gateway"])# EdgeType (Gatewat, Device)

// add node config
config.Node = nodeConfig

Device config setting

deviceConfig = agent.NewDeviceConfig("deviceID")
deviceConfig.SetName("DeviceName")
deviceConfig.SetType("Device Type")
deviceConfig.SetDescription("Description")

// add devices
nodeConfig.DeviceList = append(nodeConfig.DeviceList, deviceConfig)

Analog tag config setting

analogConfig = agent.NewAnaglogTagConfig("AnalogTag")
analogConfig.SetDescription("AnalogTag")
analogConfig.SetReadOnly(True)
analogConfig.SetArraySize(0)
analogConfig.SetSpanHigh(10)
analogConfig.SetSpanLow(0)
analogConfig.SetEngineerUnit("cm")
analogConfig.SetIntegerDisplayFormat(4)
analogConfig.SetFractionDisplayFormat(2)

// add tags
deviceConfig.AnalogTagList = append(deviceConfig.AnalogTagList, analogConfig)

Discrete tag config setting

discreteConfig = agent.NewDiscreteTagConfig("DiscreteTag")
discreteConfig.SetDescription("DiscreteTag")
discreteConfig.SetReadOnly(false)
discreteConfig.SetArraySize(2)
discreteConfig.SetState0("1")
discreteConfig.SetState1("0")
// discreteConfig.SetState2()
// discreteConfig.SetState3()
// discreteConfig.SetState4()
// discreteConfig.SetState5()
// discreteConfig.SetState6()
// discreteConfig.SetState7()
)

// add tags
deviceConfig.DiscreteTagList = append(deviceConfig.DiscreteTagList, discreteConfig)

Text tag config setting

textConfig = agent.NewTextTagConfig("TextTag")
textConfig.SetDescription("TextTag")
textConfig.SetReadOnly(true)
textConfig.SetArraySize(0)

// add tags
deviceConfig.TextTagList = append(deviceConfig.TextTagList, textConfig)

Block Config

Create block config:

 var blockConfig = agent.NewBlockConfig("Pump")
 blockConfig.AnalogTagList = append(blockConfig.AnalogTagList, analogConfig)
 blockConfig.DiscreteTagList = append(blockConfig.DiscreteTagList, discreteConfig)
 blockConfig.TextTagList = append(blockConfig.TextTagList, textConfig)

for idx := 0; idx < analogNum; idx++ {
	config := generateAnalogConfig(idx + 1)
	blockConfig.AnalogTagList = append(blockConfig.AnalogTagList, config)
}
for idx := 0; idx < discreteNum; idx++ {
	config := generateDiscreteConfig(idx + 1)
	blockConfig.DiscreteTagList = append(blockConfig.DiscreteTagList,config)
}
for idx := 0; idx < textNum; idx++ {
	config := generateTextConfig(idx + 1)
	blockConfig.TextTagList = append(blockConfig.TextTagList, config)
}

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

deviceConfig.AddBlock("Pump01", blockConfig)
deviceConfig.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 a tag value to the cloud

// deviceNum: 3
// tagNum: 5
for i := 1; i < 4; i++ {
  for j := 1; j &lt; 6; j++ {
    deviceID := fmt.Sprintf(&quot;%s%d&quot;, &quot;Device&quot;, i)
    tagName := fmt.Sprintf(&quot;%s%d&quot;, &quot;ATag&quot; + j)
    value := random.uniform(0, 100)
    tag := agent.EdgeTag{
      DeviceID: deviceID,
      TagName: tagName,
      Value: value,
    }
    edgeData.TagList = append(edgeData.TagList, tag)
  }
  for j := 1; j < 6; j++ {
    deviceID := fmt.Sprintf(&quot;%s%d&quot;, &quot;Device&quot;, i)
    tagName := fmt.Sprintf(&quot;%s%d&quot;, &quot;DTag&quot; + j)
    value := random.randint(0,99)
    value = value % 2
    tag := agent.EdgeTag{
      DeviceID: deviceID,
      TagName: tagName,
      Value: value,
    }
    edgeData.TagList = append(edgeData.TagList, tag)
  }
  for j := 1; j < 6; j++ {
    deviceID := fmt.Sprintf(&quot;%s%d&quot;, &quot;Device&quot;, i)
    tagName := fmt.Sprintf(&quot;%s%d&quot;, &quot;TTag&quot; + j)
    value = random.uniform(0, 100)
    value = &quot;TEST&quot; + str(value)
    tag = EdgeTag(deviceID, tagName, value)
    tag := agent.EdgeTag{
      DeviceID: deviceID,
      TagName: tagName,
      Value: value,
    }
    edgeData.TagList = append(edgeData.TagList, tag)
  }
}

result = edgeAgent.SendData(edgeData)

An array tag value must use “map”. The value is defined according to the tag type. (Analog: float64, Discrete: int32, Text: string).

# analog array tag
dicVal := map[string]int {
  "0": 0.5,
  "1": 1.42,
}
tag := agent.EdgeTag{
  DeviceID: "deviceID",
  TagName: "ATag",
  Value: dicVal
}

# discrete array tag
dicVal = map[string]int {
  "0": 0,
  "1": 1,
}
tag = agent.EdgeTag{
  DeviceID: "deviceID",
  TagName: "DTag",
  Value: dicVal.
}

# text array tag
dicVal = map[string]int {
  "0": "zero",
  "1": "one"
}
tag = agent.EdgeTag{
  DeviceID: "deviceID",
  TagName: "TTag",
  Value: dicVal
}

SendDeviceStatus (EdgeDeviceStatus deviceStatus)

Send the device status to the cloud when the status is changed.

status := agent.EdgeDeviceStatus{
  TimeStamp: time.Now(),
}

// deviceNum: 3
for i := 1; i < 4; i++ {
  s := {
    ID: fmt.Sprintf(&quot;%s%d&quot;, &quot;Device&quot;, i),
    Status: agent.Status[&quot;Online&quot;], // Online, Offline
  }
  status.DeviceList = append(status.DeviceList, s)
}

result = edgeAgent.SendDeviceStatus(status)

Property

Property Name	Data Type	Description
IsConnected	Boolean	Connection Status (read only)

Sample Code

• GitHub
  • dc-edge-sdk-golang-sample

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.0.8] - 2021-09-09
  • Added
    • Add “SendWhenValueChanged” parameter in AnalogTagConfig, DiscreteTagConfig, and TextTagConfig
• [1.0.7] - 2021-09-09
• [1.0.6] - 2020-10-13
  • Fixed
    • Fix customized timestamp parsing incorrect
• [1.0.5] - 2020-09-30
  • Fixed
    • Solved some package lost after reconnecting from losing internet connection in macOS and Linux
    • Able to upload the self-bring-in timestamp in SendData()
• [1.0.4] - 2020-08-07
  • Added
    • Use go mod to manage libraries
  • Fixed
    • MQTT over SSL connection issue
    • Data recovery issue
• [1.0.3] - 2020-02-18
  • Added
    • Automatic rounding down of tag value by “FractionDisplayFormat”
    • Keep the last uploaded config for internal data processing
• [1.0.2] - 2019-12-27
  • Added
    • Add the “RetentionPolicyName” property to DeviceConfig. This will automatically bind the Retention Policy to your device on the cloud.
  • Changed
    • Remove the deprecation properties of NodeConfig: name and description
• [1.0.1] - 2019-12-04
  • Added
    • Add “Delsert” action of config uploading
  • Fixed
    • Real-time data is always delayed by a couple of seconds
    • Some panic issues
• [1.0.0] - 2019-11-20