Skip to content

Commit e724664

Browse files
committed
Improve README presentation and troubleshooting
1 parent 28ef43c commit e724664

2 files changed

Lines changed: 52 additions & 42 deletions

File tree

‎KOReader Logo.png‎

996 KB
Loading

‎README.md‎

Lines changed: 52 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
<div align="center">
22

3+
<img src="KOReader%20Logo.png" alt="KOReader Remote logo" width="220">
4+
35
# KOReader Remote
46

57
**Turn pages and control KOReader from your phone browser.**
@@ -11,7 +13,7 @@
1113

1214
⭐ **If this plugin is useful to you, starring the repository helps a lot.** ⭐
1315

14-
https://github.com/user-attachments/assets/f81e5089-8f5f-4a0a-93cc-433873eff57c
16+
[https://github.com/user-attachments/assets/5f46e15f-ffde-4b26-80c3-23264d424e81](https://github.com/user-attachments/assets/e6ffbf5f-6218-4887-b6f7-f912cd8d8683)
1517

1618
</div>
1719

@@ -32,71 +34,79 @@ The whole project was mostly vibe-coded -- okay, basically all of it. It
3234
started as a tiny page-turn experiment and slowly became a real KOReader
3335
plugin. =)
3436

35-
## 🚀 Start here
36-
37-
### What you need
37+
## ✅ Requirements
3838

39-
- KOReader and a device that permits external KOReader plugins
40-
- Your reader and phone on the same local network
41-
- A network that allows devices to communicate directly
42-
- A jailbroken device where the platform requires one
39+
- KOReader installed
40+
- A device that permits KOReader plugins
41+
- Reader and phone on the same local network
42+
- Direct device-to-device communication on that network
43+
- Jailbreak access where required by the platform
4344

4445
Guest Wi-Fi networks often block local device-to-device traffic.
4546

46-
### Install and pair
47+
## 🚀 Start here
4748

48-
1. Download and extract `koreaderremote-v*.zip` from the
49-
[latest release](https://github.com/helitra/koreader-remote/releases/latest).
50-
2. Copy `koreaderremote.koplugin` into KOReader's plugin directory:
49+
1. Download the latest `koreaderremote-v*.zip` from
50+
[Releases](https://github.com/helitra/koreader-remote/releases/latest).
51+
2. Extract the ZIP and copy the complete `koreaderremote.koplugin` folder to:
5152

5253
```text
5354
Kindle: koreader/plugins/
5455
Kobo: .adds/koreader/plugins/
5556
```
5657

57-
3. Restart KOReader, open a book, then select:
58+
3. Restart KOReader and open a book.
59+
4. Select **Tools -> KOReader Remote -> Start remote server**.
60+
5. Select **Show QR code** and scan it with your phone.
5861

59-
```text
60-
Tools -> KOReader Remote -> Start remote server
61-
```
62+
The QR code opens a local address such as `http://192.168.1.42:8081/`.
6263

63-
4. Select **Show QR code** and scan the code with your phone.
64+
## ✨ Features
6465

65-
The QR code opens a local address such as `http://192.168.1.42:8081/`.
66+
- Turn pages with large touch controls.
67+
- Use keyboard arrow keys when available.
68+
- Browse, search, sort, and open bookmarks, highlights, and notes.
69+
- Open detected EPUB footnotes.
70+
- Edit and sync the active KOReader note draft.
71+
- Control supported frontlight, brightness, warmth, and night mode settings.
72+
- Trigger a full-screen refresh on supported E-Ink devices.
73+
- Use OLED mode for a pure-black interface.
74+
- Recover the connection after standby and Wi-Fi reconnects.
75+
- Start the server automatically with KOReader.
76+
- No phone app, account, cloud service, or background GitHub polling.
6677

67-
## ✨ What it does
78+
## 🛠️ Troubleshooting
6879

69-
### Read comfortably
80+
### “Remote UI missing”
7081

71-
- Large thumb-friendly previous/next page controls and keyboard arrow keys
72-
- Open the next detected EPUB footnote from the current page
73-
- Browse, search, sort, and jump to bookmarks, highlights, and notes
74-
- Return to the reading position after inspecting annotations
75-
- Optional pure-black OLED mode
82+
The plugin cannot find `web/index.html`. Make sure the complete plugin folder
83+
was copied and that the file exists at:
7684

77-
### Control supported devices
85+
```text
86+
Kindle: koreader/plugins/koreaderremote.koplugin/web/index.html
87+
Kobo: .adds/koreader/plugins/koreaderremote.koplugin/web/index.html
88+
```
7889

79-
- Front light, brightness, warmth, night mode, and full-screen refresh
80-
- Presets plus precise one-percent adjustment with gentle hold-to-repeat
81-
- Controls appear only when KOReader reports support for the device
90+
Download the ZIP again if the file is missing. Also check that the folder is
91+
not nested twice, for example:
92+
`koreaderremote.koplugin/koreaderremote.koplugin/`.
8293

83-
### Work with notes
94+
### The phone cannot connect
8495

85-
- Create a selected-text note from the phone
86-
- Pull the open KOReader draft to the phone, or let changes sync automatically;
87-
save the note from either device
88-
- Edit a highlight note, remove its text while retaining the highlight, or
89-
delete the complete annotation
96+
- Confirm that the reader and phone are on the same Wi-Fi network.
97+
- Avoid guest networks that isolate connected devices.
98+
- Restart the remote server after changing Wi-Fi networks.
99+
- Show and scan the QR code again if the reader received a new IP address.
90100

91-
Only one remote-note session is active at a time. It expires after 30 minutes
92-
and prevents either device from silently overwriting a newer draft.
101+
### The server does not return after standby
93102

94-
### Stay connected
103+
- Wait a few seconds for Wi-Fi to reconnect after waking the reader.
104+
- Manually started sessions are restored after short sleep periods.
105+
- Enable **Auto start remote server** to restore the server after longer sleep.
106+
- The remote cannot wake a sleeping reader.
95107

96-
- QR-code sharing and configurable server port
97-
- Optional automatic start with KOReader
98-
- Wi-Fi recovery after standby and browser reconnection when the reader returns
99-
- The server remains available while changing books or visiting the file manager
108+
If the problem continues, include the device model, KOReader version, plugin
109+
version, steps to reproduce, and a screenshot in a GitHub issue.
100110

101111
## 📖 Everyday use
102112

0 commit comments

Comments
 (0)