# Agent Hub

> Replace an existing MTConnect Agent, or serve Devices from many Agents and SHDR Adapters from a single port as a central hub.

URL: https://www.trakhound.com/docs/mtconnect-server/agent-hub

The **Agent Hub** is a complete MTConnect Agent for every machine, served from a single port. It can **replace an existing Agent**, or act as a **central hub** for the Agents you already have, giving client applications one place to read data from across the shop floor. It's run by the **Agent Hub Worker**, powered by the [MTConnect.NET](https://www.trakhound.com/docs/mtconnect-net) Agent, and is free to use, with no License.

- Each Device runs its **own MTConnect Agent**, with a buffer and instance ID isolated from every other Device. Restarting or changing one Device doesn't affect the others.
- All Devices are served from **one HTTP port** (default `5001`), with the Device UUID as the first part of the path.
- The endpoints are the **standard MTConnect HTTP requests**, so any MTConnect client can read them.

Diagram: Agents and SHDR Adapters are each read into their own MTConnect Agent inside the Agent Hub, which serves all of them from port 5001 with the Device UUID in the path.

> MTConnect Server is designed to run on a **central server** and serve every machine from one place, set up from the browser. The [MTConnect.NET Agent](https://www.trakhound.com/docs/mtconnect-net) is designed to run **on the machine**, as one Agent for each machine or control. They work together: the Agent Hub can serve MTConnect.NET Agents as a central hub, or replace them by reading the machines' Adapters directly.

## Two Ways to Use It

Each Device chooses its source, so the two can be mixed on one Hub.

|  | Replace an Existing Agent | A Central Hub |
| --- | --- | --- |
| **Source** | An SHDR Adapter, read directly | An existing MTConnect Agent |
| **Device model** | A Device file you upload, copy from the old Agent's probe, or paste, or a saved [Model](https://www.trakhound.com/docs/mtconnect-server/models) | The Agent's probe, or a saved Model in its place |
| **Use when** | You want one Agent to install and maintain instead of a separate Agent for each machine or cell | The Agents are already running (ex. built into a control or supplied with a machine), and clients should read every machine from one address |
| **After a restart** | Data the Adapter sent while disconnected is lost, the same as a standalone Agent | Reads what was missed from the Agent's buffer |

### Replacing an Agent

1. Add a Device for each Adapter the Agent reads from (**Devices > Add Device > SHDR Adapter**). Copy the Device model from the Agent's probe, so the DataItem IDs stay the same.
2. Check the Device's **AgentHub Data** tab, and that **Keys Not in Model** stays at zero.
3. Stop the old Agent, since some Adapters only accept one client.
4. Point clients at the Hub. Each Device is served under its UUID (ex. `http://{server}:5001/{deviceUuid}/current`), not at the root, so update the URLs clients read from.

> To keep a port clients already use (ex. `5000`), set it as the Hub's **Port** once the old Agent is stopped. Sequence numbers and the instance ID start over, the same as when an Agent restarts, so clients read from the start of the new buffer.

## Serve a Device

Turn on **Serve through the AgentHub** when [adding a Device](https://www.trakhound.com/docs/mtconnect-server/devices), or click **Add to AgentHub** on its **AgentHub** tab. The Device is started as soon as it's enabled.

- **MTConnect Agent** - The Device model comes from the Agent's probe, or from a saved [Model](https://www.trakhound.com/docs/mtconnect-server/models). After a restart, the Device reads what was missed from the Agent's buffer.
- **SHDR Adapter** - The Device is described by its Device model, and the Adapter's keys are matched to the model's DataItems.
- A Device is published with its configured UUID, or the UUID of its source (the Agent or the Device model) when one isn't set.

## Endpoints

```
http://{server}:5001/{deviceUuid}/probe
http://{server}:5001/{deviceUuid}/current?path=//DataItem[@type="EXECUTION"]
http://{server}:5001/{deviceUuid}/sample?from=100&count=500
http://{server}:5001/{deviceUuid}/sample?interval=1000
http://{server}:5001/{deviceUuid}/assets
```

Probe, Current, Sample (including `interval` streaming), Assets, Asset, PUT / POST, `path` filters, document formats, and compression all behave the same as a standard MTConnect Agent. A request for an unknown Device UUID returns an MTConnect error document (`NO_DEVICE`).

### List the Devices

`GET http://{server}:5001/` returns the running Devices as JSON, with each Device's UUID, configuration ID, name, Group, manufacturer, model, Connection Status, and probe path. A Device doesn't have a UUID or probe path until it's available.

There isn't a probe of all Devices. Each Device keeps the IDs from its source, and IDs must be unique within an MTConnect document, so two Devices using the same ID would make a combined document invalid.

### The Agent Device

The Agents serving Devices don't include an MTConnect Agent Device, so a Device's sequence numbers are only used by its own Observations. The Hub has a single Agent Device, served by its own Agent at `/agent/`, with an Adapter Component for each running Device that reports its source URI and Connection Status:

```
http://{server}:5001/agent/probe
http://{server}:5001/agent/current
```

`agent` is reserved, so a Device can't be published with that UUID. The Agent Device is read only, and its values aren't kept when the Worker restarts.

## Hub Settings

Go to **AgentHub > Hub**. The settings apply to every Device, and the defaults work for most installs:

| Setting | Default | Description |
| --- | --- | --- |
| Enabled | On |  |
| Address | (blank) | Blank listens on all network interfaces |
| Port | `5001` | Allow it through the Windows Firewall for MTConnect clients on other computers. (`5000` is commonly used by MTConnect Agents) |
| Document Format | `XML` | `XML`, `JSON`, or `JSON-cppagent` |
| MTConnect Version | (blank) | The version of response documents. Blank for the latest |
| Output Validation |  | The validation level of response documents |
| Response Compression | None | `gzip`, `deflate`, and / or `br` |
| Indent Output / Output Comments |  | Formatting of response documents |
| Allow PUT / POST | Off | Allow Observations and Assets to be added over HTTP, optionally only from specific IP addresses |
| Certificate (TLS) | None | Serve over https with a PFX or PEM certificate |

Click **Save Changes**. Changing the Hub settings restarts every Device's Agent, which clears its buffer.

> The Agent Hub's port doesn't require signing in, since MTConnect clients don't sign in. Only allow it through the firewall on networks that should read the machines' data.

## Overview and Statistics

**AgentHub** in the menu is a live overview of the Hub: how many enabled Devices are connected, Observations per minute, active clients and requests, and whether the Hub is running, with charts over the last 10 minutes. **Needs Attention** lists Devices that aren't connected or served, and Devices with rejected Observations. Each Device is listed with its metrics, under its [Group](https://www.trakhound.com/docs/mtconnect-server/groups).

![The Agent Hub overview, with two Devices connected](https://www.trakhound.com/img/screenshots/previews/mtconnect-server-agent-hub.webp)

**AgentHub > Statistics** charts the Observations and rejected Observations per second, requests per second, and active clients for each Device or all of them, with a table of each Device's counters.

![Agent Hub Statistics, with each Device's counters and charts of the last 10 minutes](https://www.trakhound.com/img/screenshots/previews/mtconnect-server-agent-hub-statistics.webp)

| Metric | Description |
| --- | --- |
| **Observations / min** | Observations added to the Device's Agent in the last minute. A value that didn't change isn't added |
| **Observations** | Observations added since the Device started, not counting the initial `UNAVAILABLE` values |
| **Rejected** | Observations the Device's Agent rejected |
| **Keys Not in Model** | For an SHDR Adapter, the keys received that have no DataItem in the Device model. Their data is ignored |
| **Connections** / **Connection Errors** | How many times the connection to the source was established, and how many connection errors occurred |
| **Active Clients** / **Requests** | Requests in progress (including `sample` streams), and all requests to the Device through the Hub |

Metrics count from when a Device started, and restart when it restarts (ex. its Configuration is changed or the Worker restarts). A served Device's **AgentHub** and **AgentHub Data** tabs show its own metrics, URLs, and buffer, and what the Hub serves for it (see [Devices](https://www.trakhound.com/docs/mtconnect-server/devices#device-page)).
