trueanalyticssolutions/mtconnect.adapter

This fork of the MC2 example project aims to industrialize the adapter implementation.

Based on the Dot Net SDK

MTConnect® Adapter by TAMS

This repo contains two important libraries for implementing a MTConnect® Adapter each providing tools for rapid Adapter development.

AdapterInterface

An assembly for implementing custom software adapters formatted for connecting with the reference MTConnect® Agent.

See the AdapterInterface project readme for more information.

TcpAdapter

An implementation of the abstract Adapter class within the AdapterInterface that communicates with the reference MTConnect® Agent via TCP/IP.

See the MtconnectCore.TcpAdapter project readme for more information.

Examples

See the Wiki for examples on implementing an Adapter.

Features

Here is a list of important features that this library provides:

Configuration Options

This Adapter library provides some configuration options to alter the behavior of the Adapter and output of DataItems. Some of those options include:

• enqueue indicates whether or not the Adapter should queue all incoming data. Allowing the Adapter to queue DataItems can ensure that all values are sent to a client. Traditionally, Adapters only send the most current DataItem value, allowing some changes to the DataItems to be lost due to the sample rate.
• heartbeat allows you to manipulate the heartbeat of the Adapter.

DataItem Options

Individual DataItem configuration is also available, giving you more control over how each DataItem is processed before sending to the client(s).

• name allows you to override the DataItem name that is sent to the client(s).
• format allows you to override the value that is sent to the client(s). NOTE: This option MUST be encrypted for security purposes. Additionally the use of this feature should be in coordination with any network and security policies.

TCP Options

When communicating with clients via TCP, here are some options for setting up those connections:

• address allows you to explicitly specify the IP Address you wish to host the Adapter on.
• port allows you to explicitly specify the port number you wish to host the Adapter on.
• maxConnections allows you to adjust how many concurrent client connections you wish the Adapter to handle at any given point.

UPnP Options

Adapters can optionally make themselves discoverable using UPnP by adding the UPnP property to the Adapter configuration section of the appsettings. Here are some of the settings for configuring the UPnP host:

• Type specifies the System.Type of the UPnPService implementation.
• Options is a dictionary of constructor parameters for the UPnPService implementations:
  • broadcastRate is the rate (in milliseconds) at which the service will publish a (ssdp:update) notification on the network. The default is essentially 24hrs.
  • address is the intended IP Address to host the HTTP server. The default is localhost
  • port is the intended port number to host the HTTP servre. The default is 7879. This value must be unique on the machine

NOTE: UPnP should be tested and evaluated for security concerns in coordination with any network and security policies.

API

In order to stay compliant with the reference MTConnect C++ Agent, there are some commands that must be issued to the Agent. This Adapter library expands on this concept by allowing the TCP clients to issue commands to retrieve this information on-demand.

Agent SHDR Commands

These are commands that can be issued to the client(s) (aka Agent):

• * PONG <heartbeat>
• * adapterVersion: <version>
• * calibration: XXX
• * conversionRequired: <yes|no>
• * device: <uuid|name>
• * description: XXX
• * manufacturer: XXX
• * mtconnectVersion: <version>
• * nativeName: XXX
• * realTime: <yes|no>
• * relativeTime: <yes|no>
• * serialNumber: XXX
• * shdrVersion: <version>
• * station: XXX
• * deviceModel: <XML>

Adapter Commands

These are commands that can be issued to the Adapter from the client(s):

• * PING returns the PONG Agent command
• * dataItems returns a pipe-delimitted list of the registered DataItem names.

Example:

<* dataItems: avail|exec|xPos

• * dataItemDescription: <name> returns the description, if available, for the provided DataItem.

Example:

>* dataItemDescription: exec
<* dataItemDescription: The execution state of NC code on the main controller

• * dataItem: <name> returns the current value of the provided DataItem.

Example:

>* dataItem: exec
<* dataItem: READY

mtconnect.adapter's Issues

GET List of DataItem keys

The TcpAdapter should listen for requests to get a list of the supported DataItem keys. This could be useful when configuring the Devices.xml for an unfamiliar Adapter.

The command could simply be DATAITEMS that returns a pipe-delimited list of the DataItem keys in the IAdapter.

Implement Network Discovery

The TcpAdapter should provide a means of making itself discoverable on the network.

• Create a UdpClient
• Have the UdpClient.JoinMulticastGroup() for multicasting to multiple clients (Agents, PUTTY, etc.)
• Broadcast information about the Adapter connection such as the local IP Address and port for the Adapter and perhaps the device name, if available. For example: deviceName=123.123.123.123:7878

For future consideration:
Once Adapters are discoverable, an Agent could theoretically request the DataItem details from the Adapter to automatically build the Devices.xml using the command structure recently implemented. For example: the Agent could issue a command like * dataItems to receive a pipe delimited list of the DataItems, their types/subtypes, category, units, nativeUnits, etc..

This presents a fork in the road, should the Agent then assume the appropriate placement within the Component model based on the DataItem types? Or, should the Adapter maintain an understanding of the Component model as well and provide endpoints for the Agent to consider?

Add TCP Commands from C++ Reference Agent

Need to add support for the following commands coming from the C++ Agent (see Commands section):

• * adapterVersion
• * calibration
• * conversionRequired
• * device
• * description
• * manufacturer
• * mtconnectVersion
• * nativeName
• * realTime
• * relativeTime
• * serialNumber
• * shdrVersion
• * station

Commands should be issued to the client at the start of each connection. Each command should be capable of being triggered by a message from the client.

The PING/PONG commands should also fall under this supported behavior

Null or empty values crash the Agent

Null or empty values submitted to the Agent seem to crash the Agent. The AdapterInterface should automatically set the underlying _value to UNAVAILABLE when attempting to update the DataItem.Value with a null or empty value.

Missing support for TABLE

The Adapter is missing support for the TABLE value type (See model)

Add integrated documentation

Need static documentation

TCP Adapter publishes to all network cards

Using IPAddress.Any blocks the same PID from reading data from connecting to a TCP stream. For example, if one NIC is used to read data from a machine, then publishing data to a different port on the same NIC is not allowed from the same process ID.

The adapter should have a configuration option to specify which address to publish the data thru.

Generic Adapter Service

The generic interfaces now make it possible to create a generic Windows Service that can execute virtually any implementation of the IAdapter.

A new project should be added that dynamically loads DLLs of IAdapter implementations (like TcpAdapter) and IAdapterSource.

Missing support for DATA_SET

The Adapter does not currently support DATA_SET values (See model)