Bridge

To simplify the implementation of hardware that is connected via certain standardized physical connection layers and protocols, those are implemented as Bridges.

1. Http

Http is a widely used standard for web communication. It is used for some hardware devices like electric meters, relays and so on. The standard architecture used by the devices are RESTful api’s.

Source Code

2. M-Bus

M-Bus is a widely used standard for fieldbus communication. It enables connection to M-Bus devices like meters.

2.1. Setup note

This bridge depends on jMbus, a user guide for it can be found at https://www.openmuc.org/m-bus/user-guide/.

Note: For jMbus to work you need to install the native part of RxTx which is a library for serial port communication jMbus is dependent on. See paragraph 2.5 for further information.

For Linux users: In case the RxTx library cannot be found under /usr/lib/jni you can try to move all .so files of that directory to /usr/lib (see OpenEMS Community).

3. Modbus

Modbus is a widely used standard for fieldbus communications. It is used by all kinds of hardware devices like photovoltaics inverters, electric meters, and so on.

3.1. Modbus/TCP

Bridge Modbus/TCP for fieldbus communication via TCP/IP network.

3.2. Modbus/RTU

Bridge Modbus/RTU Serial for fieldbus communication via RS485 serial bus.

3.3. Implementation details

OpenEMS Components that use Modbus communication, must implement the ModbusComponent interface and provide a ModbusProtocol. A protocol uses the notion of a Task to define an individual Modbus Read or Write request that can cover multiple Modbus Registers or Coils depending on the Modbus function code. It is possible to add or remove tasks to/from a protocol at runtime or to change the execution Priority. The Modbus Bridge (Bridge Modbus/RTU Serial or Bridge Modbus/TCP) collects all protocols and manages the execution of Tasks.

3.3.1. Execution of Modbus Tasks

Execution of Modbus Tasks is managed by the ModbusWorker. It…​ - executes Write-Tasks as early as possible (directly after the EXECUTE_WRITE event) - executes Read-Tasks as late as possible to have values available exactly when they are needed (i.e. just before the BEFORE_PROCESS_IMAGE event). To achieve this, the ModbusWorker evaluates all execution times and 'learns' an ideal delay time, that is applied on every Cycle - the 'CycleDelay' - handles defective ModbusComponents (i.e. ones where tasks have repeatedly failed) and delays reading from/writing to those components in order to avoid having defective components block the entire communication bus. Maximum delay is 5 minutes for read from defective components. ModbusComponents can trigger a retry from a defective Component by calling the retryModbusCommunication() method.

3.3.2. Priority

Read-Tasks can have two different priorities, that are defined in the ModbusProtocol definition: - HIGH: the task is executed once every Cycle - LOW: only one task of all defined LOW priority tasks of all components registered on the same bridge is executed per Cycle Write-Tasks always have HIGH priority, i.e. a set-point is always executed as-soon-as-possible - as long as the Component is not marked as defective

3.3.3. Channels

Each Modbus Bridge provides Channels for more detailed information: - CycleTimeIsTooShort: the configured global Cycle-Time is too short to execute all planned tasks in one Cycle - CycleDelay: see 'CycleDelay' in the 'ModbusWorker' description above

3.3.4. Logging

Often it is useful to print detailed logging information on the Console for debugging purposes. Logging can be enabled on Task level in the definition of the ModbusProtocol by adding .debug() or globally per Modbus Bridge via the LogVerbosity configuration parameter:

  • NONE: Show no logs

  • DEBUG_LOG: Shows basic logging information via the Controller.Debug.Log

  • READS_AND_WRITES: Show logs for all read and write requests

  • READS_AND_WRITES_VERBOSE: Show logs for all read and write requests, including actual hex or binary values of request and response

  • READS_AND_WRITES_DURATION: Show logs for all read and write requests, including actual duration time per request

  • READS_AND_WRITES_DURATION_TRACE_EVENTS: Show logs for all read and write requests, including actual duration time per request & trace the internal Event-based State-Machine

The log level via configuration parameter may be changed at any time during runtime without side-effects on the communication.

4. OneWire

OneWire is a widely used protocol for home automation. It is used by sensors like thermometers.

4.1. Setup

This implementation directly talks to the OneWire busmaster, e.g. a DS9490R USB dongle, without requiring the OneWire File System (OWFS). It therefore requires the natively compiled C library by the manufacturer of the OneWire chip Maxim Integrated. This library is then accessed using Java JNI.

To compile the native library follow the guide on https://www.maximintegrated.com/en/design/technical-documents/app-notes/5/5917.html.

  1. Download the OneWireViewer-Linux.zip file

  2. Unzip the file (unzip OneWireViewer-Linux.zip)

  3. Prepare compile environment (sudo apt-get install libusb-dev build-essential)

  4. Install Java JDK (e.g. sudo apt-get install openjdk-8-jdk)

  5. Compile (cd OneWireViewer-Linux/PDKAdapterUSB && make && sudo make install)

The library needs exclusive access to the busmaster.

  1. Unload the default Linux driver: rmmod ds2490

  2. Block the driver from loading on next boot echo blacklist ds2490 > /etc/modprobe.d/ds2490.conf

4.2. Identifying devices

The OneWire Bridge provides a JSON-RPC Request that reads all devices connected to the OneWire bus.

Example: read via OpenEMS Backend

{
  "method": "edgeRpc",
  "params": {
    "edgeId": "edge0",
    "payload":{
      "method": "componentJsonApi",
      "params": {
        "componentId": "onewire0",
        "payload": {
          "method": "getDevices",
          "params": {}
        }
      }
    }
  }
}

Example Response:

{
  "jsonrpc":"2.0",
  "id":"UUID",
  "result":{
    "payload":{
      "jsonrpc":"2.0",
      "id":"UUID",
      "result":{
        "devices":[
          {
            "address":"4D0000094xxxxxxx",
            "name":"DS18B20",
            "alternateName":"DS1820B, DS18B20X",
            "description":"Digital thermometer measures temperatures from -55C to 125C in 0.75 seconds (max).  +/- 0.5C accuracy between -10C and 85C. Thermometer resolution is programmable at 9, 10, 11, and 12 bits. ",
            "details":{
              "type":"TemperatureContainer",
              "temperature":17.5625
            }
          },
          {
            "address":"6F0000022xxxxxxx",
            "name":"DS2438",
            "alternateName":"Smart Battery Monitor",
            "description":"1-Wire device that integrates the total current charging or discharging through a battery and stores it in a register. It also returns the temperature (accurate to 2 degrees celsius), as well as the instantaneous current and voltage and also provides 40 bytes of EEPROM storage.",
            "details":{
              "type":"TemperatureContainer",
              "temperature":19.3125
            }
          }
        ]
      }
    }
  }
}