rmview/README.md

154 lines
7.4 KiB
Markdown
Raw Normal View History

2020-05-01 21:50:08 +01:00
# rMview: a fast live viewer for reMarkable
2020-09-11 17:09:21 +02:00
[![Demo](https://raw.githubusercontent.com/bordaigorl/rmview/vnc/screenshot.png)][demo]
2020-05-03 22:12:31 +01:00
2020-05-30 00:13:18 +01:00
2020-09-11 17:04:35 +02:00
## Features
* Demo [:rocket: here][demo]
* Fast streaming of reMarkable's screen to a window in your computer
* UI for zooming, panning, rotating
* Pen tracking: a pointer follows the position of the pen when hovering on the reMarkable
* Clone a frame into separate window for reference
* Save screenshot as PNG
> :loudspeaker: **Volunteers needed**: if you have experience with producing binary bundles with pyQt, and feel like contributing to the project, drop me a line!
2020-09-12 21:41:30 +02:00
> :warning: **WARNING** :warning::
> rMview has only been tested with reMarkable 1.
> Support for reMarkable 2 may come once it gets wider diffusion.
2020-09-11 17:04:35 +02:00
## Installation
2020-09-12 21:41:30 +02:00
1. You will need [Python3][py3] on your computer.
2020-09-11 17:04:35 +02:00
> :warning: Please make sure `pip` is pointing to the Python3 version if your system has Python2 as well.
If not, use `pip3` instead of `pip` in what follows.
2020-05-30 00:13:18 +01:00
2020-09-11 17:04:35 +02:00
2. The easiest installation method is by using pip:
2020-05-30 00:13:18 +01:00
2020-09-11 17:04:35 +02:00
pip install .
2020-05-30 00:13:18 +01:00
2020-09-11 17:04:35 +02:00
which will install all required dependencies and install a new `rmview` command.
Alternatively you may want to install the dependencies ([PyQt5][pyqt5], [Paramiko][paramiko], [Twisted][twisted]) with `pip` manually.
2020-05-30 00:13:18 +01:00
2020-05-01 21:50:08 +01:00
2020-09-11 17:04:35 +02:00
3. On the reMarkable itself you need to install [rM-vnc-server][vnc] and its dependency [mxc_epdc_fb_damage](https://github.com/peter-sa/mxc_epdc_fb_damage).
Instructions can be found in the [wiki](https://github.com/bordaigorl/rmview/wiki/How-to-run-the-VNC-based-version).
This last step will be automated in the near future.
2020-05-01 21:50:08 +01:00
2020-09-11 17:04:35 +02:00
To run the tool after installation just run `rmview` from a console.
2020-05-01 21:50:08 +01:00
2020-09-11 17:04:35 +02:00
> :warning: **WARNING** :warning::
> If you use [Anaconda][anaconda], please install the dependencies via `conda` (and not `pip`).
2020-05-01 21:50:08 +01:00
2020-09-11 17:04:35 +02:00
Tested with Python 3.8.2, PyQt 5.14.2, MacOs 10.15.4, reMarkable firmware 2.1.1.3.
## Usage and configuration
You can invoke the program with
rmview [config]
2020-05-01 21:50:08 +01:00
the optional `config` parameter is the filename of a json configuration file.
If the parameter is not found, the program will look for a `rmview.json` file in the current directory, or, if not found, for the path stored in the environment variable `RMVIEW_CONF`.
If none are found, or if the configuration is underspecified, the tool is going to prompt for address/password.
2020-09-11 17:04:35 +02:00
### Configuration files
2020-09-11 02:02:54 +02:00
The supported configuration settings are below.
Look in file `example.json` for an example configuration.
All the settings are optional.
| Setting key | Values | Default |
| ------------------------ | ------------------------------------------------------- | ------------- |
| `ssh` | Connection parameters (see below) | `{}` |
| `orientation` | `"landscape"`, `"portrait"`, `"auto"` | `"landscape"` |
| `pen_size` | diameter of pointer in px | `15` |
2020-09-11 17:04:35 +02:00
| `pen_color` | color of pointer and trail | `"red"` |
2020-09-11 02:02:54 +02:00
| `pen_trail` | persistence of trail in ms | `200` |
| `background_color` | color of window | `"white"` |
2020-09-11 17:04:35 +02:00
| `hide_pen_on_press` | if true, the pointer is hidden while writing | `true` |
| `show_pen_on_lift` | if true, the pointer is shown when lifting the pen | `true` |
2020-09-11 02:02:54 +02:00
Connection parameters are provided as a dictionary with the following keys (all optional):
| Parameter | Values | Comments |
| ------------------------ | -------------------------------------- | ------------------------------- |
| `address` | IP of remarkable | tool prompts for it if missing |
| `username` | username for ssh access on reMarkable | default: `"root"` |
| `key` | Local path to key for ssh | not needed if password provided |
| `password` | Password provided by reMarkable | not needed if key provided |
| `timeout` | connection timeout in seconds | default: 1 |
| `insecure_auto_add_host` | ignores the check on the fingerprint | default: `false` |
:warning: **Connecting after an update:**
An update to the reMarkable tablet would change its "fingerprint" i.e. the identifier that signals we are connecting to the expected device (and not somebody impersonating it).
When this happens you may get an error message upon connection.
There are two main ways to fix this:
1. Change your `.known_hosts` file to match the new fingerprint (you can get instructions by connecting manually via ssh).
2. Set the `insecure_auto_add_host` setting to `true`, which will make rmview ignore the check.
This is not recommended unless you are in a trusted network.
:warning: **Key format error:**
If you get an error when connect using a key, but the key seems ok when connecting manually with ssh, you probably need to convert the key to the PEM format (or re-generate it using the `-m PEM` option of `ssh-keygen`). See [here](https://github.com/paramiko/paramiko/issues/340#issuecomment-492448662) for details.
2020-11-12 21:33:25 +01:00
2020-05-01 21:50:08 +01:00
## To Do
- [ ] Settings dialog
- [ ] About dialog
- [ ] Pause stream of screen/pen
2020-09-11 17:04:35 +02:00
- [ ] Binary bundles for Window, Linux and MacOs (PyInstaller?)
2020-05-02 16:43:44 +01:00
- [ ] Add interaction for Lamy button? (1 331 1 down, 1 331 0 up)
2020-05-30 00:13:18 +01:00
- [ ] Remove dependency to Twisted in `vnc` branch
2020-05-01 21:50:08 +01:00
2020-09-11 17:04:35 +02:00
## Legacy reStreamer-like version
There are two versions of rMview, presenting the same interface but using different back-ends (thus requiring different setups on the reMarkable):
* The "VNC-based" version, in the [`vnc` branch][vnc-branch] (default)
* The "reStreamer-like" version, in the [`ssh` branch][ssh-branch]
In my tests, the VNC version is a clear winner.
The `ssh` branch of this repo hosts the reStreamer-like version for those who prefer it, but I am not planning to update it.
2020-05-01 21:50:08 +01:00
## Credits
I took inspiration from the following projects:
- [QtImageViewer](https://github.com/marcel-goldschen-ohm/PyQtImageViewer/)
- [remarkable_mouse](https://github.com/Evidlo/remarkable_mouse/)
- [reStream](https://github.com/rien/reStream)
2020-05-30 00:13:18 +01:00
- [rM-vnc-server](https://github.com/peter-sa/rM-vnc-server)
- [VNC client](https://github.com/sibson/vncdotool) originally written by Chris Liechti
2020-05-01 21:50:08 +01:00
2020-05-02 16:43:44 +01:00
Icons adapted from designs by Freepik, xnimrodx from www.flaticon.com
2020-05-01 21:50:08 +01:00
2020-09-11 17:25:11 +02:00
Thanks to @adem amd @ChrisPattison for their [PRs](https://github.com/bordaigorl/rmview/issues?q=is%3Apr+is%3Aclosed).
2020-05-03 22:11:58 +01:00
2020-05-04 23:05:32 +01:00
## Disclaimer
2020-05-03 22:11:58 +01:00
This project is not affiliated to, nor endorsed by, [reMarkable AS](https://remarkable.com/).
2020-05-05 22:14:53 +01:00
**I assume no responsibility for any damage done to your device due to the use of this software.**
2020-05-03 22:11:58 +01:00
2020-05-01 21:50:08 +01:00
## Licence
GPLv3
2020-05-30 00:13:18 +01:00
[vnc]: https://github.com/peter-sa/rM-vnc-server
2020-09-11 17:04:35 +02:00
[demo]: https://www.reddit.com/r/RemarkableTablet/comments/gtjrqt/rmview_now_with_support_for_vnc/
[ssh-branch]: https://github.com/bordaigorl/rmview/tree/ssh
[vnc-branch]: https://github.com/bordaigorl/rmview/tree/vnc
[py3]: https://www.python.org/downloads/
[anaconda]: https://docs.anaconda.com/anaconda
[pyqt5]: https://www.riverbankcomputing.com/software/pyqt/
[paramiko]: http://www.paramiko.org/
[twisted]: https://twistedmatrix.com/trac/