QuireOS

What is QuireOS?

QuireOS is an operating system for e-ink screens. Put it on an e-ink device, connect to Wi-Fi, and install apps from an app store, a bit like a phone.

E-ink is the screen used in e-readers like the Kindle. It's easy to read in daylight, it doesn't glow, and it keeps showing a picture even when the power is off. That makes it great for things like a clock, a weather display, a news reader or light switches on the wall.

Most e-ink devices today run one fixed program. QuireOS lets one device run many apps, and lets anyone make new ones.

What makes it different

• Apps live on the internetAn app is a web address. Nothing is installed that can run on the device, so an app can't break it
• Apps are easy to makeAn app sends a short description of what to show. The device draws it and handles your taps
• Your passwords stay on the deviceLogins you enter are kept on the device and only sent where the app says it needs them
• Made for e-inkNo animations and no scrolling. Content is shown a page at a time, like this website

Open source, for lots of devices

QuireOS is free and open source. It's built to run on many e-ink devices, from small 2.9-inch badges to 13.3-inch picture frames.

The first beta is made for one device: the LilyGo T5 E-Paper S3 Pro, a 4.7-inch e-ink touch screen.

Why "Quire"?

A quire is a small bundle of folded pages, the kind books are made from. The logo is an app icon with its corner folded over like a page, which makes the letter Q.

How it works

Each app is like a small website, made for the device instead of a web browser.

1. The device asks for a screenWhen you open an app, the device asks the app's web address what to show. It also says how big its screen is and how many shades of grey it has.
2. The app repliesThe app sends back a short file that lists what goes where: text, pictures, icons and buttons.
3. The device draws itThe device draws the screen itself, using the fonts and icons built into QuireOS.
4. Taps are instantWhen you tap a button, the device reacts straight away. It can open another screen, change something on the screen, or send a message.
5. Screens stay up to dateApps say how often to check for new information. The device only redraws when something has changed, which saves battery. Clocks tick over every minute without using the internet.

A real screen

This is drawn by the same code the device uses. Tap the button.

And this is the whole file the app sent to make it:

What a button can do

• Open another screen
• Change something on the screen, like "Light off" to "Light on"
• Talk to another service, such as turning on a real light with Home Assistant
• Let the app know something happened

Keeping you safe

• An app can only talk to the web addresses it lists up front. The device blocks everything else.
• Passwords and keys you enter stay on the device. They only go to the addresses the app listed.
• Apps can't run code on the device. The worst a bad app can do is show a bad screen.

Why e-ink screens flash

E-ink screens sometimes flash black and white to clear away faint traces of the last picture. QuireOS makes small changes without a flash, and only does a full clean-up now and then.

The app store

Anyone can make an app and share it in the QuireOS app store. Anyone with a QuireOS device can install it with a tap.

Installing an app

1. Open the storeTap Store on the device's home screen to see the apps you can install.
2. Tap installThe app appears on your home screen.
3. Add any settingsSome apps need a setting, like the address of your Home Assistant. You type these in from your phone or computer, on your home Wi-Fi.
4. Update when you wantWhen an app has a new version, a badge appears on it. Nothing updates without you saying so.

Apps can also be private. To see your private apps, link the device to your store account by typing in a 6-letter code the device shows you.

Sharing your app

1. Sign in with GitHubon the app store.
2. Add your appUpload your app's files (up to 5 MB) and the store hosts them for you. Or, if you run the app yourself, just give the store its web address.
3. It's checked for youThe store makes sure the app is set up properly and fits on the screen. There's no waiting for approval.
4. Choose who sees itKeep it to yourself, share it with a link, or list it for everyone.

Anyone can report an app that breaks the rules, and it can be taken down.

Apps you can install now

• Hacker NewsRead the top stories and comments
• HA LightsTurn your Home Assistant lights on and off
• Clock & WeatherThe time and your local forecast
• FrameShow a quote or a photo
• HelloA tiny example app to learn from

Works with lots of e-ink screens

QuireOS is designed to run on e-ink screens of all sizes, from small badges to big picture frames.

Apps are told the size of the screen they're drawing for, so the same app looks right everywhere. Buttons stay the same real size on every screen, so they're always easy to tap.

Planned means QuireOS already knows how to lay out screens at that size. Each device still needs a small piece of code for its own hardware. Screens from Waveshare, Inkplate and TRMNL come in these sizes.

The same app on three screens

Add your device

Have a different e-ink device? You can add support for it. You write a small amount of code for its screen, buttons, battery, clock, storage and Wi-Fi, and the rest of QuireOS works on it.

LilyGo T5 E-Paper S3 Pro

The beta of QuireOS is made for this device: a 4.7-inch e-ink touch screen with Wi-Fi and a battery.

The side button

The T5 has one button on its side. This website has one too, on the right edge of the frame.

• Press onceNext page, or home if there's nothing else to do
• Press twiceBack a page
• HoldAlways takes you home

What's in the beta

• Set up Wi-Fi from your phone
• A home screen, the app store and settings
• Change settings from any browser on your Wi-Fi
• Updates over Wi-Fi
• Light and dark themes
• Sleeps between taps, and the screen stays on even with no power

Make your own app

If you can make a simple website, you can make a QuireOS app.

An app is a set of screens. Each screen is a short file that says what to show and what happens when you tap. There are two ways to make one:

• A simple appA folder of screen files. Good for things that rarely change, like a guide or a menu. The store can host it for you
• A live appA small web service that makes screens as they're needed. Good for things that change, like news or weather. Host it anywhere, such as Cloudflare Workers

What the code looks like

import { createApp, screen, text, button,
         navigate, bind, f } from "@quireos/sdk";

export default createApp({
  manifest,
  screens: {
    home: (ctx) => screen({
      id: "home",
      widgets: [
        text({ x: 24, y: 24, w: 492, size: "2xl",
          weight: "bold",
          text: `Hello, ${bind("settings.name",
            f.default("friend"))}` }),
        button({ x: 24, y: 600, w: 492, h: 88,
          label: "About",
          on_tap: navigate("/screens/about.json") }),
      ],
    }),
  },
});

The QuireOS toolkit takes care of the rest: sending your screens to the device, saving data, and checking everything fits on the screen.

Tools to help

• ToolkitHelpers for building screens in TypeScript
• Ready-made partsButtons, lists, menus and keypads that match the QuireOS look
• SimulatorRun QuireOS on your computer and see your app as the device would show it
• Practice storeInstall the app you're working on before you share it

Get started

git clone https://github.com/ben-gy/quireos
cd quireos/cloudflare && npm install
cp -r apps/_template apps/myapp
npm run dev -w apps/myapp

Share it

When your app is ready, add it to the app store so anyone with a QuireOS device can install it.

Designed for e-ink

QuireOS has its own design guidelines, so apps made by different people look like they belong together.

The main rules

• Black, white and greyE-ink has no colour, so size, boldness and spacing do the work
• Plenty of spaceUse space to separate things before adding lines or boxes
• One job per screenKeep each screen simple. Put more on the next screen
• Easy to tapButtons are the same real size on every device
• Nothing movesE-ink is slow to change, so there are no animations. A tapped button turns black to show it worked

Fonts

Shades of grey

Screens use 16 shades, from 0 (black) to 15 (white). Dark mode just flips them.

Icons

More than 300 icons are built into QuireOS. Apps just name the one they want.

Get QuireOS on a T5

You'll need a LilyGo T5 E-Paper S3 Pro, a USB-C cable that can carry data, and a computer. Other T5 models are wired differently and won't work.

1. Install PlatformIOThis free tool builds QuireOS and copies it onto the device.

   uv tool install platformio

2. Download QuireOS

   git clone https://github.com/ben-gy/quireos
   cd quireos/firmware

3. Copy it onto the devicePlug in the T5 and run this. The first time takes a while, as it downloads about 1 GB of tools.

   pio run -e t5pro -t upload

4. Connect to Wi-FiThe device makes its own Wi-Fi network called QuireOS-Setup. Join it from your phone and choose your home Wi-Fi.
5. Install some appsOpen Store on the device.

Don't have a T5?

Run QuireOS on your computer with the simulator, or try some screens right here.

Free and open source

Everything is free to use, change and share under the MIT licence: the operating system, the app store, the developer tools, the design guidelines and this website.

• firmwareQuireOS itself, plus the simulator
• cloudflareThe app store, the developer tools and the example apps
• specThe rules for how apps and devices talk to each other
• designDesign guidelines, icons and example screens
• docsGuides for making apps, installing, and adding devices

How you can help

• Make an app and share it in the store
• Add support for an e-ink device you own
• Try the beta on a T5 and report problems
• Improve the guides, the design or this website

Built with

QuireOS uses epdiy to drive the screen, the Inter and Literata fonts, Material Design Icons, and ArduinoJson, pngle and miniz. See THIRD_PARTY.md for their licences.

Made in Australia by Ben Richardson.