//    This file is part of HG12 - Hybrid Genset controller software type 
//    12.
//
//    Copyright (C) 2020-2021  TEROC AB.
//
//    HG12 is free software: you can redistribute it and/or modify
//    it under the terms of the GNU General Public License as published by
//    the Free Software Foundation, either version 3 of the License, or
//    (at your option) any later version.
//
//    HG12 is distributed in the hope that it will be useful,
//    but WITHOUT ANY WARRANTY; without even the implied warranty of
//    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
//    GNU General Public License for more details.
//
//    You should have received a copy of the GNU General Public License
//    along with HG12.  If not, see <http://www.gnu.org/licenses/>.
//
//    Note that HG12 depends on other software, with different licensing
//    conditions.
//
//    We are thankful to Wago and others, who have provided helpful
//    examples and support.
//
//    For more information, contact Sven Ruin, sven.ruin@teroc.se

A typical use of HG12 is in a hybrid power system, to automatically start and 
stop a connected genset (number 1) for cycle charging, based on the following 
inputs:
- Battery bank State of Charge (SoC), if available from another device.
- Battery bank voltage.
- Charger fault or battery bank warning/fault (low State of Health), if 
available from another device.
- Inverter power, if available from another device.

In addition, HG12 can control an auxiliary relay, which can for example be 
used to start/stop a small wind turbine to prevent overcharging of a battery.

HG12 is designed to run on a target PLC consisting of the following Wago 
hardware:
1 pc 750-862 Ethernet programmable fieldbus controller.
1 pc 753-402 4-channel digital input.
1 pc 753-648 LON FTT (supplied with 24 V via jumper contacts from 753-402).
1 pc 753-483 2-channel analog input.
1 pc 753-517 2-channel digital output (changeover relay).
1 pc 753-650/003-000 RS-232 (for communicating with e.g. battery monitor).
1 pc 753-653/003-000 RS-485 (for communicating with e.g. genset controller).
1 pc 750-623 Supply module to provide 5 V for RS-485 etc.
1 pc 750-600 End module.
6 pcs 753-110 Plug for 753-modules.

The Wago hardware above preloaded with HG12 is called TIP12 and is sold by 
TEROC. As a possible extension, HG2x/TIP2x can be used, to enable redundant 
control of a second genset.

One of the advantages of using HG12 together with a battery monitor is that 
the control is then based on SoC, but this is not necessary for basic 
functionality. Either e-xpert 501 or Pro/Pro-hv from TBS Electronics can be 
connected by RS-232. Such a battery monitor will need a RS-232 
communication kit from TBS and a suitable communication cable to interface 
to the PLC. Values from the battery monitor are then published as network 
variable outputs on the PLC's LON interface, which can be useful e.g. for 
monitoring as well. An alternative is to connect SoC from a battery monitor 
to a LON network variable input of the PLC.

If the genset has a Bernini Be-One controller, that can communicate with the 
PLC by Modbus on RS-485, provided that suitable cable/termination is used. 
This way, the PLC becomes a LON interface for the genset. An alternative is 
to connect a genset that follows the LonMark Functional Profile 13110 to the 
PLC's LON interface. The PLC also has digital inputs and outputs for basic 
control.

Data from an inverter can be connected to the PLC's LON interface, for 
example using i.LON SmartServer FT, where we have implemented e.g. the 
communication protocol for Studer Xtender.

HG12 version 2.0.1 was created using CoDeSys ver 2.3.9.49 (Wago-I/O-Pro) 
with added support for 750-862 (we have used TSP rev 111626), on a separate 
computer. You will need CoDeSys if you wish to edit the HG12 software. Wago-
I/O-Check 3 might also be needed for settings (see below). Those programs 
connect to the 750-862 e.g. using a 750-923 USB service cable, which needs a 
device driver.

The following CoDeSys 2.3 libraries, which are normally included in CoDeSys 
from Wago, are used:
mod_com.lib (17.5.05)
Modb_l05.lib (16.1.09)
SerComm.lib (9.2.04)
serial_interface_01.lib (27.1.09)
Standard.lib (1.12.04)
ModbusEthernet_04.lib
Ethernet.lib

If you wish to use Wago's LON Configurator (part of this version of CoDeSys), 
see the LON Configurator manual regarding additional requirements such as 
LonMark resource files.

The following settings have been used on 753-650/003-000 for e-xpert 501:
Baudrate: 2400 Baud
Data frame: 8 Databits, Even-Parity
Stopbits: 1 *
Output format: Standard
Data bytes (BK): 5
RTS/CTS: Disable
Copy State Byte: Normal *
XON/XOFF (Send): OFF *
XON/XOFF (Receive): OFF *
Continuous Send: OFF *

The following settings have been used on 753-653/003-000 for Be-One:
Baudrate: 9600 Baud *
Data frame: 8 Databits, No-Parity *
Stopbits: 1 *
Output format: Standard
Data bytes (BK): 5
Duplex Mode: Halfduplex
Copy State Byte: Normal *
XON/XOFF (Send): OFF *
XON/XOFF (Receive): OFF *
Module Type: RS485 *
Continuous Send: OFF *

Note that there are different ways to set up the IP communication parameters 
in 750-862. One way is in the PLC program, which is used when the "address 
selection switch" is set to 0. This way, the IP address is presently set to 
196.168.0.203 (C0A800CB) in PLC_PRG. For other methods, see e.g. the Wago 
manual for 750-862.

Regarding LON setup, we have noticed that it can be difficult to commission 
the node based on 753-648 with i.LON SmartServer FT standalone network 
management.

Example of setup using LonMaker and network interface to connect to the LON:
1. Using CoDeSys, ensure that the HG12 program is downloaded in the PLC, 
running and that it is the boot project. CoDeSys can be used to change the 
retain parameters (and make other changes in the code, but be aware that this 
can have consequences, for example that the LON interface might not work as 
intended).
2. The following steps are carried out after a LonMaker project has been 
created/opened on the computer, with the computer and the PLC both connedted 
to the LON (OnNet mode).
3. Create the application device for the HG12 node in LonMaker by dragging a 
Device shape into the drawing and so on (see the LonMaker manual). Select 
"Commission device" and "Create new device template".
4. Regarding the External Interface Definition, select "Load XIF" and click 
"Browse..." to locate the HG12_2_0.xif file (for example in the C:\LonWorks\
import\TEROC folder, if it has been stored there).
5. Do NOT select "Load application image". The State can be set to Online.
6. Trigger Service Pin on the 753-648 module (by bridging connections 2 and 6 
on the module) when requested to do so by LonMaker.
7. If you get an error message, for example "The requested information is not 
available from the device", it is probably possible to continue anyway.
8. In LonMaker drag a Functional Block (FB) shape into the drawing and select 
FB Name: HybridGen. You probably want to select "Create all network variable 
shapes".
9. It should now be possible to browse network variables, make bindings etc 
in LonMaker.

Be aware that the network variable output called nvoG1Running on HG11 has 
been renamed to nvoRunStatus on HG12. This is one of the changes made to 
better follow LonMark Functional Profile 13110. So if HG12 is used together 
with HG2x, make sure that you bind nvoRunStatus on HG12 to nviG1Running on 
HG21.

Also be aware that the nviShutdownCmd cannot override a local manual run 
command and that the shutdown command is reset for example if power to the 
PLC is turned off. 

Note that the functionality is determined by the retain parameters in the 
HG12 program. The defaut setting of Par1=74853 means that:
1st digital input is Fuel warning.
2nd digital input is Genset 1 warning.
3rd digital input is Genset 1 fault.
4th digital input is Genset 1 ready.
1st analog input is Battery bank voltage.
2nd analog input is Genset 1 starting battery voltage.
(Not all of the above inputs are necessary for basic operation.)
1st digital output is Genset 1 start/stop (PULLED RELAY = GENSET 1 OFF).
2nd digital output is Genset 1 start warning signal.
RS-232 communication with TBS e-xpert 501 is selected.
RS-485 Modbus communication with genset controller Bernini Be-One is selected.
Genset is assumed to communicate Battery bank voltage (because Bit 13 is 1 in 
Par1, otherwise it would be interpreted as Genset 1 starting battery voltage).
A genset is not configured to start because battery monitor is ouf of sync 
(because Bit 14 is 0 in Par 1).
Modbus TCP communication with TriStar MPPT is selected.

Other parameters are by default set for a typical battery bank with 24 V 
nominal voltage. For more information, see comments in the program.

Be aware that that CoDeSys re-initializes variables declared as retain in case 
of 
- Reset origin
- Reset cold
- repeated program download

Revision history:

Ver 2.0.1 (2021-01)
Added simple visualization.
Corrected small mistakes regarding handling of LON network variables.

Ver 2.0.0 (2020-12)
Main changes from HG11 ver 1.3:
Changed hardware from 750-819 to 750-862 and 753-648.
XIF file now available.
Added Modbus TCP communication with TriStar MPPT.
LON interface updated, so it better follows LonMark Functional Profile 13110 
and has additional network variables (however, nviFaultResetCmd not used yet).
Added support for auxiliary relay.
