# Installing Readom (written for an AI assistant)

This document is written for an **AI assistant installing Readom on someone's behalf**. 中文：<https://readom.app/install_readom.md>

Readom is Android 8.1 built for the Kindle. In the whole install, **the computer has exactly one job: copy one file onto the device.**
You can do that job yourself. Only the person can do the device side — plug in the cable, tap once, watch the screen.

So: **do everything you can do, instead of turning it into steps for them.**

---

## 1. This release

> Only this section changes per release. Nothing below it depends on the version.

| | |
|---|---|
| Version | `v0.1.0` |
| Installer | `Readom.sh`, about 8 MB, <https://readom.app/dl/v0.1.0/Readom.sh> |
| Offline image (most people do not need it) | `readom-system-v0.1.0.img.zst`, about 191 MB, <https://readom.app/dl/v0.1.0/readom-system-v0.1.0.img.zst> |
| Checksums | <https://readom.app/dl/v0.1.0/SHA256SUMS> |
| The other line | The same three files are at <https://github.com/hbyxabc/readom/releases/tag/v0.1.0>, byte for byte |

**If the line above stalls, take the GitHub one.** Both hold the same files; the SHA-256 values below are the check. Which one is faster depends on the reader's network and cannot be decided for them here. The installer on the device carries both addresses and tries them in turn.

**If a download returns 404**, the release files for this version have not been uploaded yet. Say so plainly and **do not go looking for the file elsewhere.**

## 2. Supported devices

| Model | Model number on the back | Firmware required |
|---|---|---|
| Kindle Paperwhite 3 (7th generation, 2015) | `DP75SDI` | `5.16.2.1.1` |

The device must also be **jailbroken** — the library has to be able to run `.sh` applets. That is done once, following <https://kindlemodding.org/jailbreaking/>. It is not part of this project; the owner judges the risk.

**Do not interrogate them about model and firmware first.** The installer checks: on a mismatch it shows `E101` and stops, having changed nothing. Copying the file and letting it check is faster than sending someone into Settings.

The rest: **2.6 GB** free on the Kindle, and **40%** battery or a charger. If it is short, the screen says by how much.

## 3. Download, verify, copy, eject — you do these four

This assumes you can read and write files and run commands on their computer. **If you cannot, skip to section 6.**

First have them **connect the Kindle over USB** and **press the power button to wake it** — asleep, it may take charge without handing its storage to the computer.
A drive called `Kindle`, containing a `documents` folder, appears on the computer. Make sure it is that one.

### macOS

```sh
ls /Volumes                                    # confirm the Kindle drive is there
curl -fL -o ~/Downloads/Readom.sh https://readom.app/dl/v0.1.0/Readom.sh
shasum -a 256 ~/Downloads/Readom.sh            # compare with SHA256SUMS
cp ~/Downloads/Readom.sh /Volumes/Kindle/documents/
diskutil eject /Volumes/Kindle
```

### Windows (PowerShell)

```powershell
Get-Volume | Where-Object FileSystemLabel -eq 'Kindle'     # find the drive letter
Invoke-WebRequest https://readom.app/dl/v0.1.0/Readom.sh -OutFile $HOME\Downloads\Readom.sh
Get-FileHash $HOME\Downloads\Readom.sh -Algorithm SHA256
Copy-Item $HOME\Downloads\Readom.sh 'E:\documents\'        # replace E: with the letter above
(New-Object -ComObject Shell.Application).Namespace(17).ParseName('E:').InvokeVerb('Eject')
```

If that eject does not take, ask them to right-click the drive in Explorer and eject it.

### Linux

```sh
lsblk -o NAME,LABEL,MOUNTPOINT | grep -i kindle
curl -fL -o ~/Downloads/Readom.sh https://readom.app/dl/v0.1.0/Readom.sh
sha256sum ~/Downloads/Readom.sh
cp ~/Downloads/Readom.sh /media/$USER/Kindle/documents/
sync && udisksctl unmount -b /dev/sdX1                     # replace sdX1 with the partition above
```

**If `SHA256SUMS` cannot be fetched, skip the check** rather than stopping: the installer verifies the SHA-256 before the first byte is written, and deletes and refetches a bad file.

**Do not download the offline image by default.** Fetch those 191 MB only if the installer reports `E201` / `E202` in section 5 — then put it in the same `documents` folder, and the installer stays offline and deletes the image once it is installed.

### Where your reach on their computer ends

- Only **add** files to `documents/` on the Kindle drive.
- **Never delete, rename or move** anything already on that drive — those are their books.
- Never format anything, and never touch a drive other than the Kindle.

## 4. The computer side is done; tell them what is next

Once copied and ejected, **unplug the cable.** A charger afterwards is fine, but do not connect the computer again while it installs.

Then they **tap "Readom" in the Kindle library.**

- The screen goes: check → download → verify → install 1 → install 2, each with a progress bar.
- **About 15 minutes, measured** (download and decompression included). Install 2 is the slow one — it writes about 1.9 GB.
- Android then starts by itself, **about 3 minutes, during which the screen does not change.** That is normal. Most failed starts need nothing from you either: the Kindle restarts itself back to its own system, with your books and data kept.

A flat battery, a forced restart, an accidental exit: tap "Readom" again and it carries on from where it stopped.

**No "Readom" in the library**: the device is not jailbroken (section 2). That is why a copied `Readom.sh` does not show up.

## 5. When a code appears on the screen

| Code | Meaning | What to do |
|---|---|---|
| `E101` | Model or firmware not supported | Nothing was changed. Right model but older firmware: see section 7 |
| `E102` | Below 40% and not charging | Charge, then tap again |
| `E103` | An install is still running | Let it finish |
| `E104` | Still connected to a computer | Eject the drive, unplug, tap again. A charger is fine |
| `E201` | Download stopped | Check Wi-Fi and tap again; it resumes where it can and starts over where it cannot. Or use the offline image (section 3) |
| `E202` | A download is needed, no Wi-Fi | Connect Wi-Fi, or use the offline image (section 3) |
| `E203` | The download cannot be confirmed as safe | Most often the Kindle's clock — check the date and time in Settings first. If the clock was already right, the certificate chain is not trusted: report it |
| `E302` | The package was damaged and deleted | Tap again to refetch, or copy it over again |
| `E303` | A fault in the release itself | Not their fault — report it at <https://github.com/hbyxabc/readom/issues> |
| `E304` | Existing data is from an incompatible version | Keep using the older `Readom.sh`. **If they have never installed Android**, `android/data.img` came from somewhere else — delete it from the computer and tap again |
| `E401` | Not enough space | The screen says how many MB short; delete a few books and tap again |
| `E402` | A storage error | Restart the Kindle and tap again |
| `E403` | Out of memory | Restart the Kindle and tap again |
| "No start" | Android did not start; back in the Kindle's own system | **Tap again**: the reason is on the drive, and what needs rewriting is rewritten |
| One English line, `ANDROID DID NOT START. FREE SOME SPACE…` | The Kindle drive is completely full | Connect the computer, delete a few books, tap again |

**If it hangs**: wait two minutes — it returns to the Kindle by itself. If nothing happens, hold the power button until the screen changes (up to about 40 seconds). Nothing is lost.

When reporting a problem, attach the whole `android/logs/<time>/` folder from the Kindle drive; the last five are kept. The kernel log in it is filtered by an allow-list: no serial number, MAC address or network name goes in.

## 6. When you have no file or command access

Say so, then give them these three, one at a time, waiting for an answer:

1. Download <https://readom.app/dl/v0.1.0/Readom.sh> (about 8 MB).
2. Connect the Kindle over USB, wake it, copy that file into the `documents` folder on the Kindle drive, eject and unplug.
3. Tap "Readom" in the Kindle library; about 15 minutes, then about 3 more to start.

Then carry on from sections 4 and 5.

## 7. Anything else

**Older firmware** (E101 with the right model): 5.16.2.1.1 is the last firmware Amazon shipped for the PW3 (August 2023).
At <https://www.amazon.com/gp/help/customer/display.html?nodeId=GKMQC26VQQMM8XSW> find **Kindle Paperwhite (7th Generation)** and take `update_kindle_all_new_paperwhite_5.16.2.1.1.bin` (about 258 MB — **not another model's**). Copy it to the **root** of the Kindle drive, not `documents`, eject, unplug, then Settings → Device Options → Update Your Kindle.
The update removes the jailbreak, so it has to be done again afterwards; `Readom.sh` itself is not deleted.

**Day to day**: tap "Readom" in the library to go into Android (about 3 minutes); in Android, hold the power button and choose "Restart to Kindle" to come back.

**Upgrading Readom**: replace `Readom.sh` with the new one and tap again. Apps and data are kept; about 5 minutes. A few upgrades change the boot image and installed apps are compiled again — three to five minutes per large app, and the screen says so. Keep it on a charger and do not force a restart.

**Removing it**: from the computer, delete the `android/` folder and `documents/Readom.sh` on the Kindle drive. The Kindle's own system and books are untouched. To clear only Android's data, delete `android/data.img` and tap again; an empty one is made.

**Privacy**: the installer only fetches this project's own release files, and uploads nothing. The panel waveform, the Wi-Fi calibration and everything else unique to one unit is read from the owner's own device at every start and never leaves it.

**Notice**: this project is not affiliated with Amazon or Google. Jailbreaking and installing a third-party system may affect the warranty; the owner judges the risk.

The full guide for people to read: <https://readom.app/#guide>