smart_keymap/
lib.rs

1#![warn(missing_docs)]
2
3//! Smart Keymap library.
4//!
5//! A "smart keyboard" is a keyboard where the keys can perform
6//!  multiple actions, depending on the context.
7//! Features such as layering, tap-hold, and tap-dance are
8//!  examples of smart keyboard functionality.
9//!
10//! The smart keymap library provides an interface for the "smart keymap"
11//!  part of smart keyboard firmware.
12//! i.e. the part that takes key presses and releases as input,
13//!  and outputs HID keyboard reports (or other smart keyboard outputs).
14//!
15//! This crate can be used directly with Rust, or built as a C library.
16//!
17//! # Usage as a C library
18//!
19//! ## Custom Keymap
20//!
21//! When used as a C library, the library should be built by setting
22//!  the environment variable `SMART_KEYMAP_CUSTOM_KEYMAP` to the path
23//!  of a custom keymap file.
24//!
25//! `SMART_KEYMAP_CUSTOM_KEYMAP` can be set either to a `.ncl` file,
26//!  or to a `.rs` file (generated using the scripts under `ncl/`).
27//!
28//! ## Keyboard Firmware Implementation
29//!
30//! When used as a C library, the firmware should call to
31//!  `keymap_init`, `keymap_register_input_keypress`, `keymap_register_input_keyrelease`,
32//!  and `keymap_tick` functions.
33//! The `keymap_tick` function should be called every ms, and should copy the
34//!  HID keyboard report to the given buffer.
35//!
36//! # Implementation Overview
37//!
38//! The heart of the library is the [key] module, and its
39//! [key::Key], [key::Context], [key::KeyState] traits.
40//!
41//! These provide the interface with which 'smart keys' are implemented.
42
43#![cfg_attr(not(feature = "std"), no_std)]
44
45/// Structs for input to the keymap.
46pub mod input;
47/// Smart key interface and implementations.
48///
49/// The core interface for the smart keymap library is [key::Key],
50///  and its associated [key::Context], `PendingKeyState`, and [key::KeyState] types.
51/// Together, these are used to define smart key behaviour.
52pub mod key;
53/// Keymap implementation.
54pub mod keymap;
55/// Keys1, Keys2, etc. tuple structs for defining keymaps.
56pub mod tuples;
57
58/// Split keyboard support.
59pub mod split;
60
61/// Types and initial data used for constructing a [keymap::Keymap].
62/// cbindgen:ignore
63#[cfg(not(custom_keymap))]
64pub mod init {
65    use crate::key::{composite, keyboard};
66    use crate::keymap;
67    use crate::tuples::Keys1;
68
69    /// Config used to construct initial context.
70    pub const CONFIG: crate::key::composite::Config = crate::key::composite::DEFAULT_CONFIG;
71
72    /// Number of layers supported by the [crate::key::layered] implementation.
73    pub const LAYER_COUNT: usize = 8;
74
75    /// The maximum number of chords.
76    pub const MAX_CHORDS: usize = 4;
77
78    /// The tap-dance definitions.
79    pub const MAX_TAP_DANCE_DEFINITIONS: usize = 3;
80
81    pub use composite::Context;
82
83    pub use composite::Event;
84
85    pub use composite::PendingKeyState;
86
87    pub use composite::KeyState;
88
89    pub use composite::Key;
90
91    /// Initial [Context] value.
92    pub const CONTEXT: Context = composite::Context::from_config(CONFIG);
93
94    /// Alias for a tuples KeysN type. Without a custom keymap, just a single [composite::Key].
95    pub type KeyDefinitionsType = Keys1<Key, Context, Event, PendingKeyState, KeyState>;
96
97    /// Alias for the [keymap::Keymap] type.
98    pub type Keymap = keymap::Keymap<Context, Event, PendingKeyState, KeyState, KeyDefinitionsType>;
99
100    /// A tuples KeysN value with keys. Without a custom keymap, just the letter 'A'.
101    pub const KEY_DEFINITIONS: KeyDefinitionsType =
102        Keys1::new((Key::keyboard(keyboard::Key::new(0x04)),));
103}
104
105#[cfg(custom_keymap)]
106include!(concat!(env!("OUT_DIR"), "/keymap.rs"));
smart_keymap/lib.rs

smart_keymap/
lib.rs
