mehalter · mehalter · Sep 18, 2020 · Sep 17, 2020 · Sep 17, 2020 · Sep 17, 2020
diff --git 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/python-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!
 
-<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>
+<a href="https://github.com/makerdiary/python-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 tutorial</button></a>
diff --git a/docs/assembling.md b/docs/assembling.md
@@ -4,16 +4,13 @@
 
 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](./assets/images/attaching-antennas-to-m2.jpg)
 
 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)
diff --git a/docs/assets/images/attaching-antennas-to-m2.jpg b/docs/assets/images/attaching-antennas-to-m2.jpg
diff --git a/docs/backlight.md b/docs/backlight.md
@@ -0,0 +1,35 @@
+# Backlight
+
+The keboard has 64 programmable RGB LEDs. We are still working on the backlight. Before we get it done,
+you are able to customize the backlight in the `macro_handler`.
+For example, we set <kbd>9</kbd> to red color when a macro key pressed, and turn into green color
+when the macro key is released:
+
+```python
+def macro_handler(dev, n, is_down):
+    if is_down:
+        dev.backlight.pixel(9, 0xff, 0, 0)
+    else:
+        dev.backlight.pixel(9, 0, 0xff, 0)
+    dev.backlight.update()
+```
+
+`dev.backlight` provides some basic fucntions to control the RGB LEDs
+
+## Backlight APIs
++ `update()` synchronizes with its buffer.
++ `pixel(i, r, g, b)` sets the bufffer of the LED `i`
++ `set_brightness(value)` sets the global brightness of all LEDs (from 0 to 255)
+
+## Index of RGB LED
+You can find the index of an LED here.
+```
+# ESC(0)    1(1)   2(2)   3(3)   4(4)   5(5)   6(6)   7(7)   8(8)   9(9)   0(10)  -(11)  =(12)  BACKSPACE(13)
+# TAB(27)   Q(26)  W(25)  E(24)  R(23)  T(22)  Y(21)  U(20)  I(19)  O(18)  P(17)  [(16)  ](15)   \(14)
+# CAPS(28)  A(29)  S(30)  D(31)  F(32)  G(33)  H(34)  J(35)  K(36)  L(37)  ;(38)  "(39)      ENTER(40)
+#LSHIFT(52) Z(51)  X(50)  C(49)  V(48)  B(47)  N(46)  M(45)  ,(44)  .(43)  /(42)            RSHIFT(41)
+# LCTRL(53)  LGUI(54)  LALT(55)               SPACE(56)          RALT(57)  MENU(58)  Fn(59)  RCTRL(60)
+```
+
+No.61 and No.62 are under the space key. No.63 is at the back of keyboard.
+
diff --git 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,13 +95,15 @@ 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 will not damage the hardware. Just use another keyboard to fix the error and save the file, and 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
 
-1.  To swap the positions of <kbd>Caps</kbd> and <kbd>LCtrl</kbd>, just swap `CAPS` and `LCTRL` in `layer 0` of `keymap`:
+If you already Python, configuring the keyboard is simple. If not, here are some examples to get started.
+
+1.  Swap the positions of <kbd>Caps</kbd> and <kbd>LCtrl</kbd>. To do this, just swap `CAPS` and `LCTRL` in `layer 0` of `keymap`:
 
     ```python
         # layer 0
@@ -114,7 +116,7 @@ If you know how Python works, configuring the keyboard would be very easy. If no
         ),
     ```
 
-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:
+2.  Use <kbd>Caps</kbd> as a Tap-key to activate navigation functions, instead of <kbd>D</kbd>. To implement this, you only need to change `layer 0` to:
 
     ```python
         # layer 0
@@ -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 <kbd>Fn</kbd> and <kbd>Enter</kbd> to trigger No.1 macro. Just add `MACRO(1)` to `layer 1`:
+3.  Add a new macro. For example, the below uses <kbd>Fn</kbd> and <kbd>Enter</kbd> to trigger macro number 1 (the second macro, after macro number 0). Just add `MACRO(1)` to `layer 1`:
 
     ```python
         # layer 1
@@ -142,7 +144,7 @@ If you know how Python works, configuring the keyboard would be very easy. If no
 
     To define the function of the macro, please follow [the macro guide](macro.md)
 
-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:
+4.  Use <kbd>RShift</kbd>, <kbd>RGUI</kbd>, <kbd>Fn</kbd> and <kbd>RCtrl</kbd> 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

diff --git a/docs/developer_guide/hardware.md b/docs/developer_guide/hardware.md
@@ -0,0 +1,57 @@
+# Hardware
+
+## 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                                                                                        |
+
+![](https://github.com/makerdiary/python-keyboard/blob/master/img/hotswappable.jpg?raw=true)
+
+## Keyboard Matrix
+The pins of 8x8 keyboard matrix:
+
+|     | 1     | 2     | 3     | 4     | 5     | 6     | 7     | 8     |
+|-----|-------|-------|-------|-------|-------|-------|-------|-------|
+| ROW | P0_05 | P0_06 | P0_07 | P0_08 | P1_09 | P1_08 | P0_12 | P0_11 |
+| COL | P0_19 | P0_20 | P0_21 | P0_22 | P0_23 | P0_24 | P0_25 | P0_26 |
+
+## Power
++ When powered by USB, the keyboard is always on.
++ When powered by a battery, the keyboard is on if the ON/OFF button is pressed or pin `P0_28` outputs `0`.
+
+## Button
+The ON/OFF Button is at the back of the keyboard. It is connected to `P0_27`.
+
+## LEDs on M.2
+| LEDs           |  Pin  |
+|--------------- | ------|
+| Red LED        | P0_30 |
+| Green LED      | P0_29 |
+| Blue LED       | P0_31 |
+
+## RGB LEDs Matrix
+The RGB LEDs Matrix has 64 RGB LEDs and is driven by IS32FL3733.
+
+| name           |  Pin   |     note      |
+|--------------- | -------| --------------|
+| Power          | P1_04  | 1: on, 0: off |
+| I2C SDA        | P1_05  |               |
+| I2C SCL        | P1_06  |               |
+| Interrupt      | P1_07  |               |
+
+
+## Battery
+| name           |  Pin   |     note      |
+|--------------- | -------| --------------|
+| Charging       | P0_03  | 0: charging   |
+| Voltage        | P0_02  | AIN0          |
+
diff --git a/docs/developer_guide/index.md b/docs/developer_guide/index.md
@@ -0,0 +1,19 @@
+# Dive Into Keyboard
+
+Normally, you only need to change `code.py` to configure the keyboard.
+If you are very good at Python and have a new idea which can not be implemented in `code.py`,
+you can modify [the `keyboard` library](https://github.com/makerdiary/python-keyboard/tree/main/keyboard).
+
+
+!!! Note
+    When you modify the `keyboard` library, the keyboard may stop working if there is any syntax error or other error in the code. You will need another keyboard to fix it. If you get a fatal error, you can always do a [factory reset](../factory_reset.md).
+
+By default, The CircuitPython firmware of M60 has two frozen modules - [`adafruit_ble`](https://github.com/adafruit/Adafruit_CircuitPython_BLE) and `PYKB`. `PYKB` is a frozen version of the `keyboard` library.
+
+## Use latest `keyboard` library
+1. Copy `keyboard` folder of [python-keyboard](https://github.com/makerdiary/python-keyboard/tree/main/keyboard) to the `lib` directory of the `CIRCUITPY` USB drive.
+2. Replace `from PYKB import *` to `from keyboard import *` in `code.py` of the USB drive.
+
+
+## Develop with C/C++, Rust, JerryScript, TinyGo
+The M60 keybaord also supports C/C++, Rust, JerryScript and TinyGo. To create your own firmware, read [the hardware information](hardware.md) to get started.
diff --git a/docs/factory_reset.md b/docs/factory_reset.md
@@ -0,0 +1,7 @@
+# Factory Reset
+
+If you get a fatal error when you modify the code of keyboard, you can always do a factory reset:
+
+1. Download [factory_reset.uf2](https://gitee.com/makerdiary/python-keyboard/attach_files/469654/download), follow [the firmware upgrade guide](upgrade_firmware.md) to flash `factoary_reset.uf2`. It will erase the storage of the keyboard.
+
+2. Flash the latest firmware from [python-keyboard / firmware](https://github.com/makerdiary/python-keyboard/tree/main/firmware).