From dad4d6fe96437d97f63ee296fa50ac11bd87be91 Mon Sep 17 00:00:00 2001 From: Andrew Russell Date: Thu, 17 Sep 2020 12:48:31 -0400 Subject: [PATCH 01/19] Adjust and smooth out the language --- docs/getting-started.md | 59 ++++++++++++++++++++++------------------- 1 file changed, 32 insertions(+), 27 deletions(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index 539a13a..6f31fcc 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -7,57 +7,60 @@ M60 is a compact keyboard. It has a keymap composed of multiple layers, which is ## Keymap As the 60% keyboard lacks a lot of keys such as F1~F12 and arrow keys, Fn is used to activate a new layer. -When holding Fn down, the following keys are activated. + +By default, holding Fn down activates the following functions: ![](https://gitee.com/makerdiary/python-keyboard/raw/resource/img/layer1.svg) -+ Fn + M triggers No.0 macro -+ Fn + P suspends the keyboard when only powered by battery. -+ Fn + B enters its bootloader (only for upgrade) +- Fn + M triggers No.0 macro +- Fn + P suspends the keyboard when only powered by battery. +- Fn + B enters its bootloader (only for used for firmware upgrades) + +Except for Fn, any normal key can be used as a Tap-key. A Tap-key is a key that can be used as an ordinary key when tapped, or can be held down to activate alternate functions. -Except Fn, a normal key can be used as a Tap-key, which is holding a key down to activate an alternate function. +All of the default Tap-keys, including D, B, and ; can be [re-configured](configuration.md). ### Using B to configure Bluetooth and USB -B is used as a Tap-key to configure Bluetooth and USB. Taping B outputs `b` (press & release quickly). Holding B down activates another new layer. With the layer, the following functions are available: +B is the default Tap-key to configure Bluetooth and USB. Tapping B (i.e., pressing & releasing it quickly) outputs `b`. Holding B down activates another the Bluetooth keyboard layer. When the Bluetooth layer is active, the following functions are available: -+ B + Esc toggles Bluetooth -+ B + 0 ~ 9 changes Bluetooth ID to switch between multiple computers and phones -+ B + U toggles USB +- B + Esc toggles Bluetooth +- B + 0 ~ 9 changes Bluetooth ID to switch between multiple computers and phones +- B + U toggles USB ### Using D for Navigation -D is also used as a Tap key for navigation functions. +D is the default Tap-key to activate the navigation functions. ![](https://gitee.com/makerdiary/python-keyboard/raw/master/img/d-for-navigation.png) -+ D + H → ← -+ D + J → ↓ -+ D + K → ↑ -+ D + L → → -+ D + U → PgUp -+ D + N → PgDn +- D + H → ← +- D + J → ↓ +- D + K → ↑ +- D + L → → +- D + U → PgUp +- D + N → PgDn ### Using ; as Ctrl -; is another type of Tap-key. Taping ; outputs `;`. However, holding ; down outputs `Ctrl` instead of activating a layer. +; is a different type of Tap-key. Tapping ; outputs `;`. However, holding ; down outputs `Ctrl` instead of activating a layer. ![](https://github.com/xiongyihui/keyboard/raw/master/img/semicolon_as_ctrl.png) -+ ; + c = Ctrl + c -+ ; + v = Ctrl + v -+ ; + x = Ctrl + x -+ ; + a = Ctrl + a - +- ; + c = Ctrl + c +- ; + v = Ctrl + v +- ; + x = Ctrl + x +- ; + a = Ctrl + a ## Using Pair-keys -Simultaneously pressing two keys (interval less than 10ms) activates an alternate function. -By default, J K are used as a pair-keys. When simultaneously pressing J and K in a text editor, it will output a pre-defined string. +Simultaneously pressing two keys (i.e., pressing them in an interval of less than 10ms) activates an alternate function. + +Two sets of pair-keys are configured by default, to illustrate how to set up these keys. These include J K and U I. As shipped, simultaneously pressing J and K or U and I in a text editor will output a pre-defined string (_e.g._, "You just triggered pair keys #0"). ## Setup Bluetooth -First, we press B + 1 to start Bluetooth advertising, and then we will see the blue LED under 1 is in breathing mode： +First, press B + 1 to start Bluetooth advertising. You will then see the blue LED under 1 enter in "breathing" mode and flash slowly： ![](https://gitee.com/makerdiary/python-keyboard/raw/resource/img/ble_broadcast.gif) @@ -73,8 +76,10 @@ Choose `Bluetooth` in the `Add a device` dialog, then you will see the device `P -When to connect the keyboard to a second computer, just use B + 2 to start connecting. From 0 to 9, the keyboard can connect to 10 bluetooth devices. +In order to connect the keyboard to a second computer, just use B + 2 to start connecting. From 0 to 9, the keyboard can connect to 10 bluetooth devices. ## Go further -We hope M60 brings you an idea to make a keyboard more productive. You may have your own thoughts of configuring a keyboard. Follow [the configuring guide](configuration.md) to find what works best for you. +We hope M60 keyboard incites ideas to make a keyboard more productive, all without having to install any third-party software or drivers on your computer. + +If you have your own thoughts on how to best configure the keyboard, just follow [the configuring guide](configuration.md) to find what works best for you. From 421151ce92d9f0d0f6572142ce9a5884cbb3e5cf Mon Sep 17 00:00:00 2001 From: Andrew Russell Date: Thu, 17 Sep 2020 12:56:28 -0400 Subject: [PATCH 02/19] Smooth out language, typo fixes, example heading --- docs/configuration.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index 1615d2a..ad06745 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -1,11 +1,11 @@ # Keyboard Configuration 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. -In `code.py`, we can modify its keymap, add a macro and add a new feature to keyboard. +Using `code.py`, you can modify they keyboard's keymap, and add macros, Tap-keys and more. ![](https://gitee.com/makerdiary/python-keyboard/raw/resource/img/CIRCUITPY-en.png) -The default content of `code.py` is: +An up-to-date `code.py` is included in this repository. Example content for `code.py` could be: ```python @@ -95,11 +95,13 @@ keyboard.run() ``` -`keymap` contains multiple layers of keycodes. `macro_handler` is used to handle all macros. `pairs_handler` is used to handle any pair-keys. +The `keymap` variable can contains multiple layers of keycodes. The `macro_handler` is used to handle all macros. The `pairs_handler` is used to handle any pair-keys. -**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** +**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. Use another keyboard to fix the error and save it, then the keyboard will recover.** -If you know how Python works, configuring the keyboard would be very easy. If not, we have some examples to get started. +## Examples + +If you already Python, configuring the keyboard is simple. If not, here are some examples to get started. 1. To swap the positions of Caps and LCtrl, just swap `CAPS` and `LCTRL` in `layer 0` of `keymap`: @@ -127,7 +129,7 @@ If you know how Python works, configuring the keyboard would be very easy. If no ), ``` -2. Add a new macro. Use Fn and Enter to trigger No.1 macro. Just add `MACRO(1)` to `layer 1`: +3. Add a new macro. Use Fn and Enter to trigger No.1 macro. Just add `MACRO(1)` to `layer 1`: ```python # layer 1 From 4034fe6cfdcf742b032eff73e96dac36e428285a Mon Sep 17 00:00:00 2001 From: Andrew Russell Date: Thu, 17 Sep 2020 13:02:45 -0400 Subject: [PATCH 03/19] Fix typos, fix broken link, smooth out language --- docs/CONTRIBUTING.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index e97f3c9..0c61b3b 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -5,14 +5,14 @@ you do, please read the following guidelines. ## Got a question or problem? -For quick questions there's no need to open an issue as you can reach us on [makerdiary/community](https://community.makerdiary.com). +For quick questions there's no need to open an issue, because you can reach us on [makerdiary/community](https://community.makerdiary.com). ## Found a bug? -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. +If you find 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. ## Requesting a tutorial -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! +If you don't see what you're looking for, you can request a tutorial by submitting an issue to our GitHub Repository. We'd love to see your feedback! - \ No newline at end of file + From 727e921f25382e7cc6e1c9b4615d39329f00768d Mon Sep 17 00:00:00 2001 From: Andrew Russell Date: Thu, 17 Sep 2020 13:13:32 -0400 Subject: [PATCH 04/19] List features; add specs; add orientation warning --- docs/index.md | 37 ++++++++++++++++++++----------------- 1 file changed, 20 insertions(+), 17 deletions(-) diff --git a/docs/index.md b/docs/index.md index c7ad572..24f30ea 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,6 +1,6 @@ # M60 Mechanical Keyboard - **En** | [中文][1] +**En** | [中文][1] M60 is a hot-swappable 60% Keyboard with USB, BLE 5.0 and RGB backlight. It is highly configurable and extensible. It can run Python code saved in its USB storage, which makes it super powerful. It has very low power consumption and only needs about 160uA current when connected to a computer via Bluetooth. It is one of the lowest latency USB keyboards. @@ -9,32 +9,35 @@ It can run Python code saved in its USB storage, which makes it super powerful. ## Features -- BLE 5.0 Multi-pairing up to 10 devices -- Hot-swappable -- USB Type-C +- Bluetooth, including BLE 5.0 multi-pairing up to 10 devices +- Hot-swappable key switch mounts +- USB Type-C connector - Standard 60% layout (61 keys) - 6KRO -- RGB backlit +- RGB backlight (pending software support) - Supports Windows/macOS/Linux/iOS/Android - Low power consumption - All keys remappable - Up to 32 layers - Macros - Pair-keys +- Tap-keys ## Specs -| | M60 Keyboard | -|-----------------|-----------------------------------------------------------------------------------| -| Core Module | nRF52840, Arm Cortex-M4F, 64MHz, 256KB RAM, 1MB FLASH, 8MB QSPI Flash, M.2 KEY-E | -| Wireless | Bluetooth Low Energy 5.0, NFC | -| USB | Type-C | -| Layout | 60% (61 Keys) | -| Hot-Swappable | Yes | -| Switch Option | Cherry MX compatible Switches | -| Backlight | 64 RGB LEDs, IS32FL3733 | -|Battery Connector| JST 1.25mm 3-Pin | -| RF Antennas | 2.4GHz Cabled PCB Antenna, NFC Cabled PCB Antenna | -| Dimensions | 285 mm x 94.6 mm | +| | M60 Keyboard | +| ----------------- | -------------------------------------------------------------------------------- | +| Core Module | nRF52840, Arm Cortex-M4F, 64MHz, 256KB RAM, 1MB FLASH, 8MB QSPI Flash, M.2 KEY-E | +| Wireless | Bluetooth Low Energy 5.0, NFC | +| USB | Type-C | +| Layout | 60% (61 Keys) | +| Hot-Swappable | Yes | +| Switch Option | Cherry MX compatible Switches | +| Backlight | 64 RGB LEDs, IS32FL3733 | +| Battery Connector | JST 1.25mm 3-Pin | +| RF Antennas | 2.4GHz Cabled PCB Antenna, NFC Cabled PCB Antenna | +| Dimensions | 285 mm x 94.6 mm (compatible with DZ60 cases) | + +**Note: The PCB uses north-facing switch orientation, and the switches are mounted below the LEDs. If you intend to use Cherry MX or low-profile keycaps, be sure to purchase key switches that are beveled on both sides. See Issue #3.** [1]: https://gitee.com/makerdiary/python-keyboard/wikis/pages From c622104f51d41b66be00fd4c1969bdc7d409e2eb Mon Sep 17 00:00:00 2001 From: Andrew Russell Date: Thu, 17 Sep 2020 13:15:09 -0400 Subject: [PATCH 05/19] Formatting cleanup --- docs/keycodes.md | 58 ++++++++++++++++++++++-------------------------- 1 file changed, 26 insertions(+), 32 deletions(-) diff --git a/docs/keycodes.md b/docs/keycodes.md index 584960a..1d36fff 100644 --- a/docs/keycodes.md +++ b/docs/keycodes.md @@ -1,63 +1,58 @@ - - - Name | Description ---------------|-------------------- -`NO` | Do nothing -`TRANSPARENT` | Use the key of next active layer +| Name | Description | +| ------------- | -------------------------------- | +| `NO` | Do nothing | +| `TRANSPARENT` | Use the key of next active layer | ## Bluetooth - Name | Description ---------------|------------------- -`BT0` ~ `BT9` | Switch to Bluetooth ID n (0 - 9) -`BT_TOGGLE` | Toggle Bluetooth +| Name | Description | +| ------------- | -------------------------------- | +| `BT0` ~ `BT9` | Switch to Bluetooth ID n (0 - 9) | +| `BT_TOGGLE` | Toggle Bluetooth | ## USB - Name | Description ---------------|------------------- -`USB_TOGGLE` | Toggle USB +| Name | Description | +| ------------ | ----------- | +| `USB_TOGGLE` | Toggle USB | -!!! note - When connecting the keyboard to a computer via USB, USB will be enabled automatically. - When both USB and Bluetooth are enabled, USB will be used. +**Note: When connecting the keyboard to a computer via USB, USB will be enabled automatically. When both USB and Bluetooth are enabled, USB will be used.** ## System - Name | Description ---------------|----------------------------------------- -`BOOTLOADER` | Enter the bootloader of the keyboard -`HEATMAP` | Generate heatmap (todo) -`SUSPEND` | Suspend. To wake up keyboard, just press any key -`SHUTDOWN` | Shutdown. Use ON/OFF button to power on the keyboard +| Name | Description | +| ------------ | ---------------------------------------------------- | +| `BOOTLOADER` | Enter the bootloader of the keyboard | +| `HEATMAP` | Generate heatmap (todo) | +| `SUSPEND` | Suspend. To wake up keyboard, just press any key | +| `SHUTDOWN` | Shutdown. Use ON/OFF button to power on the keyboard | ## Layer & Modifier -+ `MODS_KEY(mods, key)` sends one or more modifier(s) + a normal key. `MODS()` is used to wrap modifiers. +- `MODS_KEY(mods, key)` sends one or more modifier(s) + a normal key. `MODS()` is used to wrap modifiers. `MODS_KEY(MODS(LCTRL), C)`, `MODS_KEY(MODS(LCTRL, LSHIFT), C)`, `MODS_KEY(MODS(LCTRL, LSHIFT, LALT), C)` -+ `LAYER_TOGGLE(n)` toggles layer `n` +- `LAYER_TOGGLE(n)` toggles layer `n` -+ `MACRO(n)` creates macro `n` +- `MACRO(n)` creates macro `n` ### TAP-Key -`TAP-Key` has 2 modes - tap (press and release quickly) and hold (long press) +A `TAP-Key` has 2 modes - tap (press and release quickly) and hold (long press) -+ `LAYER_TAP(n, key)` tap - outputs `key`, hold - turns on layer n momentary +- `LAYER_TAP(n, key)` tap - outputs `key`, hold - turns on layer n momentary -+ `LAYER_TAP_TOGGLE(n)` tap - toggles layer n, hold - turns on layer n momentary +- `LAYER_TAP_TOGGLE(n)` tap - toggles layer n, hold - turns on layer n momentary -+ `LAYER_MODS(n, mods)` tap - outputs specified modifier(s), hold - turns on layer n momentary +- `LAYER_MODS(n, mods)` tap - outputs specified modifier(s), hold - turns on layer n momentary `LAYER_MODS(1, MODS(LCTRL))`, `LAYER_MODS(1, MODS(LCTRL, LSHIFT))` -+ `MODS_TAP(mods, key)` tap - outputs `key`, hold - outputs specified modifier(s) +- `MODS_TAP(mods, key)` tap - outputs `key`, hold - outputs specified modifier(s) `MODS_TAP(MODS(LCTRL), ';')`, `MODS_TAP(MODS(LCTRL, LALT), LEFT)` - ## APP & Media ``` @@ -298,4 +293,3 @@ SHIFT ALT GUI ``` - From af472c8a5dd7e8ff1f1fce142f4eec7ea660442f Mon Sep 17 00:00:00 2001 From: Andrew Russell Date: Thu, 17 Sep 2020 13:17:29 -0400 Subject: [PATCH 06/19] Formatting and language updates --- docs/macro.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/macro.md b/docs/macro.md index 0458a4e..b6cf884 100644 --- a/docs/macro.md +++ b/docs/macro.md @@ -1,6 +1,6 @@ # Macro -To setup a macro, add a macro to the keymap and define its function. For example, use Fn as No.0 macro: +To set up a macro, add a macro to the keymap and define its function. By default, Fn is configured as macro number 0: ```python # code.py @@ -27,9 +27,11 @@ keyboard.macro_handler = macro_handler keyboard.run() ``` -## Use a macro to launch the Calculator on Windows +## Examples -Replace the function `macro_handler` with the following code to launch the Calculator with a single keystroke. +### Use a macro to launch the Calculator on Windows + +Replace the function `macro_handler` with the following code to launch the Calculator with a single keystroke: ```python def macro_handler(dev, n, is_down): @@ -39,9 +41,9 @@ def macro_handler(dev, n, is_down): dev.send_text('calc\n') ``` -## Automatic typing +### Automatic typing -Read a file in the USB storage and type its content automatically. +Read a file in the keyboard's USB storage and type its content automatically. ```python def macro_handler(dev, n, is_down): @@ -51,9 +53,9 @@ def macro_handler(dev, n, is_down): dev.send_text(line) ``` -## Repeated typing +### Repeated typing -Use a macro to trigger a repeated sequence of typing until a new key is pressed. +Use a macro to trigger a repeated sequence of key presses until a new key is pressed. ```python def macro_handler(dev, n, is_down): From 1173e19c7dfdbca08c3cbb861677b7b68073def2 Mon Sep 17 00:00:00 2001 From: Andrew Russell Date: Thu, 17 Sep 2020 13:21:22 -0400 Subject: [PATCH 07/19] Clean up and clarify text --- docs/pair-keys.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/pair-keys.md b/docs/pair-keys.md index 27ff3b8..b19182a 100644 --- a/docs/pair-keys.md +++ b/docs/pair-keys.md @@ -1,9 +1,10 @@ # Pair-Keys -When two keys are pressed simultaneously (interval less than 10ms), we use it to activate a pre-defined function. -It is similar to Macro. While, pair-keys doesn't have a released event. +They keyboard can be configured to activate a pre-defined function when two keys are pressed simultaneously (_i.e._, within an interval less than 10ms). -For example, we use J K and U I as pair-keys. +Like a macro, activating pair-keys triggers an immediate event. Unlike a macro, pair-keys do not have a released (key-up) event. + +By default, the keyboard uses J K and U I as pair-keys to trigger an example function (_e.g._, typing "You just triggered pair keys #0"). ```python # code.py From 38bfe111b33587cf83d1765fc2f61b362edaa9e1 Mon Sep 17 00:00:00 2001 From: Andrew Russell Date: Thu, 17 Sep 2020 13:23:39 -0400 Subject: [PATCH 08/19] Tweak formatting, clarify language --- docs/upgrade_firmware.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/docs/upgrade_firmware.md b/docs/upgrade_firmware.md index a081add..bcf3af0 100644 --- a/docs/upgrade_firmware.md +++ b/docs/upgrade_firmware.md @@ -2,18 +2,17 @@ The keyboard has a built-in bootloader to upgrade its firmware. -## Check Current Firmware Version +## How to Check Current Firmware Version -To check the information of the firmware, just open the `boot_out.txt` file in the USB storage of the keyboard. The file contains the version and the compiled date of the firmware: +To check the current version of the firmware, just open `boot_out.txt` in the USB storage device of the keyboard. This file contains the version number and the compiled date of the firmware, for example: ``` Adafruit CircuitPython 6.0.0-alpha.1-110-g121d78ec9 on 2020-08-27; Makerdiary M60 Keyboard with nRF52840 ``` -If you find a newer firmware (file with `.uf2` extension) in [python-keyboard / firmware](https://github.com/makerdiary/python-keyboard/tree/zh-cn/firmware), you could do an upgrade. +If you there is a newer firmware (file with `.uf2` extension) in [python-keyboard / firmware](https://github.com/makerdiary/python-keyboard/tree/zh-cn/firmware), you can do an upgrade. - -## Enter Bootloader +## How to Enter the Bootloader There are 4 ways to run into the bootloader: @@ -31,7 +30,7 @@ There are 4 ways to run into the bootloader: 4. When battery is not attached, hold the ON/OFF button and power on the keyboard with USB. -## Upgrade +## How to Upgrade When the bootloader is running, a USB drive named `M60Keyboard` will appear in your computer. -Download the latest `.uf2` firmware, drag-n-drop the firmware into the USB drive, then wait until a new USB drive named `CIRCUITPY` appears. +Download the latest `.uf2` firmware, drag-n-drop the firmware into the USB drive, and then wait until a new USB drive named `CIRCUITPY` appears. From 4a30f607f978218bbf9c6998cb3555a5b35fa13a Mon Sep 17 00:00:00 2001 From: Andrew Russell Date: Thu, 17 Sep 2020 13:25:38 -0400 Subject: [PATCH 09/19] Formatting update --- docs/assembling.md | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/docs/assembling.md b/docs/assembling.md index aa0c443..70ba82e 100644 --- a/docs/assembling.md +++ b/docs/assembling.md @@ -4,16 +4,12 @@ 2. Attach the provided 2.4GHz and NFC cabled PCB antennas to the nRF52840 M.2 module as shown in the figure below: - ![Attaching Antennas](https://wiki.makerdiary.com/nrf52840-m2-devkit/assets/images/attaching-antennas-to-m2.webp) + ![Attaching Antennas](https://wiki.makerdiary.com/nrf52840-m2-devkit/assets/images/attaching-antennas-to-m2.webp) 3. Insert the module into the connector as shown in the figure below: - - !!! Warning "Angle of Insertion" - Angled insertion is allowable and preferred to minimize the insertion force. The angle of insertion is **5° ~ 25°**, **typically 20°**. - - ![Module Insertion](https://wiki.makerdiary.com/nrf52840-m2-devkit/assets/images/m2-module-insertion.png) + **Warning regarding the angle of insertion: Angled insertion is allowable and is preferred to minimize the insertion force. The angle of insertion is 5° ~ 25°, typically 20°.** + ![Module Insertion](https://wiki.makerdiary.com/nrf52840-m2-devkit/assets/images/m2-module-insertion.png) 4. Secure the module using the provided mounting screw as shown in the figure below: - ![Secure the module](https://wiki.makerdiary.com/nrf52840-m2-devkit/assets/images/secure-m2-module-screw.png) - + ![Secure the module](https://wiki.makerdiary.com/nrf52840-m2-devkit/assets/images/secure-m2-module-screw.png) From 3c1d347eb2c291512b6a6b9ac725851e862e7335 Mon Sep 17 00:00:00 2001 From: Andrew Russell Date: Thu, 17 Sep 2020 13:26:31 -0400 Subject: [PATCH 10/19] Formatting fix --- docs/assembling.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/assembling.md b/docs/assembling.md index 70ba82e..d6f7994 100644 --- a/docs/assembling.md +++ b/docs/assembling.md @@ -7,6 +7,7 @@ ![Attaching Antennas](https://wiki.makerdiary.com/nrf52840-m2-devkit/assets/images/attaching-antennas-to-m2.webp) 3. Insert the module into the connector as shown in the figure below: + **Warning regarding the angle of insertion: Angled insertion is allowable and is preferred to minimize the insertion force. The angle of insertion is 5° ~ 25°, typically 20°.** ![Module Insertion](https://wiki.makerdiary.com/nrf52840-m2-devkit/assets/images/m2-module-insertion.png) From d6120337f16051d0a3d8d5775294d748d30803a1 Mon Sep 17 00:00:00 2001 From: Andrew Russell Date: Thu, 17 Sep 2020 13:31:36 -0400 Subject: [PATCH 11/19] Additional phrasing adjustments --- docs/configuration.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index ad06745..350515a 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -97,13 +97,13 @@ keyboard.run() The `keymap` variable can contains multiple layers of keycodes. The `macro_handler` is used to handle all macros. The `pairs_handler` is used to handle any pair-keys. -**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. Use another keyboard to fix the error and save it, then the keyboard will recover.** +**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 will not damage the hardware. Just use another keyboard to fix the error and save the file, and then the keyboard will recover.** ## Examples If you already Python, configuring the keyboard is simple. If not, here are some examples to get started. -1. To swap the positions of Caps and LCtrl, just swap `CAPS` and `LCTRL` in `layer 0` of `keymap`: +1. Swap the positions of Caps and LCtrl. To do this, just swap `CAPS` and `LCTRL` in `layer 0` of `keymap`: ```python # layer 0 @@ -116,7 +116,7 @@ If you already Python, configuring the keyboard is simple. If not, here are some ), ``` -2. Instead of D, use Caps as a Tap-key to activate navigation functions. Only need to change `layer 0` to: +2. IUse Caps as a Tap-key to activate navigation functions, instead of D. To implement this, you only need to change `layer 0` to: ```python # layer 0 @@ -129,7 +129,7 @@ If you already Python, configuring the keyboard is simple. If not, here are some ), ``` -3. Add a new macro. Use Fn and Enter to trigger No.1 macro. Just add `MACRO(1)` to `layer 1`: +3. Add a new macro. For example, the below uses Fn and Enter to trigger macro number 1 (the second macro, after macro number 0). Just add `MACRO(1)` to `layer 1`: ```python # layer 1 @@ -144,7 +144,7 @@ If you already Python, configuring the keyboard is simple. If not, here are some To define the function of the macro, please follow [the macro guide](macro.md) -4. Use RShift, RGUI, Fn and RCtrl as Tap-keys. Tapping them outputs arrows keys (press & release quickly). Just change `layer 0` to: +4. Use RShift, RGUI, Fn and RCtrl as Tap-keys, so that tapping them outputs arrows keys (press & release quickly). To do this, just change `layer 0` to: ```python # layer 0 From b166cc20110ba2ebffef05d9cf9599368b0c5bc9 Mon Sep 17 00:00:00 2001 From: Andrew Russell Date: Thu, 17 Sep 2020 13:32:26 -0400 Subject: [PATCH 12/19] Language tweak --- docs/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuration.md b/docs/configuration.md index 350515a..3118ccd 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -144,7 +144,7 @@ If you already Python, configuring the keyboard is simple. If not, here are some To define the function of the macro, please follow [the macro guide](macro.md) -4. Use RShift, RGUI, Fn and RCtrl as Tap-keys, so that tapping them outputs arrows keys (press & release quickly). To do this, just change `layer 0` to: +4. Use RShift, RGUI, Fn and RCtrl as Tap-keys, so that tapping them (_i.e._, quickly pressing & releasing them) outputs arrows keys. To do this, just change `layer 0` to: ```python # layer 0 From 6083750fab9ca05d891096abd3d4f9398a0b5fcb Mon Sep 17 00:00:00 2001 From: Andrew Russell Date: Thu, 17 Sep 2020 13:39:58 -0400 Subject: [PATCH 13/19] Additional phrasing fixes; add layer numbers; fix order --- docs/getting-started.md | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index 6f31fcc..2a0ff10 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,12 +1,12 @@ # Get started with M60 Keyboard -M60 is a compact keyboard. It has a keymap composed of multiple layers, which is [similar to TMK Keyboard](https://github.com/tmk/tmk_keyboard/blob/master/tmk_core/doc/keymap.md). By default, No.0 layer is used: +M60 is a compact keyboard. It has a keymap composed of multiple layers, [similar to TMK Keyboard](https://github.com/tmk/tmk_keyboard/blob/master/tmk_core/doc/keymap.md). By default, layer number 0 is used, which includes a normal key map: ![](https://gitee.com/makerdiary/python-keyboard/raw/resource/img/layer0.svg) ## Keymap -As the 60% keyboard lacks a lot of keys such as F1~F12 and arrow keys, Fn is used to activate a new layer. +As the 60% keyboard lacks a lot of keys such as F1~F12 and arrow keys, Fn is used to activate a second layer, layer number 1. By default, holding Fn down activates the following functions: @@ -20,17 +20,9 @@ Except for Fn, any normal key can be used as a Tap-key. A Tap-key is All of the default Tap-keys, including D, B, and ; can be [re-configured](configuration.md). -### Using B to configure Bluetooth and USB - -B is the default Tap-key to configure Bluetooth and USB. Tapping B (i.e., pressing & releasing it quickly) outputs `b`. Holding B down activates another the Bluetooth keyboard layer. When the Bluetooth layer is active, the following functions are available: - -- B + Esc toggles Bluetooth -- B + 0 ~ 9 changes Bluetooth ID to switch between multiple computers and phones -- B + U toggles USB - ### Using D for Navigation -D is the default Tap-key to activate the navigation functions. +D is the default Tap-key to activate the navigation functions. Holding it activates layer number 2, which includes navigation keys: ![](https://gitee.com/makerdiary/python-keyboard/raw/master/img/d-for-navigation.png) @@ -41,6 +33,14 @@ All of the default Tap-keys, including D, B, and ;D + U → PgUp - D + N → PgDn +### Using B to Configure Bluetooth and USB + +B is the default Tap-key to configure Bluetooth and USB. Tapping B (i.e., pressing & releasing it quickly) outputs `b`. Holding B down activates another the Bluetooth keyboard layer, layer number 3. When the Bluetooth layer is active, the following functions are available: + +- B + Esc toggles Bluetooth +- B + 0 ~ 9 changes Bluetooth ID to switch between multiple computers and phones +- B + U toggles USB + ### Using ; as Ctrl ; is a different type of Tap-key. Tapping ; outputs `;`. However, holding ; down outputs `Ctrl` instead of activating a layer. @@ -56,9 +56,9 @@ All of the default Tap-keys, including D, B, and ;J K and U I. As shipped, simultaneously pressing J and K or U and I in a text editor will output a pre-defined string (_e.g._, "You just triggered pair keys #0"). +Two sets of pair-keys are configured by default, to illustrate how to setup these keys. These include J K and U I. As shipped, simultaneously pressing J and K or U and I in a text editor will output a pre-defined string (_e.g._, "You just triggered pair keys #0"). -## Setup Bluetooth +## How to Setup Bluetooth First, press B + 1 to start Bluetooth advertising. You will then see the blue LED under 1 enter in "breathing" mode and flash slowly： @@ -78,8 +78,8 @@ Choose `Bluetooth` in the `Add a device` dialog, then you will see the device `P In order to connect the keyboard to a second computer, just use B + 2 to start connecting. From 0 to 9, the keyboard can connect to 10 bluetooth devices. -## Go further +## Go Further We hope M60 keyboard incites ideas to make a keyboard more productive, all without having to install any third-party software or drivers on your computer. -If you have your own thoughts on how to best configure the keyboard, just follow [the configuring guide](configuration.md) to find what works best for you. +If you have your own thoughts on how to best configure the keyboard, just follow [the configuration guide](configuration.md) to find what works best for you. From c124090a9f912ce6ba4b3982a7a648e1e8ef9380 Mon Sep 17 00:00:00 2001 From: Andrew Russell Date: Thu, 17 Sep 2020 13:44:30 -0400 Subject: [PATCH 14/19] Tweak warning message --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 24f30ea..170e939 100644 --- a/docs/index.md +++ b/docs/index.md @@ -38,6 +38,6 @@ It can run Python code saved in its USB storage, which makes it super powerful. | RF Antennas | 2.4GHz Cabled PCB Antenna, NFC Cabled PCB Antenna | | Dimensions | 285 mm x 94.6 mm (compatible with DZ60 cases) | -**Note: The PCB uses north-facing switch orientation, and the switches are mounted below the LEDs. If you intend to use Cherry MX or low-profile keycaps, be sure to purchase key switches that are beveled on both sides. See Issue #3.** +**Note: The M60 PCB uses a north-facing switch orientation. If you plan to use Cherry MX or low-profile keycaps, be sure to purchase key switches that are beveled on both the north and south ends. See Issue #3.** [1]: https://gitee.com/makerdiary/python-keyboard/wikis/pages From 60d4b6d111f43c21b51ad4d3a2252f56cb8e0776 Mon Sep 17 00:00:00 2001 From: Andrew Russell Date: Thu, 17 Sep 2020 13:45:29 -0400 Subject: [PATCH 15/19] Tweak headings --- docs/macro.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/macro.md b/docs/macro.md index b6cf884..125fc2c 100644 --- a/docs/macro.md +++ b/docs/macro.md @@ -29,7 +29,7 @@ keyboard.run() ## Examples -### Use a macro to launch the Calculator on Windows +### Use a macro to launch the Calculator application on Windows Replace the function `macro_handler` with the following code to launch the Calculator with a single keystroke: @@ -53,7 +53,7 @@ def macro_handler(dev, n, is_down): dev.send_text(line) ``` -### Repeated typing +### Repeated key strokes Use a macro to trigger a repeated sequence of key presses until a new key is pressed. From 867e8470e0953c21f1d105b90d0881def30c251d Mon Sep 17 00:00:00 2001 From: Andrew Russell Date: Thu, 17 Sep 2020 13:46:06 -0400 Subject: [PATCH 16/19] Tweak language --- docs/macro.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/macro.md b/docs/macro.md index 125fc2c..27c2305 100644 --- a/docs/macro.md +++ b/docs/macro.md @@ -43,7 +43,7 @@ def macro_handler(dev, n, is_down): ### Automatic typing -Read a file in the keyboard's USB storage and type its content automatically. +Use the following code to read a file in the keyboard's USB storage and type its content automatically: ```python def macro_handler(dev, n, is_down): @@ -55,7 +55,7 @@ def macro_handler(dev, n, is_down): ### Repeated key strokes -Use a macro to trigger a repeated sequence of key presses until a new key is pressed. +Use a macro to trigger a repeated sequence of key presses until a new key is pressed: ```python def macro_handler(dev, n, is_down): From 4f76a8fb5dfe6e8fa398a1bf8e34b2c99787e7ef Mon Sep 17 00:00:00 2001 From: Andrew Russell Date: Thu, 17 Sep 2020 13:47:28 -0400 Subject: [PATCH 17/19] Language tweak --- docs/pair-keys.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/pair-keys.md b/docs/pair-keys.md index b19182a..02d7b1e 100644 --- a/docs/pair-keys.md +++ b/docs/pair-keys.md @@ -2,9 +2,9 @@ They keyboard can be configured to activate a pre-defined function when two keys are pressed simultaneously (_i.e._, within an interval less than 10ms). -Like a macro, activating pair-keys triggers an immediate event. Unlike a macro, pair-keys do not have a released (key-up) event. +Like a macro, activating pair-keys triggers an immediate event. Unlike a macro, pair-keys do not have a release (key-up) event. -By default, the keyboard uses J K and U I as pair-keys to trigger an example function (_e.g._, typing "You just triggered pair keys #0"). +By default, the keyboard uses J K and U I as pair-keys to trigger example functions (_e.g._, typing "You just triggered pair keys #0"). ```python # code.py From 101acc9c029c5dafd318cf2bc3a28d67d7a6039b Mon Sep 17 00:00:00 2001 From: Andrew Russell Date: Thu, 17 Sep 2020 13:49:14 -0400 Subject: [PATCH 18/19] Tweak language --- docs/upgrade_firmware.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/upgrade_firmware.md b/docs/upgrade_firmware.md index bcf3af0..18c614f 100644 --- a/docs/upgrade_firmware.md +++ b/docs/upgrade_firmware.md @@ -10,7 +10,7 @@ To check the current version of the firmware, just open `boot_out.txt` in the US Adafruit CircuitPython 6.0.0-alpha.1-110-g121d78ec9 on 2020-08-27; Makerdiary M60 Keyboard with nRF52840 ``` -If you there is a newer firmware (file with `.uf2` extension) in [python-keyboard / firmware](https://github.com/makerdiary/python-keyboard/tree/zh-cn/firmware), you can do an upgrade. +If you there is a newer firmware revision (file with `.uf2` extension) in [python-keyboard / firmware](https://github.com/makerdiary/python-keyboard/tree/zh-cn/firmware), you upgrade to the newest version by following the instructions below. ## How to Enter the Bootloader @@ -28,7 +28,7 @@ There are 4 ways to run into the bootloader: mcu.reset() ``` -4. When battery is not attached, hold the ON/OFF button and power on the keyboard with USB. +4. When a battery is not attached, hold the ON/OFF button and power on the keyboard with USB. ## How to Upgrade From b444046958f8f40c59618f3c19e8de6972ca881c Mon Sep 17 00:00:00 2001 From: Andrew Russell Date: Thu, 17 Sep 2020 13:52:16 -0400 Subject: [PATCH 19/19] Fix i.e. --- docs/getting-started.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index 2a0ff10..f74dd3e 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -35,7 +35,7 @@ All of the default Tap-keys, including D, B, and ;B to Configure Bluetooth and USB -B is the default Tap-key to configure Bluetooth and USB. Tapping B (i.e., pressing & releasing it quickly) outputs `b`. Holding B down activates another the Bluetooth keyboard layer, layer number 3. When the Bluetooth layer is active, the following functions are available: +B is the default Tap-key to configure Bluetooth and USB. Tapping B (_i.e._, pressing & releasing it quickly) outputs `b`. Holding B down activates another the Bluetooth keyboard layer, layer number 3. When the Bluetooth layer is active, the following functions are available: - B + Esc toggles Bluetooth - B + 0 ~ 9 changes Bluetooth ID to switch between multiple computers and phones @@ -54,7 +54,7 @@ All of the default Tap-keys, including D, B, and ;J K and U I. As shipped, simultaneously pressing J and K or U and I in a text editor will output a pre-defined string (_e.g._, "You just triggered pair keys #0").