//    This file is part of HG21 - Hybrid Genset controller software type 
//    21.
//
//    Copyright (C) 2019-2020  TEROC AB.
//
//    HG21 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.
//
//    HG21 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 HG21.  If not, see <http://www.gnu.org/licenses/>.
//
//    Note that HG21 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 HG21 is in a hybrid power system, to automatically start and 
stop a connected genset (number 2) 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.

Note that to use the full functionality of HG21, it is intended to be used 
together with another controller that runs HG1x (to control Genset 1). Both 
should be part of a LonWorks network (LON) that is based on LNS. 

HG21 is designed to run on a target PLC consisting of the following Wago 
hardware:
1 pc 750-819 LON programmable fieldbus controller.
1 pc 753-402 4-channel digital input.
1 pc 753-483 2-channel analog input.
1 pc 753-517 2-channel digital output (changeover relay).
1 pc 750-600 End module.
3 pcs 753-110 Plug for 753-modules.

The Wago hardware above preloaded with HG21 is called TIP21 and is sold by 
TEROC. We are planning to also support more advanced controllers and other 
type of communication in the future.

The purpose of HG21 is to enable redundant control. If a battery monitor 
communicates with HG21 via LON, the control is based on SoC, which is 
recommended (but not necessary for basic functionality). This can be 
accomplished for example by using a e-xpert 501 or Pro/Pro-hv from TBS 
Electronics with HG1x and binding the SoC network variable between the 
nodes.

If Genset 2 follows the LonMark Functional Profile 13110, it can communicate 
with the PLC's LON interface. The PLC also has digital inputs and outputs for 
basic control. If the genset has a Bernini Be-One controller, the PLC can be 
extended with RS485 communication to communicate with it by Modbus (this is 
prepared in the HG21 software).

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.

HG21 version 1.1 was created using CoDeSys ver 2.3.9.13 (Wago-I/O-Pro), on 
a separate computer. You will need CoDeSys if you wish to edit the HG21 
software. This program usually connects to the 750-819 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)

You probably also want the following software running on the computer 
(in order to use the LON interface of the 750-819):
- A LNS-based commissioning tool, such as LonMaker by Echelon (HG21 has 
been tested with LonMaker 3.20.50 Professional Turbo Edition, which has been 
replaced by IzoT Commissioning Tool / OpenLNS).
- Device driver for the network interface used to connect the computer to 
the LON (HG21 has been tested with NIC709-USB100 from Loytec).
- Wago TOPLON-PRIO, which can be used as a plug-in with the commissioning 
tool (HG21 has been tested with version 1.60.0000 for LNS 3). HG21 has 
been used with Wago's template PRIO_20_32_02, but also other templates can 
be used. If you wish to access the retain parameters (configuration 
properties) from LON, PRIO_20_32_01 should be possible to use.

Example of setup:
1. Using CoDeSys, ensure that the HG21 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 HG21 node in LonMaker by dragging a 
Device shape into the drawing and so on (see the LonMaker manual). Wago's 
template PRIO_... can be selected in this process (be aware that this may be 
difficult to change later).
4. Commission the device. You may need to load the application image.
5. Right-click the device and start the plug-in TOPLON-PRIO, in order to set 
up the LON interface.
6. TOPLON-PRIO should now show you a screen for the hardware configuration. 
7. If you wish you can in TOPLON-PRIO click Close (Continue..) / Schliessen 
(Weiter..), import the file HG21_1_1.tpi (for PRIO_20_32_02), check/edit the 
software configuration as desired, click OK and jump to step 10.
8. Check the hardware configuration and specify digital/analog modules.
9. Open the SYM file of HG21 and do your own software configuration of network 
variables.
10. Close TOPLON-PRIO.
11. In LonMaker drag a Functional Block (FB) shape into the drawing and select 
FB Name (VarActuator..., VarSensor...).
12. It should now be possible to create more FBs, browse network variables, 
make bindings etc in LonMaker.

It is important to bind the network variable output nvoG1Inhibit on HG21 with 
the network variable input nviG1Inhibit on HG1x, because this will inhibit 
operation of Genset 1 when HG21 takes over to operate Genset 2. For this, 
suitable heartbeats shall be used on that output and timeout on that input. 
The same applies to G1Running network variables. Heartbeats and timeout are 
also used e.g. for the network variable for SoC. This has been prepared in the 
tpi-files enclosed for HG21 and HG11.

Note that the functionality is determined by the retain parameters in the 
HG21 program. The defaut setting of Par1=37 means that:
1st digital input is Fuel warning.
2nd digital input is Genset 2 warning.
3rd digital input is Genset 2 fault.
4th digital input is Genset 2 ready.
1st analog input is Battery bank voltage.
2nd analog input is Genset 2 starting battery voltage.
(Not all of the above inputs are necessary for basic operation.)
1st digital output is Genset 2 start/stop (PULLED RELAY = GENSET 2 ON).
2nd digital output is Genset 2 start warning signal.
A genset is not configured to start because battery monitor is ouf of sync 
(because Bit 14 is 0 in Par 1).

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

Note that Par5-Par21 must normally have the same settings in HG21 as in the 
controller for Genset 1 (HG1x). Both nodes should normally also have as 
identical input information as possible (about battery bank voltage etc).
