diff --git a/README.md b/README.md index 9507b6c..9a2a3c0 100644 --- a/README.md +++ b/README.md @@ -8,51 +8,77 @@

-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= build-app ``` -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= build-app +just pb_sdk_version= build-example +``` + +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= build-example +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/`: @@ -64,6 +90,22 @@ so for example: `examples/hello_world` just pb_device= deploy-usb ``` -## 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`. + diff --git a/utils/README.md b/utils/README.md index 25739fb..b042362 100644 --- a/utils/README.md +++ b/utils/README.md @@ -31,7 +31,28 @@ Copy and start `app-receiver.app` on the pocketbook device, then launch: ./app-sender.sh ``` -## 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@:/mnt/ext1/applications/application.app.stage && \ +ssh -p 2222 -o HostKeyAlgorithms=+ssh-rsa reader@ \ +'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@:/mnt/ext1/applications/application.app.stage && \ +ssh -o HostKeyAlgorithms=+ssh-rsa root@ \ +'sh -c "killall application.app; mv /mnt/ext1/applications/application.app.stage /mnt/ext1/applications/application.app; /mnt/ext1/applications/application.app"' +```