Better documentation

README.md

@@ -1,6 +1,16 @@
 # reStream
 
-Snappy reMarkable screen sharing over SSH.
+reMarkable screen sharing over SSH.
+
+## Usage
+
+1. Connect your reMarkable with the USB cable.
+2. Make sure you can [open an SSH connection](https://remarkablewiki.com/tech/ssh).
+3. Run `./reStream.sh`.
+4. If you don't have `zstd` installed, it will ask you to copy it. You can answer no, and it will fall back to gzip (which will be slower).
+5. A screen will pop-up on your local machine, with a live view of your reMarkable!
+
+If you have problems, don't hesitate to [open an issue](https://github.com/rien/reStream/issues/new) or [send me an email](mailto:rien.maertens@posteo.be).
 
 ## Requirements
 
@@ -9,6 +19,17 @@ On your **host** machine:
 - ffmpeg (with ffplay)
 - ssh
 
-On your **reMarkable** it is recommended to install [zstd](https://zstd.net) (`opkg install zstd` if you have [entware](https://github.com/evidlo/remarkable_entware) installed.) to have a smoother experience (sub-second latency). However, if you don't have it installed `reStream` will fall back to `gzip` which is installed by default.
+On your **reMarkable** nothing is needed, unless you want...
 
+### Sub-second latency
+
+To achieve sub-second latency, you'll need [zstd](https://zstd.net) on your
+host and on your reMarkable. 
+
+You can install `zstd` on your host with your usual package manager. On Ubuntu,
+`apt install zstd` will work.
+
+On your **reMarkable** you can do `opkg install zstd` if you have [entware](https://github.com/evidlo/remarkable_entware) installed. If you don't you can use the binary provided in this repository. In general you shouldn't trust binaries strangers on the internet provide to you, but I provide the option if you don't want the hassle of installing entware.
+
+You can copy the binary to your remarkable with `scp zstd root@10.11.99.1:/home/root/zstd`.
 

reStream.sh

@@ -1,34 +1,64 @@
 #!/bin/sh
-ssh_host="root@10.11.99.1"
-landscape=true
 
+# these are probably the only two parameters you need to change
+ssh_host="root@10.11.99.1" # location of the remarkable
+landscape=true             # set to false if you want it horizontal
+
+# technical parameters
 width=1408
 height=1872
 bytes_per_pixel=2
 loop_wait="true"
 loglevel="info"
 
+# check if we are able to reach the remarkabl
 if ! ssh "$ssh_host" true; then
     echo "$ssh_host unreachable"
     exit 1
 fi
 
-# Gracefully degrade to gzip if zstd is not present
-if which zstd && ssh "$ssh_host" "[ -f /opt/bin/zstd ]"; then
-    compress="/opt/bin/zstd"
-    decompress="zstd -d"
-else
+fallback_to_gzip() {
+    echo "Falling back to gzip, your experience may not be optimal."
+    echo "Go to https://github.com/rien/reStream/#sub-second-latency for a better experience."
     compress="gzip"
     decompress="gzip -d"
+    sleep 2
+}
+
+# check if zstd is present on remarkable
+if ssh "$ssh_host" "[ -f /opt/bin/zstd ]"; then
+    compress="/opt/bin/zstd"
+elif ssh "$ssh_host" "[ -f /home/root/zstd ]"; then
+    compress="/home/root/zstd"
+fi
+
+# gracefully degrade to gzip if zstd is not present on remarkable or host
+if [ -z "$compress" ]; then
+    echo "Your remarkable does not have zstd."
+    fallback_to_gzip
+elif ! which zstd; then
+    echo "Your host does not have zstd."
+    fallback_to_gzip
+else
+    decompress="zstd -d"
 fi
 
 
+
+
+# calculte how much bytes the window is
 window_bytes="$(($width*$height*$bytes_per_pixel))"
+
+# rotate 90 degrees if landscape=true
 landscape_param="$($landscape && echo '-vf transpose=1')"
+
+# read the first $window_bytes of the framebuffer
 head_fb0="dd if=/dev/fb0 count=1 bs=$window_bytes 2>/dev/null"
+
+# loop that keeps on reading and compressing, to be executed remotely
 read_loop="while $head_fb0; do $loop_wait; done | $compress"
 
-set -e
+set -e # stop if an error occurs
 
 ssh  "$ssh_host" "$read_loop" \
     | $decompress \