From 9b5fa070d57130dbd114dba443d2a4889bfe0d84 Mon Sep 17 00:00:00 2001 From: Patrick Ritchie Date: Sat, 2 Dec 2023 22:22:31 -0500 Subject: [PATCH] Updated ReadMe --- README.md | 205 ++++++++++++---------------- agent/MTConnect.NET-Agent/README.md | 3 - 2 files changed, 88 insertions(+), 120 deletions(-) diff --git a/README.md b/README.md index c338d106..9f0d2c16 100644 --- a/README.md +++ b/README.md @@ -2,98 +2,116 @@ # MTConnect.NET -[![MTConnect.NET](https://github.com/TrakHound/MTConnect.NET/actions/workflows/dotnet.yml/badge.svg)](https://github.com/TrakHound/MTConnect.NET/actions/workflows/dotnet.yml) -[![GitHub all releases](https://img.shields.io/github/downloads/TrakHound/MTConnect.NET/total?label=Release%20Downloads)](https://github.com/TrakHound/MTConnect.NET/releases/latest) -[![Nuget](https://img.shields.io/nuget/dt/MTConnect.NET?label=Nuget%20Downloads)](https://www.nuget.org/packages/MTConnect.NET) +> 12/4/2023 : Version 6.0 Released with new Agent, Adapter, & SysML Import ->9/5/2023 Updated for MTConnect v2.2 +## Download + + + + + + + + + + + + + + + + + + + + +
NameLink
Agenthttps://github.com/TrakHound/MTConnect.NET/releases
Nugethttps://www.nuget.org/packages/MTConnect.NET
## Overview -MTConnect.NET is a fully featured .NET library for MTConnect to develop Agents, Adapters, and Clients. Supports MTConnect Versions up to 2.2. - -The Agent, Buffers, and Adapter are separated into individual classes in order to allow for modular implementations such as the following : - -- A traditional Agent that uses a REST Api, in-memory buffer, and Adapters that communicate using the SHDR protocol -- An agent imbedded with the Adapter (which elminates the need for the Adapter TCP communication) -- Supports SHDR Apdaters -- Supports HTTP and MQTT -- Integration with cloud services such as AWS and Azure - -Other features of MTConnect.NET : -- Extensible through plugin libraries to extend Types -- Presistent Buffers that are backed up on the File System. Retains state after Agent is restarted -- Supports multiple MTConnect Version output. Automatically removes data that is not compatible with the requested version -- Supports running as Windows Service with easy to use command line arguments +MTConnect.NET is a fully featured and fully Open Source .NET library for MTConnect to develop Agents, Adapters, and Clients. Supports MTConnect Versions up to 2.2. A pre-compiled Agent application is available to download as well as an Adapter application that can be easily customized. + +- .NET Native MTConnect Agent +- Adapter framework used to send data to an MTConnect Agent +- Libraries to easily implement MTConnect Agent, Adapters, or Clients into custom applications + +### Features +- Module based Agent & Adapter architecture + - Supports running as Windows Service with easy to use command line arguments + - Presistent Agent Buffers that are backed up on the File System. Retains state after Agent is restarted +- Fully compatible up to the latest MTConnect v2.2 + - Kept up to date by utilizing the MTConnect SysML Model to generate source files + - Supports multiple MTConnect Version output. Automatically removes data that is not compatible with the requested version +- Full client support for requesting data from any MTConnect Agent (Probe, Current, Sample Stream, Assets, etc.). + - Supports HTTP, MQTT, and SHDR + - Supports compression (polling & streaming) + - Supports XML & JSON + - Supports HTTPS & TLS for secure communication +- Python Input Processors to transform data before loading into Agent - Full data validation - Validation on Input - XML Schema Validation on output - Configurable Validation Levels - Fully documented objects using text from the MTConnect Standard. This enables Intellisense in applications such as Visual Studio. -- Full list of Device, Component, Composition, and DataItem types. See [Devices](https://github.com/TrakHound/MTConnect.NET/tree/master/src/MTConnect.NET-Common/Devices) for more information. -- Full list of Asset types. See [Devices](https://github.com/TrakHound/MTConnect.NET/tree/master/src/MTConnect.NET-Common/Assets) for more information. - Fully supports Unit conversion. Default Units and UnitConversion is done automatically when sending Streams and when reading Streams. -- Full client support for requesting data from any MTConnect Agent (Probe, Current, Sample Stream, Assets, etc.). See [Clients](https://github.com/TrakHound/MTConnect.NET/tree/master/src/MTConnect.NET-HTTP/Clients/Rest) for more information. -- (In-Progress) [Models](https://github.com/TrakHound/MTConnect.NET/tree/master/src/MTConnect.NET-Models/Models) framework for setting and accessing data using an object model as opposed to DataItem ID's and Types - -## Download - -- [Agent Releases](https://github.com/TrakHound/MTConnect.NET/releases) -- [Adapter Source](https://github.com/TrakHound/MTConnect.NET/tree/version-6.0/adapter/MTConnect.NET-Adapter) -- [Nuget](https://www.nuget.org/packages/MTConnect.NET#readme-body-tab) - -## Usage - -### Create Agent -```c# -using MTConnect.Agents; - -var agent = new MTConnectAgent(); -``` - -### Create Adapter -```c# -using MTConnect.Adapters; -var adapter = new ShdrAdapter(); -``` +### Integrate +- Easily integrate with cloud services such as AWS and Azure +- Use client libraries to export MTConnect data to a Database (ex. SQL, Redis, MongoDB, etc.) +- Create custom dashboards and data collection applications to utilize equipment data +- Embed an MTConnect Agent into your adapter (remove need for separate SHDR Adapter) -### Create Client -```c# -using MTConnect.Clients; +#### MTConnect Version Compatibility +MTConnect.NET is designed to be fully compatible for all versions of the MTConnect standard. This is done through processing by the [MTConnectAgent](https://github.com/TrakHound/MTConnect.NET/tree/master/src/MTConnect.NET-Common/Agents/MTConnectAgent.cs) class before data is output. This allows the version to be a parameter when requesting data from the Agent. More information can be found in the [Devices README](https://github.com/TrakHound/MTConnect.NET/tree/master/src/MTConnect.NET-Common/Devices/README.md). -var client = new MTConnectHttpClient(); -``` +#### Data Validation +Validation is performed on a Device, Component, Composition, or DataItem level through the classes in [Devices](https://github.com/TrakHound/MTConnect.NET/tree/master/src/MTConnect.NET-Common/Devices). This allows for validation without the need to use XML schemas (although XML Validation against XSD schemas is supported). -## Agent Applications +### Live Demo +A live demo of the MTConnect Gateway HTTP Agent (AspNetCore) application is running at [https://mtconnect.trakhound.com](https://mtconnect.trakhound.com?outputComments=true&indentOutput=true&version=2.1). +- [https://mtconnect.trakhound.com/current](https://mtconnect.trakhound.com/current?outputComments=true&indentOutput=true&version=2.1) +- [https://mtconnect.trakhound.com/sample](https://mtconnect.trakhound.com/sample?outputComments=true&indentOutput=true&version=2.1&count=500) +- [https://mtconnect.trakhound.com/assets](https://mtconnect.trakhound.com/assets?outputComments=true&indentOutput=true) -#### Recommended (Windows / Linux) -- [MTConnect HTTP Agent](https://github.com/TrakHound/MTConnect.NET/tree/master/applications/Agents/MTConnect-Agent-Http) : MTConnect Agent application is fully compatible with the latest Version 2.2 of the MTConnect Standard. It uses the SHDR protocol to receive data from Adapters, an in-memory buffer with an optional durable file system based buffer, and an Http REST interface for retrieving data. +## Agents +Agents are implemented using the MTConnectAgent class and IMTConnectAgent interface. The MTConnectAgent class implements the MTConnect standard and is inteded to be full implemenation. More information about agents can be found at [Agents](https://github.com/TrakHound/MTConnect.NET/tree/master/src/MTConnect.NET-Common/Agents) and Agent Applications can be found at [Agent Applications](https://github.com/TrakHound/MTConnect.NET/tree/master/applications/Agents). -- [MTConnect HTTP Gateway Agent](https://github.com/TrakHound/MTConnect.NET/tree/master/applications/Agents/MTConnect-Agent-Http-Gateway) : MTConnect Agent application is fully compatible with the latest Version 2.2 of the MTConnect Standard. It receives data from other MTConnect Agents using HTTP, an in-memory buffer with an optional durable file system based buffer, and an Http REST interface for retrieving data. +### SHDR > HTTP Implementation +A SHDR to HTTP implementation is the traditional MTConnect Agent configuration. The agent reads from one or more Adapter applications that implement the SHDR Protocol. Data is then read from the Agent using the HTTP REST protocol. The agent and adapter(s) are typically separate applications. The agent and adapter(s) can still be run on the same PC (or HMI) but there is still TCP communication between them. -- [MTConnect MQTT Relay Agent](https://github.com/TrakHound/MTConnect.NET/tree/master/applications/Agents/MTConnect-Agent-MQTT-Relay) : This MTConnect Agent application is fully compatible with the latest Version 2.2 of the MTConnect Standard. It uses the SHDR protocol to receive data from Adapters, an in-memory buffer with an optional durable file system based buffer, and an MQTT client to publish messages to an external MQTT Broker. +![Traditional Agent Architecture](https://raw.githubusercontent.com/TrakHound/MTConnect.NET/dev/img/mtconnect-agent-http-shdr-communication-white.png) -- [MTConnect MQTT Broker Agent](https://github.com/TrakHound/MTConnect.NET/tree/master/applications/Agents/MTConnect-Agent-MQTT-Broker) : This MTConnect Agent application is fully compatible with the latest Version 2.2 of the MTConnect Standard. It uses the SHDR protocol to receive data from Adapters, an in-memory buffer with an optional durable file system based buffer, and a built-in MQTT broker. +### HTTP > HTTP Implementation +An HTTP to HTTP implementation reads from other MTConnect Agents and forwards that data to a central MTConnect Agent. This implementation can be used to create a "Gateway" that multiple other MTConnect Agents can be forwarded to. This can be used to provide a single access point, implement stricter security policies, or upgrade an older agent without effecting other applications that may already be using the older version. -- [MTConnect MQTT Relay Gateway Agent](https://github.com/TrakHound/MTConnect.NET/tree/master/applications/Agents/MTConnect-Agent-MQTT-Relay-Gateway) : This MTConnect Agent application is fully compatible with the latest Version 2.2 of the MTConnect Standard. It receives data from other MTConnect Agents using HTTP and an MQTT client to publish messages to an external MQTT Broker. +![Traditional Agent Architecture](https://raw.githubusercontent.com/TrakHound/MTConnect.NET/dev/img/mtconnect-agent-http-http-communication-white.png) -- [MTConnect MQTT Broker Gateway Agent](https://github.com/TrakHound/MTConnect.NET/tree/master/applications/Agents/MTConnect-Agent-MQTT-Broker-Gateway) : This MTConnect Agent application is fully compatible with the latest Version 2.2 of the MTConnect Standard. It receives data from other MTConnect Agents using HTTP and a built-in MQTT broker. +### SHDR > MQTT Implementation +A SHDR to MQTT implementation uses MQTT to send and receive messages. The agent reads from one or more Adapter applications that implement the SHDR Protocol. Data is then read from the Agent using the MQTT protocol. The agent and adapter(s) are typically separate applications. The agent and adapter(s) can still be run on the same PC (or HMI) but there is still TCP communication between them. -#### Specialized (IIS) +![Traditional Agent Architecture](https://raw.githubusercontent.com/TrakHound/MTConnect.NET/dev/img/mtconnect-agent-shdr-mqtt-communication-white.png) -- [MTConnect HTTP Agent - AspNetCore](https://github.com/TrakHound/MTConnect.NET/tree/master/applications/Agents/MTConnect-Agent-Http-AspNetCore) : Similar to the MTConnect Agent application but uses either the built-in Kestrel server or can be setup through IIS (Internet Information Services). This allows the agent to be used with all of the features available through ASP.NET and IIS such as security, permissions, monitoring, etc. +### Embedded Implementation +An embedded implementation uses the MTConnect.NET library to implement an MTConnect Agent in the same application that is reading from the machine PLC. This creates a simple and compact solution that can be deployed as a single application/product. When compared to a SHDR to HTTP implementation, this eliminates the need to use the SHDR protocol as well as eliminates the TCP communication between the Adapter and the Agent. Implementation is simplified using the [MTConnect.NET-Applications-Agents](https://github.com/TrakHound/MTConnect.NET/tree/master/src/MTConnect.NET-Applications-Agents) Library that can be as simple as a few lines of code and can be kept up to date using Nuget. -- [MTConnect HTTP Gateway Agent - AspNetCore](https://github.com/TrakHound/MTConnect.NET/tree/master/applications/Agents/MTConnect-Agent-Http-Gateway-AspNetCore) : An Agent that runs mulitple MTConnectClients on the backend and passes that data to an MTConnectAgent. This can be used to access MTConnect data on a central server. Uses either the built-in Kestrel server or can be setup through IIS (Internet Information Services). This allows the agent to be used with all of the features available through ASP.NET and IIS such as security, permissions, monitoring, etc. +![Traditional Agent Architecture](https://raw.githubusercontent.com/TrakHound/MTConnect.NET/dev/img/mtconnect-agent-http-communication-white.png) -### Live Demo -A live demo of the MTConnect Gateway HTTP Agent (AspNetCore) application is running at [https://mtconnect.trakhound.com](https://mtconnect.trakhound.com?outputComments=true&indentOutput=true&version=2.1). -- [https://mtconnect.trakhound.com/current](https://mtconnect.trakhound.com/current?outputComments=true&indentOutput=true&version=2.1) -- [https://mtconnect.trakhound.com/sample](https://mtconnect.trakhound.com/sample?outputComments=true&indentOutput=true&version=2.1&count=500) -- [https://mtconnect.trakhound.com/assets](https://mtconnect.trakhound.com/assets?outputComments=true&indentOutput=true) +## Adapters -## Docker -Docker images are located at : -- MTConnect HTTP Agent : [https://hub.docker.com/r/trakhound/mtconnect-agent-http](https://hub.docker.com/r/trakhound/mtconnect-agent-http) +### Modular Adapter Application +A preconfigured [Application](https://github.com/TrakHound/MTConnect.NET/tree/version-6.0/adapter/MTConnect.NET-Adapter) & [Library](https://github.com/TrakHound/MTConnect.NET/tree/version-6.0/adapter/MTConnect.NET-Applications-Adapter) to build an Adapter is available and supports: +- Modular architecture + - SHDR Module (export data to an MTConnect Agent using the SHDR protocol) + - MQTT Module (export data to an MQTT Broker to be read by an MTConnect Agent) +- Run as a Windows Service +- Extensible configuration file and monitors for changes +- Customizable Data Source engine (to read from a PLC) +- Updated through a Nuget package (no source code copy & paste required when updating to new versions) + +### SHDR Adapter Classes +- [ShdrAdapter](https://github.com/TrakHound/MTConnect.NET/blob/master/src/MTConnect.NET-SHDR/Adapters/Shdr/ShdrAdapter.cs) : Sends the most recent values On-Demand using the SendCurrent() method. This is used when full control of the communication is needed. +- [ShdrIntervalAdapter](https://github.com/TrakHound/MTConnect.NET/blob/master/src/MTConnect.NET-SHDR/Adapters/Shdr/ShdrIntervalAdapter.cs) : Sends the most recent values at the specified Interval. This is used when a set interval is adequate and the most recent value is all that is needed +- [ShdrQueueAdapter](https://github.com/TrakHound/MTConnect.NET/blob/master/src/MTConnect.NET-SHDR/Adapters/Shdr/ShdrQueueAdapter.cs) : Queues all values that are sent from the PLC and sends them all on demand using the SendBuffer() method. This is used when all values are needed and full control of the communication is needed. +- [ShdrIntervalQueueAdapter](https://github.com/TrakHound/MTConnect.NET/blob/master/src/MTConnect.NET-SHDR/Adapters/Shdr/ShdrIntervalQueueAdapter.cs) : Queues all values that are sent from the PLC and sends any queued values at the specified Interval. This is used when all values are needed but an interval is adequate. ## Nuget Packages The Nuget packages for the libraries in this repo are listed below: @@ -112,13 +130,12 @@ The Nuget packages for the libraries in this repo are listed below: - [MTConnect.NET-Applications-Agents-MQTT](https://www.nuget.org/packages/MTConnect.NET-Applications-Agents-MQTT/) ## Supported Frameworks +- .NET 8.0 - .NET 7.0 - .NET 6.0 - .NET 5.0 - .NET Core 3.1 - - .NET Standard 2.0 - - .NET Framework 4.8 - .NET Framework 4.7.2 - .NET Framework 4.7.1 @@ -126,57 +143,11 @@ The Nuget packages for the libraries in this repo are listed below: - .NET Framework 4.6.2 - .NET Framework 4.6.1 -## MTConnect Version Compatibility -MTConnect.NET is designed to be fully compatible for all versions of the MTConnect standard. This is done through processing by the [MTConnectAgent](https://github.com/TrakHound/MTConnect.NET/tree/master/src/MTConnect.NET-Common/Agents/MTConnectAgent.cs) class before data is output. This allows the version to be a parameter when requesting data from the Agent. More information can be found in the [Devices README](https://github.com/TrakHound/MTConnect.NET/tree/master/src/MTConnect.NET-Common/Devices/README.md). - -## Data Validation -Validation is performed on a Device, Component, Composition, or DataItem level through the classes in [Devices](https://github.com/TrakHound/MTConnect.NET/tree/master/src/MTConnect.NET-Common/Devices). This allows for validation without the need to use XML schemas (although XML Validation against XSD schemas is supported). - -## Releases -Releases are available at : [Releases](https://github.com/TrakHound/MTConnect.NET/releases) - -## Agents -Agents are implemented using the MTConnectAgent class and IMTConnectAgent interface. The MTConnectAgent class implements the MTConnect standard and is inteded to be full implemenation. More information about agents can be found at [Agents](https://github.com/TrakHound/MTConnect.NET/tree/master/src/MTConnect.NET-Common/Agents) and Agent Applications can be found at [Agent Applications](https://github.com/TrakHound/MTConnect.NET/tree/master/applications/Agents). - -### SHDR > HTTP Implementation -A SHDR to HTTP implementation is the traditional MTConnect Agent configuration. The agent reads from one or more Adapter applications that implement the SHDR Protocol. Data is then read from the Agent using the HTTP REST protocol. The agent and adapter(s) are typically separate applications. The agent and adapter(s) can still be run on the same PC (or HMI) but there is still TCP communication between them. - -![Traditional Agent Architecture](https://raw.githubusercontent.com/TrakHound/MTConnect.NET/dev/img/mtconnect-agent-http-shdr-communication-white.png) - -### HTTP > HTTP Implementation -An HTTP to HTTP implementation reads from other MTConnect Agents and forwards that data to a central MTConnect Agent. This implementation can be used to create a "Gateway" that multiple other MTConnect Agents can be forwarded to. This can be used to provide a single access point, implement stricter security policies, or upgrade an older agent without effecting other applications that may already be using the older version. - -![Traditional Agent Architecture](https://raw.githubusercontent.com/TrakHound/MTConnect.NET/dev/img/mtconnect-agent-http-http-communication-white.png) - -### SHDR > MQTT Implementation -A SHDR to MQTT implementation uses MQTT to send and receive messages. The agent reads from one or more Adapter applications that implement the SHDR Protocol. Data is then read from the Agent using the MQTT protocol. The agent and adapter(s) are typically separate applications. The agent and adapter(s) can still be run on the same PC (or HMI) but there is still TCP communication between them. - -![Traditional Agent Architecture](https://raw.githubusercontent.com/TrakHound/MTConnect.NET/dev/img/mtconnect-agent-shdr-mqtt-communication-white.png) - -### Embedded Implementation -An embedded implementation uses the MTConnect.NET library to implement an MTConnect Agent in the same application that is reading from the machine PLC. This creates a simple and compact solution that can be deployed as a single application/product. When compared to a SHDR to HTTP implementation, this eliminates the need to use the SHDR protocol as well as eliminates the TCP communication between the Adapter and the Agent. Implementation is simplified using the [MTConnect.NET-Applications-Agents](https://github.com/TrakHound/MTConnect.NET/tree/master/src/MTConnect.NET-Applications-Agents) Library that can be as simple as a few lines of code and can be kept up to date using Nuget. - -![Traditional Agent Architecture](https://raw.githubusercontent.com/TrakHound/MTConnect.NET/dev/img/mtconnect-agent-http-communication-white.png) - -## Adapters -### SHDR Adapter -Adapters are used to convert data read from a machine or PLC to the SHDR Protocol that can then be sent over TCP to an MTConnect Agent. There are several adapter types available in the [MTConnect.NET-SHDR](https://github.com/TrakHound/MTConnect.NET/tree/master/src/MTConnect.NET-SHDR) library that are listed below: -- [ShdrAdapter](https://github.com/TrakHound/MTConnect.NET/blob/master/src/MTConnect.NET-SHDR/Adapters/Shdr/ShdrAdapter.cs) : Sends the most recent values On-Demand using the SendCurrent() method. This is used when full control of the communication is needed. -- [ShdrIntervalAdapter](https://github.com/TrakHound/MTConnect.NET/blob/master/src/MTConnect.NET-SHDR/Adapters/Shdr/ShdrIntervalAdapter.cs) : Sends the most recent values at the specified Interval. This is used when a set interval is adequate and the most recent value is all that is needed -- [ShdrQueueAdapter](https://github.com/TrakHound/MTConnect.NET/blob/master/src/MTConnect.NET-SHDR/Adapters/Shdr/ShdrQueueAdapter.cs) : Queues all values that are sent from the PLC and sends them all on demand using the SendBuffer() method. This is used when all values are needed and full control of the communication is needed. -- [ShdrIntervalQueueAdapter](https://github.com/TrakHound/MTConnect.NET/blob/master/src/MTConnect.NET-SHDR/Adapters/Shdr/ShdrIntervalQueueAdapter.cs) : Queues all values that are sent from the PLC and sends any queued values at the specified Interval. This is used when all values are needed but an interval is adequate. - ## Developer Notes -This repo along with the libraries and applications are free to use and hopefully will help those that are looking at either getting started using MTConnect or those that are looking to use MTConnect for more advanced use cases. +This repo along with the libraries and applications are free to use and distribute and hopefully will help those that are looking at either getting started using MTConnect or those that are looking to use MTConnect for both basic and more advanced use cases. Feel free to comment, or create pull-requests for anything that could be coded, formatted, or worded better. Attention to detail and continuous improvement are important in manufacturing so they should be just as important for manufacturing software. -One of this project's goals is to expand the use cases for MTConnect and by breaking apart the functionalities of the agent, hopefully that will allow others to be creative in how to use the MTConnect standard. - -Hopefully this repo will serve as a "one stop shop" for .NET developers looking to use MTConnect. If anyone is interested in developing a similar repo for another framework or language, feel free to use this as a guide as I imagine some of the classes (which is the most tedious part of the code) could be converted to other languages fairly easily. - -This MTConnect.NET update is Part 1 of **The TrakHound Project** which is a project to provide open source code as well as products for each part of a full IIOT implementation. Please show support for our project at [www.TrakHound.com](http://www.trakhound.com). - Thanks for your interest in using these libraries and applications and feel free to contribute or give feedback. \- Patrick diff --git a/agent/MTConnect.NET-Agent/README.md b/agent/MTConnect.NET-Agent/README.md index d4635813..565e7aa3 100644 --- a/agent/MTConnect.NET-Agent/README.md +++ b/agent/MTConnect.NET-Agent/README.md @@ -19,9 +19,6 @@ This project is a full implementation of an MTConnect Agent used to read data fr - Configuration File monitoring to automatically restart the Agent upon configuration file changes - Flexible Logging using NLog which can be used to output log information to separate files for easier analysis - -![Traditional Agent Architecture](https://raw.githubusercontent.com/TrakHound/MTConnect.NET/master/img/mtconnect-agent-http-shdr-communication-white.png) - ## Download To download the latest release as a Windows Installer, use the link below: