HTTP Server

Serve the MTConnect REST protocol (/probe, /current, /sample, /asset) over HTTP or HTTPS.
MTConnect.NET Docs Menu
  • Module name — MTConnect HTTP Server agent module
  • Identifier — http-server
  • NuGet package — MTConnect.NET-AgentModule-HttpServer
  • Source path — agent/Modules/MTConnect.NET-AgentModule-HttpServer/

Purpose

Serves the MTConnect REST protocol — /probe, /current, /sample, /asset — over HTTP or HTTPS. This is the most common way to expose an agent to dashboards, bridges, and other consumers. The module wraps MTConnectHttpServer (under MTConnect.Servers.Http), accepts content-negotiated XML and JSON output, optionally accepts HTTP PUT of observations and assets, and serves a configurable set of static files (schemas, stylesheets, favicons).

Configuration Schema

The module's configuration class is HttpServerModuleConfiguration (it derives from HttpServerConfiguration). The keys below describe the YAML map under http-server:. Booleans use lowercase true / false; integer ports are unquoted decimals.

KeyTypeDefaultPermissible valuesNotes
hostnamestringnull (binds to all interfaces)hostname, IP address, or localhostThe IP address or hostname the server binds to.
portint50001-65535The TCP port to listen on.
tlsmapnull (HTTP only)see belowTLS configuration; presence switches the listener to HTTPS.
acceptmap[string,string]{ "text/xml": "XML", "application/xml": "XML", "application/json": "JSON" }HTTP-accept-header to document-format-id pairsNegotiates the response document format from the Accept header.
responseCompressionstring[]nullgzip, br, deflateCompression encodings advertised to the client.
allowPutboolfalsetrue, falseAllow HTTP PUT or POST of observation values and assets.
allowPutFromstring[]nullhostname or IP listRestricts PUT / POST access to listed hosts when allowPut is true.
defaultVersionstringunset (latest)MTConnect version (e.g. 1.7, 2.0, 2.7)The MTConnect version the agent emits when the request does not specify one.
documentFormatstringXMLXML, JSON, JSON-cppAgentDefault response document format.
indentOutputbooltruetrue, falseIndents the response document for readability.
outputCommentsboolfalsetrue, falseEmbeds MTConnect-standard descriptions as comments in the response.
outputValidationLevelint00 (Ignore), 1 (Warning), 2 (Strict)Server-side validation level applied before emitting the response.
fileslist of FileConfigurationnullsee belowStatic files served alongside the protocol endpoints (schemas, stylesheets, favicon).
devicesNamespaceslist of NamespaceConfigurationnullsee belowExtra XML namespaces injected into Devices envelopes.
streamsNamespaceslist of NamespaceConfigurationnullas aboveExtra XML namespaces injected into Streams envelopes.
assetsNamespaceslist of NamespaceConfigurationnullas aboveExtra XML namespaces injected into Assets envelopes.
errorNamespaceslist of NamespaceConfigurationnullas aboveExtra XML namespaces injected into Error envelopes.
devicesStyleStyleConfigurationnullXSLT stylesheet referenceServer-side XSLT applied to Devices responses.
streamsStyleStyleConfigurationnullas aboveServer-side XSLT applied to Streams responses.
assetsStyleStyleConfigurationnullas aboveServer-side XSLT applied to Assets responses.
errorStyleStyleConfigurationnullas aboveServer-side XSLT applied to Error responses.

files[] Schema

Each entry describes a static-file mount:

KeyTypePermissible valuesNotes
pathstringfilesystem pathThe location on the server (relative to the agent's working directory or absolute).
locationstringURL path segmentThe path component to match in the inbound URL.

tls Schema

The map accepts either a PFX bundle or a PEM triple:

KeySub-keyTypeNotes
pfxcertificatePathstringPath to the .pfx file.
pfxcertificatePasswordstringPFX password.
pemcertificatePathstringPath to the .pem certificate file.
pemprivateKeyPathstringPath to the key file.
pemprivateKeyPasswordstringKey password (if encrypted).
pemcertificateAuthoritystringPath to the CA certificate.
verifyClientCertificate—boolToggles mutual-TLS verification of client certificate chains.

Wire Interaction

ConsumerA dashboard, bridge, or browser
HTTP
http-server modulePort 5000 by default
AgentDevices and the sequence buffer
  1. Probe
  2. Consumer http-serverGET /probe
  3. http-server AgentGetDevicesResponseDocument(...) returns the Devices document
  4. http-server Consumer200 OK with the Devices document
  5. Current
  6. Consumer http-serverGET /current
  7. http-server BufferGetObservations(at: latest) returns the latest Observation of each DataItem
  8. http-server Consumer200 OK with a Streams document
  9. Sample
  10. Consumer http-serverGET /sample?from=N&heartbeat=10000
  11. http-server BufferGetObservations(from: N, ...) returns a page of Observations
  12. http-server Consumer200 OK with a Streams document, or a chunked stream of new pages
Streaming /sample requests stay open, with a heartbeat when there's nothing new to send.

For long-running sample requests the module emits an HTTP chunked-transfer stream and pushes new observation pages as the agent receives them, holding the connection open up to the configured heartbeat interval.

Example Configuration

modules:
  - http-server:
      hostname: 0.0.0.0
      port: 5000
      allowPut: true
      indentOutput: true
      documentFormat: XML
      accept:
        text/xml: XML
        application/xml: XML
        application/json: JSON-cppAgent
      responseCompression:
        - gzip
        - br
      files:
        - path: schemas
          location: schemas
        - path: styles
          location: styles
        - path: styles/favicon.ico
          location: favicon.ico
      tls:
        pfx:
          certificatePath: /etc/mtconnect/certs/agent.pfx
          certificatePassword: changeme
        verifyClientCertificate: false

Troubleshooting

  • XSD validation failures — see XSD validation failures. The .NET BCL ships XSD 1.0 features only; the v2.x MTConnect schemas use XSD 1.1 constructs.
  • MQTT TLS handshake failures apply to the broker / relay modules; for HTTPS handshake failures the certificate must be readable by the agent's user account and the tls.pfx.certificatePassword must decrypt the PFX bundle.
  • Schema-version mismatches — set defaultVersion to the MTConnect version the consumer expects when the consumer does not send a version parameter.

Classes

The main classes in the MTConnect.NET-AgentModule-HttpServer package:

  • HttpServerModuleConfiguration — the module's configuration class.
  • HttpServerConfiguration — the base configuration shape this module extends.
  • MTConnectHttpServer — the runtime HTTP server the module wraps.
  • MTConnectShdrHttpAgentServer — the concrete server with SHDR-protocol PUT handling enabled.
  • TlsConfiguration — the TLS configuration schema.