Xteink X4 イーペーパーリーダー用コミュニティファームウェア

Xteink X4 イレクトロニックペーパー（e-paper）読書器用ファームウェア（Xteink 社との関係はありません）。PlatformIO を使用し、ESP32-C3 マイクロコントローラーをターゲットとして構築されています。CrossPoint Reader は、公式の Xteink ファームウェアへの完全なオープンソースによる代替品として設計された専用ファームウェアであり、標準的な EPUB 読書の体験に匹敵するか、それ以上のものを実現することを目的としています。

モチベーション

イレクトロニックペーパー端末は読書には素晴らしいデバイスですが、市販されている多くは閉じたシステムであり、カスタマイズの選択肢が限定されています。Xteink X4 は手頃な価格のイレクトロニックペーパー端末である一方、その公式ファームウェアもまだクローズドです。CrossPoint Reader は、エコシステムの開放化とデバイスの真の可能性を解き放つため、娯楽的なサイドプロジェクトの一部として、そしてコミュニティにより多くの可能性を開くためにも作成されています。

CrossPoint Reader の目的は以下の通りです：

• 公式ファームウェアに対する完全なオープンソースの代替手段を提供すること。
• 制約のあるハードウェア上で EPUB コンテンツを扱えるドキュメントリーダーを提供すること。
• フォント、レイアウト、およびディスプレイオプションのカスタマイズをサポートすること。
• 純粋に Xteink X4 のハードウェア上だけで動作すること。

当プロジェクトは Xteink と一切関係がございません。コミュニティ主導の開発プロジェクトとして構築されています。

機能と使用方法

• EPUB 対応: EPUB 2 および EPUB 3 の解析およびレンダリング。
• 画像対応: EPUB 内蔵の画像への対応。
• 進捗保存: 読み进み位置の保存機能。
• ファイルエクスプローラー: ルートディレクトリからのファイル選択、ネストされたフォルダのサポート、表紙画像付きの EPUB ピッカー。
• スリープ画面: カスタムスリープ画面および表紙表示スリープ画面。
• 接続性: WiFi 経由での書籍アップロードおよび OTA（オーバー・ザ・エア）更新。
• 同期機能: KOReader シングとの統合により、複数デバイス間の読み進み位置の同期が可能です。
• カスタマイズ: フォント、レイアウト、ディスプレイオプションを設定可能。
  • ユーザーが提供したフォントの使用。
  • 完全な UTF-8 コードポイントサポート。
  • スクリーン回転対応。
• 多言語対応: 英語、スペイン語、フランス語、ドイツ語、イタリア語、ポルトガル語、ロシア語、ウクライナ語、ポーランド語、スウェーデン語、ノルウェー語など、様々な言語に対応。

CrossPoint の操作方法については、ユーザーガイド をご参照ください（KOReader シングの簡易セットアップを含む）。プロジェクトのスコープの詳細については、SCOPE.md ドキュメントをご覧ください。

インストール手順

Web ブラウザ（最新版ファームウェア）

1. Xteink X4 を USB-C ケーブルでコンピュータに接続し、デバイスを起動してロックを解除します。
2. https://xteink.dve.al/ にアクセスし、「Flash CrossPoint firmware」ボタンをクリックしてください。

元に戻す場合: 公式ファームウェアへの復元をご希望の場合は、https://xteink.dve.al/ から最新の公式ファームウェアをフラッシュするか、以下のリンクの「Swap boot partition」ボタンを使用して別のパーティションに切り替えることができます: https://xteink.dve.al/debug

Web ブラウザ（特定のバージョン）

1. Xteink X4 を USB-C ケーブルでコンピュータに接続します。
2. リリースページから、ご希望のバージョンの

   firmware.bin

   ファイルをダウンロードしてください。
3. https://xteink.dve.al/ にアクセスし、「OTA fast flash controls」セクションを使用して、ダウンロードしたファームウェアファイルをフラッシュしてください。

元に戻す場合: 公式ファームウェアへの復元をご希望の場合は、https://xteink.dve.al/ から最新の公式ファームウェアをフラッシュするか、以下のリンクの「Swap boot partition」ボタンを使用して別のパーティションに切り替えることができます: https://xteink.dve.al/debug

コマンドライン（特定のバージョン）

1. esptool

   をインストールしてください：

   # オスごとに適切なインストールコマンドを実行してください（ソース内には記載せず、ユーザー側で行うものと仮定）
   

2. リリースページから、ご希望のバージョンの

   firmware.bin

   ファイルをダウンロードしてください。
3. Xteink X4 を USB-C ケーブルでコンピュータに接続します。デバイスのポート場所を確認しておいてください。
   • Linux の場合：接続後に

     dmesg

     コマンドを実行。
   • macOS の場合：

     log stream --predicate 'subsystem == "com.apple.iokit"' --info
     

4. ファームウェアをフラッシュします：

   esptool.py --chip esp32c3 --port /dev/ttyACM0 --baud 921600 write_flash 0x10000 /path/to/firmware.bin
   

   ※

   /dev/ttyACM0

   はお使いのシステム上のデバイスポートに差し替えてください。

マニュアル（開発モード）

詳細は下の Development セクションを参照してください。

開発環境

前置条件

• PlatformIO Core (

  pio

  ) または VS Code + PlatformIO IDE
• Python 3.8 以上
• ESP32-C3 のフラッシュ用の USB-C ケーブル
• Xteink X4 デバイス

コードの取得（クローン）

CrossPoint Reader はファームウェアのビルドおよびフラッシュに PlatformIO を使用しています。開始するにはリポジトリをクローンしてください：

git clone --recursive https://github.com/crosspoint-reader/crosspoint-reader

または、すでに

--recursive

git submodule update --init --recursive

デバイスのフラッシュ

Xteink X4 を USB-C ケーブルでコンピュータに接続し、上記 [インストール] セクションの手順に従ってフラッシュコマンドを実行してください。

デバッグ

新しい機能をフラッシュした後には、シリアルポートからの詳細なログをキャプットすることを推奨します。まず、必要な Python パッケージがインストールされていることを確認してください：

python3 -m pip install pyserial colorama matplotlib

インストール後、お使いのオペレーティングシステムに対応するデバッグスクリプトを実行してください：

• Linux: （Debian でテスト済み；多くの Linux システムで動作すると期待されます）

  python3 scripts/debugging_monitor.py
  

• macOS:

  python3 scripts/debugging_monitor.py /dev/cu.usbmodem2101
  

Windows ではいくつかの微調整が必要になる場合があります。

内部構造

CrossPoint Reader は RAM 使用量を最小限に抑えるために、SD カードまでデータをキャッシュするという非常に積極的なアプローチを採用しています。ESP32-C3 の利用可能な RAM は約 380KB に過ぎず、そのため慎重に対応する必要があります。ファームウェア設計における多くの決定は、この制約に基づいています。

データキャッシング

本を最初に読み込む際、章のデータが SD カードにキャッシュされます。その後の読み込みはキャッシュからサービスされます。このキャッシュディレクトリは SD カード上の

.crosspoint

.crosspoint/
├── epub_12471232/       # 各 EPUB は `epub_<hash>` という名のサブディレクトリにキャッシュされます
│   ├── progress.bin     # 読み込み進捗（章、ページなど）を格納
│   ├── cover.bmp        # 書籍表紙画像（一度生成されれば有効）
│   ├── book.bin         # 書籍メタデータ（タイトル、著者、スピン、目次など）
│   └── sections/        # すべての章データが sections サブディレクトリに格納
│       ├── 0.bin        # 章データ（画面数、すべてのテキストレイアウト情報など）
│       ├── 1.bin        # ファイル名はスピン内のインデックス番号で決定
│       └── ...
└── epub_189013891/

.crosspoint

内部ファイル構造の詳細については、file formats ドキュメントを参照してください。

貢献（コントリビューション）

貢献は非常に歓迎いたします！

• コードベースに慣れない場合は、まずは貢献ガイドラインをご覧ください。
• ご支援方法を模索中の方は、アイデア掲示板をご覧ください。
• やりたいことがあれば、コメントを残して重複する労働を避けるようお願いします。

このコミュニティの全員がボランティアであり、ご協力を仰ぐ際は敬意と patience をお持ちください。ガバナンスおよびコミュニティ原則の詳細については、GOVERNANCE.md を参照してください。

貢献を送信するには：

1. リポジトリをフォーク。
2. ブランチを作成（例：

   feature/dithering-improvement

   ）。
3. 変更を加える。
4. プルリクエスト（PR）を提出。

免責事項: CrossPoint Reader は Xteink や X4 ハードウェアの製造業者とは一切関係ありません。

なお、CrossPoint を製作する際に多くのインスピレーションを得た atomic14 氏の diy-esp32-epub-reader プロジェクトに心より感謝申し上げます。