Cat-Printer/development.md

Development

Overview

This application have a Client/Server module, but it's 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.

And the frontend is in a "old good" way, that use no "framework".
It needs roddeh-i18n lib for localization, and optionally vConsole for debugging on mobile.

My workspace stack is Linux/GNU/Artix/KDE/VSCodium, if you're interested.
For Android, GNU/Linux is required, though.

The Android version is built with python-for-android.
In our case it's NOT something easy, 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

Get Dependencies

Basic

Just clone this repo first!

1. Get Bleak BLE lib:
   pip install bleak
2. Grab i18n.js here, put to www as i18n.js

You are already well done for basic development. See files section for what all the files do.
For more, read on...

Additional

Sorry, I'm not a dev package manager enthusiast.

If there are something better to organize these, feel free to discuss in issue.

• 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 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
• Grab i18n.js typings index.d.ts from here, put to www as i18n.d.ts
  In the file, replace the last line:
  export = roddeh_i18n;
  with:
  declare var i18n = roddeh_i18n;
  Now you are ready to do more with i18n lib with the typing hint
• Get a 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

Files

• server.py - A Web server that:

  • Is single threaded, to work with Android/pyjnius
  • 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
  • Handles frontend configuration
  • 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

• .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.

• 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.

• www/main.comp.js - Compatibility script:

  • Transpiled with TypeScript, for fallback on old browsers
  • Bundled all required scripts, see file 0-transpile.sh
  • Is not there by default. Transpile it yourself

• www/*.js - Other scripts:

  • Small but useful, just look at them directly

• www/jslicense.html - Dedicated JavaScript License information

• www/lang/*.json - Languages

• 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

  • You can define what to include or not in this script, just modify directly, while trying to not alter other
  • 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

• build-common/0-bundle-all.sh - Bundle all editions at once

• 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 needs a pre-built "bare" edition zip, and should be passed a version id (like 0.1.0)
  • Also unlike dev, this doesn't enforce the custom blacklist, since "bare" is already minimal

Be aware that...

If there are intermediate development files that are not meant to be in this public repo, please add to .gitignore