New Magellan
New Magellan is a C# driver process that runs in the background to manage communication between scanner scales and POS as well as credit card terminals and POS. It is located in pos/is4c-nf/scale-drivers/drivers/NewMagellan and generally needs to be compiled before use. The driver is not currently distributed as a binary and does need to be compiled.
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"
- Windows 7
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.
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).
Datacap requires some extra software and extra compilation steps. It also only works using the .NET 4.0+ version. There's an EMV module and a non-EMV module.
In either case,
- Install the USB driver for the VX805. This creates a virtual COM port (COM9 by default).
- Install dsiPDCX. This is required in either case.
- Run aximp.exe on dsiPDCX.ocx to generate C# wrappers (see the README file in NewMagellan for details on aximp).
For EMV:
- Install dsiEMVUS.
- Run aximp.exe on dsiEMVX.ocx
- Install the NetEPay server (this currently MUST be locally on the lane).
- Run the NetEPay server. Click through some initial set up stuff, then click the setup icon to enter your Deployment ID.
- Run the EMV US client test app and use the ParamDownload option to make sure EMV is enabled on the terminal
Finally, run "msbuild" to compile with driver modules for Datacap. Typical ports.conf configuration would be one of these (where the VX805 is on COM9):
- VX805XPI_MERCURY_E2E:9 SPH_Datacap_PDCX
- VX805XPI_MERCURY_E2E:9 SPH_Datacap_EMVX
Make sure the directory ss-output exists is writable by the driver and PHP (these are Linux directions; default permissions in Windows are usually fine):
$ ls -l ss-output
If it doesn't exist:
$ mkdir ss-output
$ sudo chmod -R 777 ss-output
NewMagellan is configured to load one or more modules where each module is responsible for managing a specific hardware devices. Both configuration methods that follow involve mapping driver modules to devices. See NewMagellan Modules for information about available modules.
Note: this only works when the driver is compiled for .NET 4.0+ with Newtonsoft.Json.
Go to the lane's configuration page and click the HW Driver tab. Add or delete devices and update each device's port assignment via that page. If you want to make manual adjustments, the configuration format is:
{
"NewMagellanPorts":[
{
"module":"SPH_Magellan_Scale",
"port":"COM1"
},
{
"module":"SPH_Datacap_EMVX",
"port":"VX805XPI_MERCURY_E2E:9"
}
]
}If ini.json is present and has NewMagellanPorts values, those values will be used instead of ports.conf.
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 windows config, scanner/scale
COM1 SPH_Magellan_Scale
# But leave lines for devices you aren't using commented:
# typical linux config, scanner/scale
/dev/ttyS0 SPH_Magellan_Scale
# typical windows config, USB IDtech
#USB SPH_SignAndPay_USB
# typical linux config, USB IDtech
#/dev/hidraw0 SPH_SignAndPay_USB
Once ports.conf is correct for the attached hardware,
run pos.exe. In Linux you will need to use mono, e.g.,
$ sudo mono pos.exe
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
...
These are the mono-related packages I have installed on a 14.04 host the compiles successfully. I naively thought that apt-get install mono-xbuild would grab everything I'd need in resolving dependencies. It did not come particularly close.
$ dpkg -l | grep mono
ii fonts-ubuntu-font-family-console 0.80-0ubuntu6 all Ubuntu Font Family Linux console fonts, sans-serif monospace
ii libmono-corlib2.0-cil 3.2.8+dfsg-4ubuntu1.1 all Mono core library (for CLI 2.0)
ii libmono-corlib4.0-cil 3.2.8+dfsg-4ubuntu1.1 all Mono core library (for CLI 4.0)
ii libmono-corlib4.5-cil 3.2.8+dfsg-4ubuntu1.1 all Mono core library (for CLI 4.5)
ii libmono-csharp4.0c-cil 3.2.8+dfsg-4ubuntu1.1 all Mono.CSharp library (for CLI 4.0)
ii libmono-data-tds4.0-cil 3.2.8+dfsg-4ubuntu1.1 all Mono Data Library (for CLI 4.0)
ii libmono-i18n-west2.0-cil 3.2.8+dfsg-4ubuntu1.1 all Mono I18N.West library (for CLI 2.0)
ii libmono-i18n-west4.0-cil 3.2.8+dfsg-4ubuntu1.1 all Mono I18N.West library (for CLI 4.0)
ii libmono-i18n4.0-cil 3.2.8+dfsg-4ubuntu1.1 all Mono I18N base library (for CLI 4.0)
ii libmono-microsoft-build-engine4.0-cil 3.2.8+dfsg-4ubuntu1.1 all Mono Microsoft.Build.Engine library (for CLI 4.0)
ii libmono-microsoft-build-framework4.0-cil 3.2.8+dfsg-4ubuntu1.1 all Mono Microsoft.Build.Framework library (for CLI 4.0)
ii libmono-microsoft-build-tasks-v4.0-4.0-cil 3.2.8+dfsg-4ubuntu1.1 all Mono Microsoft.Build.Tasks.v4.0 library (for CLI 4.0)
ii libmono-microsoft-build-utilities-v4.0-4.0-cil 3.2.8+dfsg-4ubuntu1.1 all Mono Microsoft.Build.Utilities.v4.0 library (for CLI 4.0)
ii libmono-microsoft-build2.0-cil 3.2.8+dfsg-4ubuntu1.1 all Mono Microsoft.Build libraries (for CLI 2.0)
ii libmono-microsoft-csharp4.0-cil 3.2.8+dfsg-4ubuntu1.1 all Mono Microsoft.CSharp library (for CLI 4.0)
ii libmono-posix2.0-cil 3.2.8+dfsg-4ubuntu1.1 all Mono.Posix library (for CLI 2.0)
ii libmono-posix4.0-cil 3.2.8+dfsg-4ubuntu1.1 all Mono.Posix library (for CLI 4.0)
ii libmono-security2.0-cil 3.2.8+dfsg-4ubuntu1.1 all Mono Security library (for CLI 2.0)
ii libmono-security4.0-cil 3.2.8+dfsg-4ubuntu1.1 all Mono Security library (for CLI 4.0)
ii libmono-system-configuration4.0-cil 3.2.8+dfsg-4ubuntu1.1 all Mono System.Configuration library (for CLI 4.0)
ii libmono-system-core4.0-cil 3.2.8+dfsg-4ubuntu1.1 all Mono System.Core library (for CLI 4.0)
ii libmono-system-data-linq4.0-cil 3.2.8+dfsg-4ubuntu1.1 all Mono System.Data.Linq Library (for CLI 4.0)
ii libmono-system-data4.0-cil 3.2.8+dfsg-4ubuntu1.1 all Mono System.Data library (for CLI 4.0)
ii libmono-system-drawing4.0-cil 3.2.8+dfsg-4ubuntu1.1 all Mono System.Drawing library (for CLI 4.0)
ii libmono-system-enterpriseservices4.0-cil 3.2.8+dfsg-4ubuntu1.1 all Mono System.EnterpriseServices library (for CLI 4.0)
ii libmono-system-numerics4.0-cil 3.2.8+dfsg-4ubuntu1.1 all Mono System.Numerics library (for CLI 4.0)
ii libmono-system-runtime-serialization4.0-cil 3.2.8+dfsg-4ubuntu1.1 all Mono System.Runtime.Serialization Library (for CLI 4.0)
ii libmono-system-security4.0-cil 3.2.8+dfsg-4ubuntu1.1 all Mono System.Security library (for CLI 4.0)
ii libmono-system-transactions4.0-cil 3.2.8+dfsg-4ubuntu1.1 all Mono System.Transactions library (for CLI 4.0)
ii libmono-system-xml4.0-cil 3.2.8+dfsg-4ubuntu1.1 all Mono System.Xml library (for CLI 4.0)
ii libmono-system2.0-cil 3.2.8+dfsg-4ubuntu1.1 all Mono System libraries (for CLI 2.0)
ii libmono-system4.0-cil 3.2.8+dfsg-4ubuntu1.1 all Mono System libraries (for CLI 4.0)
ii libmono-xbuild-tasks2.0-cil 3.2.8+dfsg-4ubuntu1.1 all Mono Mono.XBuild.Tasks library (for CLI 2.0)
ii libmono-xbuild-tasks4.0-cil 3.2.8+dfsg-4ubuntu1.1 all Mono Mono.XBuild.Tasks library (for CLI 4.0)
ii mono-4.0-gac 3.2.8+dfsg-4ubuntu1.1 all Mono GAC tool (for CLI 4.0)
ii mono-gac 3.2.8+dfsg-4ubuntu1.1 all Mono GAC tool
ii mono-mcs 3.2.8+dfsg-4ubuntu1.1 all Mono C# 2.0 / 3.0 / 4.0 / 5.0 compiler for CLI 2.0 / 4.0 / 4.5
ii mono-runtime 3.2.8+dfsg-4ubuntu1.1 amd64 Mono runtime - default version
ii mono-runtime-common 3.2.8+dfsg-4ubuntu1.1 amd64 Mono runtime - common files
ii mono-runtime-sgen 3.2.8+dfsg-4ubuntu1.1 amd64 Mono runtime - SGen
ii mono-xbuild 3.2.8+dfsg-4ubuntu1.1 all MSBuild-compatible build system for Mono