Skip to content

Commit fdc17db

Browse files
xiongyihuixiongyihui
committed
add docs
1 parent 934efa6 commit fdc17db

File tree

8 files changed

+407
-114
lines changed

8 files changed

+407
-114
lines changed

‎README.md

Lines changed: 9 additions & 109 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,7 @@ Python Keyboard
44
English | [中文][1]
55
---------|----------
66

7-
From a hand-wired USB & Bluetooth keyboard powered by Python to production.
8-
9-
The Python keyboard works so well thanks to MicroPython and CircuitPython.
7+
Create a hand-wired keyboard, run Python on it, turn it into production.
108

119
![](img/python-inside-keyboard.png)
1210

@@ -21,9 +19,9 @@ With putting more time into the Python keyboard, we find it more and more intere
2119
[![](img/m60.jpg)](https://makerdiary.com/m60)
2220

2321
## To be a productive keyboard
24-
As the 60% keyboard lacks a lot of keys (F1~F12, arrow keys and etc). We can add
22+
As the 60% keyboard lacks a lot of keys (F1~F12, arrow keys and etc). We can use
2523
[features like TMK's layers and composite keys](https://github.com/tmk/tmk_keyboard/blob/master/tmk_core/doc/keymap.md) to make the small keyboard much more powerful.
26-
With the idea of [Toward a more useful keyboard](https://github.com/jasonrudolph/keyboard) to keep our fingers at the home row, we can optimize the keyboard to make us more productive.
24+
With the idea from [Toward a more useful keyboard](https://github.com/jasonrudolph/keyboard) to keep our fingers at the home row, we can optimize the keyboard to make us more productive.
2725

2826
Adding the Tap-key feature, which is holding a key down to activate an alternate function, can make a big difference.
2927

@@ -41,128 +39,30 @@ Taping <kbd>d</kbd> outputs <kbd>d</kbd> (press & release quickly), holding <kbd
4139
+ <kbd>d</kbd> + <kbd>n</kbd> as <kbd>PageDown</kbd>
4240

4341

44-
To apply the feature, change `code.py` to:
45-
46-
```python
47-
# code.py
48-
49-
from keyboard import *
50-
51-
52-
keyboard = Keyboard()
53-
54-
___ = TRANSPARENT
55-
L1D = LAYER_TAP(1, D) # Holding D down to activate the layer #1
56-
57-
keyboard.keymap = (
58-
# layer #0
59-
(
60-
ESC, 1, 2, 3, 4, 5, 6, 7, 8, 9, 0, '-', '=', BACKSPACE,
61-
TAB, Q, W, E, R, T, Y, U, I, O, P, '[', ']', '|',
62-
CAPS, A, S, L1D, F, G, H, J, K, L, ';', '"', ENTER,
63-
LSHIFT,Z, X, C, V, B, N, M, ',', '.', '/', RSHIFT,
64-
LCTRL, LGUI, LALT, SPACE, RALT, MENU, L1, RCTRL
65-
),
66-
67-
# layer #1
68-
(
69-
'`', F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, DEL,
70-
___, ___, ___, ___, ___, ___, ___,PGUP, ___, ___, ___, ___, ___, ___,
71-
___, ___, ___, ___, ___, ___,LEFT,DOWN, UP,RIGHT, ___, ___, ___,
72-
___, ___, ___, ___, ___, ___,PGDN, ___, ___, ___, ___, ___,
73-
___, ___, ___, ___, ___, ___, ___, ___
74-
),
75-
)
76-
77-
keyboard.run()
78-
```
79-
8042
### Using <kbd>;</kbd> as <kbd>Ctrl</kbd>
81-
Use <kbd>;</kbd> as a MODS_TAP key, taping <kbd>;</kbd> outputs <kbd>;</kbd>, holding <kbd>;</kbd> down outputs <kbd>Ctrl</kbd>. To enable it, change the keymap to:
82-
83-
```python
84-
# code.py
85-
from keyboard import *
86-
87-
88-
keyboard = Keyboard()
43+
Use <kbd>;</kbd> as a MODS_TAP key, taping <kbd>;</kbd> outputs <kbd>;</kbd>, holding <kbd>;</kbd> down outputs <kbd>Ctrl</kbd>.
8944

90-
___ = TRANSPARENT
91-
L1D = LAYER_TAP(1, D) # D as a LAYER_TAP key
45+
![](https://github.com/xiongyihui/keyboard/raw/master/img/semicolon_as_ctrl.png)
9246

93-
# Semicolon & Ctrl
94-
SCC = MODS_TAP(MODS(RCTRL), ';') # ; as a MODS_TAP key
95-
96-
keyboard.keymap = (
97-
# layer #0
98-
(
99-
ESC, 1, 2, 3, 4, 5, 6, 7, 8, 9, 0, '-', '=', BACKSPACE,
100-
TAB, Q, W, E, R, T, Y, U, I, O, P, '[', ']', '|',
101-
CAPS, A, S, L2D, F, G, H, J, K, L, SCC, '"', ENTER,
102-
LSHIFT,Z, X, C, V, B, N, M, ',', '.', '/', RSHIFT,
103-
LCTRL, LGUI, LALT, SPACE, RALT, MENU, L1, RCTRL
104-
),
105-
106-
# layer #1
107-
(
108-
'`', F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, DEL,
109-
___, ___, ___, ___, ___, ___, ___,PGUP, ___, ___, ___, ___, ___, ___,
110-
___, ___, ___, ___, ___, ___,LEFT,DOWN, UP,RIGHT, ___, ___, ___,
111-
___, ___, ___, ___, ___, ___,PGDN, ___, ___, ___, ___, ___,
112-
___, ___, ___, ___, ___, ___, ___, ___
113-
),
114-
)
115-
116-
keyboard.run()
117-
```
11847

11948
### Using Pair-keys
120-
Simultaneously pressing two keys (interval less than 25ms) activates an alternate function.
121-
122-
```python
123-
def pairs_handler(dev, n):
124-
dev.send_text('You just trigger No.{} pair keys'.format(n))
125-
126-
keyboard.pairs_handler = pairs_handler
127-
128-
# Map key to number
129-
#
130-
# ESC 1 2 3 4 5 6 7 8 9 0 - = BACKSPACE
131-
# TAB Q W E R T Y U I O P [ ] |
132-
# CAPS A S D F G H J K L ; " ENTER
133-
#LSHIFT Z X C V B N M , . / RSHIFT
134-
# LCTRL LGUI LALT SPACE RALT MENU L1 RCTRL
135-
#
136-
# 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13,
137-
# 27,26, 25, 24, 23, 22, 21, 20, 19, 18, 17, 16, 15, 14,
138-
# 28,29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40,
139-
# 52,51, 50, 49, 48, 47, 46, 45, 44, 43, 42, 41,
140-
# 53, 54, 55, 56, 57, 58, 59, 60
141-
142-
# Pairs: J & K
143-
keyboard.pairs = [{35, 36}]
144-
145-
keyboard.run()
146-
```
49+
Simultaneously pressing two keys (interval less than 10ms) activates an alternate function.
14750

14851
### Optimizing with C modules<sup><kbd>in progress</kbd></sup>
14952

150-
A C module `matrix` of keyboard matrix is written to reduce latency and improve power efficiency. The module has the same function as [`keyboard/matrix.py`](keyboard/matrix.py).
151-
152-
The module is included in the latest firmware in `firmware/`. If you are interested, you can build it from [circuitpython/tree/m60](https://github.com/xiongyihui/circuitpython/tree/m60).
53+
A C module `matrix` of keyboard matrix is written to reduce latency and power consuption. The module has the same function as [`keyboard/matrix.py`](keyboard/matrix.py).
15354

15455

15556
## Todo
156-
- [x] add macro
157-
- [x] add cosumer keys
158-
- [X] add RGB backlight
15957
- [ ] add system keys
16058
- [ ] add mouse keys
16159

16260

16361
## Credits
16462
+ [MicroPython](https://github.com/micropython/micropython)
16563
+ [CircuitPython](https://github.com/adafruit/circuitpython)
64+
+ [TMK](https://github.com/tmk/tmk_keyboard)
65+
+ [Toward a more useful keyboard](https://github.com/jasonrudolph/keyboard)
16666

16767

16868
[1]: https://gitee.com/makerdiary/python-keyboard

‎docs/CONTRIBUTING.md

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Contributing
2+
3+
Interested in contributing to [python-keyboard](https://github.com/makerdiary/python-keyboard)? Want to report a bug? Before
4+
you do, please read the following guidelines.
5+
6+
## Got a question or problem?
7+
8+
For quick questions there's no need to open an issue as you can reach us on [makerdiary/community](https://community.makerdiary.com).
9+
10+
## Found a bug?
11+
12+
If you found a bug in the source code, you can help us by submitting an issue to the [issue tracker](https://github.com/makerdiary/mx-keyboard/issues) in our GitHub repository. Even better, you can submit a Pull Request with a fix.
13+
14+
## Requesting a tutorial
15+
16+
If you don't see what you're looking for, you can request a tutoial by submitting an issue to our GitHub Repository. We'd love to see your feedback!
17+
18+
<a href="https://github.com/makerdiary/mx-keyboard/issues/new?title=Tutorial%20Request:%20%3Ctitle%3E&body=Description%0A%0ATechnical%20Level%0Abeginner%20%7C%20intermediate%20%7C%20advanced%0A%0ALength%0Ashort%20(%3C%20250%20words)%20%7C%20medium%20(250-500%20words)%20%7C%20long%20(1000%20words+)%0A"><button data-md-color-primary="red-bud" style="width: auto;"><i class="fa fa-github"></i> Request a tutoial</button></a>

‎docs/configuration.md

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
# Keyboard Configuration
2+
3+
M60 is not just a USB HID device, but also a USB storage device. Python code can be saved and executed in the keyboard. When the keyboard powers on, it will run the Python file `code.py` in its USB storage.
4+
In `code.py`, we can modify its keymap, add a macro and add a new feature to keyboard.
5+
6+
![](https://gitee.com/makerdiary/python-keyboard/raw/resource/img/CIRCUITPY.png)
7+
8+
The default content of `code.py` is:
9+
10+
```python
11+
12+
from PYKB import *
13+
14+
15+
keyboard = Keyboard()
16+
17+
___ = TRANSPARENT
18+
BOOT = BOOTLOADER
19+
L1 = LAYER_TAP(1)
20+
L2D = LAYER_TAP(2, D)
21+
L3B = LAYER_TAP(3, B)
22+
LSFT4 = LAYER_MODS(4, MODS(LSHIFT))
23+
RSFT4 = LAYER_MODS(4, MODS(RSHIFT))
24+
25+
# Semicolon & Ctrl
26+
SCC = MODS_TAP(MODS(RCTRL), ';')
27+
28+
keyboard.keymap = (
29+
# layer 0
30+
(
31+
ESC, 1, 2, 3, 4, 5, 6, 7, 8, 9, 0, '-', '=', BACKSPACE,
32+
TAB, Q, W, E, R, T, Y, U, I, O, P, '[', ']', '|',
33+
CAPS, A, S, L2D, F, G, H, J, K, L, SCC, '"', ENTER,
34+
LSFT4, Z, X, C, V, L3B, N, M, ',', '.', '/', RSFT4,
35+
LCTRL, LGUI, LALT, SPACE, RALT, MENU, L1, RCTRL
36+
),
37+
38+
# layer 1
39+
(
40+
'`', F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, DEL,
41+
___, ___, UP, ___, ___, ___, ___, ___, ___, ___,SUSPEND,___,___,___,
42+
___,LEFT,DOWN,RIGHT,___, ___, ___, ___, ___, ___, ___, ___, ___,
43+
___, ___, ___, ___, ___,BOOT, ___,MACRO(0), ___, ___, ___, ___,
44+
___, ___, ___, ___, ___, ___, ___, ___
45+
),
46+
47+
# layer 2
48+
(
49+
'`', F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, DEL,
50+
___, ___, ___, ___, ___, ___, ___,PGUP, ___, ___, ___,AUDIO_VOL_DOWN,AUDIO_VOL_UP,AUDIO_MUTE,
51+
___, ___, ___, ___, ___, ___,LEFT,DOWN, UP,RIGHT, ___, ___, ___,
52+
___, ___, ___, ___, ___, ___,PGDN, ___, ___, ___, ___, ___,
53+
___, ___, ___, ___, ___, ___, ___, ___
54+
),
55+
56+
# layer 3
57+
(
58+
BT_TOGGLE,BT1,BT2, BT3,BT4,BT5,BT6,BT7, BT8, BT9, BT0, ___, ___, ___,
59+
___, ___, ___, ___, ___, ___,___,USB_TOGGLE,___,___,___,___,___, ___,
60+
___, ___, ___, ___, ___, ___, ___, ___, ___, ___, ___, ___, ___,
61+
___, ___, ___, ___, ___, ___, ___, ___, ___, ___, ___, ___,
62+
___, ___, ___, ___, ___, ___, ___, ___
63+
),
64+
65+
# layer 4
66+
(
67+
'`', ___, ___, ___, ___, ___, ___, ___, ___, ___, ___, ___, ___, ___,
68+
___, ___, ___, ___, ___, ___, ___, ___, ___, ___, ___, ___, ___, ___,
69+
___, ___, ___, D, ___, ___, ___, ___, ___, ___, ';', ___, ___,
70+
___, ___, ___, ___, ___, B, ___, ___, ___, ___, ___, ___,
71+
___, ___, ___, ___, ___, ___, ___, ___
72+
),
73+
)
74+
75+
76+
def macro_handler(dev, n, is_down):
77+
if is_down:
78+
dev.send_text('You pressed macro #{}\n'.format(n))
79+
else:
80+
dev.send_text('You released macro #{}\n'.format(n))
81+
82+
def pairs_handler(dev, n):
83+
dev.send_text('You just triggered pair keys #{}\n'.format(n))
84+
85+
86+
keyboard.macro_handler = macro_handler
87+
keyboard.pairs_handler = pairs_handler
88+
89+
# Pairs: J & K, U & I
90+
keyboard.pairs = [{35, 36}, {20, 19}]
91+
92+
keyboard.verbose = False
93+
94+
keyboard.run()
95+
96+
```
97+
98+
`keymap` contains multiple layers of keycodes. `macro_handler` is used to handle all macros. `pairs_handler` is used to handle any pair-keys.
99+
100+
**When `code.py` is saved, the keyboard will reload it. If `code.py` has a syntax error, the keyboard will stop working. But, don't worry, it wouldn't damage the hardware. Fix the error and save it, then the keyboard will recover**
101+
102+
If you know how Python works, configuring the keyboard would be very easy. If not, we have some examples to get started.
103+
104+
1. To swap the positions of <kbd>Caps</kbd> and <kbd>LCtrl</kbd>, just swap `CAPS` and `LCTRL` in `layer 0` of `keymap`:
105+
106+
```python
107+
# layer 0
108+
(
109+
ESC, 1, 2, 3, 4, 5, 6, 7, 8, 9, 0, '-', '=', BACKSPACE,
110+
TAB, Q, W, E, R, T, Y, U, I, O, P, '[', ']', '|',
111+
LCTRL, A, S, L2D, F, G, H, J, K, L, SCC, '"', ENTER,
112+
LSFT4, Z, X, C, V, L3B, N, M, ',', '.', '/', RSFT4,
113+
CAPS, LGUI, LALT, SPACE, RALT, MENU, L1, RCTRL
114+
),
115+
```
116+
117+
2. Instead of <kbd>D</kbd>, use <kbd>Caps</kbd> as a Tap-key to activate navigation functions. Only need to change `layer 0` to:
118+
119+
```python
120+
# layer 0
121+
(
122+
ESC, 1, 2, 3, 4, 5, 6, 7, 8, 9, 0, '-', '=', BACKSPACE,
123+
TAB, Q, W, E, R, T, Y, U, I, O, P, '[', ']', '|',
124+
LAYER_TAP(2, CAPS), A, S, D, F, G, H, J, K, L, SCC, '"', ENTER,
125+
LSFT4, Z, X, C, V, L3B, N, M, ',', '.', '/', RSFT4,
126+
LCTRL, LGUI, LALT, SPACE, RALT, MENU, L1, RCTRL
127+
),
128+
```
129+
130+
2. Add a new macro. Use <kbd>Fn</kbd> and <kbd>Enter</kbd> to trigger No.1 macro. Just add `MACRO(1)` to `layer 1`:
131+
132+
```python
133+
# layer 1
134+
(
135+
'`', F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, DEL,
136+
___, ___, UP, ___, ___, ___, ___, ___, ___, ___,SUSPEND,___,___,___,
137+
___,LEFT,DOWN,RIGHT,___, ___, ___, ___, ___, ___, ___, ___, MACRO(1),
138+
___, ___, ___, ___, ___,BOOT, ___,MACRO(0), ___, ___, ___, ___,
139+
___, ___, ___, ___, ___, ___, ___, ___
140+
),
141+
```
142+
143+
To define the function of the macro, please follow [the macro guide](macro.md)
144+
145+
4. Use <kbd>RShift</kbd>, <kbd>RGUI</kbd>, <kbd>Fn</kbd> and <kbd>RCtrl</kbd> as Tap-keys. Tapping them outputs arrows keys (press & release quickly). Just change `layer 0` to:
146+
147+
```python
148+
# layer 0
149+
(
150+
ESC, 1, 2, 3, 4, 5, 6, 7, 8, 9, 0, '-', '=', BACKSPACE,
151+
TAB, Q, W, E, R, T, Y, U, I, O, P, '[', ']', '|',
152+
CAPS, A, S, L2D, F, G, H, J, K, L, SCC, '"', ENTER,
153+
LSFT4, Z, X, C, V, L3B, N, M, ',', '.', '/', MODS_TAP(MODS(RSHIFT), UP),
154+
LCTRL, LGUI, LALT, SPACE, RALT, MODS_TAP(MODS(RGUI), LEFT), LAYER_TAP(1, DOWN), MODS_TAP(MODS(RCTRL), RIGHT)
155+
),
156+
```

0 commit comments

Comments
 (0)