Skip to content

Edge Xrt V1 to V2 Migration Guide

This guide describes the changes required to migrate from Edge Xrt v1.x to v2.x. Specific changes required that affect the OPC-UA device service to migrate from v2.0 - v2.1 are described in Edge Xrt V2.0 to V2.1 Migration Guide

Device Profiles

Device Resources

The properties field is simplified in a device resource:

  • units is now a single string field and is optional
  • value object is removed and its contents placed directly in the properties object
#v1.x
"deviceResources": [
    {
      "description": "X axis rotation rate",
      "name": "Xrotation",
      "properties": {
        "value": {
          "type": "Int32",
          "readWrite": "RW"
        },
        "units": {
          "type": "String",
          "readWrite": "R",
          "defaultValue": "degrees/sec"
        }
      },
      "attributes": {
        "sequenceType": "arithmetic"
      }
    }
  ]

#v2.x
"deviceResources": [
    {
      "description": "X axis rotation rate",
      "name": "Xrotation",
      "isHidden": false,
      "properties": {
        "valueType": "Int32",
        "readWrite": "RW",
        "units": "degrees/sec"
      },
      "attributes": {
        "sequenceType": "arithmetic"
      }
    }
  ]

Device Commands

get and set ResourceOperation field is replaced with a single readWrite field to eliminate the duplicate definition. index is removed; the resources are ordered as they are specified.

#v1.x
"deviceCommands": [
    {
      "name": "Rotation",
      "get": [
        {
          "index": "0",
          "operation": "get",
          "deviceResource": "Xrotation"
        },
        {
          "index": "1",
          "operation": "get",
          "deviceResource": "Yrotation"
        }
      ],
      "set": [
        {
          "index": "0",
          "operation": "set",
          "deviceResource": "Xrotation"
        },
        {
          "index": "1",
          "operation": "set",
          "deviceResource": "Yrotation"
        }
      ]
    }
  ]

#v2.x
"deviceCommands": [
    {
      "name": "Rotation",
      "readWrite": "RW",
      "resourceOperations": [
        {
          "deviceResource": "Xrotation"
        },
        {
          "deviceResource": "Yrotation"
        }
      ]
    }
  ]

Device Services

OPC-UA

Driver Options

  • N/A

Device Resources

  • nsIndex now represented as an integer instead of a string

  • monitored now represented as a boolean instead of a string

  • publishInterval now represented as a double instead of a string

Device Protocols

  • RequestedSessionTimeout now represented as an integer instead of a string

  • BrowseDepth now represented as an integer instead of a string

  • BrowsePublishInterval now represented as a double instead of a string

  • ConnectionReadingPostDelay now represented as a integer instead of a string

For a full explanation along with valid values for the protocols, resources and driver options, see the OPC-UA device service documentation.

BACnet

Driver Options

NetworkID is replaced with DeviceObject that contains several new settings within it:

  • InstanceID

  • ObjectName

  • VendorName

  • VendorID

  • Location

  • Description

  • ModelName

  • ApplicationSoftware

  • DisableMultiRead changed to MultiRead

    • true and false usage switched around

  • DisableMultiWrite changed to MultiWrite

    • true and false usage switched around

  • DefaultDiscoveryMode changed to DiscoverMode

New options:

  • DiscoverProperties

  • DiscoverObjects

  • DiscoveryDuration

  • DiscoveryRetries

Device Resources

  • The attributes property, type, instance and index are now integers and not strings

  • Any device resources that had Binary as the data type are now uint8array

    • This means that instead of receiving a base64 encoded value back (“MTIz”) a uint8array will be returned of the data ([123])

    • This is the same for writing data where a uint8 array value should be provided instead of base64

  • Device resource for Recipient List (102) property is now a data type ObjectArray instead of Object

    • This means that the list is represented by an array of objects instead of a map keyed by “recipient_list” with a list of objects within the key

    • The recipient list changes from:

      {
  "recipient_list":[
      {
        "confirmed_notify":false,
        "process_identifier":121,
        "recipient":{
            "device_identifier":101
        },
        "from_time":{
            "hour":11,
            "hundredths":0,
            "min":13,
            "sec":14
        },
        "to_time":{
            "hour":22,
            "hundredths":0,
            "min":12,
            "sec":22
        },
        "valid_days": ["MONDAY", "TUESDAY", "FRIDAY", "SUNDAY"],
        "transitions": ["TO_OFFNORMAL", "TO_NORMAL"]
      },
      {
        "recipient":{
            "address":{
              "ip":"192.168.1.128",
              "port":4455
            }
        }
      },
      {
        "confirmed_notify":true,
        "process_identifier":7,
        "recipient":{
            "address":{
              "routed":{
                  "network_number":242,
                  "mac":"aa:bb:cc:dd:ee:ff"
              }
            }
        },
        "from_time":{
            "hour":11,
            "hundredths":0,
            "min":13,
            "sec":14
        }
      }
  ]
}

      To this:

      [
  {
    "confirmed_notify": false,
    "process_identifier": 121,
    "recipient": {
      "device_identifier": 101
    },
    "from_time": {
      "hour": 11,
      "hundredths": 0,
      "min": 13,
      "sec": 14
    },
    "to_time": {
      "hour": 22,
      "hundredths": 0,
      "min": 12,
      "sec": 22
    },
    "valid_days": ["MONDAY", "TUESDAY", "FRIDAY", "SUNDAY"],
    "transitions": ["TO_OFFNORMAL", "TO_NORMAL"]
  },
  {
    "recipient": {
      "address": {
        "ip": "192.168.1.128",
        "port": 4455
      }
    }
  },
  {
    "confirmed_notify": true,
    "process_identifier": 7,
    "recipient": {
      "address": {
        "routed": {
          "network_number": 242,
          "mac": "aa:bb:cc:dd:ee:ff"
        }
      }
    },
    "from_time": {
      "hour": 11,
      "hundredths": 0,
      "min": 13,
      "sec": 14
    }
  }
]

Devices

The DeviceInstance protocol property of a device is now represented as an integer instead of a string:

{
...
      "protocols":{
         "BACnet-IP":{
            "DeviceInstance": 1234
         }
      }
...
}

For a full explanation along with valid values for the protocols, resources and driver options, see the BACnet device service documentation.

S7

Device Resources

The following attribute key changes have been made in v2.x:

  • Type has been changed to type

  • Operation has been changed to operation

  • Start has been changed to start

  • Size has been changed to size

  • DB_number remains the same

The following attribute value changes for operation have been made in v2.x:

  • State has been changed to state

  • Job_res has been chnaged to job_res

  • Err_text has been changed to err_text

  • Conn_state has been changed to conn_state

Values are no longer passed in as strings, numbers are set as integers as shown below:

#v1.x 
{ Type: "DB", DB_number: "1" , Start: "0" , Size: "4" }

#v2.x
{ type: "DB", DB_number: 1 , start: 0 , size: 4 }

Device Protocols

Values are no longer passed in as strings, numbers are set as integers as shown below:

"S7": {
  "IP": "0.0.0.0",
  "Rack": 0,
  "Slot": 2
}

For a full explanation along with valid values for the protocols, resources and driver options, see the S7 device service documentation.

GPS

Driver Options

Driver options for GPS have been replaced by protocol properties. Below is an example of the v1.1 Driver options that have been moved to protocol properties:

  "Driver":{
    "GpsdHostname": "0.0.0.0",
    "GpsdPort": "2947",
    "GpsdMode": "poll"
  }

Device Resources

GPS now has an attribute called data which is used to determine the type of data to return for the request. Previously this was done by request name. For a list of valid attribute values see the Xrt GPS device service documentation.

Device Protocols

Options that were set in the Driver are now set in the device protocol properties. Below is a list of options that were previously Driver options:

  • GpsdHostname
  • GpsdPort
  • GpsdMode

New protocol options have been added for v2.x as shown in the example below:

"GPS": {
  "GpsdConnTimeout": 2500,
  "GpsdHostname": "0.0.0.0",
  "GpsdMode": "poll",
  "GpsdPort": 2947,
  "GpsdRequestTimeout": 5000,
  "GpsdRetries": 5
}

As can be seen, numerical values are written as integers where previously they were written as string. For a full explanation along with valid values for the protocol options see the GPS device service documentation for Edge Xrt.

EtherNet/IP

Driver Options

A new driver option has been introduced to EtherNet/IP for v2.x called ConnectionTimeout. It takes in an integer value to set the wait time to check for each EtherNet/IP UCMM state change. Below is an example of v2.x Driver Options that can be set:

#v2.x
"Driver": {
  "NetworkInterface": "docker0",
  "ConnectionTimeout" : 3000
  }

Device Resources

  • All numerical values in the Device Resources have now been changed from being written as strings in v1.x to their literal types in v2.x.

  • Ability to use hex values in resources has been removed in v2.x.

  • The readOnChange field used on implicit types has now been removed in v2.x.

Below is an implicit and explicit resource from Edge Xrt v1.x:

#v1.x
  {
      "name": "DI7",
      "description": "Digital Input 7",
      "attributes": {
        "type": "T2O",
        "offsetBytes": "0",
        "offsetBits": "7",
        "readOnChange": "true"
      },
      "properties": {
        "value": {
          "type": "Bool",
          "readWrite": "R"
        }
      }
    },
    {
      "name": "IdentityClass",
      "description": "Get Attributes All Command to Identity Object Instance",
      "attributes": {
        "type": "EM",
        "objClass": "0x01",
        "instID": "1",
        "serviceCode": "0x01"
      },
      "properties": {
        "value": {
          "type": "String",
          "readWrite": "R"
        }
      }
    }

In Edge Xrt v2.x, we convert the hex values to integers, and do not pass in numerical values as strings. The above resources would look like the extract below when used in Edge Xrt v2.x:

#v2.x
   {
      "name": "DI7",
      "description": "Digital Input 7",
      "attributes": {
        "offsetBits": 7,
        "offsetBytes": 0,
        "type": "O2T"
      },
      "properties": {
        "readWrite": "W",
        "valueType": "Bool"
      }
    },
    {
    "name": "IdentityClass",
    "description": "Get Attributes All Command to Identity Object Instance",
    "attributes": {
      "instID": 1,
      "objClass": 1,
      "serviceCode": 1,
      "type": "EM"
    },
    "properties": {
      "readWrite": "R",
      "valueType": "String"
    }
  },

Device Protocols

  • All numerical values in Device Protocols have now been changed from being written as strings in v1.x to their literal types in v2.x.

For a full explanation along with valid values for the Protocols, Resources and Driver Options, see the EtherNet/IP device service documentation.

EtherCAT

Driver Options

The CycleTime_us option is now an unsigned integer rather than a string.

Device Resources

Various attributes which were formerly strings are now unsigned integers:

  • index
  • subIndex
  • byteLength
  • value
  • offsetBytes
  • offsetBits

The RxPDO and TxPDO attributes used for AssignPDO resources should be arrays of unsigned integers. Note that these must be decimal, the use of the 0x prefix for hex numbers is not supported.

Device Protocols

Various protocol values which were formerly strings are now unsigned integers:

  • NetworkIndex
  • SerialNumber
  • SyncShift
  • SyncMode
  • Sync0Cycle
  • Sync1Cycle
  • Sync01Cycle

For a full explanation along with valid values for the Protocols, Resources and Driver Options, see the EtherCAT device service documentation.

PROFINET

Device Resources

The Q-offset, I-offset and byteLength attributes are now unsigned integers rather than strings. The new I-offset-bits attribute is introduced for boolean values, this specifies which bit is to be read. For example:

#v1.x
"attributes": { "I-offset": "5.2" }

#v2.x
"attributes": { "I-offset": 5, "I-offset-bits": 2 }

Device Protocols

The Q-base and I-base protocol values are now unsigned integers rather than strings.

For a full explanation along with valid values for the protocols, resources and driver options, see the PROFINET device service documentation.

AzureSphere

The device twin mechanism is still in use for configuring Edge Xrt dynamically in the Azure Cloud/CLI.

All the respective Device Service changes to the Profiles, Device Resources, Protocols, and Driver Options apply to Device Twin Xrt configurations for AzureSphere.

Device Resources

Below is an example of a BACnet Device Resource in v1.x and how it now looks in v2.x:

#v1.x
{
  "name": "Accumulator0",
  "attributes": {
      "instance": "0",
      "property": "85",
      "type": "23"
  },
  "properties": {
      "value": {
          "readWrite": "RW",
          "type": "uint64"
      }
  }
}

#v2.x
{
  "name": "Accumulator0",
  "attributes": {
    "instance": 0,
    "property": 85,
    "type": 23
    },
  "properties": {
    "readWrite": "RW",
    "valueType": "uint64"
  }
}

Devices

Devices, along with all the above mentioned changes, are now loaded in as vectors rather than maps. Below is an example of a BACnet Device Configuration in v1.x and how it now looks in v2.x:

#v1.x
"Devices": {
  "BacnetSimulator": {
    "profile": "bacnet-simulator",
    "protocols": {
      "BACnet-IP": {
        "DeviceInstance": "2749",
        "Port": "47808"
        },
      "BACnetSupportedServices": {
        "DS-RPM-B": "true",
        "DS-WPM-B": "true"
        }
      }
    }
  },

#v2.x
"Devices": [
  {
    "name": "BacnetSimulator",
    "profileName": "bacnet-simulator",
    "protocols": {
            "BACnet-IP": {
                "DeviceInstance": 2749,
                "Port": 47808
            },
            "BACnetSupportedServices": {
                "DS-RPM-B": "true",
                "DS-WPM-B": "true"
            }
        }
    }
]

Schedules

The Resources field in schedules are loaded in as vectors rather than maps. Below is an example of a BACnet Schedule Configuration in v1.x and how it now looks in v2.x:

#v1.x
"Schedules": [
  {
    "device": "BacnetSimulator",
    "resource": "Accumulator0",
    "interval": 4000000,
    "name": "schedule1"
    }
]

#v2.x
"Schedules": [
  {
    "device": "BacnetSimulator",
    "resource": [
      "Accumulator0"
      ],
    "interval": 4000000,
    "name": "schedule1"
  }
]

For more information about Xrt device twin configurations for AzureSphere see the Azuresphere User Documentation