Improve onboarding materials

README.md

@@ -8,51 +8,77 @@
 </p>
 
 
-This repo contains bindings for libinkview, which is used by pocketbook devices.
+This repo contains bindings for `libinkview`, which is used by pocketbook devices.
 
-We load libinkview dynamically rather than linking it so that users of this
-crate don't have to setup the pocketbook SDK. Instead you just need to
-cross-compile to `armv7-unknown-linux-gnueabi.2.23` (`cargo zigbuild` works well
-for this) and your binary will run on a pocketbook E-Reader.
+## Overview
 
-Also in this repo is `inkview-slint` which provides a slint `Backend` that works
-with inkview. And a demo application `inkview-slint-demo`.
+- `inkview` is the core of the project.
+It dynamically loads `libinkview` rather than linking it statically, so that users of this
+crate don't have to setup the pocketbook SDK.
+Instead, one needs to cross-compile to `armv7-unknown-linux-gnueabi.2.23`
+(`cargo zigbuild` works well for this) and the binary will run on a pocketbook E-Reader.
 
-`inkview-eg` is a [embedded-graphics-core](https://crates.io/crates/embedded-graphics-core) driver for inkview-rs.
+- `inkview-eg` is an [embedded-graphics-core](https://crates.io/crates/embedded-graphics-core) driver for `inkview-rs`.
 
-## Prerequisites
+- `inkview-slint` provides a backend for the [slint](https://github.com/slint-ui/slint)
+crate that works with `inkview`, with a respective demo project under `examples/inkview-slint-demo`.
 
-[Zig](https://ziglang.org/learn/getting-started/#installing-zig) must be installed.
+The subprojects may contain examples that lay under `examples/` subfolders (e.g. `inkview/examples`)
 
-To run recipes from the justfile, install the [just](https://github.com/casey/just) command runner.
+## Prerequisites (Set-up)
 
-Available recipes can be listed with:
+1. [Zig](https://ziglang.org/learn/getting-started/#installing-zig) must be installed.
+1. [just](https://github.com/casey/just) command runner must be installed.
+    The build and deployment helper commands are defined in the [justfile](./justfile).
+    Available recipes can be listed with:
+    ```bash
+    just --list
+    ```
+1. Set-up a reproducible build environment for the target `armv7-unknown-linux-gnueabi.2.23` (two ways):
+    1. (EITHER - recommended) one must install [NIX](https://nixos.org/download/) +
+    [direnv](https://direnv.net/docs/installation.html) +
+    [devenv](https://devenv.sh/getting-started/).
+        - This way Nix installs a sandbox environment with the exact cross-compilation tools required for the e-reader, 
+        while direnv automatically injects them into your shell the moment you enter the project directory.
+    1. (EITHER) Execute `just prerequisites` to install the `armv7-unknown-linux-gnueabi` rustc target and `cargo-zigbuild` globally
+        - **NOTE:** this way has proved to be problematic in use on macOS when building `inkview-slint` project
+
+## Build
+
+To build a binary crate located in this repo, run:
 
 ```bash
-just --list
+just pb_sdk_version=<sdk-version> build-app <name>
 ```
 
-Then execute the following to install the `armv7-unknown-linux-gnueabi` rustc target and `cargo-zigbuild`:
-
+For example:
 ```bash
-just prerequisites
+just pb_sdk_version=6.8 build-app inkview-slint
 ```
 
-## Build
+**NOTE:** while the demo projects lay in the [./examples/](./examples/) folder they are still apps,
+and therefore should be built with the `build-app` command
 
-To build a binary crate located in this repo, run:
+To build an example, run:
 
 ```bash
-just pb_sdk_version=<sdk-version> build-app <name>
+just pb_sdk_version=<sdk-version> build-example <crate> <name>
+```
+
+For example:
+```bash
+just pb_sdk_version=6.8 build-example inkview hello_world
 ```
 
-To build an example:
+By default, any build is going to be done with the `debug` profile.
+Changing the profile to `release`, one should add the `cargo_profile=release` argument.
 
+For example:
 ```bash
-just pb_sdk_version=<sdk-version> build-example <crate> <name>
+just pb_sdk_version=6.8 cargo_profile=release build-app inkview-slint-demo
 ```
 
-## Deploy a binary
+## Deployment
 
 To deploy a built binary to the device over USB, run the following,  
 assuming the device is connected and appears in path `/run/media/$USER/<pb-device>`:
@@ -64,6 +90,22 @@ so for example: `examples/hello_world`
 just pb_device=<your-device> deploy-usb <path-to-binary> <target-name>
 ```
 
-## Generate bindings
+For example:
+```bash
+just cargo_profile=release pb_device=PB632 deploy-usb inkview-slint-demo application.app
+```
+
+For more information take a look at [utils README.md](./utils/README.md)
+
+## Bindings generation
 
 See documentation for the `generate-bindings` just recipe.
+
+## New `inkview-rs` projects templating
+
+Setting up new projects that make use of `inkview-rs` with properly configured linking, building, and deployment from scratch can be quite tedious.
+Often, it would require pretty much the same preconfiguration: `devenv.nix` config, justfile with the basic build and deploy helper comands, etc.
+
+To simplify this repeated process, one can make use of the adjacent templating project [inkview-rs-templates](https://github.com/ihrfv/inkview-rs-templates).
+It only requires `cargo-generate` to be installed, and allows you to create preconfigured basic projects for vanilla `inkview-rs`, `inkview-eg`, and `inkview-slint`.
+

utils/README.md

@@ -31,7 +31,28 @@ Copy and start `app-receiver.app` on the pocketbook device, then launch:
 ./app-sender.sh <app-binary> <remote-app-name> <remote-ip>
 ```
 
-## SSH Dropbear Server
+## SSH
+If you want to ssh to your device, send applications to it and listen for stdin messages,
+then you have 2 ways:
+1. Via KOReader (no need to root your device)
+2. By setting up your own SSH Dropbear Server on the device (the device must be rooted)
+
+### KOReader as bypass for SSH connection
+
+[KOReader](https://github.com/koreader/koreader/releases) apart from being a third party read
+it also contains some networking functionality, namely, it allows for establishing SSH connection with the device.
+There is no need to root your device.
+
+**NOTE:** Such ssh connection DOES NOTE give you root permissions.
+Nevertheless, it is sufficient to deploy your app as following (it goes with no saying that before you have to register your public key):
+
+```bash
+scp -P 2222 -o HostKeyAlgorithms=+ssh-rsa target/armv7-unknown-linux-gnueabi/release/inkview-slint-demo reader@<device-ip>:/mnt/ext1/applications/application.app.stage && \
+ssh -p 2222 -o HostKeyAlgorithms=+ssh-rsa reader@<device-ip> \
+'sh -c "killall application.app; mv /mnt/ext1/applications/application.app.stage /mnt/ext1/applications/application.app; /mnt/ext1/applications/application.app"'
+```
+
+### Custom SSH Dropbear Server
 
 The device must be rooted (see [here](https://github.com/ezdiy/pbjb)).
 
@@ -51,3 +72,10 @@ Host pocketbook
   PubkeyAuthentication=no
   StrictHostKeyChecking=no
 ```
+
+Example:
+```bash
+scp -o HostKeyAlgorithms=+ssh-rsa target/armv7-unknown-linux-gnueabi/release/inkview-slint-demo root@<device-ip>:/mnt/ext1/applications/application.app.stage && \
+ssh -o HostKeyAlgorithms=+ssh-rsa root@<device-ip> \
+'sh -c "killall application.app; mv /mnt/ext1/applications/application.app.stage /mnt/ext1/applications/application.app; /mnt/ext1/applications/application.app"'
+```