.. comment Copyright 2021-2024 Evolabel AB. All Rights Reserved Author: Henrik Bohre, Anders Ejdeling .. _pdf-index: ########### PDF Support ########### .. warning:: Experimental support only. Subject to change without prior notice! This document describes firmware version 20240904 and later. The printer has native support for printing PDF files (Portable Document Format). The PDF file is transferred and printed in one of two ways: 1. Direct printing to TCP port 9100 or :ref:`LPD ` 2. SFTP transfer followed by JSON-RPC activation *************************** PDF server on TCP port 9100 *************************** ============= Prerequisites ============= Enable the PDF protocol server by navigating to :menuselection:`SETTINGS --> Print Jobs --> Protocol Emulation` and selecting :menuselection:`PDF`. This is only supported on CPU3 SE and CPU3 PE using the operating system *Ubuntu 20.04 LTS* or later. The current operating system can be seen under :menuselection:`SETTINGS --> System --> Software Version`. ================= Raw TCP port 9100 ================= Open a TCP connection to the printer on port 9100 and send the PDF file. When the connection is closed, a new print job will be created with the contents of the PDF. === LPD === Send the PDF as a print job using LPD, see :ref:`example `. .. _pdf-multiple_pages: ============== Multiple pages ============== If the PDF has multiple pages, they will be used for the different sides of a product. Examples: .. csv-table:: :header: Number of Pages in PDF, Labels per Product, Page Numbers Printed 1, 1, 1 1, 2, "1, 1" 2, 2, "1, 2" 2, 3, "1, 2, 2" 3, 2, "1, 2" =========== Limitations =========== * Max file size is 1 MB (1 000 000 bytes). * Up to 10 jobs can be queued in the printer. See :ref:`queuing `. * Only one PDF file can be sent per TCP connection. .. note:: A PDF file will create a job for one product (product count 1). In order to print multiple copies on a batch of products, enable :menuselection:`Force Unlimited Product Count` ****************** SFTP with JSON-RPC ****************** .. attention:: Storing PDF files on the printer is **deprecated**. The recommended way to print PDF files is to send them directly to TCP port 9100, as described above. PDF files must be transferred to the printer using `sftp `_ or a similar mechanism. The file name can then be referenced by a job like below. ================================= SSH File Transfer Protocol (SFTP) ================================= The `user` account can only upload files to the :file:`/home/evolabel/userdata` folder, and is recommended to use for transferring user data files like images, layouts, and so on. In the examples, we have used the :file:`dropzone` folder. This folder is constrained to keep a maximum of 1000 files, or 200 MB. .. note:: The client must check that there is sufficient storage before uploading files. Example: .. code-block:: console sftp> df . Size Used Avail (root) %Capacity 4061540 3682020 153492 379520 90% sftp> df -h . Size Used Avail (root) %Capacity 3.9GB 3.5GB 150MB 371MB 90% If the disk space is filled, the system is not guaranteed to work properly. Linux Example ============= .. code-block:: console $ sftp user@al-12345 user@al-12345's password: Connected to al-12345. sftp> put sscc_123456789012345678.pdf dropzone Uploading sscc_123456789012345678.pdf to /userdata/dropzone/sscc_123456789012345678.pdf sscc_123456789012345678.pdf sftp> ls sscc_123456789012345678.pdf sftp> rm sscc_123456789012345678.pdf sftp> ls sftp> Windows SFTP ============ Prerequisites ------------- 1. PuTTY SFTP (PSFTP.exe) must be present. The PuTTY package (zip or installer) includes PSFTP.exe, or it may be `downloaded `_ as a stand-alone executable. 2. Note the directory where the package is installed. Typically this will be :file:`C:\\Program Files (x86)\\PuTTY`, or wherever the downloaded stand-alone executable is saved. .. note:: `PuTTY `_ is a third party package that is not provided, nor supported, by Evolabel. Using psftp ----------- 1. From the Windows menu :menuselection:`Start --> Run`, type :command:`cmd` to open a command line window. 3. Using the set command, add the path to the :file:`psftp.exe` location: .. code-block:: doscon set PATH="C:\Program Files (x86)"\PuTTY;%PATH% 4. Change to the directory where the files that will be uploaded are located. 5. Use psftp to connect to the printer, using the username *user*. The default password is *auto*, and it can be changed from :menuselection:`SETTINGS --> System --> Access --> SFTP --> Set SFTP Password`. .. code-block:: doscon psftp al-12345 -l user psftp> 6. Use the cd command to change to the desired directory. .. code-block:: doscon psftp> cd dropzone 7. Use the put command to upload the file. Substitute "filename" with the actual name of the file. .. code-block:: doscon psftp> put sscc_123456789012345678.pdf 8. Type quit to exit psftp, once the upload is complete. ====================================== Example: Referencing a stored PDF-file ====================================== When referencing non-native layout files, the ``"layout"`` attribute shall be an object containing ``"uri"``, and ``"content-type"``. Example request: .. code-block:: json { "method": "jobs.put", "params": { "pages": [ { "layout": { "uri": "file://dropzone/sscc_123456789012345678.pdf", "content-type": "application/pdf" }, "copies": 1 } ] }, "id": 0, "jsonrpc": "2.0" } Example response from a successful PDF job creation: .. code-block:: json { "id": 0, "jsonrpc": "2.0", "result": { "created": "2021-08-25T12:59:18.782614+02:00", "extendable": false, "pages": [ { "copies": 1, "layout": { "uri": "file://dropzone/sscc_123456789012345678.pdf", "content-type": "application/pdf" } } ], "product_count": -1, "product_matching": false, "replace_current": false, "reprintable": true, "required_variables": [], "usage_count": 0, "variables": {} } } Example request asking not to include the job in the response: .. code-block:: json { "method": "jobs.put", "params": { "pages": [ { "layout": { "uri": "file://dropzone/sscc_123456789012345678.pdf", "content-type": "application/pdf" }, "copies": 1 } ], "include_job": false }, "id": 0, "jsonrpc": "2.0" } Example response without the job: .. code-block:: json { "id": 0, "jsonrpc": "2.0", "result": null } Example error response when referencing a non-existing file: .. code-block:: json { "error": { "code": -32602, "data": "Resource unknown: 'file://dropzone/sscc_123456789012345678.pdf'", "message": "Invalid params" }, "id": 0, "jsonrpc": "2.0" } Example request with two pages: .. note:: Using a PDF with multiple pages and also specifying multiple pages in the ``"pages"`` array will give unexpected results. See above on how :ref:`pdf-multiple_pages` from the same PDF document are used. .. code-block:: json { "method": "jobs.put", "params": { "pages": [ { "layout": { "uri": "file://dropzone/sscc_123456789012345678.pdf", "content-type": "application/pdf" }, "copies": 1 }, { "layout": { "uri": "file://dropzone/sscc_123456789012345678_2.pdf", "content-type": "application/pdf" }, "copies": 1 } ], "include_job": false }, "id": 0, "jsonrpc": "2.0" }