Adapters configuration
Purpose: Each Adapter is configured through its relevant Module Twin Desired Properties JSON in Azure IoT Hub. Each adapter expects its own specific set properties and some common properties. These configurations can be found and changed through Upkip Administration or Azure IoT Hub Devices. Different adapters are implemented as Modules in IoT devices running on Windows machines or Modules in IoT Edge devices running on Linux machines in manufacturer premises.
- Adapters Configuration in Upkip Administration
- Adapters as Windows modules
- Adapters as Linux modules
Adapters Configuration in Upkip Administration
Precondition: Log in Upkip Administration with Microsoft user. Select Organization. Select Gateways. From TAB Modules, select module and press Edit.
Figure 1: Upkip Gateways Device modules configuration
- The module desired and reported configurations are shown as JSON with all specific properties for the adapter.
Users can make changes only in Desired configuration and click the Save button.
- The configuration is updated in Azure IoT Hub.
The Desired configuration is filled by developers.
The Reported configuration is returned by Azure.
Both configurations are expected to be the same.
Adapters Configuration in IoT Hub
Precondition: Log in to azure portal with the registered user. Select IoT Hub.
Figure 2: IoT Hub - IoT Edge device
Select IoT devices à the list of devices is shown.
Click on some device:
- The list of modules is shown. Modules are different adapters in the platform.
When clicking on some module there is opened Module Identity Details page.
Figure 3: IoT Hub - IoT Edge device - Module Details
When clicking on Module Identity Twin
- The adapter configuration is opened with filled JSON – desired and reported configurations. Users can make some changes in the JSON with the desired configuration and click Save.
- The adapter (Module) configuration is saved and updated.
Figure 4: IoT Hub - IoT Edge device - Module Identity Twin
Adapters as Windows modules
Purpose: Adapters are implemented as windows IoT Hub/IoT devices/Modules. They are used to support connection and communication with the corresponding type of machines, equipment, or protocols. They run on Windows machines in the manufacturer's premises.
Below are described configurations for the following adapters implemented as IoT Hub/IoT devices/Windows Modules:
- Adapter for Heidenhain machines
- Adapter for Fanuc controllers
- Adapter for MTConnect protocol
- Adapter for OPC protocols
- Adapter for Siemens S7 controllers
- Adapter for ABB Robot controllers
- Adapter for Balluf controllers
- Adapter for SQL DB communication
- MELSEC protocol adapter
Each Windows adapter contains:
- Three ConnectionRetry properties that modify how the adapter is maintaining its Azure IoT Hub connection:
{
"ConnectionRetryInterval": 1,
"ConnectionRetryAttempts": 1,
"ConnectionRetryMaxInterval": 5
}
- SensorDataItemsToMonitor: a dictionary with Sensor ID as a key. The value contains a CSV list of tag names to monitor:
"SensorDataItemsToMonitor": {
"M1": "Name1,Name2,…"
}
- TagDownsampling contains settings for downsampling tag data based on rules:
{
"TagDownsampling": {
"1": {
"Pattern": "<regex>",
"TimeInterval": "0.00:00:20",
"Percent": 0.6,
"Absolute": 10,
"SpikePercent": 50,
"RegEx": "<regex>"
}
}
}
- “1” is the priority of the rule
- the pattern is a regex that defines for which tags this rule is applicable
- The other settings define how to downsample tag values: based on time, value change, value contents.
- Heartbeat interval in seconds as property “HeartbeatInterval”
- ForceUpdateTags which is a CSV list of tag names which values should always be sent, no matter if their values are changed or not
Adapter for Heidenhain machines
Purpose: To support communication with Heidenhain machines (a third-party license is required)
Configuration JSON:
"desired": {
"IPAddress": "192.168.1.98",
"Port": "19000",
"Devices": {
"M79": "79;19200;8;N;1;Heidenhain 79;192.168.1.51;19000;0;localhost;3;0;none;none;1;heidenhain.dll",
"M211": "211;19200;8;N;1;Heidenhain 211;192.168.1.49;19000;0;localhost;2;0;none;none;1;heidenhain.dll",
"M45": "45;19200;8;N;1;Heidenhain 45;192.168.1.98;19000;0;localhost;1;0;none;none;1;heidenhain.dll"
},
"LicenseKey": "1234567890acbdefghijklmnopqrstuvwxyz"
}
Description:
- Under Devices, each device that the adapter should connect to is listed with its Sensor ID from the Administration Portal. Also a list of values is prepared separated with a semicolon (;). The values are as follows:
- Machine Nr; Baud; Databits; Parity; StopBits; Machine Name; IP; Port; Method; DNS-Name; Mitsubishi Nr.; PLC Addr.(Counter); Share; Logfile Name; Logfile Version; DLL Name (16 items)
Adapters for Fanuc Controllers
Purpose: Adapters support communication with Fanuc controllers by different interfaces - MTConnect protocol or by using Fanuc Robots interface SDK.
Adapter for Fanuc Controller using Fanuc Robot Interface SDK
Purpose: To support communication with Fanuc Controllers by using Fanuc Robots Interface SDK.
Configuration JSON:
"desired": {
"TimeZone": "E. Europe Standard Time",
"Robots": {
"R218": {
"HostName": "192.168.1.86",
"Interval": 2000,
"MonitorAlarms": true,
"SysVariables": "$FAST\_CLOCK:int",
"RegNumerics": "1,2,3,4,5,...",
"RegStrings": "1,2,3,4,5,...",
"MonitorProgram": true
}
}
}
Description:
- Under Robots each robot that the adapter should connect to is listed with its Sensor ID from the Administration Portal:
- SysVariables contains a CSV list of variable names with their corresponding data type
- RegNumerics and RegStrings contain a CSV list of registry indexes
Fanuc Focas MTConnect Adapter
Purpose: To support communication with Fanuc Controllers by MT Connect protocol
Configuration JSON:
"desired": {
"Machines": {
"M1": {
"ConfigFilename": "adapter.ini",
"AdapterArguments": "debug <configFilename>",
"Port": "7801",
"MachineIP": "192.168.1.83",
"MachinePort": "8193",
"SspeedOvr": "30",
"Fovr": "12"
}
}
}
Description:
- Under Machines each machine that the adapter should connect to is listed with its Sensor ID from the Administration Portal:
- ConfigFileName and AdapterArguments should not be changed
- All other properties are according to the network and machine
Adapter for MTConnect protocol
Purpose: To support communication with machines by MTConnect protocol. MTConnect Adapter supports connection with the machine and collects data. MTConnect Agent supports connection with set of adapters and buffers data. MTConnectController collects data received from the agent and transfers data to the cloud.
Adapter MTConnect Agent
Purpose: Support connection with the machine, collect and buffer data.
Configuration JSON:
"desired": {
"configFilename": "agent.cfg",
"agentArguments": "debug <configFilename>",
"BufferSize": "20",
"MaxAssets": "1025",
"CheckpointFrequency": "1000",
"DevicesXmlFileName": "Devices.xml",
"Port": "5000",
"ReconnectInterval": "1000",
"IgnoreTimestamps": "true",
"Adapters": {
"M1": {
"Host": "127.0.0.1",
"Port": "7886"
}
}
}
Description:
- ConfigFileName and AdapterArguments should not be changed
- DevicesXmlFileName is specific for the environment and should be manually defined and added in the installation of the gateway
- Under Adapters each machine that the adapter should connect to is listed with its Sensor ID from the Administration Portal
- All other properties are specific to the MTConnect protocol adapters (refer MTConnect documentation)
Adapter MTConnect Collector
Purpose: Receive and buffer data from MTConnect agent and transfer data to the cloud.
Configuration JSON:
"desired": {
"mtcAgentSockets": {
"main": {
"URL": "http://127.0.0.1:5000/",
"PollIntervalMS": 1000,
"DataItemsToRequest": 10000
}
},
"dataItemsToMonitor": {
"M1": "path\_position,block,line,f\_command,"
},
"ErrorSplit": {
"Heidenhain": {
"BaseErrorDataItem": "ERRTX",
"BaseErrorDataItemClearValues": "None,NONE,Unavailable,MAGAZINE IS RUNNING",
"SplitByDataItem": "ERRCL",
"SplitByDataItemClearValues": "0",
"OutputDataItems": {
"ERRTX\_warning": {
"SplitValues": "2,3,4,5,6,7"
},
"ERRTX\_info": {
"SplitValues": "8"
}
}
}
}
}
Description:
- mtcAgentSockets describes all MTConnect agents that should be monitored
- Under dataItemsToMonitor, each machine is listed with its Sensor ID from the Administration Portal. For each machine, a CSV list of values to monitor is given. These values should match the names of the DataItem elements in the XML of the MTConnect agent
- ErrorSplit contains configuration based on machine manufacturer as defined in the XML of the MTConnect agent. The configuration works on CONDITION elements and gives the possibility to split messages into error, warning and info tags.
Adapter for OPC protocols
Purpose: To support communications with machines by OPC (OLE for Process Control) protocols.
Adapter for OPC Classic protocol
Purpose: To support communications with machines by OPC (Classic) protocol.
Configuration JSON:
"desired": {
"servers": {
"M1": {
"UrlNoProtocol": "OPC\_SERVER/server.name.1/{013ge92f-96cd-12d3-87f2-4402041ff057}",
"SamplingRate": 500,
"AlarmsAndEventsFilters": {
"LowSeverity": 1,
"HighSeverity": 1000,
"Qualities": "\*",
"Types": "\*",
"Sources": "\*"
},
"ConnectAeClient": false,
"SendFalseBooleans": true,
"SamplingRateSpecified": true
}
}
}
Description:
- Under servers each machine is listed with its Sensor ID from the Administration Portal. For each machine a set of properties specific to the OPC classic communication is given
Adapter for OPC UA protocol
Purpose: To support communication with machines through OPC UA (Unified Architecture) protocol.
Configuration JSON:
"desired": {
"servers": {
"R1": {
"DiscoveryUrl": "opc.tcp://192.168.1.120:4840",
"SessionChannelTimeout": 30000,
"PublishingInterval": 500,
"KeepAliveCount": 10,
"LifetimeCount": 30,
"PublishingEnabled": true,
"UserName": "",
"Password": "",
"SamplingInterval": -1,
"QueueSize": 1,
"DiscardOldest": true,
"OverrideServerTime": true,
"SecurityPolicy": "None",
"HandshakeTags": {
"0134\_WP\_DataPresent": {
"Enabled": true,
"ServerValue": "True",
"ClientValue": "False",
"DataType": "System.Boolean",
"ReadTags": "3:name1,3:name2,…"
}
},
"BitwiseTags": {
"0004\_Safety\_State": {
"Bits": {
"0": {
"Type": "Safety\_DoorLeftOpen"
},
"1": {
"Type": "Safety\_DoorRightOpen"
},
"2": {
"Type": "Safety\_DoorWeldCelllOpen"
},
"3": {
"Type": "Safety\_LightgridTables"
},
"4": {
"Type": "Safety\_RobotInAutoPos"
},
"5": {
"Type": "Safety\_EstopLeftOpPanel"
},
"6": {
"Type": "Safety\_EstopRightOpPanel"
},
"7": {
"Type": "Safety\_EstopRobot"
},
"8": {
"Type": "Safety\_EstopWeld"
}
}
}
},
"EnableInternalLogs": false,
"HandshakeRetryDelay": "10000"
}
}
}
Description:
- Under servers, each OPC UA server is listed with its Sensor ID from the admin portal. Also, a set of properties specific to the OPC UA communication is given.
- HandshakeTags contains a list of tags for which confirmation should be sent to the server. Each handshake could force to read the tags listed in ReadTags.
BitwiseTags defines how to identify separate bits in tags that contain bitwise values
Adapter for Siemens S7 controllers
Purpose: To support communication with SiementsS7 controllers.
Configuration JSON:
"desired": {
"Machines": {
"PLC-Process1": {
"SensorID": "PLC-Process1",
"CPUType": "S71500",
"IPAddress": "172.16.2.110",
"Port": 102,
"Rack": 0,
"Slot": 1,
"Tags": {
"MachineNumber": "DB1011.DBW12",
"Spindle": "DB1011.DBW124"
},
"TimerIntervalSec": 1
}
}
}
Description:
- Under Machines, each machine is listed with its Sensor ID from the Administration Portal. For each machine, a set of properties specific to the OPC classic communication is given
- The Tags dictionary contains a list of tags to read from the controller. The key is the tag name that will be sent to the cloud
There is also a developed adapter for RPC Sinumerik interfaces for Siemens controllers.
Adapter for ABB Robot controllers
Purpose: To support communication with ABB robots controllers.
Configuration JSON:
"desired": {
"Robots": {
"Robot1": {
"IP": "192.168.1.95",
"Interval": 5000,
"Monitor": {
"State": true,
"OperatingMode": true,
"ExecutionStatus": true,
"ExecutionCycle": true,
"IOSignals": "Start,Stop,MotorsOFF,MotorsON",
"EventLogTypes": "Error,Warning,Information",
"ActiveMechanicalUnitProperties": "\*"
},
"OverrideServerTime": true
}
}
}
Description:
- Under Robots, each machine is listed with its Sensor ID from the Administration Portal. For each machine, a set of properties specific to the communication is given.
- Properties under Monitor define which items to be monitored from the target controller**
Adapter for Balluff controllers
Purpose: To support communication with Balluff controllers
Configuration JSON:
"desired": {
"controllers": {
"COM3": {
"Interface": "Serial",
"Port": "COM3",
"SerialParity": "None",
"Interval": 100,
"HeadToSensorID": {
"1": "COM3-Head1",
"2": "COM3-Head2",
"3": "COM3-Head3",
"4": "COM3-Head4"
}
}
}
}
Description:
- Under controllers, each controller is listed with its Sensor ID from the admin portal. Also, a set of properties specific to the COM communication is given.
- Properties under HeadToSensorID override the Sensor ID per Balluff controller Head
Adapter for SQL DB communication
Purpose: To support communication with SQL databases.
Configuration JSON:
"desired": {
"TimerTickMs": 5000,
"Clients": {
"DMG\_MORI\_Messenger\_V2": {
"ConnectionString": "<connection\_string>",
"ProgressFileName": "progress.txt",
"Entries": {
"DMG": {
"SensorID": "DMG",
"Queries": {
"1": {
"Sql": "SELECT \* FROM [db].[dbo].[Table] WHERE EntryType = 4 AND id > {0} ORDER BY id DESC",
"Items": {
"Timestamp": "Timestamp",
"Parameter": "ERRNO",
"ExtendedParameter": "ERRTX"
},
"Identifier": "Id"
}
}
}
}
}
}
}
Description:
- TimerTicksMs defines how often to execute queries against the SQL servers
- Under Clients, each SQL server to connect to is listed
- ProgressFileName is an internal file to track progress
- Under Entries, each machine that the adapter is going to read data is listed with its Sensor ID from Administration Portal. For each query there are properties defining how to parse the results.
MELSEC protocol adapter
Purpose: To support communication with Mitsubishi Controllers using MELSEC protocol.
Configuration JSON:
"desired": {
"Machines": {
"M1": {
"SensorID": "M1",
"Port": "1025",
"IPAddress": "192.168.1.83",
"MachinePort": "1025",
"TimerIntervalSec": "5",
“Tags”: {
“relay1status”: {
“DeviceType”: “M”,
“AddressDec”: “94”,
“AddressHex”: “5E”,
“DataType”: “int”
}
}
}
}
}
Description: Under Machines each machine that the adapter should connect to is listed:
- SensorID – As listed in the Upkip Administration
- IPAddress – the address of the MELSEC controller
- Port – the port of the MELSEC controller
- TimerIntervalSec – the scan interval. All registers will be read at this interval.
- Tags – List of all tags which will be updated by the adapter. The name of the tag is specified. Ex: ”relay1status”.
- DeviceType – The device from which the register will be read.
- AddressDec / AddressHex – only one can be provided, depending on the registry.
- DataType – type of the registry data – it can be int, bool, short, string.
Adapters as Linux modules
Purpose: Adapters are implemented as IoT Hub/IoT Edge devices/Modules. They are used to support connection and communication with the corresponding type of machines, equipment, or protocols. They run on Linux machines in the manufacturer premises.
Below are described configurations for the following adapters implemented as IoT Edge devices/Linux modules:
- Adapter for Modbus protocol
- Adapter for OPC UA protocol
- Adapter for MTConnect protocol
- Adapter for SAPB1 ERP communication
Each Linux adapter contains:
- Three ConnectionRetry properties that modify how the adapter is maintaining its Azure IoT Hub connection:
"ConnectionRetryInterval": 1,
"ConnectionRetryAttempts": 1,
"ConnectionRetryMaxInterval": 5
- SensorDataItemsToMonitor or dataItemsToMonitor: a dictionary with Sensor ID as a key. The value contains a CSV list of tag names to monitor:
"SensorDataItemsToMonitor": {
"M1": "Name1,Name2,…"
}
- TagDownsampling contains settings for downsampling tag data based on rules:
{
"TagDownsampling": {
"1": {
"Pattern": "<regex>",
"TimeInterval": "0.00:00:20",
"Percent": 0.6,
"Absolute": 10,
"SpikePercent": 50,
"RegEx": "<regex>"
}
}
}
- “1” is the priority of the rule
- The pattern is a regex that defines for which tags this rule is applicable
- The other settings define how to downsample tag values: based on time, value change, value contents.
- Heartbeat interval in seconds as property “heartbeatInterval”
- ForceUpdateTags which is a CSV list of tag names which values should always be sent, no matter if their values are changed or not
- APPINSIGHTS_INSTRUMENTATIONKEY – identifies the key for the target Azure Application Insights log collector
- NLOG_MINLEVEL – defines the min log level to output
- timerInterval – an interval on which to start periodic operations
Adapter for Modbus protocol
Purpose: To support communication with Modbus protocol.
Configuration JSON:
"desired": {
"servers": {
"Legiomix": {
"Port": "/dev/ttyS0",
"SlaveID": 1,
"BaudRate": 9600,
"Parity": "Even",
"StopBits": "One",
"RegTags": {
"0": "model",
"1": "id\_modbus",
"2": "T1",
"3": "T2",
"4": "id\_number",
"5": "serial\_number",
"6": "nc\_status"
},
"BitwiseTags": {
"8": {
"Bits": {
"0": {
"Type": "IN1\_STATUS"
},
"1": {
"Type": "IN2\_STATUS"
},
"8": {
"Type": "OUT1\_STATUS"
},
"9": {
"Type": "OUT2\_STATUS"
},
"10": {
"Type": "OUT3\_STATUS"
}
}
}
},
"RegistryRanges": {
"1": {
"StartingAddress": 0,
"NumberOfValues": 15
},
"2": {
"StartingAddress": 1000,
"NumberOfValues": 31
}
}
}
}
}
Description:
- Under servers, each controller is listed with its Sensor ID from the admin portal. Also, a set of properties specific to the COM communication is given.
- BitwiseTags defines how to identify separate bits in tags that contain bitwise values
- RegTags and RegistryRanges define how to interpret and monitor tags
Adapter for OPC UA protocol
Purpose: To support communication with machines through OPC UA (Unified Architecture) protocol.
Configuration JSON and description can be found under the same adapter on Windows Gateway. To OPC UA protocol adapter.
Adapters for MTConnect protocol
Purpose: To support communication with machines by MTConnect protocol. MTConnect Adapter supports connection with the machine and collects data. MTConnect Agent supports connection with a set of adapters and buffers data. MTConnect Controller collects data received from the agent and transfers data to the cloud.
Configuration JSON and description can be found under the same adapter on Windows Gateway.
To adapters for MTConnect protocol
Adapter MTConnect Agent
Purpose: To support connection with the machine, collect and buffer data.
Configuration JSON and description can be found under the same adapter on Windows Gateway.
Adapter MTConnect Collector
Purpose: Receive and buffer data from the MTConnect agent and transfer data to the cloud.
Configuration JSON and description can be found under the same adapter on Windows Gateway.
Adapter for SAPB1 ERP communication
Purpose: To support communication with SAP Business 1 ERP system.
Configuration JSON:
"desired": {
"sapB1ConnectionSring": "<connection\_string>",
"sapB1dbName": "SBO\_Live",
"organizationId": "2",
"syncDaysBack": "5000",
"messageRows": 20,
"operationsWithoutProgress": "OperationName",
"departmentMapping": "Drei=Turning,Fres=Milling",
"timeZoneId": "Europe/Oslo"
}
Description:
- sapB1ConnectionSring and sapB1dbName identify the SAP B1 SQL Database
- organizationId identifies the id of the organization to which to bind the ERP data. In the common case, it is always 2.
- syncDaysBack is for initial sync
- messageRows limits the number of rows per Azure IoT Hub message
- departmentMapping maps departments from SAP B1 to departments from Administration Portal: SapName=AdminName