npm package: @mplattu/signalk-modbus-serial-client
Description: A plugin for SignalK to read data via Modbus serial
Author: Matti Lattu
Latest version: 1.0.1

# signalk-modbus-serial-client

This is a SignalK server plugin for reading Modbus serial data.
It owns a lot to (well, it is almost a verbatim copy of)
[signalk-modbus-plugin](https://github.com/codekilo/signalk-modbus-plugin)
which implements similar interface for Modbus TCP devices.

For obvious reasons I am using the concepts "server" (the device which produces
the data) and "client" (the device which reads the data) instead of the traditional
slave/master terms.

## Configuration

The plugin creates a configuration editor to Server > Plugin config. The configuration
file is stored to server's `plugin-config-data/signalk-modbus-serial-client.json`.
In case you edit the file don't forget to restart the SignalK server.

### Sample Configuration

The sample configuration works with
 * Sunbeam MoonRay MPPT 320 solar charger (tested)
 * EPSolar/EPEver Tracer A/B-Series ([reference](https://github.com/tekk/Tracer-RS485-Modbus-Blynk-V2))

 1. Copy the attached `signalk-modbus-serial-client-SOLAR.json` as
    `plugin-config-data/signalk-modbus-serial-client.json`. The `plugin-config-data`
    exists in your SignalK data directory.
 1. Edit the `devicePath` value. The default value works with the tested USB-RS485
    converter.
 1. Restart the SignalK Server.
 1. Go to Data Browser on SignalK Server UI and give `electrical.solar.flybridge` as
    search filter. You should see values generated by the plugin.
 1. If you want to add metadata to the data you'll have to edit the
    [server metadata](https://signalk.org/specification/1.7.0/doc/data_model_metadata.html).
    The SignalK Server FAQ explains [how to find the metadata file](https://github.com/SignalK/signalk-server/wiki/FAQ:-Frequently-Asked-Questions#how-to-add-missing-units-and-static-data).
 1. Metadata sample:
    ```
    {
      "context": "vessels.self",
      "updates": [
        {
          "meta": [
            {
              "path": "electrical.solar.flybridge.batteryRemaining",
              "value": {
                "displayName": "Solar Battery Remaining",
                "longName": "Solar Battery Remaining",
                "shortName": "Solar Batt Remaining",
                "units": "%"
              }
            },
            {
              "path": "electrical.solar.flybridge.batteryVoltage",
              "value": {
                "displayName": "Solar Battery Voltage",
                "longName": "Solar Battery Voltage",
                "shortName": "Solar Batt Voltage",
                "units": "V"
              }
            },
            {
              "path": "electrical.solar.flybridge.chargePower",
              "value": {
                "displayName": "Solar Charge Power",
                "longName": "Solar Charge Power",
                "shortName": "Solar Chg Pwr",
                "units": "W"
              }
            },
            {
              "path": "electrical.solar.flybridge.panelPower",
              "value": {
                "displayName": "Solar Panel Power",
                "longName": "Solar Panel Power",
                "shortName": "Solar Panel Pwr",
                "units": "W"
              }
            }
          ]
        }
      ]
    }
    ```

### Troubleshooting

 1. Check SignalK Server Dashboard. The Connection & Plugin Status should have the
    `signalk-modbus-serial-client` entry. If you don't have one, the plugin is not
    enabled.
 1. Check the Status column. In normal operation it says "Running" while in other cases
    you should see a helpful error message.
 1. Check Server > Server Log for other messages.

## Development

### Installing SignalK Server

The installation process is described in the
[SignalK documentation](https://github.com/SignalK/signalk-server). You can either
make Modbus (mock) device interface available for Docker image or install the SignalK
server from git:

```
git clone https://github.com/SignalK/signalk-server.git
cd signalk-server
npm install
npm run build:all
bin/signalk-server
```

### Cloning the Plugin

To install the plugin into SignalK for development first clone the repository and link the npm module:

```
$ git clone
$ cd signalk-modbus-serial-client
$ npm link
```

Then go to the SignalK configuration directory (probably `~/.signalk`)  and link the module again:

```
$ cd .signalk
$ npm link @mplattu/signalk-modbus-serial-client
```

The plugin should now be installed and visible when the server has restarted.

### Tests

The test automation uses Mocha, virtual serial interface and Modbus mock server
(`modbus-mock-server/`). Executing `make test` should do everything automatically.

### Publishing to npmjs

1. Make a branch
1. Invent a new [semantic version number](https://semver.org/)
1. Update `version` field in the `package.json`
1. Create a changelog entry below
1. Push your changes to the branch
1. Make sure the tests (`publish-to-npmhs.yaml`) are ok
1. Merge the branch to the main branch and make sure the `publish-to-npmjs.yaml` runs without errors

## Changelog

* `1.0.1` (8-JUL-2022) Make plugin more robust by not stopping it in case Modbus
   connection fails on user errors, e.g. timeout.
* `1.0.0` (2-JUL-2022) Official release after successful field testing. Added
   instructions of adding metadata.
* `0.1.0` (4-APR-2022) First public version for beta testing.