# Bitpool Edge Modbus

## Getting Started

This is a standard Node.js module developed specifically to function within the Node-RED ecosystem.

## How to Use

Use the following procedure to install this module to your Node-RED instance, or download the pre-themed Bitpool-Edge Docker image that contains all our favourite nodes pre-installed.

### Bitpool-Edge Install

1. Log into your Bitpool-Edge instance and click the `Hamburger` icon, in the top-right corner.
2. Select `Manage Palette` from the drop down menu then click the `Pallete->Install` tabs to install.
3. Using the search bar type `@bitpoolos/edge-modbus` and install the module once displayed.
4. Finally, use the left most navigation menu to scroll down to the heading `Bitpool Modbus` to reveal available nodes.

### Docker Install :whale:

This Modbus module and many other Bitpool developed nodes have been pre-installed for your convenience in a Bitpool themed Node-RED application.

Go here for how to install Bitpool-Edge.

### Modbus Nodes

The Modbus library of nodes is broken down into 4x functional blocks.

<figure><img src="https://3902784585-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F28eeWKJBGNSvwO7hWa0f%2Fuploads%2FoFPH8juQaxnwr2WDudKj%2Fimage.png?alt=media&#x26;token=2f21563f-3adc-4ea1-aeca-bb81c59e7ed0" alt=""><figcaption></figcaption></figure>

1. `device` - allows us to create a virtual map of a target Modbus device.
2. `reader` - defines a communication pathway to a Modbus device(s).
3. `decoder` - ensures that returned Modbus register data is correctly formatted.
4. `display` - is an *optional* component to visualise data for a unique Modbus register.

### Basic Workflow

<figure><img src="https://3902784585-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F28eeWKJBGNSvwO7hWa0f%2Fuploads%2FQCI0tcCdkFArdR26uPyM%2Fimage.png?alt=media&#x26;token=d6e5327c-8aee-408e-9287-5bdda54299f6" alt=""><figcaption></figcaption></figure>

The image above here is an example of linked Modbus nodes on a Flow tab. This is the basic flow of data.

1. The ‘Trigger’ node injects a simple timestamp into the `device` node 'ABB B23 B24'.
2. The `device` node contains a list of Modbus registers with associated information which is sent to the `reader` node ‘Modbus Con’.
3. The `reader` node queues each Modbus register request and manages serial bus arbitration. Each response is then sent to the `decoder` node ‘Decoder’.
4. The `decoder` node handles each request using information stored in the JSON object. This is converted to the correct format as a topic/value pair, then sent to the output.
5. Finally, the `display` node prints the payload to it status field for the user to see.

### Basic Workflow Node Properties

* **Trigger** - this is a standard inject node and is used to initiate a Modbus read.
  * *Payload* - set as timestamp but can be any value.
  * *Topic* - not used.
* **Device** - description of the target Modbus device.
  * *Name* - any meaningful description.
  * *Modbus ID* - the numeric value of the Modbus address.
  * **Registers**
    * *Template* - the drop-down allows the user to select a predefined templates of Modbus registers. This is a cloud service and is only available if the system has Internet access. An alternative solution is to manage templates via the upload/download templates buttons.
    * *Load* – the selected template will be loaded into the Modbus Map
    * **Filters**
      * By Name - filters user input matching the Name.
      * By Address - filters user input matching the Modbus address.
    * **Register**
      * *Name* (mandatory) – forms part of topic structure.
      * *Address* (mandatory) - address of the Modbus register.
      * *Code* (mandatory) - Modbus register type (Coil, Register)
      * *Multiplier* (mandatory) - normally set to 1 (applied to output of Decoder node).
      * *Size* (mandatory) - vendor specific setting of register data size (applied to output of Decoder node).
      * *Format* (mandatory) - vendor specific setting of register format (applied to output of Decoder node).
      * *Unit Name* (optional) - supplemental Unit of Measure field for Display node (e.g. 100Wh).
      * *Unit Scale* (optional) - supplemental scaling prefix for Display node for (e.g. 100kWh).
    * **Buttons**
      * *Add* - adds a register block to the Register Map.
      * *Delete* - deletes all register blocks from Register Map.
      * *Upload* - allows a user to upload a previously saved Register Map from the local file system.
      * *Download* - allows a user to download the current Register Map to the local file system.
      * *View* - opens browser tab to provide a view of the current Register Map, formatted as JSON.
    * **Options**
      * **General**
        * Group Reads - option to optimize the number of Modbus request being made. A single request can return multiple values if the registers are in a contiguous block.
      * **Monitoring**
        * *Activity* - option to show the node activity.
        * *Warnings* - option to output warnings to the debug tab.
* **Reader** - defines the client-side connection to the Modbus network.
  * *Name* - any meaningful description of the reader node.
  * **Connection**
    * *Name* - any meaningful description of the new client.
    * *Type* - the connection type to either network socket or serial port.
    * *Unit ID* - allows multiple nodes to independently share the same Modbus network.
    * *Timeout* - number of milliseconds the node will wait before a timeout exception is raised.
    * *Reconnect* - number of milliseconds the node will wait after a timeout exception, before reattempting a connect.
    * *Queue Delay* - number of milliseconds the node will wait between sending Modbus register requests.
    * *Activity* - shows the status of the connection to the debug tab.
* **Decoder** - converts packets received from Modbus network to those defined in the Device node (factoring, byte resizing and reordering)
  * **Options**
    * **Monitoring**
      * *Activity* - shows activity of the node.
      * *Warnings* - outputs any node warnings to the debug tab.
    * **Converting**
      * *Power Factor* - option to convert multi quadrant values (-2,-1,0,1, 2) to absolute (0-1).
      * *Reals* - fixes all decimal point values to 3 significant places.
* **Display** - selected Modbus register values will be displayed.
  * *Name* - any meaningful description.
  * *Register* - text field to manually add the Modbus register, if known.
  * *Auto-Fill Device* - selection to automatically discover upstream Device node.
  * *Auto-Fill Register* - selection to automatically discover upstream Register name of the Device node.
  * **Options**
    * *Warnings* - option to output any node warnings to the debug tab.

### Further Information

Now that your Bitpool-Edge is up and running, we have included simple examples flows to demonstrate how to create a basic solution.

1. Log into your Bitpool-Edge instance and click the `Hamburger` icon, in the top-right corner.
2. Select `Manage Palette` from the drop down menu then click the `Import->Examples` tabs to see this node.
3. Navigate the ‘Examples flows’ tree and select `@bitpoolos/edge-modbus` to reveal the preconfigured examples.
4. Click the example you would like to test the click the `Import` button.
5. Place the example nodes on a flow and review the configuration of each node. You will need to make suitable changes for your system.
6. Finally, click the `Save` to test.

> Additionally, there is basic helper documentation on each node. Just select a target node and click the `Help` tab found at the top right corner of Bitpool-Edge.
>
> **Hint** *- the icon looks like a book!*