Migration document

source/bpi-dev/mpy-tutorials.rst

@@ -10,4 +10,4 @@ MicroPython是 Python 3 语言的精简实现 ，包括Python标准库的一小
    ../bpi-mpy/know_github
    ../bpi-mpy/flash_mpy
    ../bpi-mpy/simple_use
-
+   ../bpi-mpy/basics/index

source/bpi-mpy/basics/accelerometer.md

@@ -0,0 +1,61 @@
+
+# Document
+
+![](./head.jpg)
+
+## 板子姿态检测
+
+- 这个模块可以让你获得板子当前的九轴姿态，分别是加速度、重力、磁感应的(X\Y\Z)方向状态值。
+
+- 最基本的功能是获取它们当前的 X、Y、Z 三轴的值来判断板子此时的运动状态，比如说，加速度 Z 值由小增大，表示 Z 轴方向上有在移动（有了加速度），所以可以判断出板子在移动，移动的方向在 Z 轴之上。 
+
+### 基础运用
+
+- 经过了简单的介绍，我们可以设计一个简单的判断，例如 获取板子的平衡情况，以 accelerometer 加速度模块为例，获取它的 X 轴的值，即可得到一个基本的数值，如果数值大于 20 说明它向右偏了，如果小于 - 20 则说明它向左偏了，如果在 这两者之间，则说明它是平衡的，所以有如下的代码，显示 L 表示向左偏，而显示 R 表示板子向右偏了，试试吧！
+
+```python
+from microbit import *
+
+while True:
+    reading = accelerometer.get_x()
+    if reading > 20:
+        display.show("R")
+    elif reading < -20:
+        display.show("L")
+    else:
+        display.show("-")
+```
+
+### 实测效果
+
+- ![base](how_to_accelerometer/base.gif)
+
+### 进阶运用
+
+- 姿态检测，例如上下左右左右，前进后退摇晃自由落地等，如下代码就是，当板子面向上的时候显示笑脸，面向下的则是显示生气的表情。
+
+```python
+from microbit import *
+
+while True:
+    gesture = accelerometer.current_gesture()
+    if gesture == "face up":
+        display.show(Image.HAPPY)
+    else:
+        display.show(Image.ANGRY)
+
+```
+
+### 实测效果
+
+- 当前固件还未更新该功能。
+
+### 趣味游戏
+
+- 基于先前的基础运用，我们可以做出一个趣味游戏，代码在下方连接，底下也有对应的实测动图，可能要加载一会，有些庞大。
+
+- [平衡球代码（适用于 1.4 版）](https://github.com/BPI-STEAM/BPI-BIT-MicroPython/blob/master/11.app/balance_ball.py)
+
+- ![balance_ball](how_to_accelerometer/balance_ball.gif)
+
+- ![logo](./logo.jpg)

source/bpi-mpy/basics/button.rst

@@ -0,0 +1,70 @@
+检测面板按键
+------------
+
+好的，至少我们现在已经会创建一些代码让板子做一些事情了。
+那么，接下来我们来处理设备的输入，比如按键输入吧。
+首先，我们要知道两个概念， Output 输出是表示从设备输出到外围，Input
+输入是处理设备过程中接受到的一些信息
+
+那么在板子上最明显的输入便是二个按钮，灯板左右两个 A 和 B
+按键，如果我们能想得知板子按键按下了吗，或者是按过吗，又或是，按了几次，要如何做到呢？
+
+其实这并不难，倒不如说很容易做到。
+
+.. code:: python
+
+   from microbit import *
+
+   sleep(2000)
+
+   display.scroll(str(button_a.get_presses()))
+
+这段代码运行时候会先暂停两秒，然后你才开始按键，此时将会滚动显示你按下 A
+的次数。就是这样简单，虽然这些代码并没有什么用，但还是提供了些许新思路，让你可以去想象更多控制硬件的方式。
+
+1. 这个 sleep
+   函数可以让板子暂停些许时间，暂停的时间为方块数字的毫秒，如果你想在你的程序某个时候暂停，就按照上面那样写个
+   sleep 函数就行。
+2. button_a 对象允许你通过 get_presses 方法 获取一个时间内被按的次数
+
+然后一旦 get_presses 获取到了值，将其传递到 display.sroll
+中，这个方法只能接受字符型，所以我们需要通过 str 函数将 整型转换成字符串
+所以针对 python 原理我们做了一个假设，进行更深层次的理解 如果你在 10
+秒内按了 10 次，那么上面代码的第三行怎么执行呢？ 由于 python
+是从最内层开始执行代码的。 所以：
+
+``display.scroll(str(button_a.get_presses()))``
+
+当然变成这样就会显示你按下的按键次数（一段时间里，可指定）。
+
+``display.scroll(str(10))``
+
+现在python已经知道按了多少下了，所以接下来将里面的变成字符串，记注一定是最内层优先执行，即先执行
+str(“10”)。
+
+``display.scroll(str("10"))``
+
+循环处理事件
+========
+
+如果你想要板子去响应一个按钮按压事件，那么你就需要用 if
+进行判断按钮是否按压，而且这个判断方法建议放在一个死循环中。 例如：
+
+.. code:: python
+
+   while True:
+       # Do stuff
+
+所以我们可以构筑一个很简单的代码
+
+.. code:: python
+
+   from microbit import *
+
+   while True:
+       if button_a.is_pressed():
+           display.show(Image.HAPPY)
+           display.clear()
+
+此时可以按下按键 A 显示我们之前学习到的 Image ，这便是所谓的学以致用了。
+

source/bpi-mpy/basics/compass.md

@@ -0,0 +1,69 @@
+# Document
+
+![](./head.jpg)
+
+## 指南针
+
+- 注意：在 1.2 的版型上没有磁力计功能。
+
+- 这个模块可以让你访问内置的电子罗盘(即mpu)。在使用指南针之前，应该校准指南针，否则读数可能会出错。
+
+- 校准罗盘会导致程序暂停，直到校准完成。校准由一个小游戏组成，通过旋转板子在空中画圈完成校准。
+
+## 关于指南针的函数
+
+### compass.calibrate()
+
+- 执行此函数开始校准过程，你会收到一条有指导意义的信息，然后我们需要旋转板子，在空中画一个倒立的'8'或着转圈，(这个动作可以参考你的手机，手机的指南针功能在使用之前都会有一个校准的步骤)，这个校准的过程会占用大概1分钟的时间，校准期间你无法执行其他程序
+- 提示信息
+ ![prompt](how_to_compass/prompt.png)
+
+### compass.is_calibrated ()
+
+- 如果罗盘校准成功，返回True，否则返回False。
+
+### compass.get_x ()
+
+- 返回x轴上磁场强度的读数，它是一个正整数或负整数，取决于磁场的方向。
+
+### compass.get_y ()
+
+- 返回y轴上磁场强度的读数，它是一个正整数或负整数，取决于磁场的方向。
+
+### compass.get_z ()
+
+- 返回z轴磁场强度的读数，它是一个正整数或负整数，取决于磁场的方向。
+
+### compass.heading()
+
+- 给出从上述读数计算出的罗盘航向，为0到360范围内的整数，表示按顺时针方向的角度，12点钟方向为0
+
+### compass.get_field_strength()
+
+- 返回设备周围磁场大小，它是一个整数。
+
+## 示例代码
+
+```python
+"""
+    compass.py
+    Creates a compass.
+    The user will need to calibrate the compass first. The compass uses the
+    built-in clock images to display the position of the needle.
+
+"""
+from microbit import *
+
+# Start calibrating
+compass.calibrate()
+# Try to keep the needle pointed in (roughly) the correct direction
+while True:
+    sleep(100)
+    needle = ((15 - compass.heading()) // 30) % 12
+    display.show(Image.ALL_CLOCKS[needle])
+```
+
+- 在这个例子中第一步程序先校准了电子罗盘（mpu），校准完成后我们可以看到我们的led面板上有一个指南针它不管我们如何转动板子它始终指向南方
+  ![compass](how_to_compass/compass.gif)
+
+![logo](./logo.jpg)

source/bpi-mpy/basics/display.rst

@@ -0,0 +1,126 @@
+
+Hello, World!
+------------------------
+
+以一门新语言开始编程的传统方式是让计算机说出“Hello，World！”。
+
+.. image:: images/scroll-hello.gif
+
+这对于 MicroPython 来说很容易的 ::
+
+  from microbit import *
+  display.scroll("Hello, World!")
+
+以上代码每一行都有其作用。
+
+::
+
+  from microbit import *
+
+告知 MicroPython 获取它所需的所有信息用于 BPI-BIT。所有这些都置于 microbit 模块中（一个模块是一个预先存在的代码库）。当你输入某信息时，就是在告诉MicroPython你要使用该信息。另外， * 是Python表示 所有信息 的方式。因此， from microbit import * 的意思是，我需要使用 microbit 代码库中的所有内容。
+
+::
+
+  display.scroll("Hello, World!")
+
+告诉 MicroPython 使用 display 命令去滚动 string 的 “helloworld” 字符号，这个 display 是在 microbit 中的一个模块，代表设备物理上的显示，显示的内容在引号之中（'）。
+
+将 “Hello, World!” 的相关代码复制进编辑器，并让设备显示这些字符。你可以试着改变一下显示的内容。
+
+何不自己亲自试试呢？
+
+.. image:: images/scroll.gif
+
+.. Attention::
+
+ 你写的代码可能会出错。
+
+ 但 MicroPython 会提供帮助。出现错误时，REPL 会滚动显示一些错误信息，如果可以，它将会显示出错的行号。
+
+ Python 要求输入 完全 正确的信息。比如，对 Python 来说， Bpibit、 bpibit 和 bpiBit 都是不同的东西。若 MicroPython 显示 NameError 的错误注释，可能是因为输入的信息不准确。就像 “Nicholas” 和 “Nicolas”，虽然名字很相似，却表示两个不同的人。
+
+ 若 MicroPython 提示 SyntaxError ，这是因为你输入了 MicroPython 无法识别的代码。检查下你是否忘了输入像 " 或者 : 一类的字符。这就像是在一个句子中间输入了句号，句子的意思就变得难以理解。
+
+ 板子可能会停止响应：新的代码对它不起作用，没办法将新的命令输入到 REPL 。如果发生这种情况，重启试试。拔掉USB线，如果连接了电源线，则需要同时拔掉电源线，然后重新插一下。你可能还需要退出并重新启动代码编辑器。
+
+修改字符颜色
+~~~~~~~~~~~~~~~~
+
+相比于 microbit，bpibit 的 led 面板采用的是可编程的 RGB 灯(ws2812b)。
+
+.. image:: images/ws2812.png
+
+这种RGB灯通过编程理论上可以显示 255 * 255 * 255 种颜色的，也就是 1600 万种颜色，是不是有点难以置信呢，那就让我们来开始我们的色彩 show 吧。
+
+想要改变字体的颜色是很简单的，在固件中已经预置了8种颜色
+
+.. code:: python
+
+  black = [0, 0, 0]
+  Red = [2, 0, 0]
+  Orange = [2, 1, 0]
+  Yellow = [2, 2, 0]
+  Green = [0, 2, 0]
+  Blue = [0, 0, 2]
+  Indigo = [0, 2, 2]
+  Purple = [2, 0, 2]
+
+分别是黑（灯熄灭）、红、橙、黄、绿、蓝、靛、紫。有了这几种基本的颜色就可以来修改我们的字体颜色了。
+
+.. code:: python
+
+  from display import*
+  display = Display()
+  display.scroll("Hello, World!", Yellow)
+
+.. image:: images/yellow.gif
+
+板子默认显示的颜色是红色，只要在字符串(也就是上面的“Hello, World!”)后面添加其他颜色，就可以修改显示的字符的颜色。从上面那个图可以看到我们字符的颜色已经变为黄色了。到这里可能有的同学会发出疑问了 ?
+
+那怎么让显示的每个字符的颜色都不一样呢？让我们来看一下下面的操作。
+
+.. code:: python
+
+  from display import*
+  display = Display()
+  color = [Red, Orange, Yellow, Green, Blue, Indigo, Purple]
+  display.scroll("ROYGBIP", color)
+
+.. image:: images/color.gif
+
+我们新建了一个列表 color，里面按顺序存放着每个字符所需要的颜色，然后在 scroll 函数的后面把 color 添加进去就可以了，这样每个字符的颜色就不一样了。
+
+自定义颜色
+~~~~~~~~~~~~~~~~
+
+到这里聪明的同学又要发问了，不是说好有 1600 多万种颜色吗，怎么就这几种呢，嗯，不急，容我慢慢道来。
+
+说了那么久的 RGB ，那什么是 RGB 呢？RGB色彩就是常说的三原色，R代表Red（红色），G代表Green（绿色），B代表Blue（蓝色）。自然界中肉眼所能看到的任何色彩都可以由这三种色彩混合叠加而成。在电脑中，RGB的所谓“多少”就是指亮度，并使用整数来表示。通常情况下，RGB各有256级亮度，用数字表示为从0、1、2…直到 255 。注意虽然数字最高是 255 ，但0也是数值之一，因此共256级。按照计算，256级的RGB色彩总共能组合出约1678万种色彩，即256×256×256=16777216。通常也被简称为 1600 万色或千万色。也称为24位色(2的24次方)。在led领域利用三合一点阵全彩技术，即在一个发光单元里由RGB三色晶片组成全彩像素。随着这一技术的不断成熟，led显示技术会给人们带来更加丰富真实的色彩感受。
+
+回到正题，我们要怎么控制我们的板子显示我们想要的颜色呢，前面我们用列表的方式来保存颜色的信息
+
+.. code:: python
+
+  Red = [2, 0, 0]
+
+这里我们同样也可以按照这样的方式来定义我们的颜色。
+
+那么Red为什么是[2, 0, 0]呢，实际上列表中的三个数分别对应的就是我们R（红色）G（绿色）B（蓝色）的亮度，在前面有提到了每种颜色有256个级别的亮度，显而易见[2, 0 , 0]表示的就是红色的亮度是 2 ，绿色的亮度是 0 ，蓝色的亮度是 0 。由此就可以推出其他颜色列表的含义。
+
+下面我们来定义一个 mycolor = [1 , 2 , 3] 看看显示的效果
+
+.. code:: python
+
+  from display import *
+  display = Display()
+  mycolor = [3,3,3]
+  display.scroll("hello",mycolor)
+
+.. image:: images/mycolor.gif
+
+是不是很有趣，相信此时你会有很多有趣的想法，那就赶紧来尝试一下吧
+
+.. Attention::
+
+  每个颜色的亮度都有0- 255 总共256个数值可以选择，所以最小就是[0 , 0 , 0],最大就是[ 255 , 255 , 255 ]
+  亮度不要调得太高，太亮容易伤害眼睛。