diff --git a/.gitignore b/.gitignore
index 33676fa..dbb09c2 100644
--- a/.gitignore
+++ b/.gitignore
@@ -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
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index cb6e3ab..a26fbec 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -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.
diff --git a/build-android/0-build-android.sh b/build-android/0-build-android.sh
index b59a5d2..61bf9e9 100755
--- a/build-android/0-build-android.sh
+++ b/build-android/0-build-android.sh
@@ -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 $@
diff --git a/build-android/3-formal-build.sh b/build-android/3-formal-build.sh
index da01657..08d3d29 100755
--- a/build-android/3-formal-build.sh
+++ b/build-android/3-formal-build.sh
@@ -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 $@
diff --git a/build-android/4-sign.sh b/build-android/4-sign.sh
index 7907d09..1e055b2 100755
--- a/build-android/4-sign.sh
+++ b/build-android/4-sign.sh
@@ -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
diff --git a/build-android/README.md b/build-android/README.md
new file mode 100644
index 0000000..9f03abb
--- /dev/null
+++ b/build-android/README.md
@@ -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.
diff --git a/build-android/build-deps.txt b/build-android/build-deps.txt
new file mode 100644
index 0000000..e4a265f
--- /dev/null
+++ b/build-android/build-deps.txt
@@ -0,0 +1 @@
+async_timeout,typing-extensions,android,pyjnius,bleak
\ No newline at end of file
diff --git a/build-android/fix-ndk-execs.py b/build-android/fix-ndk-execs.py
new file mode 100644
index 0000000..bb68d9d
--- /dev/null
+++ b/build-android/fix-ndk-execs.py
@@ -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)
diff --git a/build-android/manual-steps.md b/build-android/manual-steps.md
new file mode 100644
index 0000000..2493255
--- /dev/null
+++ b/build-android/manual-steps.md
@@ -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.
+
+
+
+Expand Comparison
+
+| | Minimal Ubuntu | Ubuntu | [Artix](https://artixlinux.org/) |
+| :-------------------------- | :------------: | :----: | :------: |
+| Base system1 | | ✓ | ✓ |
+| Pkg diversity | ✓ | ✓ | ✓ |
+| Fresh pkg2 | | | ✓ |
+| Less hassle3 | ✓ | | ✓ |
+| Maintainability4 | ✓ | | |
+
+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.)
+
+
+
+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
+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 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/
+# <0>
+./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/
+# <3>
+# 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.
diff --git a/build-common/bundle.py b/build-common/bundle.py
index 89d5a50..f656084 100644
--- a/build-common/bundle.py
+++ b/build-common/bundle.py
@@ -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
diff --git a/development.md b/development.md
index 0e26bdc..08714de 100644
--- a/development.md
+++ b/development.md
@@ -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.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
+
+- 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.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 `