//    This file is part of HG11 - Hybrid Genset controller software type 
//    11.
//
//    Copyright (C) 2011-2020  TEROC AB.
//
//    HG11 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.
//
//    HG11 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 HG11.  If not, see <http://www.gnu.org/licenses/>.
//
//    Note that HG11 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 HG11 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.

Note that to use the full functionality of HG11, it is intended to be part of 
a LonWorks network (LON) that is based on LNS. 

HG11 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 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.
1 pc 750-600 End module.
5 pcs 753-110 Plug for 753-modules.

The Wago hardware above preloaded with HG11 is called TIP11 and is sold by 
TEROC. As a possible extension, we have also developed HG21/TIP21, to enable 
redundant control of a second genset. We will also support more advanced 
controllers and other type of communication in the near future.

One of the advantages of using HG11 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. Data from the battery monitor is 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.

HG11 version 1.3 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 HG11 
software. Wago-I/O-Check 3 might also be needed for settings (see below). 
Those programs usually connect 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 
(especially if you wish to use the LON interface of the 750-819):
- A LNS-based commissioning tool, such as LonMaker by Echelon (HG11 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 (HG11 has been tested with NIC709-USB100 from Loytec).
- Wago TOPLON-PRIO, which can be used as a plug-in with the commissioning 
tool (HG11 has been tested with version 1.60.0000 for LNS 3). HG11 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.

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 *

Example of setup:
1. Using CoDeSys, ensure that the HG11 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 HG11 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 HG11_1_3.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 HG11 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.

Note that the functionality is determined by the retain parameters in the 
HG11 program. The defaut setting of Par1=9317 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).

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.
