zmk-nice-oled

nice!oled - nice!epaper - nice!custom

Table of Contents

• Overview
• Gallery
• Quick Installation
• Configuration
• ZMK RAW HID Implementation
• Suggestions
• Limitations
• Acknowledgments & Credits
• Support
• My other projects

Overview

Vertical widgets for oled and niceview screens using zmk (for split and non-split keyboards)

System Architecture & Implementation Summary

Modular & Submodular Design Strategy

This ZMK module implements a highly decoupled architecture designed for maximum flexibility and extensibility.

• Modular Widgets: The view layer is fully modular, permitting the runtime selection and composition of any available widget without heavy coupling to the core display logic.
• Submodular RAW HID: The RAW HID implementation is granular. Submodules such as Temperature, Time, Layout, and Volume can be independently compiled and activated via Kconfig, minimizing flash usage and processing overhead by excluding unused logic.

Abstraction Layer: nice_custom Shield

A dedicated hardware abstraction layer, the nice_custom shield, was developed to decouple driver positioning from physical hardware definitions.

• Independent Driver Coordinate System: All X/Y rendering coordinates are configurable via the configuration system (runtime/Kconfig) completely independent of the underlying shield definition.
• Code-Free Customization: Users can reposition drivers and elements to suit non-standard layouts or personal preferences purely through configuration variables, eliminating the need to fork or modify the C source code of the display driver.

Host-Side Integration (Rust)

The companion host application, zmk-hid-host, provides the necessary data bridge for universal Raw HID features (System Time, Volume, Layout) across Linux, Windows, and macOS.

• Technical Contributions (macOS Enhancements):
  • macOS Temperature Support: Implemented platform-specific temperature monitoring for macOS within the Rust codebase.
  • Spotify Integration: Engineered a native AppleScript/Rust bridge to fetch real-time track metadata from Spotify for display on the peripheral (macOS only).
  • Cross-Architecture Support: Developed a universal macOS application wrapper, bundling native binaries for both Intel (x86_64) and Apple Silicon (arm64) architectures, ensuring seamless deployment across the Apple ecosystem.

Shields supported:

• nice_oled
• nice_epaper
• nice_custom

General characteristics:

General

• Vertical Layout: Optimized for split keyboard OLED/e-Ink/ePaper screens.
• Compact Design: Maximizes information density.
• Modular Widgets: Enable/disable components independently.
• nice_custom Shield: Position drivers via config, no code required.
• Neck Strain Reduction: View info on keyboard instead of monitor.
• Dark Mode Friendly: Optimized for nice!oled.

Central Screen

• WPM Widgets: Graphs, Speedometer, Luna, Bongo Cat.
• HID Indicators: CapsLock status with Luna/Bongo Cat animations.
• Modifiers Widget: Real-time display of Ctrl, Shift, Alt, Gui.
• Raw HID Integration:
  • Spotify (macOS): Real-time track information.
  • Weather: Current temperature display.
  • System Sync: Volume, Time, and Keyboard Layout.

Peripheral Screen

• Vertical Animations: Gem, Cat, Head, Pokemon, Spaceman.
• Smart Battery: Efficient battery status animation.
• Sleep Art: Custom images during idle/sleep.
• Static Images: Vim, Custom Logos (low power mode).

Gallery

Click here for more photos or go to the gallery section photos

Quick Installation

Installation in 4 simple steps:

0. Configuration example? You should see this -> zmk-config

1. Make sure to enable the custom status screen in your *.conf file:

CONFIG_ZMK_DISPLAY=y
CONFIG_ZMK_DISPLAY_STATUS_SCREEN_CUSTOM=y

2. Copy and paste this into your config/west.yml file:

manifest:
  remotes:
    - name: zmkfirmware
      url-base: https://github.com/zmkfirmware
    # support nice_oled and nice_epaper
    - name: mctechnology17
      url-base: https://github.com/mctechnology17
  projects:
    - name: zmk
      remote: zmkfirmware
      revision: v0.3.0
      import: app/west.yml
    # support nice_oled and nice_epaper
    - name: zmk-nice-oled
      remote: mctechnology17
      revision: main
  self:
    path: config

3. In the build.yaml file, add the nice_oled shield (using the corne as an example, but it could be another shield).

For oled screen:

---
include:
  - board: nice_nano_v2
    shield: corne_left nice_oled
  - board: nice_nano_v2
    shield: corne_right nice_oled

For niceview screen:

---
include:
  - board: nice_nano_v2
    shield: corne_left nice_view_adapter nice_epaper
  - board: nice_nano_v2
    shield: corne_right nice_view_adapter nice_epaper

4. Build the firmware, flash it to your keyboard, and enjoy!

Configuration

Make sure to enable the custom status screen in your ZMK configuration:

CONFIG_ZMK_DISPLAY=y
CONFIG_ZMK_DISPLAY_STATUS_SCREEN_CUSTOM=y

Anatomy of the variables of this repository

This document lists the available configuration options for the nice_oled shield. These variables can be set in your .conf file to customize the behavior of the display widgets.

General Configuration

Sleep & Animation (Central & Peripheral)

Peripheral Specific

Central Specific

HID Indicators

Raw HID

Modifiers Indicators

Symbol Icons

When using SYMBOL style, the following real icons are displayed:

macOS mode (default):

• Control: ⌃ (caret symbol)
• Shift: ⇧ (upward arrow)
• Option: ⌥ (option key symbol)
• Command: ⌘ (command/clover symbol)

Windows mode:

• Control: ⌃ (caret symbol)
• Shift: ⇧ (upward arrow)
• Alt: Alt text icon
• Win: Windows logo

Other Widgets (Central)

Battery Widget (Experimental)

Widget Position Coordinates

These variables allow users to customize widget positions. Each widget has X and Y coordinates that can be set in your .conf file. The defaults are set per shield (OLED vs ePaper).

Layer Widget Position

Battery Widget Position

Profile Widget Position

Output Widget Position

WPM Widget Position

Luna Widget Position

Bongo Cat Widget Position

HID Indicators Widget Position

Modifiers Widget Position

Animation Peripheral Position

Raw HID Widget Position

The Raw HID widget has multiple submodules that can be positioned independently.

Base Position (fallback for “HID not found” message)

Weather (Temperature) Submodule

Time Submodule

Layout Submodule

Volume Submodule

Media Player (Spotify) Submodule

Responsive Bongo Cat Widget Position

Sleep Status Widget Position

ZMK RAW HID Implementation

This document describes the RAW HID implementation for the nice!OLED, nice!view and nice!custom.

0. Quick Start

1. Compile your .uf2 and flash your keyboard including the zmk-nice-oled shield as indicated in the instructions in the README.md
   • don’t forget to activate the flag CONFIG_NICE_OLED_WIDGET_RAW_HID=y
2. Download and install the zmk-hid-host program to your computer and configure it to always start from login
   • zmk-hid-host does not spend much 0% cpu resources!
   • modify the json file if necessary!
   • zmk-hid-host is compatible for intel and apple m series processors, it is a universal binary!
3. Enjoy your keyboard!!!
   • remember to customize to your liking.
   • TIP: you can activate seeing the weather and seeing your spotify song on macos!

1. Introduction to RAW HID

RAW HID provides a flexible way to send and receive custom data between the keyboard and the host computer. This allows for advanced features that are not covered by standard HID profiles.

To enable RAW HID, you need to set the following options in your Kconfig.defconfig:

CONFIG_NICE_OLED_WIDGET_RAW_HID=y

This will enable the RAW HID interface and the corresponding widgets.

2. Available RAW HID Features

The following features are implemented using RAW HID:

2.1. Layout Switching

This feature allows you to display the current keyboard layout on the OLED screen. The layout can be sent from the host computer.

Kconfig Options:

CONFIG_NICE_OLED_WIDGET_RAW_HID_LAYOUT=y
CONFIG_NICE_OLED_WIDGET_RAW_HID_LAYOUT_LIST="DE,US,LA,AB"
CONFIG_NICE_OLED_WIDGET_RAW_HID_LAYOUT_CUSTOM_X=0
CONFIG_NICE_OLED_WIDGET_RAW_HID_LAYOUT_CUSTOM_Y=86

The LAYOUT_LIST is a comma-separated list of layout names that will be displayed on the screen based on the index received from the host.

2.2. Weather Widget (macOS Only)

This widget displays the current temperature received from the host computer.

Kconfig Options:

CONFIG_NICE_OLED_WIDGET_RAW_HID_WEATHER=y
CONFIG_NICE_OLED_WIDGET_RAW_HID_WEATHER_CUSTOM_X=0
CONFIG_NICE_OLED_WIDGET_RAW_HID_WEATHER_CUSTOM_Y=62

The host application needs to send the temperature value to the keyboard. This feature is currently optimized for macOS.

2.3. Spotify Media Player Widget (macOS Only)

This widget displays the current song playing on Spotify on a macOS computer.

Kconfig Options:

CONFIG_NICE_OLED_WIDGET_RAW_HID_MEDIA_PLAYER_SPOTIFY_MACOS=y
CONFIG_NICE_OLED_WIDGET_RAW_HID_MEDIA_PLAYER_CUSTOM_X=0
CONFIG_NICE_OLED_WIDGET_RAW_HID_MEDIA_PLAYER_CUSTOM_Y=110

A host application is required to read the song information from Spotify and send it to the keyboard. This feature is exclusive to macOS.

2.4. System Time Widget

This widget displays the current system time synchronized with the host computer.

Kconfig Options:

CONFIG_NICE_OLED_WIDGET_RAW_HID_TIME=y
CONFIG_NICE_OLED_WIDGET_RAW_HID_TIME_CUSTOM_X=0
CONFIG_NICE_OLED_WIDGET_RAW_HID_TIME_CUSTOM_Y=74

This feature is compatible with Windows, Linux, and macOS.

2.5. System Volume Widget

This widget displays the current system audio volume.

Kconfig Options:

CONFIG_NICE_OLED_WIDGET_RAW_HID_VOLUME=y
CONFIG_NICE_OLED_WIDGET_RAW_HID_VOLUME_CUSTOM_X=0
CONFIG_NICE_OLED_WIDGET_RAW_HID_VOLUME_CUSTOM_Y=98

This feature is compatible with Windows, Linux, and macOS.

3. Host-side application

The companion host application, qmk-hid-host, provides the necessary data bridge for universal Raw HID features (System Time, Volume, Layout) across Linux, Windows, and macOS.

• Technical Contributions (macOS Enhancements):
  • macOS Temperature Support: Implemented platform-specific temperature monitoring for macOS within the Rust codebase.
  • Spotify Integration: Engineered a native AppleScript/Rust bridge to fetch real-time track metadata from Spotify for display on the peripheral (macOS only).
  • Cross-Architecture Support: Developed a universal macOS application wrapper, bundling native binaries for both Intel (x86_64) and Apple Silicon (arm64) architectures, ensuring seamless deployment across the Apple ecosystem.

You can compile the application from the source by following these steps:

1. Clone the original repository:

   git clone https://github.com/zzeneg/qmk-hid-host.git
   

2. Navigate to the project directory:

   cd qmk-hid-host
   

3. Compile the project in release mode:

   cargo build --release
   

4. The binary will be available in target/release/.

Once compiled, you can run the application. It will automatically detect your keyboard and start sending the required data.

4. Creating a .dmg for the macOS application

Once you have your host-side application, you can create a .dmg file for easy distribution and installation.

You can use the create-dmg tool, which can be installed via Homebrew:

brew install create-dmg

Then, you can create the .dmg file with the following command:

create-dmg \
  --volname "ZMK RAW HID Host" \
  --background "path/to/your/background.png" \
  --window-pos 200 120 \
  --window-size 600 400 \
  --icon-size 100 \
  --icon "YourApp.app" 170 200 \
  --hide-extension "YourApp.app" \
  --app-drop-link 430 200 \
  "ZMK_RAW_HID_Host.dmg" \
  "source_folder/"

Replace "YourApp.app" and "source_folder/" with your actual application and source folder.

5. Running the application on startup

To make the host application run automatically every time you start your Mac, you can add it to the “Login Items”.

1. Open System Settings.
2. Go to General > Login Items.
3. Click the + button.
4. Select your application from the /Applications folder.
5. Click Open.

Now, the application will start automatically when you log in, ensuring that the RAW HID features of your keyboard are always available.

6. Updating the host-side application

If you need to update the host-side application with a new binary or configuration file, you can do so by replacing the files inside the application bundle.

1. Go to your Applications folder.
2. Right-click on ZMK HID Runner.app and select “Show Package Contents”.
3. Navigate to Contents/Resources/.
4. You will see the following structure:

   .
   ├── applet.icns
   ├── applet.rsrc
   ├── description.rtfd
   │   └── TXT.rtf
   ├── Scripts
   │   └── main.scpt
   ├── zmk-hid-host
   └── zmk-hid-host.json
   

5. You can replace the zmk-hid-host binary and the zmk-hid-host.json configuration file with your new versions. Make sure the new files have the same names.

cp zmk-hid-host "/Applications/ZMK HID Runner.app/Contents/Resources/zmk-hid-host"
cp zmk-hid-host.json "/Applications/ZMK HID Runner.app/Contents/Resources/zmk-hid-host.json"

chmod +x "/Applications/ZMK HID Runner.app/Contents/Resources/zmk-hid-host"

Author and Contributions

The original qmk-hid-host project was created by zzeneg, and you can find the repository here: https://github.com/zzeneg/qmk-hid-host.

The Spotify and Weather functionalities described in this document were added in this pull request: https://github.com/zzeneg/qmk-hid-host/pull/24/files.

The RAW HID functionality in this project is a custom implementation, ported from the great work of @zzeneg in the following repositories:

• zmk-raw-hid
• zmk-nice-view-hid

This implementation is 100% independent and is activated only with the following flags, without needing any other files:

CONFIG_NICE_OLED_WIDGET_RAW_HID=y

Suggestions

If you have any implementation suggestion or something similar opens a discussion

Limitations

While nice_oled offers advanced features, there are hardware and software constraints to consider.

• Memory Usage (RAM) This shield uses the LVGL graphics library, which can be memory-intensive.
  • High Consumption: Enabling multiple large widgets (WPM Graph, Bongo Cat, Raw HID) can exhaust the available RAM on the microcontroller (nRF52840).
  • Symptoms: If memory is low, you may experience display artifacts, freezing, or Bluetooth instability.
  • Mitigation: Use the “Balanced” or “Minimal” presets described in OPTIMIZE.md if you encounter issues.
• Battery Life OLED displays and continuous animations consume power.
  • Peripheral Impact: Running complex animations (like Pokemon or Bongo Cat) on the peripheral half (which has a smaller battery in some builds) will significantly reduce battery life.
  • Refresh Rate: Higher animation speeds (lower ms values) increase CPU usage, preventing the processor from sleeping.
  • Mitigation: Use CONFIG_NICE_OLED_WIDGET_STATIC_IMAGE_PERIPHERAL=y for better battery life on split peripherals.
• Platform Compatibility (Raw HID) The Raw HID features rely on a host-side application to send data to the keyboard.
  • Universal Support (macOS, Linux, Windows): The nice_oled shield and its core Raw HID modules (System Volume, Time, Layout) are fully compatible with macOS, Linux, and Windows.
  • macOS Exclusive Features: The specific integrations for Spotify track info and Weather are currently optimized and available only for macOS.
• Performance & Latency The display runs on shared hardware resources.
  • Typing Latency: If the display thread priority is set too high (1 or 2), it might interrupt key scanning, causing perceived input lag during heavy animations.
  • Smart Battery: The experimental “Smart Battery” animation uses significant compute resources and is not recommended for stability-focused builds.
  • Mitigation: Keep CONFIG_ZMK_DISPLAY_DEDICATED_THREAD_PRIORITY at default (5) or lower (10).
• Image Rotation Strategy To maximize efficiency on the nRF52840, real-time image rotation is avoided.
  • Pre-processing: All animated assets are pre-rotated on the host computer during the design phase.
  • Reasoning: Performing geometric transformations (rotation) at runtime is computationally expensive and memory-intensive for this architecture.
  • Implementation: By storing assets as ready-to-render, pre-rotated bitmaps, we offload the processing burden from the MCU, ensuring smooth playback with minimal CPU overhead.

Acknowledgments

This project is built upon the foundation of numerous innovative contributions from the ZMK community. We extend our sincere gratitude to the following developers whose work has been a source of inspiration and whose drivers or methods have been ported or adapted for this module.

Core Inspiration & Drivers

• @M165437: For nice-view-gem, which inspired the animation implementations.
• @zzeneg: For the pioneering work on zmk-raw-hid and zmk-nice-view-hid. The Raw HID functionality in this module is a custom implementation heavily inspired by and ported from his great work.
• @englmaxi: For zmk-dongle-display, a key reference for display management.
• @infely: For nice-view-battery.
• @tobiasarndt: For zmk-config and the sleep status implementation.
• @infused-kim: For Nice Peripheral View (tmp-npv).
• @codyd51: For Mighty-Mitts.
• @badjeff: For zmk-hid-io.
• @carrefinho: For prospector-zmk-module.

Your contributions have been instrumental in making this modular shield system possible. Thank you for open-sourcing your work and driving the ZMK ecosystem forward.

If you like my contributions, please don’t forget the following:

I appreciate if you follow me on and !

My other projects:

• zmk-dongle-display-view: Use your niceview vertical with very beautiful widgets
• zmk-oled-adapter: This module is an adapter for 128x32, 128x64 and 128x128 OLED screens, to be used on keyboards with ZMK without having to modify the shields of the keyboards.
• qmk-config will be updated soon
• qmk_userspace will be updated soon
• vimtools swiss army knife for vim (features and settings that will make your life easier)
• gm cross-platform git manager with friendly user interface
• vim-better-header the best automated template
• vim-executor multilanguage code executor

If you enjoy my contributions, feel free to donate.

• paypal
• sponsor

⬆️ back to Table of Contents