From 969deddaf7f4d27e98b6452695f5243a407a4aba Mon Sep 17 00:00:00 2001 From: Patrick Ritchie Date: Tue, 28 Nov 2023 21:58:21 -0500 Subject: [PATCH] Added ReadMe files --- agent/MTConnect-Agent/README.md | 131 +++++++----------- .../MTConnectAgentApplication.cs | 1 + ...Connect.NET-AgentModule-HttpAdapter.csproj | 7 + .../README.md | 28 ++++ ...TConnect.NET-AgentModule-HttpServer.csproj | 7 + .../README.md | 55 ++++++++ ...Connect.NET-AgentModule-ShdrAdapter.csproj | 7 + .../README.md | 33 +++++ ...MTConnect.NET-AgentProcessor-Python.csproj | 7 + .../README.md | 83 +++++++++++ 10 files changed, 280 insertions(+), 79 deletions(-) create mode 100644 agent/Modules/MTConnect.NET-AgentModule-HttpAdapter/README.md create mode 100644 agent/Modules/MTConnect.NET-AgentModule-HttpServer/README.md create mode 100644 agent/Modules/MTConnect.NET-AgentModule-ShdrAdapter/README.md create mode 100644 agent/Processors/MTConnect.NET-AgentProcessor-Python/README.md diff --git a/agent/MTConnect-Agent/README.md b/agent/MTConnect-Agent/README.md index f9f2993b..93689a76 100644 --- a/agent/MTConnect-Agent/README.md +++ b/agent/MTConnect-Agent/README.md @@ -1,19 +1,20 @@ ![MTConnect.NET Logo](https://raw.githubusercontent.com/TrakHound/MTConnect.NET/dev/img/mtconnect-net-03-md.png) -# MTConnect Http Agent +# MTConnect Agent [![MTConnect.NET](https://github.com/TrakHound/MTConnect.NET/actions/workflows/dotnet.yml/badge.svg)](https://github.com/TrakHound/MTConnect.NET/actions/workflows/dotnet.yml) ## Overview -This project is a full implementation of an MTConnect Agent used to read data from industrial machine tools and devices. 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 Http REST interface for retrieving data. +This project is a full implementation of an MTConnect Agent used to read data from industrial machine tools and devices. This MTConnect Agent application is fully compatible with the latest **Version 2.2 of the MTConnect Standard**. #### Features -- Easy setup with Windows Installers availble in the latest [Releases](https://github.com/TrakHound/MTConnect.NET/releases) +- Plugin architecture to support Http Server, Mqtt Server, SHDR Adapters, etc. +- Processors for transforming input data using simple Python scripts +- Easy setup with Windows Installers - Options to run as Windows Service or as a console application (typically for testing/debugging) - Optional 'Durable' buffer used to retain the Agent data between application/machine restarts - High performance / Low resource usage - Flexible Device configurations (traditional 'devices.xml' file or 'devices' directory with individual Device files) -- SHDR protocol compatibility for easy implementation with existing MTConnect Adapters - On-Demand MTConnect Versioning allowing for older clients to request the version of MTConnect they are compatible with using HTTP Url parameters - 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 @@ -129,24 +130,53 @@ More information about [Configurations](https://github.com/TrakHound/MTConnect.N # - Device Configuration - devices: devices -# - SHDR Adapter Configuration - -# The Agent is able to receive data through a TCP port using the SHDR protocol -adapters: -- hostname: localhost - port: 7878 - reconnectInterval: 1000 +# - Modules - +- modules: + + # - Add HTTP Server module + - http-server: + hostname: localhost + port: 7878 + allowPut: true + indentOutput: true + documentFormat: xml + responseCompression: + - gzip + - br + files: + - path: schemas + location: schemas + - path: styles + location: styles + - path: styles/favicon.ico + location: favicon.ico + + # - Add MQTT Relay module + - mqtt2-relay: + server: localhost + port: 1883 + currentInterval: 5000 + sampleInterval: 500 + + # - Add SHDR Adapter module for Device = M12346 and Port = 7878 + - shdr-adapter: + deviceKey: M12346 + hostname: localhost + port: 7878 + + # - Add SHDR Adapter module for Device = OKUMA-Lathe and Port = 7879 + - shdr-adapter: + deviceKey: OKUMA-Lathe + hostname: localhost + port: 7879 + + # - Add MQTT Adapter module for Device = M12346 and Topic = cnc-01 + - mqtt-adapter: + deviceKey: M12346 + server: localhost + port: 1883 + topic: cnc-01 -# The server Hostname to bind to. -# Change this to the server's IP Address or hostname -server: localhost - -# The port number the agent binds to for requests. -port: 5000 - -# Configuration for Static Files that can be served from the Http Server -files: -- path: schemas - location: schemas # The maximum number of Observations the agent can hold in its buffer observationBufferSize: 150000 @@ -161,29 +191,6 @@ durable: false defaultVersion: 2.2 ``` -#### HTTP Configuration - -* `port` - The port number the agent binds to for requests. - -* `serverIp` - The server IP Address to bind to. Can be used to select the interface in IPV4 or IPV6. - -* `responseCompression` - Sets the List of Encodings (ex. gzip, br, deflate) to pass to the Accept-Encoding HTTP Header - -* `maxStreamingThreads` - The maximum number of Threads to use for the Http Stream Requests - -* `allowPut` - Allow HTTP PUT or POST of data item values or assets. - -* `allowPutFrom` - Allow HTTP PUT or POST from a specific host or list of hosts. - -* `indentOutput` - Sets the default response document indendation - -* `outputComments` - Sets the default response document comments output. Comments contain descriptions from the MTConnect standard - -* `outputValidationLevel` - Sets the default response document validation level. 0 = Ignore, 1 = Warning, 2 = Strict - -* `files` - Sets the configuration for Static Files that can be served from the Http Server. For more information see () - - #### Agent Configuration * `observationBufferSize` - The maximum number of Observations the agent can hold in its buffer @@ -215,38 +222,6 @@ defaultVersion: 2.2 * `devices` - The Path to look for the file(s) that represent the Device Information Models to load into the Agent. The path can either be a single file or a directory. The path can be absolute or relative to the executable's directory -#### Adapter Configuration - -* `adapters` - List of SHDR Adapter connection configurations. For more information see() - -* `allowShdrDevice` - Sets whether a Device Model can be sent from an SHDR Adapter - -* `preserveUuid` - Do not overwrite the UUID with the UUID from the adapter, preserve the UUID for the Device. This can be overridden on a per adapter basis. - -* `suppressIpAddress` - Suppress the Adapter IP Address and port when creating the Agent Device ids and names for 1.7. This applies to all adapters. - -* `timeout` - The amount of time (in milliseconds) an adapter can be silent before it is disconnected. - -* `reconnectInterval` - The amount of time (in milliseconds) between adapter reconnection attempts. - -#### XML Configuration - -* `devicesNamespaces` - List of extended XML namespaces to use with MTConnectDevicesResponse documents - -* `streamsNamespaces` - List of extended XML namespaces to use with MTConnectStreamsResponse documents - -* `assetsNamespaces` - List of extended XML namespaces to use with MTConnectAssetsResponse documents - -* `errorNamespaces` - List of extended XML namespaces to use with MTConnectErrorResponse documents - - -* `devicesStyle` - List of XSLT Stylesheets to use with MTConnectDevicesResponse documents - -* `streamsStyle` - List of XSLT Stylesheets to use with MTConnectStreamsResponse documents - -* `assetsStyle` - List of XSLT Stylesheets to use with MTConnectAssetsResponse documents - -* `errorStyle` - List of XSLT Stylesheets to use with MTConnectErrorResponse documents #### Windows Service Configuration @@ -259,9 +234,7 @@ defaultVersion: 2.2 Logging is done using [NLog](https://github.com/NLog/NLog) which allows for customized logging through the NLog.config file located in the application's install directory. The loggers are setup so that there is a separate logger for: - **(agent-logger)** MTConnect Agent - **(agent-validation-logger)** MTConnect Data Validation Errors -- **(http-logger)** Http Server -- **(adapter-logger)** MTConnect Adapters -- **(adapter-shdr-logger)** Raw SHDR lines read by the Adapter (used for debugging adapters) +- **(module-logger)** Modules The default [NLog Configuration File](https://github.com/TrakHound/MTConnect.NET/blob/master/src/MTConnect.NET-Applications-Agents/NLog.config) is shown below: diff --git a/agent/MTConnect.NET-Applications-Agents/MTConnectAgentApplication.cs b/agent/MTConnect.NET-Applications-Agents/MTConnectAgentApplication.cs index 93288f2c..57cfb1fa 100644 --- a/agent/MTConnect.NET-Applications-Agents/MTConnectAgentApplication.cs +++ b/agent/MTConnect.NET-Applications-Agents/MTConnectAgentApplication.cs @@ -59,6 +59,7 @@ public class MTConnectAgentApplication : IMTConnectAgentApplication public IMTConnectAgentBroker Agent => _mtconnectAgent; + public event EventHandler OnRestart; diff --git a/agent/Modules/MTConnect.NET-AgentModule-HttpAdapter/MTConnect.NET-AgentModule-HttpAdapter.csproj b/agent/Modules/MTConnect.NET-AgentModule-HttpAdapter/MTConnect.NET-AgentModule-HttpAdapter.csproj index 29b3d88a..48f2747b 100644 --- a/agent/Modules/MTConnect.NET-AgentModule-HttpAdapter/MTConnect.NET-AgentModule-HttpAdapter.csproj +++ b/agent/Modules/MTConnect.NET-AgentModule-HttpAdapter/MTConnect.NET-AgentModule-HttpAdapter.csproj @@ -61,4 +61,11 @@ + + + \ + True + + + diff --git a/agent/Modules/MTConnect.NET-AgentModule-HttpAdapter/README.md b/agent/Modules/MTConnect.NET-AgentModule-HttpAdapter/README.md new file mode 100644 index 00000000..2d9328fa --- /dev/null +++ b/agent/Modules/MTConnect.NET-AgentModule-HttpAdapter/README.md @@ -0,0 +1,28 @@ +![MTConnect.NET Logo](https://raw.githubusercontent.com/TrakHound/MTConnect.NET/dev/img/mtconnect-net-03-md.png) + +# MTConnect HTTP Adapter Agent Module + +## Description +This Agent Module implements an adapter to read from other MTConnect Agents using the MTConnect REST Protocol + +## Configuration +```yaml +- http-adapter: + address: localhost + port: 5001 + deviceKey: M12346 + interval: 100 +``` + +* `address` - The client Agent IP Address or Hostname to read from. + +* `port` - The port number to read from. + + +## Contribution / Feedback +- Please use the [Issues](https://github.com/TrakHound/MTConnect.NET/issues) tab to create issues for specific problems that you may encounter +- Please feel free to use the [Pull Requests](https://github.com/TrakHound/MTConnect.NET/pulls) tab for any suggested improvements to the source code +- For any other questions or feedback, please contact TrakHound directly at **info@trakhound.com**. + +## License +This application and it's source code is licensed under the [MIT License](https://choosealicense.com/licenses/mit/) and is free to use. diff --git a/agent/Modules/MTConnect.NET-AgentModule-HttpServer/MTConnect.NET-AgentModule-HttpServer.csproj b/agent/Modules/MTConnect.NET-AgentModule-HttpServer/MTConnect.NET-AgentModule-HttpServer.csproj index 0acb9ba4..cbbdb6e5 100644 --- a/agent/Modules/MTConnect.NET-AgentModule-HttpServer/MTConnect.NET-AgentModule-HttpServer.csproj +++ b/agent/Modules/MTConnect.NET-AgentModule-HttpServer/MTConnect.NET-AgentModule-HttpServer.csproj @@ -62,4 +62,11 @@ + + + \ + True + + + diff --git a/agent/Modules/MTConnect.NET-AgentModule-HttpServer/README.md b/agent/Modules/MTConnect.NET-AgentModule-HttpServer/README.md new file mode 100644 index 00000000..0e0e1ac6 --- /dev/null +++ b/agent/Modules/MTConnect.NET-AgentModule-HttpServer/README.md @@ -0,0 +1,55 @@ +![MTConnect.NET Logo](https://raw.githubusercontent.com/TrakHound/MTConnect.NET/dev/img/mtconnect-net-03-md.png) + +# MTConnect HTTP Server Agent Module + +## Description +This Agent Module implements the MTConnect REST Protocol + +## Configuration +```yaml + - http-server: + hostname: localhost + port: 7878 + allowPut: true + indentOutput: true + documentFormat: xml + responseCompression: + - gzip + - br + files: + - path: schemas + location: schemas + - path: styles + location: styles + - path: styles/favicon.ico + location: favicon.ico +``` + +* `hostname` - The server IP Address or Hostname to bind to. + +* `port` - The port number the agent binds to for requests. + +* `responseCompression` - Sets the List of Encodings (ex. gzip, br, deflate) to pass to the Accept-Encoding HTTP Header + +* `maxStreamingThreads` - The maximum number of Threads to use for the Http Stream Requests + +* `allowPut` - Allow HTTP PUT or POST of data item values or assets. + +* `allowPutFrom` - Allow HTTP PUT or POST from a specific host or list of hosts. + +* `indentOutput` - Sets the default response document indendation + +* `outputComments` - Sets the default response document comments output. Comments contain descriptions from the MTConnect standard + +* `outputValidationLevel` - Sets the default response document validation level. 0 = Ignore, 1 = Warning, 2 = Strict + +* `files` - Sets the configuration for Static Files that can be served from the Http Server. + + +## Contribution / Feedback +- Please use the [Issues](https://github.com/TrakHound/MTConnect.NET/issues) tab to create issues for specific problems that you may encounter +- Please feel free to use the [Pull Requests](https://github.com/TrakHound/MTConnect.NET/pulls) tab for any suggested improvements to the source code +- For any other questions or feedback, please contact TrakHound directly at **info@trakhound.com**. + +## License +This application and it's source code is licensed under the [MIT License](https://choosealicense.com/licenses/mit/) and is free to use. diff --git a/agent/Modules/MTConnect.NET-AgentModule-ShdrAdapter/MTConnect.NET-AgentModule-ShdrAdapter.csproj b/agent/Modules/MTConnect.NET-AgentModule-ShdrAdapter/MTConnect.NET-AgentModule-ShdrAdapter.csproj index 0645f108..a6613b2f 100644 --- a/agent/Modules/MTConnect.NET-AgentModule-ShdrAdapter/MTConnect.NET-AgentModule-ShdrAdapter.csproj +++ b/agent/Modules/MTConnect.NET-AgentModule-ShdrAdapter/MTConnect.NET-AgentModule-ShdrAdapter.csproj @@ -61,4 +61,11 @@ + + + \ + True + + + diff --git a/agent/Modules/MTConnect.NET-AgentModule-ShdrAdapter/README.md b/agent/Modules/MTConnect.NET-AgentModule-ShdrAdapter/README.md new file mode 100644 index 00000000..2c9a015d --- /dev/null +++ b/agent/Modules/MTConnect.NET-AgentModule-ShdrAdapter/README.md @@ -0,0 +1,33 @@ +![MTConnect.NET Logo](https://raw.githubusercontent.com/TrakHound/MTConnect.NET/dev/img/mtconnect-net-03-md.png) + +# MTConnect SHDR Adapter Agent Module + +## Description +This Agent Module implements the MTConnect REST Protocol + +## Configuration +```yaml +- shdr-adapter: + deviceKey: M12346 + hostname: localhost + port: 7878 +``` + +* `allowShdrDevice` - Sets whether a Device Model can be sent from an SHDR Adapter + +* `preserveUuid` - Do not overwrite the UUID with the UUID from the adapter, preserve the UUID for the Device. This can be overridden on a per adapter basis. + +* `suppressIpAddress` - Suppress the Adapter IP Address and port when creating the Agent Device ids and names for 1.7. This applies to all adapters. + +* `timeout` - The amount of time (in milliseconds) an adapter can be silent before it is disconnected. + +* `reconnectInterval` - The amount of time (in milliseconds) between adapter reconnection attempts. + + +## Contribution / Feedback +- Please use the [Issues](https://github.com/TrakHound/MTConnect.NET/issues) tab to create issues for specific problems that you may encounter +- Please feel free to use the [Pull Requests](https://github.com/TrakHound/MTConnect.NET/pulls) tab for any suggested improvements to the source code +- For any other questions or feedback, please contact TrakHound directly at **info@trakhound.com**. + +## License +This application and it's source code is licensed under the [MIT License](https://choosealicense.com/licenses/mit/) and is free to use. diff --git a/agent/Processors/MTConnect.NET-AgentProcessor-Python/MTConnect.NET-AgentProcessor-Python.csproj b/agent/Processors/MTConnect.NET-AgentProcessor-Python/MTConnect.NET-AgentProcessor-Python.csproj index 8fabeed5..9511cce7 100644 --- a/agent/Processors/MTConnect.NET-AgentProcessor-Python/MTConnect.NET-AgentProcessor-Python.csproj +++ b/agent/Processors/MTConnect.NET-AgentProcessor-Python/MTConnect.NET-AgentProcessor-Python.csproj @@ -62,4 +62,11 @@ + + + \ + True + + + diff --git a/agent/Processors/MTConnect.NET-AgentProcessor-Python/README.md b/agent/Processors/MTConnect.NET-AgentProcessor-Python/README.md new file mode 100644 index 00000000..8226b9e3 --- /dev/null +++ b/agent/Processors/MTConnect.NET-AgentProcessor-Python/README.md @@ -0,0 +1,83 @@ +![MTConnect.NET Logo](https://raw.githubusercontent.com/TrakHound/MTConnect.NET/dev/img/mtconnect-net-03-md.png) + +# MTConnect Python Agent Processor + +## Description +This Agent Processor uses individual Python script files to transform input data + +## Configuration +```yaml +- python: + directory: processors +``` + +* `directory` - The directory to load and monitor for ".py" script files. + +## Scripts +Scripts are implemented using IronPython and supports Python v3. Both the MTConnect Entity to process and the MTConnect Agent are both accessible from the script. + +### Example 1 +Change the Result for a DataItem with a Type = "EMERGENCY_STOP" +```python +def process(observation): + + if observation.DataItem.Type == 'EMERGENCY_STOP': + + result = observation.GetValue('Result') + + if result.lower() == 'TRUE'.lower(): + observation.AddValue('Result', 'ARMED') + else: + observation.AddValue('Result', 'TRIGGERED') + + return observation +``` + +### Example 2 +Change the Result for a DataItem with a Type = "PATH_FEEDRATE_OVERRIDE" from a Percentage to an Integer by multiplying by 100 +```python +def process(observation): + + if observation.DataItem.Type == 'PATH_FEEDRATE_OVERRIDE': + + result = float(observation.GetValue('Result')) + observation.AddValue('Result', result * 100) + + return observation +``` + +### Example 3 +Add a new TimeSeries observation for any time a DataItem with an ID = "L2p1Fact" changes +```python +import clr +clr.AddReference("MTConnect.NET-Common") +import MTConnect.Input + +def process(observation): + + if observation.DataItem.Id == "L2p1Fact": + + timeseries = MTConnect.Input.TimeSeriesObservationInput() + timeseries.DataItemKey = 'L2p1Sensor' + timeseries.SampleRate = 100 + + n = 15 + samples = [0] * n + + for x in range(n): + samples[x] = float(x) + + timeseries.Samples = samples + + observation.Agent.AddObservation(observation.DataItem.Device.Uuid, timeseries) + + return observation +``` + +## Contribution / Feedback +- Please use the [Issues](https://github.com/TrakHound/MTConnect.NET/issues) tab to create issues for specific problems that you may encounter +- Please feel free to use the [Pull Requests](https://github.com/TrakHound/MTConnect.NET/pulls) tab for any suggested improvements to the source code +- For any other questions or feedback, please contact TrakHound directly at **info@trakhound.com**. + +## License +This application and it's source code is licensed under the [MIT License](https://choosealicense.com/licenses/mit/) and is free to use.