SHARK WCS Driver#

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.

Command Line Argument	Description
-regfolder	Path to a folder where the data files will be stored (if running without a database). The data file is a jason file.
-nodb	No Database. The configuration is not stored in a Microsoft SQL Server, but in a simple data file.
-ui	Show the graphical user interface
-ui	Show the user interface for one or more modules. Separated by ",". Normally the module name must be prefix by the type of module eg. "AUTOMAT", but if nothing is specified, AUTOMAT is the default type. If the module supports multiple openings, the opening number can be specified with an - extension, eg. Automat A1 opening 2 is : AUTOMAT:A2-1
-connect	Used in combination with the -ui parameter to specify connection to an external service. If this argument is omitted, the WCS Driver will run embedded in the user interface as one application. The service can then not be used.
-locale	Language localisation. Default is "en_GB". Alternatives: de_DE

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:

Element	Function
host	Name of the PC/Server hosting the SHARK WCS
port	Port number for the socket. Default is 8095.
device	Define this is a basic low level command, addressing the device directly.
type	Type of the module. Possible values are:
automat/system/labelprinter/pointer/pickbylight/conveyor
module	Name of the module. Typical name could be “E1”.
command	The actually command
parameter	There can be zero or more parameters for the command. All parameters have the form <name>=<value> and must be separated by “&”.

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

Parameter	Values	Required	Notes
Error Code	1/2/3	Yes	1: Emergency stop, 2: Goods height error, 3: General error
Now	true/false	No	If true the error will be effectively immediately (default), else first when next command runs

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#

Description	Error Code
OK	1
BUSY	2
ERROR_SYNTAX_ERROR	1000
ERROR_MODULE_LOAD	1001
ERROR_TRAY_DOES_NOT_EXIST	1002
SOCKET_CONNECTION_RESET	1003
FUNCTION_NOT_IMPLEMENTED	1004
TELEGRAM_FORMAT_ERROR	1005
TELEGRAM_CHECKSUM_ERROR	1006
ARGUMENT_ERROR	1007
CONTROLLER_NOT_INITIALISED	1008
FUNCTION_NOT_SUPPORTED	1009
READ_TIMEOUT	1010
LOADING_BEANSHELL_INTERPRETER	1011
SOFTWARE_ERROR	1012
SHARK_CONTROL_STARTED	1013
ERROR_COMMUNICATION	1014
INTERNAL_PROGRAM_ERROR	1015
ERROR_CALLING_STORED_PROCEDURE	1016
LONG_EXECUTION_TIME	1017
ERROR	1018
RESTART_ERROR	1019
RESTARTING	1020
FOUND_INACTIVE_CLIENT	1021
CONFIGURATION_ERROR	1022
INITIALIZATION_ERROR	1023
SOAP_FORMAT_ERROR	1024
SOAP_EXECUTE_ERROR	1025
ERROR_MESSAGES_SUPPRESSED	1026
CONNECTED_NOT_INITIALIZED	1027
BUSY_INITIALIZING	1028
LIGHT_CURTAIN_INTERRUPTED	1029
AUTOMAT_TILT_ERROR	1031

Serial Module#

Description	Error Code
ILLEGAL_GATEWAY	1100
OPEN_ERROR	1101
READ_ERROR	1102
WRITE_ERROR	1103
GENERAL_ERROR	1104
CONNECTION_ERROR	1105
READ_WRITE_RETRY	1106
PORT_ALREADY_IN_USE	1107
NOT_INITIALIZED	1108
PING_TO_GATEWAY_FAILED	1109

Automat specific codes#

Description	Error Code
PLC_RESPONSE_FRAME_FORMAT_ERROR	1200
PLC_RESPONSE_FRAME_COMPLETION_ERROR	1201
PLC_RESPONSE_FRAME_CHECKSUM_ERROR	1202
AUTOMAT_IS_IN_MANUEL_MODE	1203
GOODS_HEIGH_EXCEEDED	1204
AUTOMAT_ERROR	1205
TRAY_DOES_NOT_EXIST	1206
NO_TRAY_AT_ELEVATOR	1207
EMERGENCY_STOP_ACTIVATED	1208
LIGHT_DETECTOR_FRONT_BLOCKED	1209
LIGHT_DETECTOR_BACK_BLOCKED	1210
TRAY_NOT_IN_POSITION	1211
MOTOR_ERROR_AT_TOP_DETECTOR	1212
MOTOR_ERROR_AT_BOTTOM_DETECTOR	1213
MOTOR_ZERO_NOT_FOUND	1214
MOTOR_ZERO_ADJUST_REQUIRED	1215
MOTOR_SERVO_LOCK_ERROR	1216
MOTOR_POSITION_ERROR	1217
ERROR_READING_AUTOMAT_CONFIGURATION	1218
LIFT_FREQ_TRANSFORMER_ERROR	1219
LIFT_FREQ_TRANSFORMER_OVERLOAD	1220
CHAIN_FREQ_TRANSFORMER_ERROR	1221
CHAIN_FREQ_TRANSFORMER_OVERLOAD	1222
AUTOMAT_LOADING_SUBSYSTEM	1223
WRONG_TRAY_AT_GATE	1224
TIMEOUT_WAITING_FOR_TRAY	1225
PLC_ORDER_STACK_NOT_EMPTY	1226
AUTOMAT_INITIALIZED	1227
AUTOMAT_COMMUNICATION_REESTABLIHED	1228
AUTOMAT_THREAD_DEAD	1229
AUTOMAT_STATUS_THREAD_INTERRUPTED	1230
AUTOMAT_STATUS_LOOP_UNKNOWN_ERROR	1231
UNKNOWN_TELEGRAM_RECEIVED	1232
SECURITY_VIOLATION	1233
POLLING_MODE_ENABELD	1234
GOODS_HEIGHT_CHANGED	1235
TRAY_INSTALLED	1236
ELEVATOR_POSITION_ERROR	1237
POINTER_POSITION_ERROR	1238
POINTER2_POSITION_ERROR	1239
AUTOMAT_DEFAULT_TRAY_CONFIG	1240
AUTOMAT_CHANGED_TRAY_CONFIG	1241
AUTOMAT_NO_SPACE	1242
MAX_GOODS_HEIGHT_EXCEEDED	1243
MAX_WEIGHT_EXCEEDED	1244
GOODS_OVERHANG_EXCEEDED	1245
TRAY_MOVED	1250
ERROR_MOVING_TRAY	1251
GET_TRAY	1252
TRAY_PACK	1253
TRAY_MOVE	1254
TRAY_INSTALL	1255
POSITION_DOES_NOT_EXIST	1256
TRAY_PACK_BEGIN	1257
TRAY_PACK_END	1258
TRAY_PACK_MOVED_ONE	1259
TRAY_PACK_ERROR	1260
TRAY_PACK_AUTO_INITIALIZED	1261
TRAY_MOVE_ERROR	1262
GATE_IS_BLOCKED	1263
TRAY_BENDING	1264
TRAY_ALREADY_EXIST	1265
SLL_NOT_INITIALIZED	1266
PLC_WARNING	1267
INCOMPATIBLE_PLC_FIRMWARE	1268
ROBOT_IN_TRAY	1269
ALREADY_A_TRAY_AT_ROBOT_GATE	1270
LIGHT_NOT_INITIALIZED	1271
LIGHT_CURTAIN_BROKEN	1272
SAFETY_STRIP_ACTIVATED	1273
EXTRACTOR_ERROR	1274
WAITING_FOR_CONTINUE	1275
TRAY_ON_ELEVATOR	1276
TRAY_RETURNED_TO_RACK	1277

DIO modules#

Description	Error Code
DIO_COMMUNICATION_ERROR	1400
DIO_ERROR_IN_COMMAND	1401
DIO_ILLEGAL_VALUE	1402
DIO_CONFIRM_KEY_POLLING_STOPPED	1403
DIO_PARAMETER_ERROR	1404
DIO_EXECUTE_ERROR	1405
DIO_ERROR_CALLING_STORED_PROCEDURE	1406
DIO_UNEXPECTED_RESPONSE	1407

Location Light#

Description	Error Code
LIGHT_LOADING_MODULE	1500
LIGHT_OPEN_COMMUNICATION	1501
LIGHT_PARAMETER_ERROR	1502
LIGHT_CMD_FAILED	1503
LIGHT_SKIPPED_WRITE	1504
LIGHT_DMX_CONTROLLER_ERROR	1505
LIGHT_TURN_ON	1506
LIGHT_TURN_OFF	1507
LIGHT_ERROR	1508

Pick carts#

Description	Error Code
PICKCART_LOADING_MODULE	1600
PICKCART_OPEN_COMMUNICATION	1601

PickToLight#

Description	Error Code
PICKTOLIGHT_LOADING_MODULE	1700
PICKLIGHT_PARAMETER_ERROR	1701
PICKTOLIGHT_COMM_ERROR	1702
PICKTOLIGHT_CONTROLLER_ERROR	1703
PICKTOLIGHT_TELEGRAM_TOO_OLD	1704
PICKTOLIGHT_UNDEFINED_MODULE_FOUND	1705

Conveyor#

Description	Error Code
CONVEYOR_TELEGRAM_PROCESSING_ERROR	1800
CONVEYOR_ERROR_WRITING_TELEGRAM	1801
CONVEYOR_UNICONTROL_CONNECTED	1802
CONVEYOR_UNICONTROL_LOST_CONNECTION	1803
CONVEYOR_LOAD_ERROR	1804
CONVEYOR_UNICONTROL_WAITING_CONNECTION	1805
CONVEYOR_UNICONTROL_INITIALIZING	1806
CONVEYOR_UNICONTROL_INIT_ERROR	1807
CONVEYOR_POSITION_NOT_DEFINED	1808
CONVEYOR_MODULE_NOT_DEFINED	1809
CONVEYOR_AUTOMAT_DEFINED_WITH_BAD_POSITION	1810
CONVEYOR_BOX_NEVER_ARRIVED	1811
CONVEYOR_TRANSPORT_REQUEST	1812
CONVEYOR_TRANSPORT_ERROR	1813
CONVEYOR_BOX_PUSH	1814
CONVEYOR_KEY_PRESS	1815
CONVEYOR_UNICONTROL_STOPPED_WAITING	1816
CONVEYOR_KEY_PRESS_ERROR	1816
CONVEYOR_NOT_READY	1817
CONVEYOR_ERROR	1818
CONVEYOR_MISSING_ACKNOWLEDGE	1819

OPC Server#

Description	Error Code
OPC_CONFIGURATION_ERROR	1900
OPC_READ_ERROR	1901
OPC_WRITE_ERROR	1902
OPC_OPEN_ERROR	1903

Transport stations#

Description	Error Code
TRANSPORT_TIMEOUT	2000
TRANSPORT_ERROR	2001
TRANSPORT_BUSY	2002
NEXT_STATION_NOT_READY	2003
SECURITY_ERROR	2004

Printers#

Description	Error Code
PRINTER_ERROR	2100

MODBUS Error#

Description	Error Code
MODBUS_ERROR	2200

ROBOT#

Error codes from SHARK WCS or status code returned from the Robot to confirm a job.

Error Code	Description
2750	ROBOT_ERROR. This is general error status.
2751	ROBOT_CANNOT_PICK_FROM_LOCATION. Status set by the robot, when it is not able to pick from a location. Typical the location will be blocked.
2752	ROBOT_DROPPED_IN_TRAY. Status set by the robot, when an item is accidential dropped in a tray.
2753	ROBOT_DROPPED_ON_FLOOR. Status set by the robot, when an item is accidential dropped on the floor.
2754