2. Socket interface
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
- Send START_PRINT_RUN, which starts a Print Run in ScreenPro Direct.
- Send SEND_IMAGE,file1.tif,10.
- Ten copies of file1.tif (found relative to ScreenPro Direct's current working directory) are queued into the ScreenPro Direct pipeline.
- Processing begins immediately.
- Send SEND_BLANK,1920,1080,8.
- A blank page at 8bpp with dimensions 1920x1080 is added to the pipeline, which creates a gap in the output of 1080 pixels.
- Send SEND_IMAGE,file2.tif,10, in which 10 copies of file2.tif are queued.
- Send END_PRINT_RUN.
- At this point, there are no more images to send, so close the Print Run to new submissions.
- Processing continues until the hardware has taken all the output image data.
- You receive "Waiting for IDLE Command" message.
- The hardware has received all data.
- The interface remains open for further status reporting.
- Send IDLE.
- If configured, the hardware is released.
- ScreenPro Direct returns to idle.
- 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 name | Type | Description |
|---|---|---|
CommandSocketPort | Integer | Port Number that ScreenPro Direct runs the command socket on. The port is listened on during application startup. |
CommandSocketTimeout | Integer | The 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 |
NumberOfStatusSocketConnections | Integer | The number of status socket clients that ScreenPro Direct waits for on startup. |
StatusSocketPort | Integer | Port Number that ScreenPro Direct runs the status socket on. The port is listened on during application startup (unless NumberOfStatusSocketConnections is 0). |
StatusSocketTimeout | Integer | The 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
}Startup sequence
On startup, ScreenPro Direct prompt you to initiate connections to the sockets as specified in the configuration file.
- 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"
- 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".
- 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".
- 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 | 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 | 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 | 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. | 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. | 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>:
| 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).
| Name | Format | Description |
|---|---|---|
| JOB_STARTED | JOB_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_COMPLETE | JOB_COMPLETE,<JobID>\n | The Job with the given JobID has successfully completed processing. |
| QueueError | QueueError:JobId=<JobID>,ImageId=<ImageID>,PlaneId=<PlaneID>,Plugin=<PluginName>\n | An error occurred while processing the given separation in the given plugin. A PRINT_RUN_ERROR event usually follows. |
| Cancelled | Cancelled JobID <JobID>\n | The Job with the given JobID has been cancelled. |
| PRINT_RUN_START | PRINT_RUN_START\n | The Print Run has started. |
| PRINT_RUN_COMPLETE | PRINT_RUN_COMPLETE\n | The Print Run has completed successfully. |
| PRINT_RUN_ERROR | PRINT_RUN_ERROR\n | The 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 | 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).
| Name | Format | Description |
|---|---|---|
| PRINT_RUN_START | PRINT_RUN_START\n | The Print Run has started. |
| PRINT_RUN_COMPLETE | PRINT_RUN_COMPLETE\n | The Print Run has completed successfully. |
| PRINT_RUN_ERROR | PRINT_RUN_ERROR\n | The Print Run has stopped unsuccessfully. |