# Modbus

#### Introduction

*Modbus*, or MODBUS, is a client/server data communications protocol in the OSI model's application layer. This protocol allows DI/DO devices to connect to the Macula, create Events based on the Device Input, and Actions based on the Device Output.

#### Modbus setup

To set up a device, you need to go to:

1. *Configuration -> Modbus clients*
2. Click the *+ New Modbus client* button at the top of the *Modbus clients* subsection. This action will bring a new pop-up window.
3. Fill the *Title* input field with a meaningful name, select the *Server* the device is connected to, and provide the *Device IP address* in the *Host* input field
4. You must also know what port the device uses.
5. If you need to provide a **Unit identifier/slave address**, you can fill out the *Device identifier* field; otherwise, leave it value 0.
6. Confirm your setup with the *Apply* and *OK* buttons.

<figure><img src="https://412599993-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeNXnJx0OpvxnmpWqOBNm%2Fuploads%2FFDIdRotw5KogJTvYxMuf%2Fimage.png?alt=media&#x26;token=f644b151-62b8-450e-b8b1-75673550e445" alt=""><figcaption></figcaption></figure>

#### Modbus event setup

After adding the device, you can create events and actions based on the device's DI/DO signals.

1. To create an *Event*, go to the *Events \&Actions -> Events*.
2. Click on the *+ New event* button at the top of the *Events* subsection.
3. You will find the Modbus device events under *External events -> Event triggered by Modbus device*. Please select it and press the *OK* button.
4. Fill in the *Title* input field with a meaningful name.
5. Click the *Change...* button in front of the *Source* field and select your connected device.
6. Select *Discrete input* from the *Data model* dropdown menu.
7. The *Address* field allows configuring which particular input (DI port/channel) will trigger the event (modbus port/channel number, such as 0, 1, etc..).
8. The *Value* field allows configuring the state of the contact. Allowed values for the DI is 0 (OFF) or 1 (ON).
9. Confirm your setup with the *Apply* and *OK* buttons.

<figure><img src="https://412599993-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeNXnJx0OpvxnmpWqOBNm%2Fuploads%2Fv729f887SxoMauZK0u2c%2Fimage.png?alt=media&#x26;token=a3731fb8-1f48-45d0-9677-cab2c22c28f5" alt=""><figcaption></figcaption></figure>

#### Additional Modbus Event Configuration Options

In the Modbus Event setup, you can further configure events using the following options:

**Data Model:**

* Input Register: Choose to trigger events based on the state of an Input Register.
* Holding Register: Choose to trigger events based on the state of a Holding Register.

**Mode:**

Use the Mode dropdown to select the criteria for triggering the event:

* **All bits**: Trigger if all bits meet the condition.
* **Any bit**: Trigger if any single bit meets the condition.
* Exact value: Trigger when the register value exactly matches the specified condition.

**HEX Mask Fields:**

* **AND Mask**: Specify a HEX value for the AND mask.
* **OR Mask**: Specify a HEX value for the OR mask.
* **NOT**: A checkbox to invert the mask logic.

**Register-Specific Fields:**

For Input Register and Holding Register types:

* **Size**: Choose either 16-bit (1 word) or 32-bit (2 words).
* **Conditional Operators**: Operators such as Greater Than, Less Than, etc., can be chosen before the value field.
* **Value Fields**: Fields that change based on the selected operator:
* **Value**: Specify an exact value.
* **Bit Mask**: Apply a bitwise mask.
* **Range**: Define a range by setting Start and End values.

**Coil-Specific Conditional Operators:**

For Coils (Discrete Outputs), available operators are limited to:

* Equal
* Not Equal

**Modbus action setup**

To complete the Modbus device setup, you also need to create an *Action*. To do so, go to:

1. *Events & Actions -> Actions*
2. Click the *+ New action* button on the top of the *Actions* subsection
3. Inside the new pop-up window, locate *Notifications -> Control Modbus device* and click the *OK* button
4. Fill in the *Title* field with the meaningful name
5. Select your device as the target device inside the *Target* input field.
6. The *Address* field allows you to set a device particular DO port/channel (modbus port/channel number, such as 0, 1, etc..).
7. The *Value* field allows to set the value that will be sent to the selected address. Available DO values: 0 (OFF) or 1 (ON).

<figure><img src="https://412599993-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeNXnJx0OpvxnmpWqOBNm%2Fuploads%2FLucD6iS6PwjDxFk8aYmw%2Fimage.png?alt=media&#x26;token=ffbb45d9-7a36-482a-938e-c77dfbedbb76" alt=""><figcaption></figcaption></figure>

#### Additional Modbus Action Configuration Options

For Modbus Actions, additional configurations can be made based on the device's output type:

**Data Model:**

Options:

* Discrete Output (Coil): For discrete output actions.
* Holding Register: For actions based on holding registers; includes a Size option for specifying 16-bit or 32-bit configurations.

Now, you are ready to implement rules for the Modbus device.