CORE-POS/IS4C

================================
COMPILATION
================================
NewMagellan is a .NET 4.0 application.

* Building the .NET 4.0 version
    * Windows 7
        * Install Windows SDK 7.1+
        * Run the SDK command line program
        * Navigate to this folder
        * Type "msbuild"
    * Windows 8
        * Install Visual Studio Community or the Windows 7.1 SDK (as above)
        * Type "Visual Studio Tools" into the start screen
        * Pick on of the command prompts
        * Navigate to this folder
        * Type "msbuild"
    * Non-Windows
        * Install mono and related development packages,
          e.g. mono-devel. If "mcs --version" returns
          3.2.8+, you're probably fine.
        * Open a terminal and navigate to this folder
        * Type "xbuild"
    * Ubuntu has a particularly fragmented mono package set. See:
      https://github.com/CORE-POS/IS4C/wiki/New-Magellan#building-on-ubuntu-1404lts

================================
NuGet
================================
The project currently supports but does not require
using NuGet. Visual Studio will probably sort things out
on its own from packages.config. For a pure command line
build download the CLI version of nuget and run "nuget restore"
to install HidSharp, Newtonsoft.Json, and RabbitMQ.Client.

At some point this might become mandatory so there isn't
3rd party code directly in the repo but for now the HidSharp
and Newtonsoft.Json will be built from the included source
if they aren't installed via NuGet.

================================
What happened to the .NET 2.0 version
================================
NewMagellan is beginning to take advantage of 3rd party libraries. 
Some of these require a build environment less than a decade old.

* HidSharp
    * This is a cross-platform abstraction layer for reading and
      writing from HID-class USB devices. NewMagellan's own USB
      implementation works OK on Windows but can be very buggy
      in Linux.
* Newtonsoft.Json
    * This is a popular library for reading and writing JSON data.
      Storing configuration data in a JSON format would let
      NewMagellan and POS reference the same configuration file
      rather than maintaining a separate ports.conf. Having a more
      flexible configuration format would also allow more run-time
      settings instead of compile-time settings.

================================
DESIGN NOTES
================================

Originally, this was similar to the original, VB magellan
and used a WebBrowser object embedded in a windows form with
various page change callbacks registered. Turns out WebBrowser
objects are flaky at best on the Linux/mono side of things, so
there's been some significant refactoring to remove the GUI 
portions. Some naming conventions seem odd now that made sense
in the original structure (e.g., DelegateForm is no longer a
System.Windows.Forms.Form, nor does it contain any delegates).

================================
WINDOWS INSTALL NOTES
================================

Indicate which ports, i.e. which peripheral devices are being monitored.
Edit ports.conf and uncomment (remove the leading "#" from) and change,
or add, as necessary the lines such as:
# <name of port> <name of handler class>
#    
# typical linux config, scanner/scale
COM1 SPH_Magellan_Scale

But leave lines for devices you aren't using commented:
# typical linux config, USB IDtech
#USB SPH_SignAndPay_USB

Once ports.conf is correct for the attached hardware,
double-click pos.exe. A .bat file is included for running
pos.exe automatically on start-up. Editing the filesystem path
in the batch file may be necessary depending where POS is
installed.

================================
DATACAP BUILD NOTES
================================
Datacap provides ActiveX controls for out-of-scope support
on both regular (credit/debit/ebt) and EMV transactions. This
is a windows-only solution. To build support for regular transactions,
dsiPDCX must be installed. To build support for EMV transactions, both
dsiPDCX and dsiEMVUS must be installed. Datacap provides click
through installers for both. After installing the control(s) and likely
rebooting, you need to build C# wrappers for the ActiveX controls.
The build scripts do *not* do this for you. To build ActiveX wrappers,
navigate to the NewMagellan directory and run:

* aximp C:\Windows\DatacapControls\dsiPDCX.ocx
* aximp C:\Windows\DatacapControls\dsiEMVX.ocx

If successful, this will create files named DSIPDCXLib.dll, AxDSIPDCXLib.dll,
DSIEMVXLib.dll, and AxDSIEMVXLib.dll.

The most common cause of errors relates 64-bit OSes. The ActiveX controls are
currently provided as 32-bit only. They will work on 64-bit Windows but you need
to use the 32-bit version of aximp.exe. Exactly where that resides depends
which build tools you're using. Something with x64 in the filesystem path is
generally wrong. Something with x86 in the filesystem path is generally right.
Usually there are only two aximp.exe files so if you can determine the bittedness
of one the other can be established by process of elimination.

If you get an error related to the control being unknown, you can try
registering it manually. On 64-bit systems, run:

* C:\Windows\SYSWOW64\regsvr32.exe C:\Windows\DatacapControls\dsiPDCX.ocx
* C:\Windows\SYSWOW64\regsvr32.exe C:\Windows\DatacapControls\dsiEMVX.ocx

On 32-bit systems, run:
* C:\Windows\System32\regsvr32.exe C:\Windows\DatacapControls\dsiPDCX.ocx
* C:\Windows\System32\regsvr32.exe C:\Windows\DatacapControls\dsiEMVX.ocx

Yes, those directory names seem reversed but they're correct.

================================
LINUX INSTALL NOTES
================================

# Make sure the directory ss-output exists is writable by the driver and PHP:
$ ls -l ss-output
# If it doesn't exist:
$ mkdir ss-output
$ sudo chmod -R 777 ss-output

Check the assignment of MAGELLAN_OUTPUT_DIR in SPH_Magellan_Scales.cs
and drivers for other devices you plan to use.
$ grep "MAGELLAN_OUTPUT_DIR =" *.cs
It should be "ss-output/", the same as the directory above, in all cases.

If it isn't, open SPH_Magellan_Scale.cs and the other files in a text
editor and change it.

Compile the driver;  the executable pos.exe is not part of the distribution:
$ make clean
$ make

Indicate which ports, i.e. which peripheral devices are being monitored.
Edit ports.conf and uncomment (remove the leading "#" from) and change,
or add, as necessary the lines such as:
# <name of port> <name of handler class>
#    
# typical linux config, scanner/scale
/dev/ttyS0 SPH_Magellan_Scale

But leave lines for devices you aren't using commented:
# typical linux config, USB IDtech
#/dev/hidraw0    SPH_SignAndPay_USB

You can run the driver in the foreground:
$ sudo mono pos.exe
If it starts OK it will immediately say:
Reading serial data

Use a script like posdriver-sph-debian to launch in the background.
(posdriver-sph is for Redhat)
posdriver-sph-debian can be configured to run pos.exe in verbose mode.
Possibly configure (which posdriver script to run) and use posd.sh
to manage the launcher.
If you do, begin with:
$ posd.sh install

If you are running pos.exe in verbose mode you can use:
$ tail -f /var/run/posdriver-sph-debian/pos.log
or the utility tail_nmd_log.sh (tnl) to monitor it.

For further help search the techhub forum for "NewMagellan".

Run the driver in the foreground:
$ sudo mono pos.exe -v
If it starts OK it will immediately say:
Reading serial data
and there may be another line of scale or scanner data such as S110000

Now scan a barcode. It should be echoed to the window running pos.exe. E.g.:
03120044618
Then put something on the scale. Expect to see something like:
S110023
where "23" is the weight, 23/100ths of a pound in this case.
Remove the thing from the scale and two more lines will probably appear:
S141
S1100000
RECV FROM SCALE: S143
PASS TO POS: S110000
the second indicating the scale is back to zero.
To stop the driver type:
^C
or
exit

You can run the driver in the foreground and use the PoS at the same time.
The items you scan and weigh (if you also enter product codes) will appear
in the transaction in the usual way.

The driver launch script posdriver-sph is set to not non-verbose mode for
production use because the logfile can grow very large.  You can change
it to verbose for debugging.  Be sure to re-install the version you
want to run at boot, possibly with:
$ posd swap

A second attempt to run the driver in the foreground may get a message like:
$ sudo mono pos.exe -v

Unhandled Exception: System.NullReferenceException: Object reference not set to an instance of an object
  at System.TermInfoDriver.CheckWindowDimensions () [0x00000] 
  at System.TermInfoDriver.get_WindowWidth () [0x00000] 
  at System.TermInfoDriver.IncrementX () [0x00000] 
  at System.TermInfoDriver.IsSpecialKey (ConsoleKeyInfo key) [0x00000] 
  at System.TermInfoDriver.IsSpecialKey (Char c) [0x00000] 
  at System.IO.CStreamWriter.Write (System.Char[] buffer, Int32 index, Int32 count) [0x00000] 
  at System.IO.CStreamWriter.Write (System.Char[] val) [0x00000] 
  at System.IO.CStreamWriter.Write (System.String val) [0x00000] 
  at System.IO.TextWriter.WriteLine (System.String value) [0x00000] 
  at System.IO.SynchronizedWriter.WriteLine (System.String value) [0x00000] 
  at System.Console.WriteLine (System.String value) [0x00000] 
  at SPH.SPH_Magellan_Scale.Read () [0x00000] 

I don't know what to do about this.
Doing again gets the same message.
Start the driver in the background, do a couple scans, stop it;
then running it in foreground may work again.

Open another terminal window and go to ss-ouput.
$ls -l will show something like:
-rwxrwxrwx 1 nobody   nogroup     8 2012-10-27 17:14 13930410
-rw-r--r-- 1 root     root        8 2012-10-27 17:34 15184740
-rw-r--r-- 1 root     root       12 2012-10-27 17:35 15206202
-rw-r--r-- 1 root     root       12 2012-10-27 17:35 15210526
-rw-r--r-- 1 root     root        8 2012-10-27 17:35 15216206
-rw-r--r-- 1 root     root        5 2012-10-27 17:35 15217402

Files contain output like that echoed to the screen, without the LABELS:.
There may be no files if the driver has been doing effective housekeeping,
but the datestamp on the directory will be recent if the scanner/scale
is active.

While the driver is running in the background,
scan and scale events are, if the -v option was used, also logged to
a file named in the driver start script, begin with, posdriver-sph, for example:
/var/run/posdriver-sph/pos.log
You can watch this as it accumulates with:
$ tail -f /var/run/posdriver-sph/pos.log
Reading serial data
Received: rePoll
RECV FROM SCALE: S143
PASS TO POS: S110000
Received: goodBeep
RECV FROM SCALE: S08A88904400002
PASS TO POS: 88904400002
Received: goodBeep
RECV FROM SCALE: S110029
RECV FROM SCALE: S1440029
PASS TO POS: S110029
RECV FROM SCALE: S1440029
...