LarkTool Command-Line Utility

Version: 01.00.20
Author: HamSlices
License: GNU General Public License v3.0

LarkTool.exe is a powerful command-line interface for the Lark Print Engine. It provides a complete suite of tools for printing, device management, detailed configuration, diagnostics, and firmware updates.

What This Tool Can Do

• Versatile Printing: Print images (.png, .jpg, etc.), multi-page PDFs, and plain text (.txt) files directly from the command line. Now with a high-contrast mode for clearer PDF prints.
• Asynchronous Operations: Perform print jobs and firmware updates asynchronously, allowing you to monitor real-time status without locking the command line.
• Powerful Print Profiles: Use pre-configured .ini files for common tasks (e.g., receipts, photos, labels) with a single --profile command, eliminating the need to type multiple options.
• Advanced Image Manipulation: On-the-fly image processing including dithering (Threshold, Bayer, Floyd-Steinberg), rotation, scaling, flipping, padding, brightness, and contrast adjustment.
• Automated Finishing Actions: Automatically add cutoff lines (dashed, dotted, triangle) and feed media after a print job for easy tearing and separation.
• Full Device Configuration: Query and set all hardware parameters like speed, motor current, microstepping, and print darkness.
• Text Rendering Engine: Print raw text strings or documents with custom TrueType/OpenType fonts, font sizes, alignment (left, center, right), and automatic word wrapping. Now supports processing of escape characters (like \n, \t) and automatic line numbering.
• Generate Any File Output: Create a file representation of any print job, with all transformations applied, without needing the hardware connected. The output format is determined by the file extension:
  • Image Preview: Save a visual preview as a .png, .jpg, or .bmp file.
  • Raw Data: Save the final, processed 1-bit monochrome data as a .bin, .raw, or .data file for debugging.
• Comprehensive Diagnostics: Instantly check device status, monitor status in real-time, read the CPU temperature, view the persistent fault log, retrieve lifetime statistics, run diagnostic prints, and verify firmware integrity with a hash check.
• Robust Firmware Updates: A simple, one-command (--dfu-update) process to update your device's firmware using standard Intel HEX files. Advanced manual control over DFU erase and program steps is also available.

Installation

1. Place LarkTool.exe in a folder of your choice.
2. Ensure all required DLL files (e.g., Lark.dll, libusbK.dll, poppler.dll, etc.) are in the same directory as LarkTool.exe.
3. Create a profiles.ini file in the same directory to define your print profiles. A sample file with recommended profiles is provided.
4. For firmware updates (DFU commands), you may need to install the libusbK driver for the device when it's in DFU mode. This can be done easily with a tool like Zadig.

Building from Source

This process builds both the Lark C++ API and the LarkTool executable from source in one step.

Prerequisites

• Windows OS
• Git
• Visual Studio 2022 with the C++ Desktop Development workload.

Build Steps

1. Clone the Repository with Submodules

Clone the repository using the --recurse-submodules flag. This is a crucial step that automatically downloads the required Lark C++ API source code into the correct directory.

git clone --recurse-submodules https://github.com/hamslices/LarkTool.git
cd LarkTool

2. Bootstrap vcpkg

The Lark API submodule uses vcpkg to manage its own dependencies (like FreeType, Poppler, etc.). You must run the bootstrap script from within the API's directory. This only needs to be done once per clone.

cd LarkAPI
.\vcpkg\bootstrap-vcpkg.bat
cd ..

3. Build the Solution

Open the Visual Studio solution (LarkTool.sln). The solution is already configured with the correct project dependencies. Simply build the solution in the desired configuration (e.g., Release).

Visual Studio will automatically perform the following steps in order:

1. Install the required libraries for the API using vcpkg.
2. Build the Lark C++ API project (Lark.lib and Lark.dll).
3. Build the LarkTool project, automatically linking it against the newly built API.

4. Run the Executable

The final LarkTool.exe and all its required DLLs (Lark.dll, poppler.dll, etc.) will be placed together in the build output directory (e.g., x64\Release). You can run the executable directly from that folder.

How to Use

Open a command prompt (cmd.exe) or PowerShell, navigate (cd) to the folder containing LarkTool.exe, and run commands.

• To see the full list of all commands and options, run:

  LarkTool.exe --help

• To check the tool and API versions, run:

  LarkTool.exe --version

Using Print Profiles

Profiles are the easiest way to get consistent, high-quality results. They are shortcuts defined in the profiles.ini file that bundle multiple settings into a single, easy-to-remember name.

Instead of typing this:

LarkTool.exe --print "photo.jpg" --speed 1.5 --darkness 95 --dither floyd --brightness 5 --contrast 5```

You can simply use the pre-configured profile:
```bash
LarkTool.exe --print "photo.jpg" --profile image-high-quality

You can customize the provided profiles.ini or add your own to streamline any printing task.

Guiding Principles (The Golden Rules)

1. One Action at a Time: You can only use one primary command (like --print, --status, --move) at once.
2. Modifiers Need a Command: Options like --speed or --rotation don't do anything by themselves. They must be used with a primary command (e.g., LarkTool.exe --print "..." --rotation 90).
3. Preview is for Printing: The --print-preview option is a modifier that only works with printing commands (--print, --text, --calibrate-darkness, etc.).

Practical Examples

Diagnostics

# Get a quick status update
LarkTool.exe --status

# Continuously monitor the printer's real-time status
LarkTool.exe --monitor

# Read the entire device configuration
LarkTool.exe --get-config

# Retrieve and display the history of device faults
LarkTool.exe --get-fault-log

# Get lifetime printer statistics (total prints, media moved, etc.)
LarkTool.exe --stats

Printing and File Generation

# Print an image with default settings
LarkTool.exe --print "C:\images\photo.jpg"

# Print a ticket asynchronously while monitoring its progress
LarkTool.exe --print-async "ticket.png"

# Generate a raw binary file of a text string with line numbers and word-wrapping
LarkTool.exe --text "This is a long line..." --font-path "C:\Windows\Fonts\Arial.ttf" --font-size 24 --align center --word-wrap --line-numbering --print-preview "text_output.bin"

Using Profiles

# Print a photo using the best possible quality settings
LarkTool.exe --print "portrait.jpg" --profile image-high-quality

# Print a QR code with settings optimized for sharpness and scannability
LarkTool.exe --print "website-qr.png" --profile line-art-and-qr

# Print a text receipt and automatically add a tear-off line and feed the paper
LarkTool.exe --text "Total: $25.50..." --profile receipt-with-tear-bar

Configuration & Maintenance

# Move the media 1.5 inches forward
LarkTool.exe --move 1.5 --units imperial

# Set the default print darkness to 80% and save it to the device's permanent memory
LarkTool.exe --set-config --darkness 80.0
LarkTool.exe --flash-save

# Clear a "No Stock" error after reloading media
LarkTool.exe --clear-faults

# Print a diagnostic pattern to check the health of the print head elements
LarkTool.exe --print-head-test

Firmware Update

# Perform a complete, automated firmware update. This one command does it all.
LarkTool.exe --dfu-update "C:\firmware\lark_firmware_v2.1.hex"

# Perform an asynchronous firmware update
LarkTool.exe --dfu-update-async "C:\firmware\lark_firmware_v2.1.hex"

Full Command Reference

This is the complete output from LarkTool.exe --help.

LarkTool: A command-line utility for the Lark device.
Usage:
  LarkTool.exe [options]

Options:
      -h, --help                  Show this help message
      --version                   Show program version
      -v, --verbose               Enable verbose output (-v for info, -vv for debug)
      --log-file arg              Redirect log output to a specified file
      --profile arg               Use a named print profile from profiles.ini

      --rt-status                 Query and display real-time device status
      -s, --status                Query and display device status
      --monitor                   Continuously monitor real-time device status
      --get-fault-log             Retrieve and display the device's in-memory fault log
      --stats                     Retrieve and display device lifetime statistics
      --temperature               Get the current temperature of the device
      --clear-faults              Clear all latched fault flags (e.g., Head Up, No Stock, Fatal Error)

      -g, --get-config            Read the current device configuration
      -c, --set-config            Set configuration parameters
      --set-defaults              Reset the printer to factory defaults

      -p, --print arg             Print a file (PDF, image, or .txt)
      --print-async arg           Print a file asynchronously while monitoring status
      -m, --move arg              Move media by a specified distance
      -t, --text arg              Print a string of text

      --print-preview arg         Generate a preview of the print output and save it to the 
                                  specified file (PNG, JPEG, BMP, DATA, RAW, BIN)

      --reset                     Reset the device
      --purge                     Purge all buffers
      --bootloader                Jump to the device's DFU bootloader
      --verify-firmware           Show verification hash of the current firmware

      --dfu-reboot                Reboot a device from DFU mode into its application
      --dfu-mass-erase            Erase the entire device via DFU
      --dfu-erase                 Erase Bank 1 of the device via DFU
      --dfu-program arg           Program firmware from an Intel HEX file via DFU
      --dfu-update arg            Update firmware from an Intel HEX file via DFU
      --dfu-update-async arg      Update firmware from an Intel HEX file via DFU asynchronously

      --flash-save                Save user settings to non-volatile memory
      --flash-load                Load user settings from non-volatile memory
      --flash-erase               Erase all non-volatile memory, returning the device to factory defaults

      --self-test                 Run Self-Test on the device
      --calibrate-darkness        Generates and prints a darkness calibration page
      --print-head-test           Generates and prints a head diagnostic pattern

      -d, --dither arg            Dither algorithm for print [threshold, bayer, floyd] (default: threshold)
      -r, --rotation arg          Rotate image/text by an angle in degrees (default: 0.0)
      --flip-horizontal           Flip the print output horizontally
      --flip-vertical             Flip the print output vertically
      --scale arg                 Uniform scaling factor for print output
      --scale-x arg               Horizontal scaling factor for print output
      --scale-y arg               Vertical scaling factor for print output
      --brightness arg            Adjust brightness [-100 to 100] (default: 0.0)
      --contrast arg              Adjust contrast [-100 to 100] (default: 0.0)
      --pl, --padding-left arg    Set left padding (requires --units) (default: 0.0)
      --pr, --padding-right arg   Set right padding (requires --units) (default: 0.0)
      --pt, --padding-top arg     Set top padding (requires --units) (default: 0.0)
      --pb, --padding-bottom arg  Set bottom padding (requires --units) (default: 0.0)

      -u, --units arg             Units for config, move, and padding [metric, imperial]
      --speed arg                 Set motor speed for config/action
      --current arg               Set motor current in mA for config/action
      --resolution arg            Set microstep resolution [full, half, quarter, eighth]
      --direction arg             Set motor direction [forward, reverse]
      --darkness arg              Darkness for print [0% to 100%] (default: 100.0)

      --font-path arg             Path to .ttf/.otf font file (for --text or .txt)
      --font-size arg             Font size in pixels (for --text or .txt)
      --align arg                 Set text alignment [left, center, right] (default: left)
      --word-wrap                 Automatically wrap long lines of text
      --line-numbering            Automatically adds line numbers to text
      --page-start arg            First page to print (1-based index) (default: 1)
      --page-end arg              Last page to print (inclusive, -1 for last page) (default: -1)
      --process-escape-chars      Process \n, \r, and \t escape sequences in text
      --pdf-high-contrast         Enable high contrast mode for PDF input files

      --cutoff-style arg          Append a cutoff bar to the print job [dotted, dashed, triangle]
      --move-after-print arg      Move media by a specified distance after printing (requires --units)

      --benchmark                 [DEBUG] Run benchmark test
      --debug-value arg           [DEBUG] Send a debug value to the hardware (float)

---

LarkTool © HamSlices 2025

The Lark Project