v/Cat-Printer
1
0
Fork 0
mirror of https://github.com/NaitLee/Cat-Printer.git synced 2025-05-15 14:50:26 -07:00
Code Issues Packages Projects Releases Wiki Activity

Write Android build guide; fixed:

Browse Source 
error when LANG=None
initial config have incorrect strength/energy
adjustments to docs and scripts
This commit is contained in:
NaitLee 2022-09-12 02:20:08 +08:00
parent cbfd904152
commit 70cdd84359
17 changed files with 516 additions and 100 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
.gitignore vendored
View File

@ -19,8 +19,11 @@ cat-printer*.zip
cat-printer-sha256-*.txt
# bleak, the bare pip package as a folder
build-common/bleak
# python embeddable package, with bleak_winrt inside
# python embeddable package, historically with bleak_winrt inside
build-common/python-win32*
build-common/python-w32*
# bleak_winrt is now outside python-w32
build-common/bleak_winrt
# dev config
config.json
# dev backup

52
CONTRIBUTING.md
View File

@ -3,73 +3,81 @@
Thank you for looking into this project.
Let's keep short & be positive:
Let’s keep short & be positive:
## Communication
1. Use Issue for a potential bug and Discussion for feature request.
But do whichever you feel better. This is just a hint.
2. Consider you're interacting with the whole world. Use English.
But you may also use another if you're confident enough that someone in community could understand it & help you.
2. Consider you’re interacting with the world. Use English.
But you may also use another if you’re confident enough that someone in community could understand it & help you.
## Sharing
Let's just call it "sharing". You can of course share your experience of this project with your friends, online or offline.
Let’s just call it “sharing”. You can of course share your experience of this project with your friends, online or offline.
This is also one step toward Software Freedom.
But note that, if necessary, disclaim that you have no relationship with any of the printer vendors. Neither the author(s) here.
Also for avoiding potential hassle, don't mention the "original" or "official" app(s).
Also for avoiding potential hassle, don’t mention the “original” or “official” app(s).
## Translating
See [i18n.md](./i18n.i18n/i18n.md) for what to do.
As a special note, try to correctly use marks & symbols:
- Use `“”‘’` in place of `"'`, except when in a terminal
- Localize marks right, e.g. `“”` in English shall correspond to `„“` in German or `»«` in French, etc.
- Keep spaces consistent, e.g. `“”` will be rendered full-width in CJK font, so leave no space around them in CJK context
Hint: a Keyboard Layout other than default maybe helpful, especially those with AltGr/Level 3 Shift keys.
You can seek for help here, to do grammar extensions & leftovers.
## Coding
1. Whether big or small, pull requests are welcome.
1. Any contribution welcome.
2. See file `TODO` for what's next. But don't limit imagination, do whatever you think is useful.
2. See file `TODO` for what’s next. But don’t limit imagination, do whatever you think is useful.
3. Keep the existing "way". Here are details:
3. Keep the existing “way”. Here are details:
- Think about the Unix Philosophy before doing. Try to suck less.
- Follow coding style & naming convention.
- Think about the use cases: Web UI and/or command-line backend, average and/or advanced users
- Test the code well. Document if necessary.
- Don't forget internationalization & necessary accessibility features.
- Don’t forget internationalization & necessary accessibility features.
4. Finally, "rules". Just skim these, don't feel pressure as I trust you won't mistake:
4. Finally, “rules”. Just skim these, don’t feel pressure as I trust you won’t mistake:
- Don't leak development/test cache/junk to the repo. Please.
And never put pictures/executables/any big binary to this repo. Try uploading in an issue/discussion instead.
- Don't connect to an online service to fetch resource.
If necessary, ask the user first.
- Don’t leak development/test cache/junk to the repo. Please.
And never put pictures/executable/any big binary to this repo. Try uploading in an issue/discussion instead.
- No more 3rd-party blackbox dependencies/assets, without explaining & using its most functionality.
Consider using existing system programs, or implementing enough from scratch.
If that really happened, make it optional (i.e. don't fail the load just for its non-existence),
And don't push the dependency source code.
For big dependencies, if you really love it, it's suggested to fork this repo & develop in your own way.
- Don't make anti-features. Don't be someone yourself dislike most.
If that really happened, make it optional (i.e. don’t fail the load just for its non-existence),
And don’t push the dependency source code.
For big dependencies, if you really love it, it’s suggested to fork this repo & develop in your own way.
- Don’t connect to an online service to fetch resource.
If necessary, ask the user first. Again, such functionality shall be elsewhere.
- Don’t make anti-features. Don’t be someone yourself dislike most.
Examples:
- You can do: simple borders & stickers, scribbling, simple PostScript interpreter, another common printing protocol
- Considering previous rule, discuss first: Bar/QR Code, formula, Native (non-Web) UI
- You shouldn't do: Way too fancy UI/editor, Cloud storage, camera integration & OCR
- You shouldn’t do: Way too fancy UI/editor, Cloud storage, camera integration & OCR
- Never consider: online account, non-free service integration, analysis/telemetry
- Please don't violate the license (GNU General Public License version 3)
- Please don’t violate the license (GNU General Public License version 3)
Modification to existing files are released under its existing license,
mostly GPL3 or CC0, according to statement in readme.
- If you want to preserve your copyright & use other license, create new file(s) for your work.
But, never release your code under any non-free license.
5. You can take any part of this project to do something else. It's also contribution! Let the ideas spread!
5. You can take any part of this project to do something else. It’s also contribution! Let the ideas spread!
## Footnote
Nothing could go wrong. Trust yourself & try your best.
Let's together build it better. Thank you.
Let’s together build it better. Thank you.

7
build-android/0-build-android.sh
View File

@ -1,8 +1,9 @@
#!/bin/sh
export version=`cat ../version`
version=`cat ../version`
p4a apk --private .. --dist_name="cat-printer" --package="io.github.naitlee.catprinter" --name="Cat Printer" \
--icon=icon.png --version=$version --bootstrap=webview --window --requirements=android,pyjnius,bleak \
--icon=icon.png --version=$version --bootstrap=webview --window --requirements="`cat build-deps.txt`" \
--blacklist-requirements=sqlite3,openssl --port=8095 --arch=arm64-v8a --blacklist="blacklist.txt" \
--presplash=blank.png --presplash-color=black --add-source="advancedwebview" --orientation=user \
--permission=BLUETOOTH --permission=BLUETOOTH_SCAN --permission=BLUETOOTH_CONNECT \
--permission=BLUETOOTH_ADMIN --permission=ACCESS_FINE_LOCATION --permission=ACCESS_COARSE_LOCATION
--permission=BLUETOOTH_ADMIN --permission=ACCESS_FINE_LOCATION --permission=ACCESS_COARSE_LOCATION $@

7
build-android/3-formal-build.sh
View File

@ -1,11 +1,12 @@
#!/bin/sh
export version=`cat ../version`
version=`cat ../version`
rm -rf "dist"
unzip -q "../cat-printer-bare-$version.zip"
mv "cat-printer" "dist"
p4a apk --private "dist" --dist_name="cat-printer" --package="io.github.naitlee.catprinter" --name="Cat Printer" \
--icon=icon.png --version="$version" --bootstrap=webview --window --requirements=android,pyjnius,bleak \
--icon=icon.png --version="$version" --bootstrap=webview --window --requirements="`cat build-deps.txt`" \
--blacklist-requirements=sqlite3,openssl --port=8095 --arch=arm64-v8a --release \
--presplash=blank.png --presplash-color=black --add-source="advancedwebview" --orientation=user \
--permission=BLUETOOTH --permission=BLUETOOTH_SCAN --permission=BLUETOOTH_CONNECT \
--permission=BLUETOOTH_ADMIN --permission=ACCESS_FINE_LOCATION --permission=ACCESS_COARSE_LOCATION
--permission=BLUETOOTH_ADMIN --permission=ACCESS_FINE_LOCATION --permission=ACCESS_COARSE_LOCATION $@

15
build-android/4-sign.sh
View File

@ -1,8 +1,13 @@
#!/bin/sh
export version=`cat ../version`
export unsigned_apk=cat-printer-release-unsigned-$version-.apk
export signed_apk=cat-printer-android-$version.apk
$ANDROIDSDK/build-tools/32.0.0/zipalign 4 $unsigned_apk $signed_apk
$ANDROIDSDK/build-tools/32.0.0/apksigner sign --ks $1 $signed_apk
version=`cat ../version`
unsigned_apk=cat-printer-release-unsigned-$version-.apk
signed_apk=cat-printer-android-$version.apk
if {
$ANDROIDSDK/build-tools/*/zipalign 4 $unsigned_apk $signed_apk;
$ANDROIDSDK/build-tools/*/apksigner sign --ks $1 $signed_apk;
}; then
echo "Complete! Moving APK..."
mv $signed_apk $signed_apk.idsig ../
rm *.apk
fi

8
build-android/README.md Normal file
View File

@ -0,0 +1,8 @@
# Build for Android
The build environment shall be setup manually, since it’s a bit complex, and I’m not so familiar with Android development.
See [Manual Steps](./manual-steps.md) to get started.
Android enthusiasts may help with automated build procedure, then for example F-Droid release would be possible.

1
build-android/build-deps.txt Normal file
View File

@ -0,0 +1 @@
async_timeout,typing-extensions,android,pyjnius,bleak

32
build-android/fix-ndk-execs.py Normal file
View File

@ -0,0 +1,32 @@
''' Some casual code to fix those alias files
in Android NDK llvm bin to symlinks instead
'''
import os
import sys
MAX_LENGTH = 256
ndk_path = sys.argv[1] if len(sys.argv) > 1 else input('Android NDK path: ')
bin_path = os.path.join(ndk_path, 'toolchains/llvm/prebuilt/linux-x86_64/bin/')
workdir = os.getcwd()
os.chdir(bin_path)
try:
for path in os.listdir():
# with this encoding it won't error when reading binary
file = open(path, 'r', encoding='iso8859-1')
data = file.read(MAX_LENGTH).strip()
file.close()
# inside the alias file is the filename that should be executed
# let's see if there is one
if os.path.isfile(data):
print('Will fix %s -> %s' % (path, data))
#os.remove(path)
os.rename(path, path + '.alias')
os.symlink(data, path)
finally:
os.chdir(workdir)

338
build-android/manual-steps.md Normal file
View File

@ -0,0 +1,338 @@
# Android Build Env Manual Setup
Expecting to cost about half a day.
Worthy to work on! This gives possibility to everything about Android in your mind!
Note: not being confirmed to 100% work yet. Be the first bird to try! Or bookmark this, arrange your time & come back later.
## Prepare
First, think about what will be your build environment. I choose to use a Ubuntu Docker container.
<details>
<summary>Expand Comparison</summary>
| | Minimal Ubuntu | Ubuntu | [Artix](https://artixlinux.org/) |
| :-------------------------- | :------------: | :----: | :------: |
| Base system<sup>1</sup> | | ✓ | ✓ |
| Pkg diversity | ✓ | ✓ | ✓ |
| Fresh pkg<sup>2</sup> | | | ✓ |
| Less hassle<sup>3</sup> | ✓ | | ✓ |
| Maintainability<sup>4</sup> | ✓ | | |
Note: “Minimal Ubuntu” can mean a Ubuntu [Docker](https://docs.docker.com/get-started/overview/) image, a Ubuntu chroot environment, etc.
1. In theory you can just have Ubuntu as base system, but see 2, 3, and 4.
2. Rolling distribution have newer packages offered.
It may give great experience in daily use, but will heavily bloat the update if many development packages are installed alltogether.
That said, Artix alone *worked* in those days. If you want, go ahead.
3. Mis-designs will stress you down. systemd will ruin your mood.
4. By operating in an isolated environment, a mess taking place inside won’t affect the host.
(Some say Docker isn’t intended to be “stateful”. But nothing is better in my mere knowledge.)
</details>
Before creating the build environment, let’s prepare requirements of the outside.
### Space
Leave enough space for the isolated environment.
For Docker, maybe keep 3 GiB free in root directory.
Locate somewhere with at least 8 GiB free space,
Make 3 folders inside:
- `git-repo`, for git clones
- `android`, for Android SDK
- `p4a`, for manipulating python-for-android intermediate data
### Git Repositories
```bash
# Remember to use your path
DIR_GIT="/mnt/data/@/git-repo/"
cd $DIR_GIT
# Cat-Printer
git clone https://github.com/NaitLee/Cat-Printer.git
# Bleak, we need some Java code from its source
git clone https://github.com/hbldh/bleak.git
# AdvancedWebView, in order to give Android WebView capability to use <input type="file" />
git clone https://github.com/delight-im/Android-AdvancedWebView.git
# Let AdvancedWebView source code be in Cat-Printer building directory
ln -s ../../Android-AdvancedWebView/Source/library/src/main/java Cat-Printer/build-android/advancedwebview
```
### Android SDK
For most cases, following [python-for-android guide](https://python-for-android.readthedocs.io/en/latest/quickstart/#basic-sdk-install) will just work.
But Note: required by newer Gradle, use Android **platform 30** (or above) rather than 27.
After that, continue to [Fix the NDK](#fix-the-ndk).
----
If you’re in China Mainland (you guessed it!), or prefer manual setup:
- Pick a working mirror. Currently there’s [Tencent Cloud](https://mirrors.cloud.tencent.com/AndroidSDK/).
- Fetch & extract some archives, as shown in this table:
| Archive file | Top-level dir inside | Target directory |
| ----------------------------------- | ----------------------- | ----------------------------------- |
| `android-ndk-r23b-linux.zip` | `android-ndk-r23b` | `android/android-ndk-r23b` |
| `build-tools_r33-linux.zip` | `android-13` | `android/build-tools/33.0.0` |
| `commandlinetools-linux-8512546_latest.zip` | `cmdline-tools` | `android/cmdline-tools/latest` |
| `platform-30_r03.zip` | `android-11` | `android/platforms/android-30` |
| `platform-tools_r33.0.3-linux.zip` | `platform-tools` | `android/platform-tools` |
For example, you get `build-tools_r33-linux.zip`, see a folder `android-13` inside;
then you create `build-tools/` in `android/`, extract `android-13` there and rename it as `33.0.0`
So after that you will get:
```
android
├── android-ndk-r23b
├── build-tools
│   └── 33.0.0
├── cmdline-tools
│   └── latest
├── platforms
│   └── android-30
└── platform-tools
```
### Fix the NDK
The NDK (particularly, the llvm/clang binary directory) have some files that contain a path to other executable as their data.
System doesn’t understand it. Let’s replace them as symlinks:
```bash
# you may already have these from p4a guide
ANDROIDSDK="/mnt/data/@/android"
ANDROIDNDK="/mnt/data/@/android/android-ndk-r23b"
# feel free to check this script
python3 $DIR_GIT/Cat-Printer/build-android/fix-ndk-execs.py $ANDROIDNDK
```
## Setup
### Environment
```bash
# Install Docker Engine. This is for Arch-based OS
sudo pacman -Syu docker
# (I didn’t try Docker Desktop)
```
For China Mainland users, configuring a mirror may be helpful. See https://mirrors.sjtug.sjtu.edu.cn/docs/docker-registry
after that, restart docker service, or reboot.
----
```bash
# let’s create the container by first pulling the image
docker pull ubuntu:latest
# please, pass previously mentioned directories (or their parent) via -v parameter, we will access them here
# example: `-v /source1/android:/target1/android -v /source2/git-repo:/target2/git-repo`
docker create --name catbuild -v /mnt/data:/mnt/data --tty -i ubuntu
# From now on, start the container like this
docker start -i catbuild
```
----
OK, we are now inside the container shell. Set it up:
```bash
# (Optional) use a Ubuntu repository mirror
# sed -i 's/archive.ubuntu.com/mirrors.ustc.edu.cn/g' /etc/apt/sources.list
dpkg --add-architecture i386
apt update
apt upgrade
# find python-for-android dependencies here:
# https://python-for-android.readthedocs.io/en/latest/quickstart/#installing-dependencies
# there should be a command for Ubuntu that you can directly run
# ... though we need more
apt install -y python3-pip lld libffi-dev zip nano
# (Optional) use a pypi mirror
# pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
pip install python-for-android cython bleak
```
### Source Code
The most tricky fact is that none of these things work out-of-the-box.
We should glue them up by hand.
```bash
# let’s put those environment variables required by python-for-android here
nano ~/.bashrc
# append in the end. use your target paths!
export ANDROIDSDK="/mnt/data/@/android"
export ANDROIDNDK="/mnt/data/@/android/android-ndk-r23b"
export ANDROIDAPI="30"
export NDKAPI="21"
# after that, apply these
source ~/.bashrc
```
----
```bash
# define shortcut(s). use your target paths!
DIR_GIT="/mnt/data/@/git-repo/"
DIR_P4A="/usr/local/lib/python3.10/dist-packages/pythonforandroid/"
# p4a will generate some intermediate data. “expose” this to the host for convenient manipulation.
mkdir -p ~/.local/share/
ln -s /mnt/data/@/p4a/ ~/.local/share/python-for-android
# give p4a the bleak recipe. fortunately, p4a will resolve this symlink
ln -s $DIR_GIT/bleak/bleak/backends/p4android/recipes/bleak $DIR_P4A/recipes/bleak
```
----
At this point, do some code patch.
AdvancedWebView have a deprecated function override that fails the compile. Remove it.
```bash
cd $DIR_GIT/Android-AdvancedWebView/Source/library/src/main/java/im/delight/android/webview/
# any editor is okay. you can do it at host side with graphical editor.
nano AdvancedWebView.java
# search for `public void onUnhandledInputEvent`, remove (or comment out) the *entire function body*
```
Modify p4a webview bootstrap to use AdvancedWebView instead
```bash
# copy source file to somewhere easy to access
cd $DIR_GIT
cp $DIR_P4A/bootstraps/webview/build/src/main/java/org/kivy/android/PythonActivity.java ./
# some sed script doing the dirty work
sed -i 's/import android.webkit.WebView;/import im.delight.android.webview.AdvancedWebView;/' PythonActivity.java
sed -i -r 's/\bWebView\b/AdvancedWebView;/g' PythonActivity.java
```
Not the end yet —
You really want to use a graphical editor now, except if you enjoy vim or emacs...
- (At host side) Open the file with an editor
- Search & remove these two `@Override` decorators:
```java
//@Override
public boolean shouldOverrideUrlLoading
//@Override
public void onPageFinished
```
- Add this after the line `protected void onActivityResult`:
```java
// pass this activity to AdvancedWebView instance, to get <input type="file" /> really work
if ( requestCode == 51426 ) {
mWebView.onActivityResult(requestCode, resultCode, intent);
return;
}
```
- (Optional) Remove the problematic “Tap again to close the app” behavior:
Find function `public boolean onKeyDown`, remove everything inside except the `return` clause.
----
```bash
# save the modification, overwrite the original
# (you can make a backup if you feel it right)
cp $DIR_GIT/PythonActivity.java $DIR_P4A/bootstraps/webview/build/src/main/java/org/kivy/android/PythonActivity.java
# customize the loading page with Cat-Printer assets
cp $DIR_GIT/Cat-Printer/www/_load.html $DIR_GIT/Cat-Printer/www/icon.svg $DIR_P4A/bootstraps/webview/build/webview_includes/
```
## Build
### Debug Build
*\*Phew\**, it should be ready. Now try to build a debug version:
```bash
# always cd here
cd $DIR_GIT/Cat-Printer/build-android/
# <dot><slash><0><tab>
./0-build-android.sh
# again, feel free to check this file
```
The initial build will cost some time.
p4a will do:
- Download some source code from Internet, notably `python3` and some essential packages like `pyjnius`, `pyffi`, etc.
- Build all of them
- Build Cat-Printer code to Cython, gather everything together
- Download a Gradle package, give those assets to Gradle to complete the build.
TODO: find a way to get Gradle in China Mainland ~~without any circumvention~~
----
It worked? Congratulations! Now test your built package with an Android phone.
(Note that if you’ve previously installed my distribution, uninstall it first, to solve signature conflict.)
It didn’t? **Don’t panic!** Check the message to see what’s wrong, try to fix it.
Get a problem? **Say what’s up in Issue/Discussion.**
Build process messed up? Changes not applied? Execute `./2-clean-up-build.sh` to clean up, then redo the build.
Other scripts inside `build-android/` may be helpful too.
### Release Build
It’s best to publish a release build. In contrast to debug build, release build have smaller size, optimized, and signed for authority.
Before start, read [development.md](../development.md) to setup for a “pure” bundle, and build one.
Okay, now let’s generate your key, to be used to sign the apk:
```bash
# keytool is of Java. use from your build environment.
# keep this file secret! put outside of git directory, don’t lose it.
keytool -genkey -v -keystore mykeyfile.key -keyalg RSA -keysize 2048 -validity 18250 -alias mykey
```
```bash
# always cd here
cd $DIR_GIT/Cat-Printer/build-android/
# <dot><slash><3><tab>
# pass the path to keyfile as parameter
./3-formal-build.sh mykeyfile.key
# again, feel free to check this file
```
This will cost a bit more time than debug build.
Note: I’m unsure if (another or the first) Gradle is being downloaded in this step.
If it also worked, congrats again!
(On Android, the debug build conflicts with a signed release build. Uninstall one to install the other.)
Try the ultimate helper `1-build.sh`, if you also have everything in [development.md](../development.md) done.
## The End
You made it! You now have ability to contribute much more, outside of Cat-Printer. Try to bring an app in your mind to reality, with just Python, Web, and this build environment.

8
build-common/bundle.py
View File

@ -103,7 +103,13 @@ with zipfile.ZipFile(bundle_name, 'w', zipfile.ZIP_DEFLATED) as bundle:
fullpath = os.path.join(path, name)
bundle.write(fullpath, os.path.join(bundle_sub_dir, fullpath))
if edition == 'windows':
os.chdir('python-win32-amd64-embed')
for path, dirs, files in os.walk('bleak_winrt'):
if path.endswith('__pycache__'):
continue
for name in files:
fullpath = os.path.join(path, name)
bundle.write(fullpath, os.path.join(bundle_sub_dir, fullpath))
os.chdir('python-w32')
for path, dirs, files in os.walk('.'):
if path.endswith('__pycache__'):
continue

128
development.md
View File

@ -3,125 +3,137 @@
## Overview
This application have a Client/Server module, but it's just locally.
This application have a Client/Server module, but just locally.
The backend is in Python 3, aiming to have fewest dependencies, and in fact currently have just `bleak`.
This can ensure the simplicity of the core part.
The backend is in Python 3, aiming to have fewest possible dependencies, and currently have just `bleak`.
This can keep the core part simple, maximize reusability.
And the frontend is in a "old good" way, that use no "framework".
The Web frontend uses no “framework”. It shouldn’t, in my opinion.
The command-line interface (CLI) could invoke other commands, to help the process.
Currently it may invoke `magick` and `gs`, for ImageMagick and Ghostscript respectively.
My workspace stack is Linux/GNU/Artix/KDE/VSCodium, if you're interested.
For Android, GNU/Linux is required, though.
The command-line interface (CLI) could invoke other commands to extend functionality.
At the moment it may invoke `magick` and `gs`, for ImageMagick and Ghostscript respectively.
The Android version is built with [python-for-android](https://python-for-android.readthedocs.io/en/latest/).
In our case it's complicated, don't go blindly if you don't want to waste your time.
There are too many hacks to be done, before and after. Let me summarize them later...
By the way, feel free to look at file `dev-diary.txt`
See [Android Readme](./build-android/README.md) to get started, but don’t forget to finish this document.
By the way, feel free to look at `dev-diary.txt`.
My workspace stack is Linux/GNU/Artix/KDE/VSCodium, if you’re interested.
## Get Dependencies
### Basic
Just clone this repo first!
0. Clone this repository
1. Install python3
2. Get Bleak BLE library:
`pip3 install bleak`
1. Get Bleak BLE lib:
`pip install bleak`
Alright, you are well done for basic development & debugging. See [files](#files) section for what all the files do.
Alright, you are already well done for basic development. See [files](#files) section for what all the files do.
For more, read on...
For more stuffs, read on...
### Optional
Sorry, I'm not a dev package manager enthusiast.
Sorry, I’m not a dev package manager enthusiast.
If there are something better to organize these, feel free to discuss in issue.
If something better can be done to organize these, feel free to discuss.
- Install [ImageMagick](https://imagemagick.org/) and [Ghostscript](https://ghostscript.com/)
- Now you can enjoy more command line features. And could make it better or debug problems
- Install TypeScript on Node.js `npm`
`npm --global install typescript`
You may need root privilege on GNU/Linux (i.e. prefix `sudo`)
Now the `0-transpile.sh` will work, you're ready to deal with compatibility
- Put the Bleak pip installation as `build-common/bleak`
- You need this in order to bundle a "pure" or "windows" release
- See [Files](#files) section about `bundle.py`
- Get an Windows 64-bit embeddable Python, extract to `build-common/python-win32-amd64-embed`
- You may remove the "bloated" parts inside, notably `libssl`, `libcrypto`, `sqlite3` and `pydoc`, of both `dll`/`pyd` files and in `python<version>.zip`, if have any.
- Now you're able to bundle a "windows" edition, via `python3 bundle.py -w`
- They have big chance to be pre-installed
- With these you can enjoy more command line features
<!-- TODO make Node.js dep optional, let’s use Deno or Bun instead. -->
- Install TypeScript:
- It’s adviced to separate [Node.js/npm](https://nodejs.org/) executables from package manager, to avoid system inconsistency
- After setting up it, do `npm install --global typescript`. You may need root privilege on \*nix systems (prefix `sudo`)
- Now the `0-transpile.sh` will work, you’re ready to deal with compatibility
- Gather Bleak:
- Get [Bleak package](https://pypi.org/project/bleak/#files), the `.whl` file in “Built Distribution”
- `.whl` is a zip file. Unzip it as usual, put `bleak` to the folder `build-common/`
- Now that you can bundle a “pure” release
- Get [Bleak winrt](https://pypi.org/project/bleak-winrt/#files), pay special attention to version, e.g.:
- `bleak_winrt-1.1.1-cp310-cp310-win32.whl` means to be used with CPython 3.10 under 32-bit Windows (or WoW64)
- Unzip it, put `bleak_winrt` to the folder `build-common/`
- Now that you can also bundle a “windows” release
- Also see [Files](#files) section about `bundle.py`
- Get an Windows embeddable Python, extract to `build-common/python-w32`
- You may remove some “bloats”, notably `libssl`, `libcrypto`, `sqlite3` and `pydoc`, of both `dll`/`pyd` files and inside `python<version>.zip`, if there are any
- Now you’re able to bundle a “windows” edition, via `python3 bundle.py -w`
- Get a [vConsole](https://www.npmjs.com/package/vconsole) script, put to `www` as `vconsole.js`
Now you're ready to debug in browsers without a dev panel, by double-tapping "Cat Printer" title in the UI
Now you’re ready to debug in browsers without a dev panel, by double-tapping status message
## Files
- `server.py` - A Web server that:
- Is single threaded & with static handler, for some reasons
- Serves static Web files, that are in folder `www`
- Opens a Web browser once launched, unless specify the `-s` command-line parameter
- Only listen to localhost, unless specify the `-a` command-line parameter
- Handles API requests via `POST`
- Tries to open a Web browser once launched, unless specify `-s`
- Only listens to localhost, unless specify `-a`
- Handles API requests via `POST` requests
- Handles frontend configuration
- Few CUPS/IPP features included
- Very basic CUPS/IPP feature included
- Interacts with `printer.py`, for the printer driver
- `printer.py` - The core printer driver:
- Have the `PrinterDriver` class, to be reused
- Have a command-line interface. Can be invoked in a shell, to do things directly
- `printer_lib/*` - Some helpers:
- These are also intended to be reused, and are in Public Domain under CC0 license
- Especially `commander.py`, which contains the printers’ BLE protocol
- `.pylintrc` - Pylint RC file:
- Include it for better experience browsing the code
- `www/main.js` - Main frontend script:
- The script for direct modification in development
- No need to care "compatibility". Transpile the scripts when release.
- No need to care “compatibility”. Transpile the scripts when release
- `www/image.js` - Image manipulation functions:
- Implementations for some grayscale/monochrome filters on a image (HTML `<canvas>` `ImageData`)
- And PBM image file format, a very simple mono bitmap format.
- Now is transpiled from `wasm/image.ts`, which is intended for WebAssembly implementation, but unfortunately slower with it
- Have some grayscale/monochrome filters for HTML `<canvas>` `ImageData`
- And PBM image file format, a very simple mono bitmap format, helpful to be read & used
- `www/main.comp.js` - Compatibility script:
- Transpiled with TypeScript, for fallback on old browsers
- Transpiled from other scripts around for falling back on old browsers
- Bundled all required scripts, see file `0-transpile.sh`
- Is not there by default. Transpile it yourself
- Isn’t there unless you transpile
- `www/i18n*` - Scripts about I18n:
- See [i18n.md](i18n.i18n/i18n.md)
- `www/*.js` - Other scripts:
- Small but useful, just look at them directly
- Most are in Public Domain
- `www/jslicense.html` - Dedicated JavaScript License information
- Most are in Public Domain under CC0 license
- `www/jslicense.html` - Dedicated JavaScript License Information, useful for user reference & LibreJS indentification
- `www/lang/*.json` - Language files for both front- & back-end
- `version` - The version tag, as a file
- Modify it to determine the version used in build scripts
- Don't leave a trailing new line
- Don’t leave a trailing new line
- `N-*.sh` - Shell files:
- Helpers for development convenience
- Quickly invoke with `./N<tab><enter>`
- `build-common/bundle.py` - Bundler for "windows", "pure" and "bare" editions
- `build-common/bundle.py` - Bundler for “windows”, “pure” and “bare” editions
- You can define what to include or not in this script, just modify directly, while trying to not alter other
- Adviced to transpile scripts before bundling
- To do the builds you should be in the build dir: `cd build-common`
- With `bleak` there you're able to bundle a "pure" edition via just `python3 bundle.py`
- In any case you're able to bundle a "bare" edition, via `python3 bundle.py -b`
- Bundle a "windows" edition with `-w` switch in place of `-b`
- You may put a version code as last parameter
- Resulting zip files will be in repo's root directory
- With `bleak` there you’re able to bundle a “pure” edition via just `python3 bundle.py`
- In any case you’re able to bundle a “bare” edition, via `python3 bundle.py -b`
- Bundle a “windows” edition with `-w` switch in place of `-b`
- You may put version tag as last parameter
- Resulting zip files will be in repo’s root directory
- `build-common/0-bundle-all.sh` - Bundle all editions at once
<!-- TODO: split to Android docs -->
- `build-android/0-build-android.sh` - The dev build script:
- Invokes `python-for-android`
- Defines many things
- Just builds using the current repo state
- **Doesn't** work out-of-the-box. Again, please wait for me to summarize the hacks...
- `build-android/3-formal-build.sh` - The "formal" build script:
- Unlike the dev version, this takes files from a "bare" edition zip
- Also unlike dev, this doesn't enforce the custom blacklist, since "bare" is already minimal
- Now it builds a "release" version. In order to be installed on Android, you need to sign it. Know more on Internet
- **Doesn’t** work out-of-the-box. Again, please wait for me to summarize the hacks...
- `build-android/3-formal-build.sh` - The “formal” build script:
- Unlike the dev version, this takes files from a “bare” edition zip
- Also unlike dev, this doesn’t enforce the custom blacklist, since “bare” is already minimal
- Now it builds a “release” version. In order to be installed on Android, you need to sign it. Know more on Internet
### Be aware that...
If there are development files that are not meant to be in this public repo, please add to `.gitignore`.
And don't put too-big files, especially binary. Not everyone have good connection to GitHub.
And don’t put big binary files, because not everyone have good connection to GitHub.
Same applies to most feature-bloated 3rd party libraries.
In our case you should try your best to avoid introducing more dev dependencies.
Tip: it's reasonable to use (invoke) a tool that is already on the system, or always accepted by users / very easy to install
Same applies to most feature-bloated 3rd-party libraries. Try your best to avoid introducing more dependencies.
Though, it’s reasonable to invoke a tool that is already on the system, or always accepted by users / very easy to install

3
printer.py
View File

@ -74,7 +74,8 @@ try:
from bleak import BleakClient, BleakScanner
from bleak.backends.device import BLEDevice
from bleak.exc import BleakError, BleakDBusError
except ImportError:
except ImportError as error:
raise error
fatal(
i18n('please-install-bleak-via-pip'),
' $ pip3 install bleak',

2
printer_lib/i18n.py
View File

@ -19,8 +19,8 @@ class I18nLib():
data: dict = {}
def __init__(self, search_path='lang', lang=None, fallback=None):
self.lang = lang or locale.getdefaultlocale()[0].replace('_', '-')
self.fallback = fallback or 'en-US'
self.lang = lang or (locale.getdefaultlocale()[0] or fallback).replace('_', '-')
with open(os.path.join(search_path, self.fallback + '.json'),
'r', encoding='utf-8') as file:
self.data = json.load(file)

2
server.py
View File

@ -78,7 +78,7 @@ class PrinterServerHandler(BaseHTTPRequestHandler):
'is_android': False,
'scan_time': 4.0,
'dry_run': False,
'energy': 0.2
'energy': 64
})
_settings_blacklist = (
'printer', 'is_android'

2
version
View File

@ -1 +1 @@
0.6.0.2
0.6.1

4
www/lang/de-DE.json
View File

@ -98,7 +98,7 @@
"all-users-and-developers": "Alle Tester & Benutzer",
"everyone-is-awesome": "Ihr seid alle fantastisch",
"license": "Lizenz",
"exiting": "Beende...",
"exiting": "Beende…",
"dark-theme": "Dunkles Design",
"high-contrast": "Hoher Kontrast",
@ -124,7 +124,7 @@
"javascript-maincompjs-description": "Transpilieren der Entwicklungsskripte für verbesserte Kompatibilität.",
"javascript-loaderjs-description": "Dynamisches Laden von Skripten und Fallbacks.",
"javascript-polyfilljs-description": "Nachrüsten von Funktionen in nicht unterstützten Browsern",
"javascript-i18nextjs-description": "I18n \"Erweiterungen\"",
"javascript-i18nextjs-description": "I18n „Erweiterungen“",
"javascript-i18njs-description": "Lokalisierung und Übersetzung",
"javascript-imagejs-description": "Bildbearbeitung",
"javascript-accessibilityjs-description": "Barrierefreiheit",

2
www/lang/en-US.json
View File

@ -142,7 +142,7 @@
"javascript-maincompjs-description": "All following development scripts, transpiled for compatibility.",
"javascript-loaderjs-description": "For dynamically loading other scripts, and fallback if there are problems.",
"javascript-polyfilljs-description": "Add features which are not supported by old browsers.",
"javascript-i18nextjs-description": "I18n \"extensions\"",
"javascript-i18nextjs-description": "I18n “extensions”",
"javascript-i18njs-description": "For internationalization (language support)",
"javascript-imagejs-description": "For canvas image manipulation",
"javascript-accessibilityjs-description": "Accessibility features",