Created Date: 08 Oct, 2020 16:42
Last Modifed Date: 29 Nov, 2021 14:48


We recommend that you drive ScreenPro Direct via the C-compatible API. See Using the ScreenPro Direct API for more details.

A low-level way of driving ScreenPro Direct is via the TCP/IP socket interface. This page contains an overview of how the interface is structured, as well as information on all the valid commands and their individual responses.

Socket interface basics

ScreenPro Direct exposes two sockets that clients can use to drive the application: the command socket and the status socket.

  • The command socket allows clients to control the print run workflow; images to be processed are specified via this socket and print run aborts are issued through here.
  • The command socket is required; a port number must be specified in the configuration file and at least one client is required to connect to it during startup.

The Status socket provides a parallel line of communication (alongside the command socket) with which to query hardware status and job status. This socket is optional.

Application cycle

Once the startup sequence is complete, ScreenPro Direct is in an idle state. Sending a START_PRINT_RUN command starts a Print Run, a processing loop where images can be sent in a first-in first-out (FIFO) manner to the hardware. When all images have been submitted, an END_PRINT_RUN command closes the Print Run to new submissions and allows the processing to finish. When prompted, an IDLE command returns to the idle state.

Issue an ABORT command at any time during a Print Run to return ScreenPro Direct to the idle state; no additional IDLE command is required in this case.

Example

  1. Send START_PRINT_RUN, which starts a Print Run in ScreenPro Direct.
  2. Send SEND_IMAGE,file1.tif,10.
    1. Ten copies of file1.tif (found relative to ScreenPro Direct's current working directory) are queued into the ScreenPro Direct pipeline.
    2. Processing begins immediately.
  3. Send SEND_BLANK,1920,1080,8.
    1. A blank page at 8bpp with dimensions 1920x1080 is added to the pipeline, which creates a gap in the output of 1080 pixels.
  4. Send SEND_IMAGE,file2.tif,10, in which 10 copies of file2.tif are queued.
  5. Send END_PRINT_RUN.
    1. At this point, there are no more images to send, so close the Print Run to new submissions.
    2. Processing continues until the hardware has taken all the output image data.
  6. You receive "Waiting for IDLE Command" message.
    1. The hardware has received all data.
    2. The interface remains open for further status reporting.
  7. Send IDLE.
    1. If configured, the hardware is released.
    2. ScreenPro Direct returns to idle.
  8. Repeat the cycle from Step 1.

Sockets in detail

Configuration

ScreenPro Direct's sockets are configured using options in the Socket  section of the configuration file.

Option nameTypeDescription
CommandSocketPort
IntegerPort Number that ScreenPro Direct runs the command socket on. The port is listened on during application startup.
CommandSocketTimeout
IntegerThe number of milliseconds the command socket remains active with no traffic. If set to 0, the socket waits indefinitely.
NumberOfCommandSocketConnections
Integer

The number of command socket clients that ScreenPro Direct waits for on startup.

Note: There must always be at least one connection to the command socket for ScreenPro Direct to run. If set to 0, it is promoted to 1 after the configuration file is read.

NumberOfStatusSocketConnections
Integer

The number of status socket clients that ScreenPro Direct waits for on startup.

StatusSocketPort
IntegerPort Number that ScreenPro Direct runs the status socket on. The port is listened on during application startup (unless NumberOfStatusSocketConnections is 0).
StatusSocketTimeout
IntegerThe number of milliseconds the status socket remains active with no traffic. If set to 0, the socket waits indefinitely.

Example

"Socket": {
		"CommandSocketPort": 9000,
		"NumberOfCommandSocketConnections": 1,
		"CommandSocketTimeout": 5000,
		"StatusSocketPort": 9001,
		"NumberOfStatusSocketConnections": 1,
		"StatusSocketTimeout": 5000
}
CODE

Startup sequence

On startup, ScreenPro Direct prompt you to initiate connections to the sockets as specified in the configuration file.

  1. The ScreenPro Direct console displays the following message: "Awaiting Command socket connection : Port <number>". ScreenPro Direct holds here until the expected number of clients (specified in the configuration file) are connected. Once all connections are made, the command socket broadcasts "COMMAND_SOCKET_READY\n"
  2. If you specify Status socket connections in the configuration file, the ScreenPro Direct console displays the following: "Awaiting Status socket connection : Port <number>". ScreenPro Direct holds here until the expected number of clients (specified in the configuration file) are connected. Once all connections are made, the status socket broadcasts "STATUS_SOCKET_READY\n".
  3. ScreenPro Direct then waits for your ScreenPro Direct password (to unlock the licence specified in the configuration file) to be set. The Command socket sends "Waiting for ScreenPro Direct Password\n". On receipt of a valid SET_PASSWORD command, the command socket sends "ScreenPro Direct Password Accepted \n".
  4. When ScreenPro Direct is ready to begin processing socket commands, the following message broadcasts on both command and status sockets: "SCREENPRODIRECT_READY\n".


Any commands sent to either socket are cleared at this point.

When the application is shutting down (following an EXIT command), both command and status sockets receive "SHUTTING DOWN\n".

Socket messages

Both the command and status sockets are completely asynchronous and function on a request-and-response basis.

A newline "\n" character is used as a delimiter, so all responses end with a newline.

ScreenPro Direct acknowledges the receipt of any command (valid or invalid) by responding with "SOCKET_RECEIVED\n". The calling application waits for the "SOCKET_RECEIVED\n" message, then for any responses the submitted command can return (detailed below).

On receipt of an unknown command, ScreenPro Direct returns "Unknown Command\n".

For synchronization purposes, do not send commands without receiving all responses from the previous command. Failure to do so will result in undefined behavior.

All command arguments are comma separated. Boolean arguments are expected as 0 for false and 1 for true.

Command socket reference

Name/description

Arguments

Success Response

Failure Response

Prompt

SET_PASSWORD

Sets the password to use with the license given in the configuration file. The password is validated when the print run begins.

Note: From ScreenPro Direct v3.6.0, the SET_PASSWORD socket interface command replaces the 
SCREENPRO_PASSWORD socket interface command. 

License Password

“ScreenPro Direct Password Accepted\n”


"ScreenPro Direct Password Incorrect\n"

Waiting for ScreenPro Direct Password\n

START_PRINT_RUN

Enters the ScreenPro Direct processing loop, allowing images to be submitted.

NONE

“PRINT_RUN_START\n”

NONE

NONE

SEND_IMAGE

Submits a supported file to be processed. Paths can be absolute or relative to ScreenPro Direct’s working directory.

1: File path, Copy count

2: File path, Copy count, Plane

1: “Queued <file path> with <copy count> copies\n”

2: “Queued <file path> with <copy count> copies on plane <plane>\n”

A: “SEND_IMAGE failed, <file path> does not exist\n”

B: “SEND_IMAGE failed, not running\n”

C: “SEND_IMAGE command error\n”

NONE

SEND_BG_IMAGE

Note: From ScreenPro Direct v3.6.0, SEND_BG_IMAGE now requires a plane number and a boolean to denote whether a submission is a final plane or not. 

Submits a supported file to be processed as a background (static) image.

(Note: Support for this is hardware dependent.)

Note: From ScreenPro Direct v3.6.0, SEND_PL_IMAGE and SEND_BG_IMAGE use PCMD_BIGIMAGE if connected to Meteor; if outputting to Meteor, update the HeaderReserve field in the JSON config to 28.

1: File path, Copy count, Plane, Final plane (boolean)

1: “Queued <file path> as a background image with <copy count> copies\n”

2: “Queued <file path> as a background image with <copy count> copies on plane <plane>\n”

A: SEND_BG_IMAGE failed, not running\n”

B: “SEND_BG_IMAGE command error\n”

C: “SEND_BG_IMAGE failed, <file path> does not exist\n”

NONE

SEND_PL_IMAGE

Submits a supported file to be processed as a preloaded (static) image.

(Note: Support for this is hardware dependent.)

Note: From ScreenPro Direct v3.6.0, SEND_PL_IMAGE and SEND_BG_IMAGE use PCMD_BIGIMAGE if connected to Meteor; if outputting to Meteor, update the HeaderReserve field in the JSON config to 28.

1: File path, Copy count, Plane, Final plane (boolean)

1: “Queued <file path> as a background image with <copy count> copies on plane <plane>\n”

 

A: SEND_BG_IMAGE failed, not running\n”

B: “SEND_BG_IMAGE command error\n”

C: “SEND_BG_IMAGE failed, <file path> does not exist\n”


SEND_BLANK

Submits a block of empty (zeroed) raster data into the pipeline. Use this if you have a blank separation and don’t want to hold an empty image on disk.

1: Width, Height, BPP

 

2: Width, Height, BPP, Plane

1: “Sent blank data : <width> x <height> at <bpp>\n”

 2: “Sent blank data : <width> x <height> at <bpp> on plane <plane>\n”

A: SEND_BLANK failed, not running\n

B: SEND_BLANK command error\n

NONE

END_PRINT_RUN

Signals that no more images are part of the current print run.

No more images can be submitted until a new print run begins, via the idle state.

NONE

“END_PRINT_RUN submitted\n”

END_PRINT_RUN failed, not running\n

NONE

IDLE

Returns to the ScreenPro Direct idle state. Hardware is released (if configured) and a new print run can begin.

NONE

A: “PRINT_RUN_COMPLETE\n”

B: “PRINT_RUN_ERROR\n”

IDLE failed, already idle\n

Waiting for IDLE command\n

ABORT

Stops the print run as soon as possible and return to idle state.

NONE

“PRINT_RUN_ERROR\n”

NONE

NONE

EXIT

Terminates the ScreenPro Direct application.

If a print run is in progress, exit occurs on the return to idle.

Note: No other command can intercept an EXIT command.

NONE

NONE

NONE

NONE

PAUSE

Prevents data from being transferred from the output stage of the pipeline.

Use this if you want to load up the pipeline queues before beginning to output.

NONE

NONE

NONE

NONE

RESUME

Restarts output flow, following a PAUSE.

NONE

NONE

NONE

NONE

PD

Sets whether the PD signal is enabled. 

(Note: Support for this is hardware dependent.)

State (Boolean)

1: “PD set to enabled\n”

2: “PD set to disabled\n”

“PD command error\n”

NONE

SET_SIGNAL

Sets a hardware signal state. 
(Note: Support for this is hardware dependent.)

Signal id, Signal value, Controller number, Head number

“Set signal\n”

A: “Failed to set signal\n”

B: “SET_SIGNAL command error\n”

NONE

SET_PARAM

Sets a hardware parameter.
(Note: Support for this is hardware dependent.)

Param id, Param value, Controller number, Head number

“Set parameter\n”

A: “Failed to set parameter\n”

B: “SET_PARAM command error\n”

NONE

DISCONNECT

When in the idle state, both socket connections are released and you are prompted (via the ScreenPro Direct console) to reconnect.

NONE

“Set Disconnect\n”

“Disconnect failed\n”

NONE

SET_CROSSWEB_OFFSET

Applies an offset across the web.

Offset value,

Plane

“CrossWebOffset applied\n”

A: “Failed to set CrossWebOffset\n”

B: “SET_CROSSWEB_OFFSET command error\n”

NONE

HEARTBEAT

A NOP you can send that keeps a socket open if a timeout is specified in the ini file.

NONE

NONE

NONE

NONE

SET_HEAD_POWER

Sets the head power state. 

(Note: Support for this is hardware dependent.)

State (Boolean)

1: “Turned on head power\n”

2: “Turned off head power\n”

A: “Failed to turn on head power\n”

B: “Failed to turn off head power\n”

C: “SET_HEAD_POWER command error”

NONE

VERSION

Gets the ScreenPro Direct version number.

NONE

“<VERSION>3.0.0.0\n”

NONE

NONE

PRINTFLAT_LICENCE

Sets the OEM Id for PrintFlat.

If the details are incorrect and do not match the screen to be used, ScreenPro Direct outputs SP_LICENSE_ERROR when you attempt to start a Print Run. Shut down ScreenPro Direct and provide correct PrintFlat license details upon restart. 

OEM_ID

 

“PRINTFLAT_LICENCE set\n”

“PRINTFLAT_LICENCE command error\n”

NONE

CANCEL

Cancels a job id from being processed.

JobId

"Cancelled JobID <id>"

 

A:Failed to cancel JobID <id>"

B: "Badly formatted CANCEL command"

NONE

SET_PARAM_EX

Sets an extension hardware parameter.

(Note: Support for this is hardware dependent.)

ParamID, Controller Number, Head Number, Jetting Assembly Number, Value

“Set parameter\n”

A: “Failed to set parameter\n”

B: “SET_PARAM command error\n”

NONE

RUN_PLUGIN_COMMAND

Runs plugin defined commands and returns plugin defined results.

Use of this command requires knowledge of plugin creation.

Target plugin (this must match the plugin name defined in getPluginName()),

Anything thereafter is specific to the plugin. It will be delivered to the plugin so it can parse/process.


A:"RUN_PLUGIN_COMMAND,SUCCESS,NO_RESULT\n"

B:"RUN_PLUGIN_COMMAND,SUCCESS,<custom result>\n"


A:"RUN_PLUGIN_COMMAND,FAIL,UNKNOWN_PLUGIN\n"

B:"RUN_PLUGIN_COMMAND,FAIL,EMPTY_PLUGIN\n"

C:"RUN_PLUGIN_COMMAND,FAIL,EMPTY_COMMAND\n"

D:"RUN_PLUGIN_COMMAND,FAIL,NO_RESULT\n"

E:"RUN_PLUGIN_COMMAND,FAIL,<custom result>\n"

NONE

GET_LICENSE_VARIANT

Gets the variant of the LE license used to run ScreenPro Direct. If password has not been successfully set yet, returns 0. 

NONE

“LICENSE_VARIANT_VALUE,<value>\n”

<value>:

  • 0: Unknown;
  • 1: Standard;
  • 2: High Data Rate;
  • 3: Ultra High Data Rate;
  • 4: Ultra High Data Rate (None plugin only)

NONE

NONE

Asynchronous events

There are various events that ScreenPro Direct may push to clients via the command socket. These may occur at any time (including during a client transaction).

NameFormatDescription
JOB_STARTEDJOB_STARTED,<JobID>,<ImageCount>\n

The Job with the given JobID has started processing with ImageCount pages.

When using the Shared Memory Interface, ImageCount will be 0.

When submitting individual TIFs, ImageCount will be 1. 

When submitting an XML file, ImageCount will be equal to the number of TIFs listed in the XML file.

JOB_COMPLETEJOB_COMPLETE,<JobID>\nThe Job with the given JobID has successfully completed processing.
QueueErrorQueueError:JobId=<JobID>,ImageId=<ImageID>,PlaneId=<PlaneID>,Plugin=<PluginName>\nAn error occurred while processing the given separation in the given plugin. A PRINT_RUN_ERROR event usually follows.
CancelledCancelled JobID <JobID>\nThe Job with the given JobID has been cancelled.
PRINT_RUN_STARTPRINT_RUN_START\nThe Print Run has started.
PRINT_RUN_COMPLETEPRINT_RUN_COMPLETE\nThe Print Run has completed successfully.
PRINT_RUN_ERRORPRINT_RUN_ERROR\nThe Print Run has stopped unsuccessfully.

Status socket

Name/description

Arguments

Success response

Failure response

STATUS                             

Returns an output-specific status packet, as a string.

NONE

“<STATUS>a,b,c,d,e…\n”

“<STATUS>NO_DATA\n”

STATUS_RAW

Returns an output-specific status packet, as raw bytes.

NONE

“<STATUS_RAW>……\n”

“<STATUS_RAW>NO_DATA\n”

HEAD_STATUS

Returns a hardware-specific head status packet, as a string.

Controller, Head number

“<HEAD_STATUS, controller,head>

a,b,c,d,e\n”

A: “<HEAD_STATUS,controller, head>NO_DATA\n”

B: “HEAD_STATUS command error\n”

HEAD_STATUS_RAW

Returns a hardware-specific head status packet, as raw bytes.

Controller, Head number

“<HEAD_STATUS_RAW, controller, head>……\n”

A: “<HEAD_STATUS_RAW, controller,head>NO_DATA\n”

B: “HEAD_STATUS_RAW command error\n”

HEARTBEAT

A NOP you can send that keeps a socket open if a timeout is specified in the config file.

NONE

NONE

NONE

DEBUG_LOG

Outputs a hardware-specific debug log.

NONE

“<DEBUG_LOG>message\n”

NONE

BUFFER
Returns the percentage level of the hardware buffer.

NONE

“<BUFFER>level\n”

NONE

HEAD_EEPROM

Returns hardware-dependent EEPROM data, as a string.

Controller, Head number

“<HEAD_EEPROM, controller,head>data\n”

A: <HEAD_EEPROM,controller,head>NO_DATA\n

B: HEAD_EEPROM command error\n

PRINT_RUN_STATUS

Returns information about the current print run.

NONE

“<PRINT_RUN_STATUS>

Jobs submitted, jobs complete, current job id, current page id, current jobs page count, average throughput\n”

NONE

THROUGHPUT

Returns the average output throughput in MB/s

NONE

“<THROUGHPUT>value\n”


Asynchronous events

ScreenPro Direct may push various events to clients via the command socket. These may occur at any time (including during a client transaction).

NameFormatDescription
PRINT_RUN_STARTPRINT_RUN_START\nThe Print Run has started.
PRINT_RUN_COMPLETEPRINT_RUN_COMPLETE\nThe Print Run has completed successfully.
PRINT_RUN_ERRORPRINT_RUN_ERROR\nThe Print Run has stopped unsuccessfully.