catprinter

README

go-catprinter is a driver and CLI application that allows you to use some BLE printers, known as "cat printers", on Linux and MacOS, without needing to use the official app.

Documentation

CLI

Grab a binary from the Releases page. Use ./catprinter --help for help.

• Basic example with provided MAC: ./catprinter --mac 41:c2:6f:0f:90:c7 --image ./gopher.png
• Basic example with auto discovery by name: ./catprinter --name X6h --image ./gopher.png

Driver

For extensive documentation, please consult the Go Reference. Check the examples/ directory for examples:

• examples/00-knownMac.go: Shows how to connect to a printer by its MAC address and print a file
• examples/01-unknownMac.go: Shows how to connect to a printer by its name address and print a file
• examples/02-options.go: Shows how PrinterOptions can be used to create a rich printing experience with previews and user interaction

Information

Printer compatibility

This software should be compatible with printers whose official apps are iPrint, Tiny Print and similar.
Probably more printers work, but it's hard to tell with how fragmented the ecosystem is. Some printers with these apps might not work. The project takes no responsibility as per the LICENSE.

The project's main developer uses a X6h (the one in the top of the README). It can be found in AliExpress bundles for around ~€8.

Thanks to...

• rbaron/catprinter and NaitLee/Cat-Printer, for providing most of the printer commands and inspiration for the project
• Shenzhen Frog To Sea Technology Co.,LTD
• Everyone who contributed, tested or used this software!

Alternatives

• NaitLee/Cat-Printer - the cat printer central, with a CLI application, a web UI, CUPS/IPP support and an Android app. The code is a bit more cluttered, but it works well.
• rbaron/catprinter - simple CLI application for cat printers with batteries included, written in Python with code that's easy to understand.
• NaitLee/kitty-printer - a web app for cat printers which leverages Web Bluetooth
• jhbruhn/catprint-rs - a driver for cat printers with a basic CLI utility, written in Rust

Documentation

Index

• Variables
• type Client
  • func NewClient() (*Client, error)
  • func NewClientFromDevice(d ble.Device) (*Client, error)
  • func (c *Client) Connect(mac string) error
  • func (c *Client) Disconnect() error
  • func (c *Client) FormatImage(img image.Image, opts *PrinterOptions) image.Image
  • func (c *Client) Print(img image.Image, opts *PrinterOptions, isAlreadyFormatted bool) error
  • func (c *Client) PrintFile(path string, opts *PrinterOptions) error
  • func (c *Client) ScanDevices(name string) (map[string]string, error)
  • func (c *Client) Stop() error
• type PrinterOptions
  • func NewOptions() *PrinterOptions
  • func (o *PrinterOptions) AutoRotate() bool
  • func (o *PrinterOptions) BestQuality() bool
  • func (o *PrinterOptions) BlackPoint() float32
  • func (o *PrinterOptions) Dither() bool
  • func (o *PrinterOptions) DitherAlgo() dither.ErrorDiffusionMatrix
  • func (o *PrinterOptions) SetAutoRotate(rotate bool) *PrinterOptions
  • func (o *PrinterOptions) SetBestQuality(best bool) *PrinterOptions
  • func (o *PrinterOptions) SetBlackPoint(bp float32) *PrinterOptions
  • func (o *PrinterOptions) SetDither(dither bool) *PrinterOptions
  • func (o *PrinterOptions) SetDitherAlgo(algo dither.ErrorDiffusionMatrix) *PrinterOptions

Variables

var (
	ErrPrinterNotFound       = errors.New("unable to find printer, make sure it is turned on and in range")
	ErrMissingCharacteristic = errors.New("missing characteristic, make sure the MAC is correct and the printer is supported")
	ErrNotBlackWhite         = errors.New("image must be black and white (NOT only grayscale)")
	ErrInvalidImageSize      = errors.New("image must be 384px wide")
)

Types

type Client

type Client struct {
	Timeout time.Duration
	Debug   struct {
		Log         bool // print logs to terminal
		DumpRequest bool // saves last data sent to printer to ./request.bin
		DumpImage   bool // saves formatted image to ./image.png
		DontPrint   bool // if true, the image is not actually printed. saves paper during testing.
	}
	// contains filtered or unexported fields
}

Client contains information for the connection to the printer and debugging options.

func NewClient

func NewClient() (*Client, error)

NewClient initiates a new client with sane defaults

func NewClientFromDevice

func NewClientFromDevice(d ble.Device) (*Client, error)

NewClientFromDevice initiates a new client with a custom ble.Device and sane defaults

func (*Client) Connect

func (c *Client) Connect(mac string) error

Connect establishes a BLE connection to a printer by MAC address.

func (*Client) Disconnect

func (c *Client) Disconnect() error

Disconnect closes any active connection to a printer

func (*Client) FormatImage

func (c *Client) FormatImage(img image.Image, opts *PrinterOptions) image.Image

FormatImage formats the image for printing by resizing it and dithering or grayscaling it

func (*Client) Print

func (c *Client) Print(img image.Image, opts *PrinterOptions, isAlreadyFormatted bool) error

Print prints an image to the connected printer. It also formats it and dithers if specified by opts and isAlreadyFormatted. Only set isAlreadyFormatted to true if the image is in black and white (NOT ONLY grayscale) and 384px wide.

func (*Client) PrintFile

func (c *Client) PrintFile(path string, opts *PrinterOptions) error

PrintFile dithers, formats and prints an image by path to the connected printer

func (*Client) ScanDevices

func (c *Client) ScanDevices(name string) (map[string]string, error)

ScanDevices scans for a device with the given name, or auto discovers it based on characteristics (not implemented yet). Returns a map with MACs as key, and device names as values.

func (*Client) Stop

func (c *Client) Stop() error

Stop closes any active connection to a printer and detaches the GATT server

type PrinterOptions

type PrinterOptions struct {
	// contains filtered or unexported fields
}

func NewOptions

func NewOptions() *PrinterOptions

NewOptions creates a new PrinterOptions object with sane defaults.

func (*PrinterOptions) AutoRotate

func (o *PrinterOptions) AutoRotate() bool

AutoRotate returns the auto rotate option.

func (*PrinterOptions) BestQuality

func (o *PrinterOptions) BestQuality() bool

BestQuality returns the quality option.

func (*PrinterOptions) BlackPoint

func (o *PrinterOptions) BlackPoint() float32

BlackPoint returns the black point.

func (*PrinterOptions) Dither

func (o *PrinterOptions) Dither() bool

Dither returns the dither option.

func (*PrinterOptions) DitherAlgo

func (o *PrinterOptions) DitherAlgo() dither.ErrorDiffusionMatrix

DitherAlgo returns the dither algorithm.

func (*PrinterOptions) SetAutoRotate

func (o *PrinterOptions) SetAutoRotate(rotate bool) *PrinterOptions

SetAutoRotate sets the auto rotate option. Default is false. If true and the image is landscape, it gets rotated to be printed in higher resolution.

func (*PrinterOptions) SetBestQuality

func (o *PrinterOptions) SetBestQuality(best bool) *PrinterOptions

SetBestQuality sets the quality option. Default is true. If true, prints slower with higher thermal strength, resulting in a darker image. Recommended for self-adhesive paper.

func (*PrinterOptions) SetBlackPoint

func (o *PrinterOptions) SetBlackPoint(bp float32) *PrinterOptions

SetBlackPoint sets the black point. Default is 0.5. If 0.5, a gray pixel will be printed as black if it's less than 50% white. Only effective if Dither is disabled.

func (*PrinterOptions) SetDither

func (o *PrinterOptions) SetDither(dither bool) *PrinterOptions

SetDither sets the dither option. Default is true. If false, dithering is disabled, and the image is converted to black/white and each pixel is printed if less white than BlackPoint.

func (*PrinterOptions) SetDitherAlgo

func (o *PrinterOptions) SetDitherAlgo(algo dither.ErrorDiffusionMatrix) *PrinterOptions

SetDitherAlgo sets the dither algorithm. Default is FloydSteinberg.