GGC - GNU Gluco Control
=======================

This are instructions on how to start the application (and how to troubleshoot if it doesn't).

GNU Gluco Control (in further text GGC) is Java application, and needs special environment to
run in, because of this and variety of Operating Systems (OS) supported, we need different
startup files for each OS. We have created special library, which does this creation of 
startup files for us, but first we need to get it to work correctly (which again requires
custom made startup files for each OS). This document is intended to help *any* user to 
setup this application with little or no action. There will be several sections here, but some
of sections are only required reading if you have problems starting application.


How to start application (REQUIRED)
====================================

If your OS is supported, you will find special batch file, ready to use. It is called
run_<OS-short-name>.<OS-extension>. To see list of all supported platforms, see Appendix B. 

If you have installed JRE (or JDK) on your OS and path set correctly (when you enter 
shell on OS, you should get long response when calling following command: 'java -version'. 
If response is short this will mean that java is not on path).  

Easiest way is to download one of our prepackaged GVM packages and extract it into GGC 
install directory. After that, running should be simply mater of issuing of 
run_<OS-short-name>.<OS-extension> command (what GVM is, see in next section).

If your OS is not on supported list, see Appendix A.

If your Meter, Pump, CGMS is on hardware supported list (file 'Diabetes_Hardware.txt'), but 
you can't get access to it (even after correct configuration), see Appendix C.
For this problem, you will also get error in application, when you try to read data
from device (on step 2). If dialog is opened with title "Error: Rxtx" this means that
something is wrong with your installation (or your binary file). Go see Appendix C.



Some Java/GGC terms explained 
==============================

Java Application - Java application is set of files, libraries and/or jar files. 

Java Library - Java Library is called application or set of classes, that was meant
   to be reusable. Java Library can be standalone jar file, or can be several files.
   In most cases Java library can use other libraries to function.
   
Class file - Class file, is base entity in java. It contains implementation of functionality.
   Class files can be in two forms: Source file, which has extension .java, here user can
   see what Class file does, and compiled Class, which has extension .class. .class file
   is created when developer has written certain Class and has compiled it. This finished
   .class file can be then started with JRE.
   
Jar file - JAR file is Java ARchive file. This is zip file, that contains one or more
   .class files and any other files required for running of application. This is preffered 
   way to deploy java applications/libraries.    
   
JRE - Java Runtime Environment. This is Java Framework, intended for end users. Each user
   that want to run finished Class, needs either this or JDK. This is set of files, which 
   are OS specific and sometimes also architecture specific. It contains executable file
   called java, which must be called with certain parameters, so that we can run our Class
   
JDK - Java Development Kit. This is Java Development Framework and is intended for users
   which, also want to help with development. It containes JRE and some other files, needed
   for development.       

JVM - Java Virtual Machine. This is java running environment. When we run 'java' executable 
   file, special environment is created (called jvm). This environment runs separate from our
   OS in this environment our .class files can run. Since this environment are separate from
   OS, we don't have direct access to all devices in that OS. We can access them through 
   jvm methods. This sometimes means that we need special libraries to access some of 
   hardware that is attached to our computer (see Native Java Library). Because java application
   needs jvm to run it usually runs a little slower than 'normal' application. Now days this
   is not problem, because most of our computers are very fast, but years ago difference 
   was quite noticable.
   
Native Java Library - this is Java Library that contains one or more jar files and also some binary
   parts (this are OS and architecture specific). If we don't have binary part for specific
   OS, then part of application will not work. In GGC we use one such library, which does 
   access devices connected through Serial interface (and also some of USB devices, which 
   use Serial-USB bridge - mostly special USB cables to connect our meters to computer).
   
GVM - This is GGC VM. It contains several groups of files
   1. JVM (it has JVM for OS for which GVM was intended, usually this is Sun's JVM if possible)
   2. Some startup scripts for GGC
   3. If available, there will also be binary/native file for Rxtx or any other Native Java Library 
   
   
   
How to Troubleshoot our problem
================================

Our Startup/Update/Db Update system (SUDUS in further text) has different parts and we will 
take a look at all of them, so that we can find a solution.

SUDUS uses special scripts and libraries to correctly start specified application (GGC in 
this case). It is totally configurable and could be used for any java application. In next
few steps we will describe, how things are done (from user point of view only).


A.) run_<OS-short-name>.<OS-extension> batch file (Main Startup file)
----------------------------------------------------------------------

This is main file, for specified OS. We will go through all steps needed for GGC 
application (all steps displayed here are in pseudo language):

1. Check if setenv_java_<OS-short-name>.<OS-extension> exists, if it exists, then do return 
     call on it
   - return call is calling sub-script and returning back to this script. Some OSes 
     have special calls like that. For example, on windows we can just use name of script, 
     but in this case execution continues in called sub-script, but it never returns to
     main script, but if you call with 'call <script-name>', execution returns to main
     script. (See B).
     
2. Return call setenv_atech.<OS-extension>
   - this will set environment variable ATECH_TOOLS_STARTUP, this variable needs to point to 
     last atech-tools-startup-<version>.jar file (see C)

3. Run following command 'java -classpath %ATECH_TOOLS_STARTUP% com.atech.update.startup.BuildStartupFile'
   - you might have to exchange %ATECH_TOOLS_STARTUP% with some other way to read environment varaible
     (for example windows uses %ATECH_TOOLS_STARTUP%, linux uses $ATECH_TOOLS_STARTUP insetad, etc)
   - this command will create specified scripts (used in next steps), with help of GGC_Update.properties 
     file, which is specified in StartupConfig.properties (see D)

4. Return call db_check.<OS-extension>
   - this command will start database check (on configured database in GGC) and create Db report file

5. Return call run_ggc.<OS-extension>
   - this start GGC application (with all needed libraries). It reads Db report file, if version number
     in report file is not correct application will not start. 

This is about all there is to know about SUDUS. There is some more stuff, but that is not relevant to user 
side of process.



B.) setenv_java.<OS-extension>
-------------------------------

This batch file, just adds path to java executable to existing PATH. If your system PATH already has java
executable file in its path (successful running of 'java -version' command can determine that), this file 
is not required. If you have GGC on USB, together with GVM for your platform, you need to have this set.
As you will see after install of GGC this file is not present by default, but if you install GVM for 
your platform this file will be added by GVM.


C.) Atech Tools Startup library and setenv_atech
-------------------------------------------------

ATech Tools is set of classes, which are helpful with some aspects of programing in java and with certain
frameworks that are used in GGC. This are all re-usable parts. Library is developed by one of our 
developers (by his company). Atech Tools Startup is just small portion of that whole library, and they
are now separately packed to solve versioning problems (we had to add new library everytime that something
changed here, now we just add new startup library, when one of startup classes changed).

setenv_atech.<OS-extension> is batch file that adds variable ATECH_TOOLS_STARTUP, to systems variables and 
this variable points at newest version of atech-tools-startup-<version>.jar. 

This library and setenv_atech.<OS-extension> batch file is updated, only if you do official update from
GGC site. 


D.) StartupConfig.properties
-----------------------------

StartupConfig.properties is used with Atech Tools Startup library. It contains two parameters. 

First is JAVA_EXE, which in old times, contained full path and java executable, but now that we work 
with PATH directly in SUDUS (see A), here we need to set just java executable (JAVA_EXE=java).

Second parameter is the one that makes SUDUS go, it's called UPDATE_CONFIG. This variable points
to GGC_Update.properties file, so that it can read configuration of files needed to run application.
This one should always be the same (UPDATE_CONFIG=../data/update/GGC_Update.properties). When 
new files come to old ones and need to be used, this configuration file is changed, but that
is job for person who creates new install (or update). At later time, when we have update in 
application working, this file will be changed automatically after each update.



E.) Rxtx Library (Native Java Library)
--------------------------------------

This is special library, which is used to access Serial Port (or USB Bridge = USB Bridge is 
device that is physically connected as USB, but internally it is identified as Serial device).

As we told before some libraries are not 100% Java (see Native Java Library) and this is one 
of those. In most cases this libraries don't work out-of-the-box. You will find all 'native' 
parts in directory <GGC-Install>\lib\native\<OS-Short-Name>, you will find that in most cases
you have also subdirectories here, denoting architecture. If this happens you need to copy
right files into root (for example in linux you have three subdirectories: ia64, x32, x64, so if
you use normal linux (32 bit), you will copy content of <GGC>\lib\native\linux\x32 to
<GGC>\lib\native\linux\. You will see that names look something like that: librxtxSerial.so, if 
name would look like librxtxSerial-2.1.7.so, you would need to either copy them to short version 
of name or make a link. I am telling you this because rxtx will look for this two native libraries:
librxtxSerial and librxtxParalel. For some OSes this binary files will be longer containing version
numbers, kernel numbers, architecture numbers and/or whatever.

If your OS is not supported, then we have a problem (or not). In unsupported cases you need to do
following:
1. Contact us on ggc@atech-software.com, asking to add support for your OS
2. a) Find binary part for rxtx. Rxtx is quite "old" library and one of mostly used ones (it's free
      and it works very good), so you will probably find binary part on internet in no time
   b) Download source files for rxtx and compile it yourself
3. Install it to <GGC>

In most cases this is it, but sometimes there are also problems with native part of library. Compile 
goes OK, but library still doesn't work. In this case you can contact us or you can contact developer
people on Rxtx to help you with your problem... They are quite good bunch of people and they are 
always willing to help. 

Supported OSes at this time are: Windows (x32, works with x64), Solaris (32/64), Mac OS X, Linux (x32, 
ia64, x64) [this are just files that are supplied with GGC from original Rxtx package, byt lots more
are supported by users.




Appendix A: Unsupported Operating Systems
==========================================

If your OS is not on supported list, please contact us on ggc@atech-software.com, so that we can 
add support for your OS into our startup library, and so that we can get your application running 
(and maybe creating new GVM for your OS).

If you are reading this you will probably have to read Appendix C too. 




Appendix B: Supported platforms
================================

Platform    |   Startup file   |  Short name  |  Rxtx  |Notes
-------------------------------------------------------------------
Windows     |  run_win.cmd     |  win         |
Linux       |  run_linux.sh    |  linux       |        | need to have sh installed (usually installed by default)
Mac         |  run_mac.sh      |  mac         |        | need to have bash installed (usually installed by default)
FreeBSD     |  run_freebsd.sh  |  freebsd     |  No    | need to have sh installed (installed by default)



Appendix C: Hardware device is not working
===========================================

If you have problem with Hardware device (Meter, Pump or CGMS that is otherwise supported) you will need to read 
following sections: 
 - Some Java/GGC terms explained
 - At least Section E of 'How to Troubleshoot our problem'



Appendix D: Hardware is not supported
======================================

GGC is open-source application, which means that everyone with Java knowledge can help, but if noone helps then
nothing is done. 

Our current core team is trying to add a lot of functionalities and also a lot of different devices, but there 
are several problems... 

1.) All of our people do this in their spare time, so it takes a lot of time.
2.) We can only add device that we have (we need device for testing) and that we know how it communicates with PC. 
   This second thing is biggest problem, if we don't know what commands and what replies are there
   we can only guess what is happening. Problem is that most companies don't like to share this details (how PC
   and device communicate is called protocol), and most that do, are already added or are in plans to be added.
   If you come across such protocol, please let us know, just knowledge of this protocol is sometimes enough to
   make device supported.  


GGC Development Team