A small node script that will communicate with a qmk keyboard over raw hid
Last updated 5 months ago by klathmon .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install @klathmon/qmk-hid-display 
SYNC missed versions from official npm registry.


A small node script that will collect data and send updates to a qmk enabled keyboard to show on the OLED display.

Klathmon's Fork

I forked this and changed it so it should run on both MacOS and Windows but with only CPU and RAM in the perf monitor. I also changed the package name to be @klathmon/qmk-hid-display so that I could publish it and run it on any computer that has node installed by just doing npx @klathmon/qmk-hid-display.


  • To use this script you must have a QMK enabled keyboard with OLED displays such as the Lily58.
  • You also need to have flashed the keyboard with custom QMK firmware that has the corresponding OLED update code
  • The update code can be found on my qmk_firmware fork in the lily58 branch.
  • You will also need to have copied over my custom font from this repo
    • This font can be found in the qmk_firmware fork here: glcdfont.c
    • font.bmp

Development Setup

  • Clone this repo
  • Run npm install in '/qmk-hid-display'
  • Plug in your QMK enabled keyboard that has the custom firmware (linked above)
  • Open '/qmk-hid-display' in VS Code
  • Press F5 to start debugging

Using the script

  • Clone this repo
  • Run npm install in '/qmk-hid-display'
  • Plug in your QMK enabled keyboard that has the custom firmware (linked above)
  • Run npm run start

How it works

  • The script simply calls various node api/packages to collect data that we want to use for the display on the keyboard oled screen
  • The examples included are:
    • Perf - shows stats for cpu, memory usage (mem), disk activity (dsk), and network bandwidth use (net). As a little bar graph.
    • Stock - shows current stock price of 4 tech stocks I added, MSFT, AAPL, GOOG, and FB.
    • Weather - shows current weather forecast for the Seattle area.
  • But essentially you can use anything that fits into the 21x4 character screen and is available in the font image
  • Once per second, the script sends over the screen data to the keyboard one line at a time which is then sent to the slave oled on the keyboard
  • The keyboard can also send data back to the script to indicate which data it would like to show.
  • Data must be sent in the form of an 84 (21*4) length byte array, where each byte corresponds to an index in the font image
    • Warning - I don't know that there is sufficient array length checks in the example firmware, so do be sure not to send the wrong amount of data
  • The keyboard already takes care of mapping normal ascii chars to the font data index, so you can just convert an 84 length string into char codes (using charCodeAt) and send that.
  • The script does some slightly fancy stuff to map to different parts of the font image where I've drawn sideways titles so that it reads correctly on the oled (but those can only be 4 spaces long due to the orientation of the oled displays)
  • Since all the processing is done in the script and the keyboard just displays whatever you send, you don't need to re-flash the firmware at all
  • This means you could do fancy effects like scrolling the text if it was too long by just sending a different string in each update (see the startWeatherMonitor())

To anyone brave enough to use this - Good Luck!

Current Tags

  • 1.0.5                                ...           latest (5 months ago)

6 Versions

  • 1.0.5                                ...           5 months ago
  • 1.0.4                                ...           5 months ago
  • 1.0.3                                ...           5 months ago
  • 1.0.2                                ...           5 months ago
  • 1.0.1                                ...           5 months ago
  • 1.0.0                                ...           5 months ago
Maintainers (1)
Today 0
This Week 6
This Month 6
Last Day 6
Last Week 0
Last Month 1
Dependencies (3)
Dev Dependencies (0)
Dependents (0)

Copyright 2014 - 2016 © taobao.org |