> For the complete documentation index, see [llms.txt](https://help.aranet.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.aranet.com/gateway/gateway-pro/integrations-and-3rd-party-systems/modbus.md).

# Modbus

Use **Modbus TCP** to integrate Gateway Pro sensor data with third‑party automation and control systems.

### Modbus TCP protocol basics

Gateway Pro uses **Modbus TCP** (Modbus over TCP/IP).

Key protocol points:

* **Transport**: TCP.
* **Default port**: `502`.
* **Client/server roles**: the data consumer is commonly called the **client** (or master). The device serving data is the **server** (or slave).
* **Data model**: values are exposed through addressable objects (commonly called coils and registers). A **register map** defines which values are available and where.
* **Unit ID**: a device identifier included in Modbus TCP frames. It is mainly used for routing through TCP-to-serial gateways. Many Modbus clients still require it to be set and to match the server configuration.

{% hint style="info" %}
Modbus address notation varies by tool.

Some clients show **0-based** register offsets. Others show **1-based** addresses (for example, “4xxxx” holding registers).
{% endhint %}

### Prerequisites

* You have an **Aranet Cloud** account.
* Your Gateway Pro is connected to Aranet Cloud. See [Connecting to Aranet Cloud](/gateway/gateway-pro/gateway-pro-configuration/connecting-to-aranet-cloud.md).
* Use the latest Gateway Pro firmware. See [Updating the Firmware](/gateway/gateway-pro/gateway-pro-configuration/updating-the-firmware.md).

### Enable Modbus integration

1. On Gateway Pro, open **Settings**.
2. Press **Integrations**.
3. Verify that the Gateway Pro is connected to Aranet Cloud.

If the Gateway Pro is not connected, you’ll see the following screen:

<figure><img src="/files/wEdd4RctrwTYZRHO8hYZ" alt="" width="375"><figcaption></figcaption></figure>

Press **Connect to Aranet Cloud**. Scan the QR code to add the Gateway Pro to a workspace.

You can also connect from Aranet Cloud directly: <https://help.aranet.com/aranet-cloud-page/aranet-cloud-landing-page/gateway-management/connect-gateway>

In Aranet Cloud:

1. Open the Gateway Pro.
2. Click **MANAGE**.
3. Open **Integration configuration**.
4. Select **MODBUS** and enable it.

Configure the required fields:

* **Port** (default: `502`)
* **Unit ID** (must match the Unit ID used by your Modbus client/master)
* **JSON file**: the register layout definition.\
  This file defines how Gateway Pro data is mapped to Modbus addresses.\
  Aranet Cloud provides an auto-generated default register layout file that you can download and review.

<div data-with-frame="true"><figure><img src="/files/9TXZde2qKcagDaq8dLAS" alt=""><figcaption></figcaption></figure></div>

Click **Save**.

{% hint style="info" %}
Close the Cloud management tab when you’re done.

The Gateway Pro UI may be unresponsive while the remote management session is open.
{% endhint %}

### Integration status

The Gateway Pro **Dashboard** shows an integration icon. Icon color indicates the current status.

**Green** means Modbus is active and healthy.

<figure><img src="/files/NqPtGIw8TCJBJrGAjUEy" alt="" width="375"><figcaption></figcaption></figure>

**Yellow** means Modbus is active, but there is a warning. Press the integration icon to view details.

<figure><img src="/files/jHyC7NEJxIqSQnvVC0n5" alt="" width="375"><figcaption></figcaption></figure>

**Red** means Modbus has an error and is unavailable. Press the integration icon to view details.

<figure><img src="/files/itwga9yG9znnnseb8a3m" alt="" width="375"><figcaption></figcaption></figure>

#### Status messages

{% tabs %}
{% tab title="Green icon (Active)" %}

<div align="left"><figure><img src="/files/1X26lCsQ04hjbaURVWnP" alt=""><figcaption></figcaption></figure></div>

Green icon + status text **Active**:

All statuses with `_INFO_` except `_INFO_DISABLED_BY_USER`.

* MODBUS\_INFO\_NO\_ERR
  {% endtab %}

{% tab title="Yellow icon (Warning)" %}

<div align="left"><figure><img src="/files/dL0i6GbCjWqSgEyuIk7u" alt=""><figcaption></figcaption></figure></div>

Yellow icon + status text **Warning**:

All statuses with `_WARNING_`.

* MODBUS\_WARNING\_MAP\_ADDR\_COLLISION
* MODBUS\_WARNING\_MAP\_OFFSET\_INVALID
  {% endtab %}

{% tab title="Red icon (Error / Expired)" %}

<div align="left"><figure><img src="/files/uz12XpgBmz3PUOR9CSsC" alt=""><figcaption></figcaption></figure></div>

Red icon + status text **Error**:

All statuses with `_ERROR_` except `_ERROR_DISABLED_BY_LICENCE`.

* MODBUS\_ERROR\_CONTEXT\_NULL
* MODBUS\_ERROR\_CONTEXT\_FAILED
* MODBUS\_ERROR\_MAP\_ALLOC\_FAILED
* MODBUS\_ERROR\_MAP\_JSON\_FAILED
* MODBUS\_ERROR\_MAP\_OFFSET\_MISSING
* MODBUS\_ERROR\_SETTINGS\_CONFIG\_FAILED
* MODBUS\_ERROR\_SETTINGS\_JSON\_EMPTY
* MODBUS\_ERROR\_SETTINGS\_WRONG\_PORT
* MODBUS\_ERROR\_SETTINGS\_WRONG\_UNIT\_ID
* MODBUS\_ERROR\_LISTEN\_FAILED
* MODBUS\_ERROR\_UNKNOWN\_ERROR

Red icon + status text **Expired**:

* MODBUS\_ERROR\_DISABLED\_BY\_LICENCE
  {% endtab %}

{% tab title="Grey icon" %}

<div align="left"><figure><img src="/files/0ZDLR2hc2KTo5AnJblli" alt=""><figcaption></figcaption></figure></div>

Grey icon

Is being shown when integration was Disabled by the user, and the license is either Available or Active.
{% endtab %}
{% endtabs %}

You can also see the status in Aranet Cloud:

<div data-with-frame="true"><figure><img src="/files/LzZlhO08gfZsVjrzjQUN" alt=""><figcaption></figcaption></figure></div>

### Modbus details shown on Gateway Pro

On the Gateway Pro display, Modbus details include:

* **Status (message)**: current Modbus integration state.
* **Updated**: timestamp of the last status refresh.
* **Port**: configured Modbus TCP port.
* **Unit ID**: configured Unit ID.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.aranet.com/gateway/gateway-pro/integrations-and-3rd-party-systems/modbus.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.