RemoteInk

A tool for using PocketBook E-Ink reader as a computer monitor on Linux

Description

This application is designed for people who like to use E-Ink displays. It's suitable for tasks where a color monitor and high reaction time aren't necessary: reading and writing texts, programming, etc.

Photo: Using Geany on Linux Mint with RemoteInk

Features

You can:

Connect a reader to a computer using Wi-Fi or USB (if supported by your device)
Configure connection parameters in UI on the reader
Change the reader's screen orientation (portrait or landscape)
Select which part of the monitor is visible or zoom it
Track windows (active window is always visible) and save scale for each of them
Easily switch between windows
Adjust active window's size to dimensions of the reader's screen
See a cursor and restrict its movements to the area visible on the reader
Invert screen colors
Customize keyboard shortcuts for most of the actions above
Set a password for a connection

Requirements

Computer: OS Linux with X11 window system.

Both typical computers (with i686/amd64 architecture) and Raspberry Pi are supported.
Reader: Pocketbook Pro/Touch series (that is, most of the Pocketbook models with an E-Ink screen).

In particular, users have successfully run RemoteInk on the following devices:
- Pocketbook Aqua 2 (report + patch to unshift the screen)
- PocketBook Inkpad (via Wi-Fi, report)
- PocketBook Inkpad 3 (Wi-Fi only, report)
- Pocketbook Pro 902 (via Wi-Fi, report)
- Pocketbook Pro 912 (report 1, report 2)
- PocketBook Touch (the developer's device, see the photo above)
- PocketBook Touch 2 (report)
- PocketBook Touch HD 3 (report)
- PocketBook Touch Lux 3 (report)
Feel free to make PRs with additions to this list if you manage to run RemoteInk on another device.

Warning: Your E-Ink display may not be designed to be updated so often. The developer of this program is not responsible for possible damage to your device.

Installation

Server

Install required dependencies:

Debian and its derivatives (Ubuntu, Linux Mint, etc.):

  $ sudo apt-get install git build-essential libfontconfig1-dev libimlib2-dev libxcb1-dev libx11-dev libxcb-keysyms1-dev libxcb-shm0-dev libxcb-xfixes0-dev fonts-freefont-ttf

Fedora:

  $ sudo dnf install git gcc make imlib2-devel fontconfig-devel libxcb-devel libX11-devel xcb-util-keysyms-devel gnu-free-sans-fonts

Arch Linux:

  $ sudo pacman -S git base-devel fontconfig imlib2 libxcb libx11 xcb-util-keysyms ttf-freefont

If neither of these commands suits you, you can try to find similar packages in repositories of your system.

Clone the repository and build the daemon:

 $ git clone https://github.com/borzunov/remoteink.git
 $ cd remoteink/server
 $ make

Install binaries and create a config directory:
```
 $ sudo make install
```
Note that uninstall command is also available:
```
 $ sudo make uninstall
```
Check shortcuts scheme. The defaults are designed for keyboards with numpad (see full description). If you don't have numpad or this scheme will be uncomfortable for you, you can change it as described here.

Note that these shortcuts must not overlap with other system-wide shortcuts.
Set up a password to the server:
```
 $ sudo remoteinkd passwd
```

Client

Place remoteink.app into applications/ folder in your reader's memory (the folder may be hidden on some devices).

Compiling the client from sources (optional)

Use Sergei Vlasov's Pocketbook Pro SDK and the following commands:

$ cd remoteink/client
$ make BUILD=arm_gnueabi

This will create executable obj_arm_gnueabi/remoteink.app.

Update: Since the version of Pocketbook Pro SDK by Sergei Vlasov is not available for download anymore, you may want to use the official Pocketbook Pro SDK. @calcreg has posted instructions on how to run the client inside an emulator from this version of the SDK on a Linux desktop.

How to use

Connection via Wi-Fi

Set up a wireless network, connect to it on the computer and find out its IP address. If you know a corresponding network interface (wlan0 in this example), it can be done using the following command:

 $ ifconfig
 [...]
 wlan0     Link encap:Ethernet  HWaddr aa:bb:cc:dd:ee:ff  
 		  inet addr:192.168.0.101  Bcast:192.168.0.255  Mask:255.255.255.0
 		  inet6 addr: xxxx::xxx:xxxx:xxxx:xxxx/64 Scope:Link
 		  UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
 [...]

Run the server using the command:
```
 $ sudo remoteinkd start
```
You can check that the server is started using the command:
```
 $ sudo remoteinkd status
 RemoteInk v0.2 - Server
 [*] remoteinkd is running (PID 1234)
 
```
If the command doesn't show that server is running, go to Troubleshooting section.
Open remoteink application on the reader. Use an interface (it supports control via touchscreen or physical keys) to enter server's IP and password and press "Connect" button. Select your network if you weren't connected to it yet.

If you don't see monitor contents, go to Troubleshooting.
After work you can stop the daemon:
```
 $ sudo remoteinkd stop
```
Or kick the current client (it's also possible to disconnect using "Back" reader's key):
```
 $ sudo remoteinkd kick
```

Connection via USB

Working via USB is implemented using g_ether.ko Linux kernel module. The module is installed on the some of the compatible readers and must present on the server-side.

On the reader open menu Settings -> Connectivity -> USB Mode and select Network over USB.
Connect the reader via a USB cable. If the described kernel module is present, a new network interface will appear. Then you can find out its IP address and follow instructions for a Wi-Fi network above.

Advice

Try to disable cursor blinking when editing texts. It may reduce the reader's screen updates count.

Default shortcuts scheme

A reader's screen is smaller than a computer's monitor, so we can see only part of the monitor on the reader (let's call it "the frame"). Shortcuts are introduced to comfortably move the frame during work with windows on the computer. This section describes purposes of each shortcut and keys corresponding to it in default scheme.

There are two modes in the application: when window tracking is enabled and when not (default mode can be changed in a config file). If window tracking is enabled, switching between windows causes moving the frame in such a way that active window stays in the center of the reader's screen. If the window doesn't fit into the screen, initially only its left top part is visible. Nevertheless, you can move the frame relative to the active window.

Ctrl+Alt+Num 0 – Toggle window tracking

Alt+Tab – Switch active window (DE's shortcut)

Ctrl+Alt+D – Show desktop (DE's shortcut)

Ctrl+Alt+Num 2/4/6/8 – Move the frame

Ctrl+Alt+Num 5 – Reset frame relative position to default

Also, you can zoom the visible image. The scale is stored separately for each window and different modes (default scale for each mode can be changed in the config). Default scale for a mode with disabled window tracking is so small that you can see the entire desktop. So, this mode can be used if you want to switch between windows using a mouse, move windows, look on desktop panels or the system tray.

Ctrl+Alt+Num 3/9 – Zoom

Ctrl+Alt+Num 1 – Reset scale to default for this mode

If an opened window doesn't fit into the reader's screen, you can adjust window size as necessary.

Ctrl+Alt+Num 7 – Adjust window size (if possible)

Some additional opportunities are available. Generally, usage of a mouse via the slow reader's screen is inconvenient, but there is a cursor capturing mode when the cursor becomes visible, and its movement is bounded in the captured frame.

Ctrl+Alt+Num Del – Toggle cursor capturing

Also, there is an opportunity to invert screen colors, but a shortcut for it is disabled by default.

Configuration

Different settings (such as a shortcuts scheme, server's port or maximal FPS value) can be changed in /etc/remoteinkd/config.ini. The config has comments that help you to understand purpose and format of each option.

The password's hash is stored in /etc/remoteinkd/passwd and can be changed using the command:

$ sudo remoteinkd passwd

Note that you should restart the daemon so as to it uses new configuration and password.

Troubleshooting

Check whether connection is not blocked

A firewall can block a reader's connection. You should add a rule that allows connections to remoteinkd (default port is 9312/tcp) or try to disable the firewall temporarily.

Look up error messages

Error messages can be displayed during daemon starting and controlling (don't forget to use sudo during these operations). Some connection errors can be displayed in the client-side.

Also, at the time of the daemon is running it uses syslog to log information and error messages. You can check the log file to find out a reason of occurred errors, for example:

$ grep remoteinkd /var/log/syslog | tail
[...]
Feb 13 19:54:22 hostname remoteinkd: Unknown modifier in shortcut "Ctrk+Alt+KP_8"

In this case, the daemon informs that one of shortcut's modifiers is incorrect. You should check the correctness of defined shortcuts in the config (actually, there's a typo in a modifier name - Ctrk instead of Ctrl).

If monitor's color depth is unsupported

Only 24-bit color depth is supported. You can reconfigure your distribution to use this depth. For example, in Raspbian running on Raspberry Pi you can add the following lines to /boot/config.txt (and restart the system):

framebuffer_depth=32
framebuffer_ignore_alpha=1

If shortcuts don't work well

Shortcuts are tested only in traditional window managers. If you use less common WM, try to disable tiling mode.

If the daemon's CPU usage is too much

It is possible on machines with weak processors (including Raspberry Pi). Try to halve the value of MaxFPS parameter in the config.

Alternatives

You can prefer a VNC client for Pocketbook created by othb08me09zp (and slightly modified by me). It uses the popular cross-platform protocol but may be less convenient for managing windows during daily work.

Download | Discussion (in Russian)

borzunov/remoteink

borzunov

Reviews

Repository Details