Integrate OpexMx with Your Machines

How to send machine parameter values from PLCs and gateways to the OpexMx API.

Overview

To bring live data from your machines into OpexMx, you typically need a gateway or middleware that can:

  • Read industrial protocols (e.g. Modbus, MQTT, OPC UA, …) from PLCs, sensors, or SCADA
  • Transform values into OpexMx's API format
  • Call our HTTP API over the network

OpexMx itself does not speak field protocols directly. Instead, your edge device (industrial PC, PLC, or gateway) is responsible for reading the protocol and then calling the OpexMx API.

For the full API reference, see: /api/openapi/scalar#tag/machine-parameter-values/post/machine-parameter-values.

API: Send Machine Parameter Values

Endpoint

  • Method: POST
  • Path: /api/machine-parameter-values

Request Body

{
  "machineParameterId": "string",
  "value": "string",
  "createdAt": "2025-12-04T07:24:20.069Z"
}
  • machineParameterId: ID of the parameter you configured in OpexMx (e.g. spindle speed, temperature, pressure).
  • value: Measured value as a string (you can send numeric values as strings; we handle parsing).
  • createdAt: ISO 8601 timestamp (UTC) when the value was captured at the machine.

Example curl Request

curl http://localhost:3000/api/machine-parameter-values \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
    "machineParameterId": "SPINDLE_SPEED",
    "value": "1500",
    "createdAt": "2025-12-04T07:24:20.069Z"
  }'

Response (201 Created)

{
  "machineParameterId": "string",
  "value": "string",
  "createdAt": "2025-12-04T07:24:20.069Z"
}

In production, replace http://localhost:3000 with your deployed OpexMx URL and attach authentication headers if required by your environment.

Architecture: Where the Integration Lives

Typical flow:

  1. PLC / Machine / Sensor
    Exposes data via Modbus, MQTT, OPC UA, or another industrial protocol.
  2. Gateway / Middleware (your component)
    • Reads machine values using a driver or SDK
    • Maps PLC addresses / topics / nodes to machineParameterIds in OpexMx
    • Periodically or on-change sends values to /api/machine-parameter-values
  3. OpexMx
    • Stores the values
    • Makes them available for dashboards, analytics, and alerts.

You can implement the gateway in any language or platform that can:

  • Connect to your field protocol
  • Perform HTTP POST requests with JSON

Tips for Connecting to Industrial Protocols

Modbus (TCP / RTU)

  • Use an existing Modbus client library (for example, pymodbus in Python, node-modbus in Node.js, or vendor-specific SDKs).
  • Define a mapping between Modbus addresses and machineParameterIds in OpexMx:
    • e.g. Holding register 40001 → SPINDLE_SPEED
    • e.g. Holding register 40002 → SPINDLE_LOAD
  • Normalize values before sending:
    • Apply scaling (e.g. raw 1500 → 1500 RPM)
    • Convert data types (16-bit/32-bit, signed/unsigned, floats).

Example pseudo-code:

// read from Modbus and push to OpexMx
const value = await readModbusRegister(40001) // e.g. 1500

await fetch("https://your-opexmx-url.com/api/machine-parameter-values", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    machineParameterId: "SPINDLE_SPEED",
    value: String(value),
    createdAt: new Date().toISOString(),
  }),
})

MQTT

  • Configure your gateway to subscribe to specific topics published by the PLC or edge device.
  • Map MQTT topics to machineParameterIds:
    • e.g. factory/line1/machineA/speed → SPINDLE_SPEED
    • e.g. factory/line1/machineA/temp → MOTOR_TEMP
  • Ensure payloads can be parsed (JSON or plain numeric strings are easiest).

Your MQTT client handler should, on every new message:

  1. Extract the value from the payload
  2. Determine the corresponding machineParameterId
  3. Call /api/machine-parameter-values with the value and timestamp.

OPC UA

  • Use an OPC UA client SDK (e.g. node-opcua, open62541, or your vendor's preferred library).
  • Create a mapping between OPC UA NodeIds and machineParameterIds.
  • Set up subscriptions/monitored items for the nodes you care about.
  • On every data change callback:
    • Read the new value
    • Send it to OpexMx with the timestamp provided by OPC UA if available.

Best Practices

  • Time synchronization

    • Keep your gateway's clock synchronized (e.g. using NTP) so createdAt is accurate.

  • Idempotency & batching

    • If your use case requires very high frequency data, consider batching multiple samples and/or reducing frequency to what your use case really needs.

  • Error handling & retries

    • If the OpexMx API is temporarily unavailable, queue data locally and retry with backoff.

  • Security

    • Run the gateway inside your industrial network.
    • Restrict outbound traffic to your OpexMx endpoint.
    • Use HTTPS in production and include authentication if configured.

Summary

  1. Use a gateway or middleware that can talk Modbus, MQTT, OPC UA, or your machine’s protocol.
  2. Map each field/tag/topic/node to a machineParameterId in OpexMx.
  3. On each new value, POST to /api/machine-parameter-values with { machineParameterId, value, createdAt }.

This pattern keeps your industrial network and protocol handling close to the machines, while OpexMx focuses on storing, visualizing, and acting on your data.