• Installation of SHARK WCS DRIVER
  • System Requirements
  • Installing the Program
  • Configuration
    • Configuration of the User Interface
  • Backup
• SHARK WCS - The REST Protocol
  • Command Format
  • Getting Started
• Simulation
  • Automats
    • Error simulation
• SHARK WCS File Interface
  • Configuration of the File Importer
  • XML Files
  • Modifying the format
• Sequencer Scripting
• General codes
• Serial Module
• Automat specific codes
• DIO modules
• Location Light
• Pick carts
• PickToLight
• Conveyor
• OPC Server
• Transport stations
• Printers
• MODBUS Error

SHARK WCS  (Warehouse Control System) is a basic control system for automation hardware. The WCS system controls the hardware at device level, e.g. fetch a tray from a vertical lift and will take care of all the lower level communication protocols. The host uses a higher level integration, typical using a REST based web service, but it is also possible to make integration with simple command files.

The REST protocol makes it for example possible to make the integration directly from a HTML page running in a browser.

Example of 3 vertical lifts controlled either by a command line or directly from a device using the REST HTTP Protocol.

Example of supported hardware devices:

• Vertical lifts.
• Pick-by-light systems.
• Conveyors.
• Scale integration.

Installation of SHARK WCS DRIVER

The installation program will install the software as a Window Service that always must run and as a separate user interface that can be started when needed. The advantages with this setup, is that the software can be used, without a user is logged in. It is also possible to run the WCS Driver as a stand-alone program, but this will require manual configuration.

System Requirements

SHARK WCS DRIVER is a stand-alone solution that typical don’t need other resources, except a Windows PC/Server for the installation. The configuration will then be stored in a configuration file. It is also possible to connect to a Microsoft SQL Server used for configuraiton storage.

Before installation the following must be available:

• The installation program.
• A product key file, This is the product license.

Installing the Program

The installation program is a single executable file. The name is *install_shark_wcs_driver_master_.exe*.

Step 1 - Start installation

Execute the installation program, this must be done with administrator privileges.

Press [Next] to continue.

Step 2 - Select installation folder

Select the folder where to instal the software - or just accept the default folder.

  Step 3 - Select short cuts

Select where the short cuts will be created, typical the default is fine, so just press [Next].

Step 4 - Start the installation

Press [Next] to start the installation.

Step 5 - Finish installation

If the software is installed successfully, the dialog below is shown.

Step 6 - Setup License

The Product Key File (License) must be copied to the “bin” folder below the installation folder (<install folder>\bin). This file is required to start the program.

Step 7 - Verify the installation

When the installation is finished, check that:

• A WCS Driver icon is created on the desktop.
• The Windows Service “Shark Control” is running. If it is not running open the service manager and start the service. 

Configuration

Start the WCS User Interface. Check that the interface is connected to the service, in the lower left corner the status must be “connected”.

Add a new module, by clicking [Add Module].

Select the module to install (here a Logimat SLL) and enter the name of the module. Press [OK] and the configuration dialog for the module will be displayed:

Note: It is required to restart the “Shark Control” service to load the new created module!*

After the new module is loaded, check it is started successfully. The configuration can be changed by right clicking the module and choose [Configuration].

Configuration of the User Interface

When installed the WCS Driver is installed as one program that includes both the user interface and driver modules. This means the user interface must be running to make the system work. An alternative setup is to install it as Windows Service without any user interface. This might be a more stable solution, because the software is started automatically with Windows and cannot be closed accidentally.

The WCS User Interface is started by a link that can be configured to customise the functionality.

Start a user interface that connects to a running service

javaw.exe -jar shark_control.jar -nodb -ui -connect localhost

Start a user interface for an automat that connects to a running service

The automat is installed as “A1”

javaw.exe -jar shark_control.jar -nodb -ui automat:a1 -connect localhost

Start the WCS Driver as  a stand-alone application (no service used)

javaw.exe -jar shark_control.jar -nodb -ui

Backup

In some configurations, the application might store important data, that is changes all the time. This could for example be tray or box positions in an automat. The data are either stored in an SQL Server or in a JSON text file on the disk. In both cases it is important to establish some kind of data backup.

SHARK WCS - The REST Protocol

The recommended way to make an integration is by means of the REST API. The reference documentation can be found with this link.

Th reference documentation, for the latest version (1.0) can be found here

The SHARK WCS REST API is a protocol that provides low-level access to the devices controlled by SHARK WCS. It is defined in a way, that makes it easy to implement in most programming languages and thereby supporting a simple integration into a Host System.

Most commands are generic and hides as much as possible, the actually physical device. This means that different types of vertical lifts and similar automats can be controlled with the same set of commands. 

The interface can be tested from a standard Web Browser, thereby the functionality of the SHARK WCS can be tested and explored before the final integration is ready. A simulation mode is also available to test the software before the actually hardware is installed.

As an alternative to use a Web Browser, the public domain tool “curl” can be used from a command line, in a scripting languages for testing or even in a final implementation.

The Host does not have to maintain the physical position of the trays, this is handled by SHARK WCS, it also knows what trays are the opening and it will automatically return trays or boxes if needed, this minimize the risk of crashes due to errors in the Host programming and means that the Host does not have to keep any state information of the machine. 

Command Format

The general format of the REST commands are:

Example of a command that will get tray number 5 from an automat:

http://localhost:8095/device/automat/a1/fetch?carrier=5

Response

The command will always return a HTTP response, formatted as a JSON document. This is a simple text string.

    { ”ErrorCode” : ”<error code>”, ”Message” : ”<message>”}

Most of the commands returns immediately and the response will indicate that the command is received correctly. It will not necessarily say that the requested operation has been fulfilled successfully, this requires a check with the “status” command.

Some of the commands will return a more complicated response, depending on the equipment used.

Getting Started

If the hardware is ready and the SHARK WCS is installed, it is pretty easy to start testing the system. Try open an Internet Web Browser, if this is done on the same PC as where the WCS is installed, the host name can just be ”localhost”.

If the hardware is not ready, a simulator is available, that allows to test the interface without having a real machine installed. This has also the advantage that the physical time of the movements can be minimized, the simulator can be set to up to 10 times the actually speed, convenient when testing.

Here the trays or boxes 1070, 1105 and 1101 are fetched to the opening using Chrome. The response is displayed in the web browser and in this example successfully received. 

A nice alternative to using an Internet Browser for testing, is the free command line tool “cURL”.

cURL can be downloaded from here: https://curl.haxx.se/

An example of using cURL for fetching boxes:

cURL can also be used to be called from a Host program, if it supports execution of Windows commands, this can in some setup be a simple way of integration.

Simulation

It can be useful to simulate the hardware, before it is available or simply to test in another environment than the final.

Automats

There is a simple simulator available for Automats. This can be used to check the communication, without having the real hardware.

Error simulation

Use the GUI to generate errors with the simulator. Use the command SETERROR.

SetError

SHARK WCS File Interface

SHARK WCS has a simple file interface, allowing controls from the hardware using simple command files. The actually commands depend on the installed drivers. 

For example to fetch tray 15 from a vertical lift, installed with the name ”A1”, drop a file in a predefined folder with this content:

AUTOMAT:A1:GETTRAY 15

If there already is a tray in the opening, SHARK WCS will return that tray first automatically.

The file will be deleted after it is processed.

Configuration of the File Importer

XML Files

Simple interface where files are used to fetch trays to the opening. Drop an XML file in a predefined folder and a tray will be fetched. This can be a practical way in some setups, where the REST protocol can be difficult to implement, but it is easy to write a file.

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <Command>
        <Machine>A1</Machine>
        <Opening>1</Opening>
        <Tray>29</Tray>
    </Command>

The file will be deleted after it is processed.

If there already is a tray in the opening, it will automatically be returned. 

To return a tray in the opening without fetching a new, send a command file with tray number “0”.

Modifying the format

The file is interpreted by a Groovy Script and converted to internal Shark device commands. The script is relative easy to modify to change the file format and add customized functionality.

Sequencer Scripting

SHARK WCS supports scripting in Groovy. Scripting allows extension of the functionality with more advanced control functions not available as standard features and typical customized for the specific installation.

Features:

• All commands, responses to queries and events passes through the script and can be modified.
• 2 timers are available for polling and similar none event based functionality.
• Hot-reload of the script with persistent storage af a key-value map.
• Support for a GUI with start/stop/pause functionality (not available as standard).

Define a script stored in a file

The Sequencer Script supports implementation of sequences of commands, triggered by events like external commands or internal events from hardware modules.

The script is written as a Groovy (Java) class and must implement the Interface dk.logiware.sharkcontrol.scripting.ScriptControllerIF .

The default script looks like this:

import dk.logiware.sharkcontrol.*
import dk.logiware.sharkcontrol.scripting.*
import dk.logiware.sharkcontrol.modules.*
import javax.servlet.ServletException;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;	
import org.eclipse.jetty.server.Request;

public class ScriptController implements ScriptControllerIF {

	/**
	 * 
	 * @param sharkControl Access to the SharkControl main class.
	 * @param systemModule Access to the System Module.
	 * @param sequencer Sequencer object.
	 * @param storage Persistent storage, to be maintained when the script is reloaded.
	 */
	public void init(SharkControlIF sharkControl, SystemModule systemModule, Sequencer sequencer, HashMap<String, Object> storage) {;}
	
	/**
	 * Called before a command is executed.
	 * The handler may choose to execute the command itself or
	 *  
	 * @param cmd
	 * @return The modified command. null will skip the command.
	 */
	public String onCommand(String cmd){
        println "CMD: $cmd";
        return cmd;
    }
	
	/**
	 * Called when an event is generated. The handler may choose to 
	 * handle the event it self or send it the normal way.
	 * 
	 * @param event Event from module.
	 * @return false: proceed the normal way, true: do not send the event.
	 */
	public boolean onEvent(SharkControlEvent event) {
        println "EVENT: " + event.toString();
        return false;
    }
	
	/**
	 * Called before a response is returned. Returns the possible
	 * modified response.
	 * 
	 * @param response
	 * @return New response (or just response).
	 */
	public String onResponse(String response){ 
        return response;
    }
	
    /**
     * Called by the Sequencer Controller UI
     */
	public void onIdle(){;}

    /**
     * Called on errors.
     */
	public void onError(){;}

    /**
     * Called by the Sequencer Controller UI
     * when the start mode is entered.
     */
	public void onStart(){;}

    /**
     * Called by the Sequencer Controller UI
     * when the stop mode is entered.
     */
	public void onStop(){;}

    /**
     * Called by the Sequencer Controller UI
     * when the pause mode is entered.
     */
	public void onPause(){;}
	
	/**
	 * This method is called when the WCS System receives a REST request. The request handler will start calling
	 * this method if define. If it returns true the request is handled by this method else it will be further 
	 * processed by the normal request handler.
	 * 
	 * @param target The URL without the server name eg. /rest/p1 
	 * @param request
	 * @param httpRequest
	 * @param response
	 * @return Return false if this handler is not the target for the command, return true if it has processed the request.
	 * 
	 */
	public boolean onRESTRequest(String target, Request request, HttpServletRequest httpRequest, HttpServletResponse response){
        return false;
    }
	
    /**
     * Will be called every 1 second.
     */
	public void onTimer1() {
        println "ontimer1() called";
    }

    /**
     * Will be called every 60 seconds.
     */
	public void onTimer2(){
        println "ontimer2() called";
    }

}

Error Codes

The WCS Driver might return error codes as a result of various issues.

General codes

Serial Module

Automat specific codes

DIO modules

Location Light

Pick carts

PickToLight

Conveyor

OPC Server

Transport stations

Printers

MODBUS Error