+ Meshtastic is an open source project for creating off-grid, affordable, and resilient communication with LoRa mesh networks. +
+
+
+---
+
+- [Purpose](#purpose)
+- [Design Principles](#design-principles)
+ - [Self-Contained](#self-contained)
+ - [Static](#static)
+ - [Non-interactive](#non-interactive)
+ - [Customizable](#customizable)
+ - [Event-Driven Rendering](#event-driven-rendering)
+ - [No `#ifdef` spaghetti](#no-ifdef-spaghetti)
+- [The Implementation](#the-implementation)
+- [The Rendering Process](#the-rendering-process)
+- [Concepts](#concepts)
+ - [NicheGraphics Framework](#nichegraphics-framework)
+ - [NicheGraphics E-Ink Drivers](#nichegraphics-e-ink-drivers)
+ - [InkHUD Applets](#inkhud-applets)
+- [Adding a Variant](#adding-a-variant)
+ - [platformio.ini](#platformioini)
+ - [nicheGraphics.h](#nichegraphicsh)
+- [Class Notes](#class-notes)
+ - [`InkHUD::InkHUD`](#inkhudinkhud)
+ - [`InkHUD::Persistence`](#inkhudpersistence)
+ - [`InkHUD::Persistence::Settings`](#inkhudpersistencesettings)
+ - [`InkHUD::Persistence::LatestMessage`](#inkhudpersistencelatestmessage)
+ - [`InkHUD::WindowManager`](#inkhudwindowmanager)
+ - [`InkHUD::Renderer`](#inkhudrenderer)
+ - [`InkHUD::Renderer::DisplayHealth`](#inkhudrendererdisplayhealth)
+ - [`InkHUD::Events`](#inkhudevents)
+ - [`InkHUD::Applet`](#inkhudapplet)
+ - [`InkHUD::SystemApplet`](#inkhudsystemapplet)
+ - [`InkHUD::Tile`](#inkhudtile)
+ - [`InkHUD::AppletFont`](#inkhudappletfont)
+
+## Purpose
+
+InkHUD is a minimal UI for E-Ink devices. It displays the user's choice of info, as statically as possible, to minimize the amount of display refreshing.
+
+It is intended to supplement a connected client app.
+
+## Design Principles
+
+### Self-Contained
+
+- Keep InkHUD code within `/src/graphics/niche/InkHUD`.
+- Place reusable components within `/src/graphics/niche`, for other UIs to take advantage of.
+- Interact with the firmware code using the **Module API**, **Observables**, and other similarly non-intrusive hooks.
+
+### Static
+
+Information should be displayed as statically as possible. Unnecessary updates should be avoided.
+
+As as example, fixed timestamps are used instead of `X seconds ago` labels, as these need to be constantly updated to remain current.
+
+### Non-interactive
+
+InkHUD aims to be a "heads up display". The intention is for the user to glance at the display. The intention is _not_ for the user to frequently interact with the display.
+
+Some interactivity is tolerated as a means to an end: the display _should_ be customizable, but this should be minimized as much as possible.
+
+_Edit: there's significant demand for keyboard support, so some sort of free-text feature will need to be added eventually, although it does go against the original design principles._
+
+### Customizable
+
+The user should be given the choice to decide which information they would like to receive, and how they would like to receive it.
+
+### Event-Driven Rendering
+
+The display image does not update "automatically". Individual applets are responsible for deciding when they have new information to show, and then requesting a display update.
+
+### No `#ifdef` spaghetti
+
+**Don't** use preprocessor macros for device-specific configuration. This should be achieved with config methods, in [`nicheGraphics.h`](#nichegraphicsh).
+
+**Do** use preprocessor macros to guard all files
+
+- `#ifdef MESHTASTIC_INCLUDE_INKHUD` for InkHUD files
+- `#ifdef MESHTASTIC_INCLUDE_NICHE_GRAPHICS` for reusable components (drivers, etc)
+
+## The Implementation
+
+- Variant's platformio.ini file extends `inkhud` (defined in InkHUD/PlatformioConfig.ini)
+ - original screen class suppressed: `MESHTASTIC_EXCLUDE_SCREEN`
+ - ButtonThread suppressed: `HAS_BUTTON=0`
+ - NicheGraphics components included: `MESHTASTIC_INCLUDE_NICHE_GRAPHICS`
+ - InkHUD components included: `MESHTASTIC_INCLUDE_INKHUD`
+- `main.cpp`
+ - includes `nicheGraphics.h` (from variant folder)
+ - calls `setupNicheGraphics`, (from nicheGraphics.h)
+- `nicheGraphics.h`
+ - includes InkHUD components
+ - includes shared NicheGraphics components
+ - `setupNicheGraphics`
+ - configures and connects components
+ - `inkhud->begin`
+
+## The Rendering Process
+
+(animated diagram)
+
+
+
+An overview:
+
+- A component calls `requestUpdate` (applets only) or `InkHUD::forceUpdate`
+- `Renderer` schedules a render cycle for the next loop(), using `Renderer::runOnce`
+- `Renderer` determines whether the update request is valid
+- `Renderer` asks relevant applets to render
+- Applet dimensions are updated (by Applet's `Tile`)
+- Applets generate pixel output, and pass this to their `Tile`
+- Tiles shift these "relative" pixels to their true region, for multiplexing
+- Tiles pass the pixels to `Renderer`
+- `Renderer` applies any global display rotation to the pixels
+- `Renderer` combines the pixels into the finished image
+- The finished image is passed to the display driver, starting the physical update process
+
+## Concepts
+
+### NicheGraphics Framework
+
+InkHUD is implemented as a _NicheGraphics_ UI.
+
+Intended as a pattern / philosophy for implementing self-contained UIs, to suit various niche devices, which are best served by their own custom user interface.
+
+Hypothetical examples: E-Ink, 1602 LCDs, tiny OLEDs, smart watches, etc
+
+A NicheGraphics UI:
+
+- Is self-contained
+- Makes use of the loose collection of resources (drivers, input methods, etc) gathered in the `/src/graphics/niche` folder.
+- Implements a `setupNicheGraphics()` method.
+
+### NicheGraphics E-Ink Drivers
+
+InkHUD uses a set of custom E-Ink drivers. These are not based on GxEPD2, or any other code base. They are written directly on-top of the Meshtastic firmware, to make use of the OSThread class for asynchronous display updates.
+
+Interacting with the drivers is straightforward. InkHUD generates a frame of 1-bit image data. This image data is passed to the driver, along with the type of refresh to use (FULL or FAST).
+
+`driver->update(uint8_t* buffer, EInk::UpdateTypes::FULL)`
+
+For more information, see the documentation in `src/graphics/niche/Drivers/EInk`
+
+### InkHUD Applets
+
+An InkHUD applet is a class which generates a screen of info for the display.
+
+Consider: `DMApplet.h` (displays most recent direct message) and `RecentsList.h` (displays a list of recently heard nodes)
+
+- Applets are modular: they are easy to write, and easy to implement. Users select which applets they want, using the menu.
+- Applets use responsive design. They should scale for different screens / layouts / fonts.
+- Applets decide when to update. They use the Module API, Observers, etc, to retrieve information, and request a display update when they have something interesting to show.
+
+See `src/graphics/niche/InkHUD/Applets/Examples` for example code.
+
+#### Writing an Applet
+
+Your new applet class will inherit `InkHUD::Applet`.
+
+```cpp
+class BasicExampleApplet : public Applet
+{
+ public:
+ // You must have an onRender() method
+ // All drawing happens here
+
+ void onRender() override;
+};
+```
+
+The `onRender` method is called when the display image is redrawn. This can happen at any time, so be ready!
+
+```cpp
+// All drawing happens here
+// Our basic example doesn't do anything useful. It just passively prints some text.
+void InkHUD::BasicExampleApplet::onRender()
+{
+ printAt(0, 0, "Hello, world!");
+}
+```
+
+Your applet will need to scale automatically, to suit a variety of screens / layouts / fonts. Make sure you draw relative to applet's size.
+
+| edge | coordinate | shorthand |
+| ------ | ---------- | --------- |
+| left | 0 | `X(0.0)` |
+| top | 0 | `Y(0.0)` |
+| right | `width()` | `X(1.0)` |
+| bottom | `height()` | `Y(1.0)` |
+
+The same principles apply for drawing text. Methods like `AppletFont::lineHeight` and `getTextWidth` are useful here.
+
+```cpp
+std::string line1 = "Line 1";
+printAt(0, Y(0.5), line1);
+drawRect(0, Y(0.5), getTextWidth(line1), fontSmall.lineHeight(), BLACK);
+```
+
+Your applet will only be redrawn when _something_ requests a display update. Your applet is welcome to request a display update, when it determines that it has new info to display, by calling `requestUpdate`.
+
+Exactly how you determine this, depends on what your applet actually does. Here's a code snippet from one of the example applets. The applet is requesting an update when a new message is received.
+
+```cpp
+// We configured the Module API to call this method when we receive a new text message
+ProcessMessage InkHUD::NewMsgExampleApplet::handleReceived(const meshtastic_MeshPacket &mp)
+{
+
+ // Abort if applet fully deactivated
+ // Don't waste time: we wouldn't be rendered anyway
+ if (!isActive())
+ return ProcessMessage::CONTINUE;
+
+ // Check that this is an incoming message
+ // Outgoing messages (sent by us) will also call handleReceived
+
+ if (!isFromUs(&mp)) {
+ // Store the sender's nodenum
+ // We need to keep this information, so we can re-use it anytime render() is called
+ haveMessage = true;
+ fromWho = mp.from;
+
+ // Tell InkHUD that we have something new to show on the screen
+ requestUpdate();
+ }
+
+ // Tell Module API to continue informing other firmware components about this message
+ // We're not the only component which is interested in new text messages
+ return ProcessMessage::CONTINUE;
+}
+```
+
+#### Implementing an Applet
+
+Incorporating your new applet into InkHUD is easy.
+
+In a variant's `nicheGraphics.h`:
+
+- `#include` your applet
+- `inkhud->addApplet("My Applet", new InkHUD::MyApplet);`
+
+You will need to add these lines to any variants which will use your applet.
+
+#### Applet Bases
+
+If you need to create several similar applets, it might make sense to create a reusable base class. Several of these already exist in `src/graphics/niche/InkHUD/Applets/Bases`, but use these with caution, as they may be modified in future.
+
+#### System Applets
+
+So far, we have been talking about "user applets". We also recognize a separate category of "system applets". These handle things like the menu, and the boot screen. These often need special handling, and need to be implemented manually.
+
+## Adding a Variant
+
+In `/variants/