Quiver

Coming soon

Quiver is coming soon to App Store.

The app is on its way to the App Store and Google Play. Once it is out, the buttons here go straight to the store.

Build guide, beta

Build your own screen.

You need an ESP32 board, a 4.2″ e-ink panel from Waveshare and a USB cable. The firmware is open source, and everything the screen shows, it gets from the Quiver app.

Start at step 1 Firmware on GitHub
4
steps
8
wires
400 × 300
pixels

You need the Quiver app and a Strava account. The screen shows what the app gets from Strava.

SHOES THIS WEEK 15.5 KM 1 Nike Zoom Fly 6 525 km 2 Adizero SL2 484 km 3 NB 1080 v15 199 km 4 Adios Pro 4 46 km LAST 30 RUNS longest 21.3 km Nano ESP32
Step1

Get the parts

A board and a panel are enough to get started. Buttons, a battery and a case can come later.

Must have

  • ESP32 board with Wi-Fi and Bluetooth LE The guide uses the Arduino Nano ESP32. The board needs MicroPython 1.22 or newer.
  • Waveshare 4.2″ e-Paper Module Black/white or black/white/red, 400 × 300 pixels. Use the SPI cable that comes with it.
  • USB cable To flash the board and power it.

Nice to have

  • Push buttons, 1 to 3 Switch views and page. One 10 kΩ pull-up per button.
  • LiPo battery Needs a board that charges and sleeps at microamps.
  • MOSFET Cuts the power to the panel between updates.
  • Frame or case A picture frame, a 3D-printed box or a shelf.

The board needs Bluetooth LE for setup and Wi-Fi to fetch pictures. The ESP32-S2 has no Bluetooth, so it won’t work. See the boards that have been tried.

Check the revision before you buy. The driver is written for the UC8176 controller, and some newer V2 panels use a different one.

Step2

Wire the panel to the board

The panel has eight wires. The colours in the drawing are the same as on the cable from Waveshare, so you can connect colour by colour. Unplug the USB cable while you wire.

Arduino Nano ESP32, seen from above Waveshare 4.2″, the connector 400 × 300 UC8176 VCCGNDDINCLKCSDCRSTBUSY USB ESP32-S3 D133V3GND D11D10D9D8D7

The wiring, wire by wire

WirePanelNano ESP32GPIO in board.json
Grey VCC 3.3V power
Brown GND GND ground
Blue DIN D11 38
Yellow CLK D13 (SCK) 48
Orange CS D10 21
Green DC D9 18
White RST D8 17
Purple BUSY D7 10
GPIO, not D labels

board.json takes the GPIO numbers in the right-hand column. The labels on the board, like D11, are only there to help you find the right pin.

Want buttons?

Connect each button between the pin and GND, with a 10 kΩ resistor to 3.3V. Next view is on D2 (GPIO 5), page down on D3 (GPIO 6) and page up on D4 (GPIO 7). The buttons wake the board from deep sleep, and without a button the screen shows one view at a time.

Use external pull-up resistors: the internal ones can’t be relied on while the board sleeps. The buttons must be on GPIO 0–21 on the ESP32-S3.

Step3

Load the firmware

The board needs MicroPython and the files from the repo. You do it all from the terminal on your computer, with the board connected over USB.

$ mpremote cp -r quiver main.py board.json : MicroPython

  1. Flash MicroPython

    Download the file for your board from micropython.org/download and flash it. For the Nano ESP32 it’s called ARDUINO_NANO_ESP32.

  2. Get the firmware

    terminal
    git clone https://github.com/wext-dev/quiver-device.git
cd quiver-device
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

  3. Pick your panel in board.json

    Copy board.example.json to device/board.json. The file only holds the setup, so passwords and tokens belong somewhere else.

    ws-4.2-bwblack/white, faster ws-4.2-bwrblack/white/red, about 15 s
    device/board.json
    {
  "panel": "ws-4.2-bwr",
  "pins": { "button": 5 }
}

  4. Copy the files to the board

    Run the command from device/ with mpremote.

    device/
    mpremote cp -r quiver main.py board.json :
Step4

Pair the screen in the app

Press RESET on the board. The panel shows “Set up the screen” with a QR code, and the board appears over Bluetooth as Quiver-XXXX.

Set up the screen Bluetooth Quiver-XXXX Add device Scan the QR code
  1. Open Devices in the app and tap Add device.
  2. Scan the QR code on the panel. The app sends the Wi-Fi password encrypted with a key that only exists in the code.
  3. Wait until the panel says “Connected”. The first picture follows right after.
Connected

Finish

The screen is ready.

From here it updates itself over Wi-Fi, firmware included. Choose what it shows in the app, and keep building when you like.

Run on battery Other boards and panels Security

Stuck?

The panel shows nothing

Check that BUSY and RST are on the right pins, and that the panel in board.json matches your panel. Check the revision too: newer V2 panels can have a different controller.

A red panel only shows black

Then the panel is probably set to ws-4.2-bw. Change it to ws-4.2-bwr and copy board.json to the board again.

The board doesn’t appear in the app

The board needs Bluetooth LE. Press RESET, and hold the phone close to the panel while you scan.

The guide is early, and not every board and panel revision has been tried. Ask in the forum if something goes wrong.

Keep building

Other boards and panels

The board needs both Wi-Fi and Bluetooth LE. The ESP32-S2 has no Bluetooth and won’t work. With a board other than the Nano ESP32 you set the pins in board.json yourself: the ESP32 can put SPI on any free pins.

BoardChipNote
Arduino Nano ESP32 ESP32-S3 The default setup in board.json. Fine on the desk, but its power LED is always on: not for battery. Default
Seeed Studio XIAO ESP32-S3 ESP32-S3 Small, with a charger. A good choice for battery. Battery
DFRobot FireBeetle 2 ESP32-S3 ESP32-S3 Made for low power, with a charger. Battery
Adafruit Feather ESP32-S3 ESP32-S3 Charger and battery connector on the board. Battery
ESP32-DevKitC and similar ESP32 (WROOM/WROVER) Has Wi-Fi and Bluetooth LE. Set the pins in board.json yourself. Should work
PanelColourspanelNote
Waveshare 4.2″ e-Paper Module (B) Black, white, red ws-4.2-bwr Red for the favourite and the week’s distance. A full refresh takes about 15 s.
Waveshare 4.2″ e-Paper Module Black, white (and grey) ws-4.2-bw Faster refresh. Can draw grey for smoother text.

Waveshare has changed the controller on some newer revisions (V2). Larger panels, like the 7.5″, need a driver of their own.

Run on battery

Most of the power goes to Wi-Fi and TLS while the board is awake. A response with nothing new leaves the panel alone. Updating every half hour, a 2000 mAh battery can last for years, but only if the board itself sleeps at microamps. Use a MOSFET to cut power to the panel between updates, and two equal resistors (e.g. 100 kΩ) as a voltage divider if you want to see the battery level.

TimeCurrent
Awake: Wi-Fi, TLS, one request3–8 s80–150 mA
Panel refresh (red)~15 s20–40 mA
Deep sleep (the ESP32 chip)the rest~10 µA

Rough numbers. Measure your own setup.

Updates

New versions of the firmware are published in the repo, and the screen fetches them itself over Wi-Fi (OTA). The README in the repo explains how to turn it off and roll back.

Security