English | Deutsch | 中文（简体字） | 中文（正體字） | 中文（香港字）

Cat-Printer

🐱🖨 A project that provides support to some Bluetooth “Cat Printer” models, on many platforms!

Models

Known to support: GB01, GB02, GB03, GT01, YT01, MX05, MX06, MX08

You can test other models with the Web UI, in Settings -> Test Unknown Device
It may work!

Features

This project is still in development. More features may be added in the future!

Simple!
- Operate via Web UI just in browser,
- or get the Android release!
- Even no problem with command line hackers!
Friendly!
- Language support! You can participate in translation!
- Good user interface, adaptive to PC/mobile and light/dark theme!
- Accessibility features, everyone is considered!
Feature-rich!
- Web UI, for most people!
  - Take full control of printer config
  - Print picture, or just test if it works
- Command line, for geeks & hackers!
  - Control printer with a few parameters
  - Simplified image/text printing
  - Make use of every part of the program
- Some other goodies!
  - Server program is also CUPS/IPP capable
Cross platform!
- Newer Windows 10 and above
- GNU/Linux
- MacOS
- and also Android!
Free, as in freedom!
- Unlike those proprietary “apps” around,
  this project is for everyone that concerns open-mind and freedom!
and Fun!
- Do whatever you like!

Get Started

Android

Get the newest apk release and install, then well done!

It may ask for background location permission, you can deny it safely.
(Foreground) Location permission is required for scanning Bluetooth devices in newer Android system.

Recommend to set scan time to 1 second.

Windows

Get the newest release archive with “windows” in the file name,
extract to somewhere and run start.bat

Windows typically needs longer scan time. Defaults to 4 seconds, try to find your case.

GNU/Linux

You can get the “pure” release, extract it, fire up a terminal and run:

python3 server.py

It is recommended to set the scan time to 2 seconds. On Arch Linux based distros you may install bluez first, as it may not be installed by default

sudo pacman -S bluez bluez-utils

Further steps

You may want to use the command line interface for hackiness...

You may or may not need to install ImageMagick and Ghostscript, depending on your distro.

sudo apt install imagemagick ghostscript

or use your distro's package manager.

Extra configuration is required for ImageMagick to work. Because IM is made for external webserver, a strict security policy is applied. You need to add the following line to /etc/ImageMagick-6/policy.xml before </policymap>:

 <policy domain="coder" rights="read | write" pattern="PDM" />

Because this script is only accesible by localhost, or at most your local network, this is safe.

Packaging is also on the way!

MacOS

For MacOS please install Python 3,
then install pyobjc and bleak via pip in terminal:

pip3 install pyobjc bleak

After that, fetch & use a “bare” release:

python3 server.py

Worth to Note

For all supported platforms,
You can also use “pure” edition once you have Python 3 installed,
or “bare” edition if you also managed to install bleak via pip.

If you like command-line, installing ImageMagick and Ghostscript could be very helpful.

See the releases now!

Problems?

Please use Issue or Discussion if there’s something in your mind!

Of course Pull Requests are welcome if you can handle them!

License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.

See file LICENSE, and detail of used JavaScript in file www/jslicense.html

Particularly, printer.py, server.py and main.js are released under GNU GPL 3 (GPL-3.0-or-later).
All other parts, except which have special statements, are in Public Domain (CC0-1.0-only).

Contribution

You may interested in language support, anyway. There are translation files in directory www/lang and readme.i18n/!

You can correct mistakes here/there, if there are any. Also feel free to make it (truly) better!

Also interested in code development? See CONTRIBUTING.md and development.md!

After that, give yourself a credit in www/about.html, if you prefer.

Credits

Of course, Python & the Web!
Bleak Bluetooth-Low-Energy library! The overall Hero!
roddeh-i18n, the current built-in i18n is inspired by this
PF2 font, great minimal raster font idea
ImageMagick & Ghostscript, never mention other if something useful is already in one’s system
python-for-android, though there are some painful troubles
AdvancedWebView for saving my life from Java
Stack Overflow & the whole Internet, you let me know Android Activity all from beginning ... and many other helpful ideas as well
Everyone that contributed through Issue/Pull Request/Discussion
Everyone that is using this & caring about software freedom
... Everyone is Awesome!

alexiri/Cat-Printer