CORE-POS/IS4C

View on GitHub
documentation/IS4C/developer/howto-newmagellan.html

Summary

Maintainability
Test Coverage
<html>
<head>
    <title>New Magellan</title>
</head>
<body>
<!--
11Apr14 AT Add current inputs & outputs
.8Nov12 EL Link to another doc about NewMagellan.
-->
    <div style="text-align:center;margin-bottom:10px;font-size:80%;">
    updated as of: April 11, 2012
    <br />last author: Andy Theuninck
    <br />original author: Andy Theuninck
    </div>
NewMagellan is one of the scale drivers included in this release.
It works to connect IS4C to a Magellan scanner/scale, but it also
serves as a base point for communicating with multiple external
devices.
<p />
NewMagellan is written in C# .NET. All traces of winforms have been
stripped out for the sake of mono compatibility. It doesn't require
Visual Studio on Windows; the .NET 2 SDK includes a command line that's
sufficient. Both a makefile for linux and a batch file for compiling
on windows included.
<p />
<h2>How it works</h2>
<p />
Magellan reads ports.conf to see what drivers to use. Entries are just
a port (COM1, /dev/Stty1, etc) and a driver name (e.g., SPH_Magellan_Scale).
You can have more than one driver running - say a scanner/scale
and a signature capture device.
<p />
Each driver is launched in its own thread. Other than implementing the
SerialPortHandler class, there's no hard and fast requirements what a driver
actually has to do. Reading from the relevant serial port would probably
be the most common. Writing to the file system is the easiest way I've found
to pass info to IS4C (similar to what ssd does).
<p />
After starting all the drivers, Magellan launches one more thread with
a simple UDP server. All it does is listen (port 9450 by default) and
pass any received messages to each driver. This way IS4C can send
commands to devices directly without intermediary files.
<p />
The current version accepts command line input of messages, too.
Re an init script to background the process see
<a href="howto-newmagellan-2.html" target="_blank">Installing NewMagellan Scanner/Scale Driver</a>
The windows version
compiles a second executable that can be registered as a windows service.
<p />
Win32 service notes: the port/driver configuration is hard-coded into
the executable, so you have to recompile to make changes (alternately you
could hard-code the path to ports.conf, but that would mean a recompile
too). The .NET SDK includes a utility called installutil.exe. To install,
run installutil.exe posSVC.exe. To remove, run installutil.exe /u posSVC.exe.
Installation prompts for a username and password. The username has to 
include the machine name (e.g., POS1\is4c_user) to work. It took me awhile
to figure that out.
<p />
<h2>Currently Supported Input Messages</h2>
These are messages sent from POS to the driver via UDP.
<ul>
    <li><b>errorBeep</b> [scale] issue three beeps</li>
    <li><b>beepTwice</b> [scale] issue two beeps</li>
    <li><b>goodBeep</b> [scale] issue one beeps</li>
    <li><b>twoPairs</b> [scale] issue four beeps with a pause between the second and third</li>
    <li><b>rePoll</b> [scale] re-request weight</li>
    <li><b>termReset</b> [cc] reset terminal to its start transaction state</li>
    <li><b>termReboot</b> [cc] reboot terminal hardware</li>
    <li><b>termManual</b> [cc] display manual card entry screen</li>
    <li><b>termApproved</b> [cc] display approval screen</li>
    <li><b>termGetType</b> [cc] display card type selection screen</li>
    <li><b>termGetTypeWithFS</b> [cc] display card type selection screen including foodstamp option</li>
    <li><b>termCashBack</b> [cc] display cash backselection screen</li>
    <li><b>termGetPin</b> [cc] display PIN entry screen</li>
    <li><b>termWait</b> [cc] display wait-for-cashier screen</li>
    <li><b>termSig[suffix]</b> [cc] do signature capture. The suffix is an optional 
    message to display on the screen (do not include the square brackets)</li>
</ul>
<p />
<h2>Currently Supported Output Messages</h2>
These are messages sent from the driver to POS by writing a file in
the ss-output directory.
<ul>
    <li><b>[numeric value]</b> [scale] UPC/EAN data</li>
    <li><b>GS1~[numeric value]</b> [scale] GS1 barcode data</li>
    <li><b>S11[four digit weight</b> [scale] current weight</li>
    <li><b>S141</b> [scale] not settled on a weight yet</li>
    <li><b>S142</b> [scale] error condition</li>
    <li><b>S143</b> [scale] weight is zero</li>
    <li><b>S145</b> [scale] weight is below zero (error condition as well)</li>
    <li><b>TERMCLEARALL</b> [cc] term has reset to start transaction state. Clear
        any pending POS-side data</li>
    <li><b>TERM:[type]</b> [cc] card type selection. <b>[type]</b> will be
        Credit, Debit, EbtFood, EbtCash, or Gift.</li>
    <li><b>TERMCB:[amount]</b> [cc] cash back amount selection.</li>
    <li><b>PINCACHE:[entryped data]</b> [cc] entryped PIN block</li>
    <li><b>PANCACHE:[entryped data]</b> [cc] entryped card data (magstripe) block</li>
    <li><b>TERMBMP[filename]</b> [cc] signature data available. The file should be located in
        ss-output/tmp/.</li>
</ul>
<b>Output notes / stuff to be aware of</b>:<br />
Any output that begins with <b>S</b> is assumed to be scale-weight data. Non-scale-weight output 
containing a colon character is parsed entirely in the background. For example, if the cashier
has typed "5*" in the input box and scans an item, the driver output will be combined with
that "5*", where as a card type output would ignore the "5*". The colon is omitted from the
signature data command intentionally because that command is typically not used in conjunction
with the "main" pos2.php screen.
</body>
</html>