Skip to content

A library for modeling the internal state of a computer keyboard

License

Notifications You must be signed in to change notification settings

nerves-keyboard/afk

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

AFK

CI Status codecov Hex.pm Version License

A library for modeling the internal state of a computer keyboard. It supports arbitrary layouts with any number of layers, and outputs a basic 6-key HID report byte string.

Its intended use is to model the state for keyboard firmware.

Installation

AFK can be installed by adding afk to your list of dependencies in mix.exs:

def deps do
  [
    {:afk, "~> 0.3"}
  ]
end

Basic Usage

First, you define a keymap:

keymap = [
  # Layer 0 (default)
  %{
    k001: AFK.Keycode.Key.new(:a),
    k002: AFK.Keycode.Modifier.new(:left_control),
    k003: AFK.Keycode.Layer.new(:hold, 1),
    k004: AFK.Keycode.Key.new(:caps_lock)
  },
  # Layer 1
  %{
    k001: AFK.Keycode.Key.new(:z),
    k002: AFK.Keycode.Modifier.new(:right_super),
    k003: AFK.Keycode.None.new(),
    k004: AFK.Keycode.Transparent.new()
  }
]

You can now start a state process using AFK.State.start_link/2, by providing a keymap, an event receiver PID, and a module that implements the AFK.HIDReport behaviour.

{:ok, state} =
  AFK.State.start_link(
    keymap: keymap,
    event_receiver: self(),
    hid_report_mod: AFK.HIDReport.SixKeyRollover
  )

AFK.State.press_key(state, :k003)
AFK.State.press_key(state, :k002)
AFK.State.press_key(state, :k001)
AFK.State.release_key(state, :k002)

# take a look at our process mailbox
:erlang.process_info(self(), :messages)

# {:messages,
#  [
#    hid_report: <<0, 0, 0, 0, 0, 0, 0, 0>>,
#    hid_report: <<128, 0, 0, 0, 0, 0, 0, 0>>,
#    hid_report: <<128, 0, 29, 0, 0, 0, 0, 0>>,
#    hid_report: <<0, 0, 29, 0, 0, 0, 0, 0>>
#  ]}

Future Features

AFK provides a behaviour for defining how to convert the state into a HID report. Currently only a 6-key rollover implementation is provided, but an N-key rollover implementation would be a great addition. (Pull requests welcome!)

It may eventually also support more complex interactions, such as sticky keys, macros, leader keys, etc. These features require a lot more thinking though, as they will require the state undergoing changes over time.

Docs

Documentation can be found at https://hexdocs.pm/afk.