# Commanding Modbus Devices

## Introduction

The BACE IoT Platform allows you to command modbus devices through writable modbus registers. This capability allows control over several device functions such as starting a motor pump, adjusting its speed, or updating a solar inverter's schedule. Refer to the Modbus device manual for understanding the appropriate registers to write to and the correct values to achieve the desired action.

Before writing to modbus registers via the BACE IoT Platform, please ensure:

1. The Modbus device is onboarded onto the BACE Gateway and actively sending measurements.
2. You have the requisite `datatype` for writing to the corresponding modbus device and registers.

If you have not onboarded your Modbus device yet, please visit [How To Onboard Modbus Devices](/bace-panel/how-to-onboard-modbus-devices.md)  on how to do so.

Once your device is properly set up, you must obtain the corresponding `datatype` for your device. As also explained in [Accessing Data](/api/accessing-data.md), there are multiple ways to retrieve all measurements and their groups. Below is an example API request to fetch all datatypes and their latest values using `id_physical_device` endpoint

## Get all datatypes and their latest data of a gateway

<mark style="color:blue;">`GET`</mark> `https://dashboard.bace-iot.com/api/v2/physical-device/{id}?expand=group.latestData`

Returns all the latest measurements collected by the gateway

#### Query Parameters

| Name                                 | Type   | Description          |
| ------------------------------------ | ------ | -------------------- |
| id<mark style="color:red;">\*</mark> | String | id\_physical\_device |

{% tabs %}
{% tab title="200: OK " %}

{% endtab %}
{% endtabs %}

## Writing to a Single Register

To write to a Modbus device, use the ModbusWrite endpoint. This process requires you to provide the `datatype` number and the desired value in the payload.

<table><thead><tr><th width="161">parameter</th><th>description</th></tr></thead><tbody><tr><td>datatype</td><td>Each modbus register has an index called <code>datatype</code> assigned by the gateway. The datatype is used for reading to and writing from modbus registers.</td></tr><tr><td>value</td><td>this is the value you want to write to the modbus register</td></tr></tbody></table>

## Using modbus-write Endpoint

The modbus-write endpoint is your interaction point to command a device. The payload must include the `datatype`number and the desired value for execution.

## Write to a Modbus Register

<mark style="color:orange;">`PUT`</mark> `https://dashboard.bace-iot.com/api/v2/physical-device/{id}/modbus-write`

modbus-write endpoint is used for writing to modbus register(s)

#### Path Parameters

| Name                                 | Type   | Description                    |
| ------------------------------------ | ------ | ------------------------------ |
| id<mark style="color:red;">\*</mark> | string | Gateway's id\_physical\_device |

#### Request Body

| Name                                       | Type      | Description                     |
| ------------------------------------------ | --------- | ------------------------------- |
| datatype<mark style="color:red;">\*</mark> | int       | datatype of the modbus register |
| value<mark style="color:red;">\*</mark>    | int/float | provide the value               |

{% tabs %}
{% tab title="200: OK Successful response" %}

```json
{
    "status": 200,
    "payload": {
        "result": "success"
    }
}
```

{% endtab %}

{% tab title="400: Bad Request Unsuccessful response" %}

{% endtab %}
{% endtabs %}

Here is an example payload for writing to a single modbus register.

```
{
    "datatype": 2100,
    "value": 15
}
```

## Writing to Multiple Registers

The endpoint can execute a write action for multiple registers simultaneously. This process requires providing all `datatype`s and their corresponding values within the same payload as an array. Below is an example payload to set schedule for a solar inverter:

```
[
  {
    "datatype": 2100,
    "value": 13
  },
  {
    "datatype": 2101,
    "value": 20
  },
  {
    "datatype": 2102,
    "value": 21
  }
]
```


---

# Agent Instructions: 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:

```
GET https://docs.bace-iot.com/api/commanding-modbus-devices.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.