> 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/base-stations/base-stations/integrations-and-3rd-party-systems/modbus/modbus-tcp-ip-configuration.md).
# Modbus TCP/IP configuration
## Modbus TCP/IP server menu and configuration settings
To enable Modbus TCP/IP feature on the Aranet base station, in the WebGUI navigate to the main menu sidebar item
shown in Fig. 1. Please note that use Modbus TCP/IP server feature requires appropriate licence file to be uploaded on
the base station.
{% columns %}
{% column %}
Figure 1: WebGUI main sidebar menu.
{% endcolumn %}
{% column valign="middle" %}
Figure 2: TCP/IP configuration menu
{% endcolumn %}
{% endcolumns %}
The following items are shown in the Modbus TCP/IP configuration panel as indicated in Fig. 2:
1. Status of Modbus TCP/IP server process
2. Switch to enable or disable server process.
3. Field to specify TCP port number (default is 502).
4. Set Modbus TCP/IP server Unit ID (a.k.a. Device ID). This must be the same as one set in TCP/IP Client side. In some Client (Master) applications, this setting may be referred to as ”Slave ID”. Client requests
with incorrect Unit ID on the Modbus TCP/IP server side will be ignored (communication timeout);
5. Reset auto-generated address-to-measurements mapping configuration file. WARNING: all addresses used will
be reset and may differ from those assigned in previous default mapping file. This request does not affect addressing
defined by “Custom layout file”.
6. Download auto-generated address-to-measurements mapping configuration file.
7. Switch to enable or disable custom mapping configuration file usage. (This feature allows to upload a userspecified address-to-measurements configuration file.)
8. Button to save configuration changes.
9. Button to revert the previous configuration without saving changes.
### Process status description
| Displayed status | Description |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SUCCESS\_NO\_ERR | No error. Modbus TCP/IP service functions correctly |
| MODBUS\_DISABLED\_BY\_USER | Service is disabled by the user. Service is not working |
| MODBUS\_DISABLED\_BY\_LICENCE | An appropriate license is not available to run this service. |
|
Service is not working.
| |
| WARN\_ADDR\_COLLISION | Warning state. Registry address overlaps with other address
(more info in “details”). Modbus server continues to accept
incoming requests and sends responses except for the registers with colliding addresses. |
| WARN\_OFFSET\_OR\_ADDRESS\_OUT\_OF\_RANGE | Warning state. One or more used offset values or resulting registry addresses (sum of all three offsets per measurement) are out of the expected range (0–65535). Modbus
server continues to accept incoming requests and sends responses except for the registers with invalid offset values or
resulting registry addresses (more info in “details”). |
| ERR\_CONTEXT\_FAILED | Error occurred. Process failed to allocate memory for the
Modbus TCP/IP server instance (not enough free memory). |
| ERR\_MAP\_ALLOC\_FAILED | Error occurred. Modbus address mapping instance allocation failed (not enough free memory). |
| ERR\_CONTEXT\_NULL | Error occurred. Error on opening Modbus TCP/IP server
socket. |
| ERR\_LISTEN\_FAILED | Error occurred. Failed to listen for incoming Modbus TCP/IP
connections (port already in use). |
| ERR\_CONFIG\_JSON\_FAILED | Error occurred. Failed to load mapping configuration JSON
file. |
| SERV\_SETTINGS\_ERR\_CONFIG\_LOAD | Error occurred. Failed to load settings configuration file (in
order to load Modbus service settings). |
| SERV\_SETTINGS\_ERR\_JSON\_EMPTY | Error occurred. The settings configuration file has an invalid
JSON structure. |
| SERV\_SETTINGS\_ERR\_WRONG\_PORT | Error occurred. Incorrect port number in the service configuration. |
| ERR\_OFFSET\_MISSING | Error occurred. Offset field is missing or type is incorrect in
mapping configuration (more info in “details”). |
Address-to-measurements mapping configuration file
#### Modbus object types
Modbus protocol has four object types (usage depends on desired functionality and data type). It is expected that in
the configuration file there are all four of these objects defined.
Modbus protocol has four object types (usage depends on desired functionality and data type). It is expected that in the configuration file there are all four of these objects defined.
| Object name | Amount of registers | Amount of bits | Read function | Write function |
|---|
| coils | 1 | 1 | Yes | Yes |
| discreteInputs | 1 | 1 | Yes | No |
| inputRegisters | 1 | 16 | Yes | No |
| holdingRegisters | | 16 | Yes | Yes |
Each type has its own address range. Each range has an offset defined by the field named offset. The address value is limited to two bytes (0–65535). There is no binding between each object type and specific address range, e.g., coils can have a range 0–9999, discrete inputs 10000–19999, input registers 20000–29999, holding registers 30000–39999, or any other configuration.
Current implementation supports discreteInputs and inputRegisters object types only. Addresses can be in the range 0–65535. All other types can be defined in the configuration file, but they will be ignored. It refers also to function codes. Only function codes 2 (read discreteInputs) and 4 (read inputRegisters) are supported.
Example minimal JSON showing an offset:
```json
{
"inputRegisters": {
"offset": 30000
}
}
```
Discrete input type returns sensors' “packets lost” (RSSI alarm) state: 0 (alarm inactive) or 1 (alarm active, sensor is lost). Implementation is available starting from firmware version 3.2.4. Starting from version 4.8.x, measurement threshold alarm states can also be read from discrete input registers.
### Object type to sensor mapping
Each Modbus object type can have a set of sensors as nested JSON objects. For each sensor object, there is expected to have its own address offset within its parent Modbus object type address range. Here is an example with sensors mapped to Modbus data type having offsets defined:
```json
{
"inputRegisters": {
"offset": 30000,
"1056849": {"offset": 0}, // register address will start from 3000X
"4196581": {"offset": 40} // register address will start from 3004X
}
}
```
Numbers “1056849” and “4196581” are internal sensor identificators. Sensors HEX identificator is mentioned in the comment of the auto-generated address-to-measurements mapping configuration file (see “Confguration controls”, Pt. 4) in the same line next to the sensor identificator.
### Address-to-sensor-to-measurement mapping
Each measurement has a field named offset which is mandatory for each object and must have a unique value between that sensor’s other measurement offset values (same rule applies also to sensors – unique offset value between sensors). Sum of all three offset values determines initial address for register. Example:
```json
{
"inputRegisters": {
"offset": 30000,
"1056849": {
"offset": 0,
"humidity": { "offset": 1 },
"temperature": { "offset": 2 }
},
"4196581": {
"offset": 10,
"temperature": { "offset": 1 }
}
}
}
```
---
# 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/base-stations/base-stations/integrations-and-3rd-party-systems/modbus/modbus-tcp-ip-configuration.md?ask=&goal=
```
`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.