This describes setting up (installing, configuring), under Linux, the software that supports a Magellan scanner/scale that IS4C is communicating with through the NewMagellan driver. It assumes the physical installation is done and also the lane level port and driver (NewMagellan) choices at http://laneX.foo.coop/IS4C/pos/is4c-nf/install/extra_config.php have been made.

If, after that is done, everything is fine, that is both scanned barcodes and weights are appearing in your PoS transactions, then you need read no further.

However, if this is a new installation, you need to learn about compiling and starting the driver, which is not started by default, and, for a production (not test) environment, about running it in the background and starting it at bootup.

This document describes how to do those things and offers some tips about solving problems at this level.

1. Open a terminal window and go to where the NewMagellan driver resides, possibly:
   $ cd /var/www/IS4C/pos/is4c-nf/scale-drivers/drivers/NewMagellan
2. Make sure the serial port you named can be written to by the driver and Apache/PHP.
   $ sudo chmod 666 /dev/ttyS0
3. See that data is getting from the scanner-scale to the serial port:
   $ cat /dev/ttyS0
   Then scan a barcode. The number should appear, with a prefix e.g. S08A if the scanner has been programmed to supply them. The whole string might then be:
   S08A03120044618, with checkdigit already removed.
   If nothing appears then check that the scanner-scale is connected to the correct serial port and that your configuration names that port.
   If you want to get a weight response at this level you first have to send the scale a weigh-request. In another terminal window:
   $ echo -e "S11\r" > /dev/ttyS0
   and then put something on the scale. If it weighs 0.23 lb you will see something like:
   S110023
   It will be superimposed on the previous output if you are under Linux and the scanner-scale terminates its output with a Carriage Return (\r):
   S11002320044618
   Type Ctrl-C to stop display from the serial port. Note that the driver will not have access to what the scanner-scale is sending as long as this cat is getting it first.
4. You can do further experiments at the level of communicating directly with the serial port using this utility:
   $ sscom.sh
   (that is still a work in progress).
5. Make sure the directory ss-output and everthing in it is writable by the driver:
   $ sudo chmod -R 777 ss-output
6. Check the assignment of MAGELLAN_OUTPUT_DIR in SPH_Magellan_Scales.cs
   $ grep MAGELLAN_OUTPUT_DIR SPH_Magellan_Scales.cs
   It should be ss-output/, the same as the directory above. If it isn't, open SPH_Magellan_Scales.cs in a text editor and change it. Note the trailing slash.
7. Compile the driver, pos.exe:
   $ make clean
   $ make This has to be done once for any Linux installation even if pos.exe already exists and you haven't changed any of the source (*.cs) files.
8. Check that the mono program is available:
   $ which mono
   # Should report something like
   /usr/bin/mono
   If which finds nothing, then install mono:
   $ sudo apt-get install mono-devel
   # or
   $ sudo apt-get install build-essential
9. Run the driver in the foreground:
   $ sudo mono pos.exe
   If it starts OK it will immediately write to the terminal:
   Reading serial data
   and there may be another line of scale or scanner data such as
   S110000
10. Now scan a barcode. It should be echoed to the window running pos.exe. E.g.:
    03120044618
11. 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
    the second indicating the scale is back to zero.
    (These "S" codes are from an SL384 but I'm pretty sure they are the same for other Magellan-series scanner/scales.)
12. To stop the driver: type Ctrl-C
13. You can run the driver in the foreground and use the PoS at the same time. The items you scan and weigh will appear in the transaction in the usual way as well as being written to the screen.
14. Still no joy? Try searching the techhub forum for NewMagellan
    If that doesn't help post to the forum yourself.
15. A second attempt to run the driver in the foreground may get a message like:

    $ sudo mono pos.exe
    
    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. Running it again gets the same message.
    You can try: Start the driver in the background (see below), do a couple scans, stop it; then running it in foreground may work again.
16. Running the driver in the background. In order to not have a terminal window open while the lane is running you can run the driver in the background. In Linux this is called running as a daemon. You will also likely want the convenience of having the daemon started automatically when the computer boots and stopped when it is shut down. There are two wrapper scripts for this in the NewMagellan directory:
    • posdriver-sph-debian
      for Ubuntu and other Debian-derived Linuxes
    • posdriver-sph
      for other flavours
    The script needs to be copied to /etc/init.d so the startup and shutdown processes will be able to find it.
    $ sudo cp script-name /etc/init.d
    After that, tell startup/shutdown about it:
    $ sudo update-rc.d script-name defaults
    A daemon installed this way is called a service.
17. The script posd.sh can be used to manage the service, including installing, starting, stopping and installing new versions and cleaning up after crashes or failures.
    $ posd.sh -h
    Usage: posd.sh stop|start|restart|status|clean|swap|remove|install
    Edit its variable POSD to refer to the service script you are using:
    POSD=posdriver-sph-debian
    # or
    POSD=posdriver-sph
    If you change the driver (pos.exe) you need to stop and start the service.
    

Some notes on what the driver is doing behind the scenes:

• Open another terminal window and cd to the ss-ouput directory.
  $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

  Each file contains output like that echoed to the screen when the driver is running in the foreground.
• While the driver is running in the background, scan and scale events are also logged to a file named in the driver start script, e.g. posdriver-sph, for example:
  /var/run/posdriver-sph/sph.log
  You can watch this as it accumulates with:
  

  $ tail -f /var/run/posdriver-sph/sph.log
  Reading serial data
  S110000
  Received: rePoll
  S110000
  03120044618
  Received: goodBeep
  S110024
  Received: goodBeep
  S141
  S110000
  85794100187 

  Ctrl-C to stop the display.