查看“Mpython conn”的源代码

== 概述 ==
　　掌控板上可以运行 microPython 程序，尽管 microPython 有着和 Python 3.x 一样的语法，但在 microPython 中无法使用原生 Python 强大的第三方资源支持。mpython_conn 是一个用于在 Python 3.x 中控制掌控板的连接库，上位机运行 Python 程序，而掌控板作为下位机完成输入输出任务。目前 mpython_conn 只支持通过 USB 线的方式连接掌控板，今后可能会推出基于 WiFi 的无线控制方式。

== 安装与准备 ==
===安装mpython_conn库===

　　Linux / Mac OS: 
    sudo pip3 install mpython_conn

　　Windows: 管理员身份运行 cmd，输入
    pip3 install mpython_conn

===连接准备===

　　将掌控板通过 USB 线连接到 PC 或者嵌入式系统的 USB 口上。

== 导入包并建立连接对象 ==
导入包：
    from mpython_conn import controller
建立连接：
    m = controller()
Python会自动从当前的串口设备中发现掌控板，如果连接了多个掌控板，也可以通过port参数手动指定串口，如：
    m = controller(port='COM11')
== PIN口基本输入输出 ==
===设置PIN口数字输出值===
    m.set_digital(pin, value)
其中pin参数为引脚号，可用的引脚包括：0, 1, 8, 9, 13, 14, 15, 16

value参数为数字值，接受0或者1

===设置PIN口PWM模拟输出值===
    m.set_analog(pin, value)
其中pin参数为引脚号，可用的引脚包括：0, 1, 8, 9, 13, 14, 15, 16

value参数为模拟值，范围为0~1023
===获取PIN口数字值===
    digital_value = m.get_digital(pin)
其中pin参数为引脚号，可用的引脚包括：0, 1, 2, 8, 9, 13, 14, 15, 16

返回值包括：0（低电平）或1（高电平）
===获取PIN口模拟值===
    analog_value = m.get_analog(pin)
其中pin参数为引脚号，可用的引脚包括：0, 1, 2

返回值范围：0~4095
== 舵机与电机控制 ==
===设置舵机角度===
    m.set_servo(pin, value)
其中pin参数为连接舵机的引脚号，可用的引脚包括：0, 1, 8, 9, 13, 14, 15, 16

value参数为舵机角度，范围从0~180
===驱动掌控宝马达M1、M2===
    m.set_motor_power(motor_id, power)
参数motor_id为马达序号，取值包括1或者2，分别表示M1/M2

power参数为马达功率，取值范围为-100~100，大于0正转，小于0反转，0停止
===马达停止===
    m.set_motor_stop(motor_id)
参数motor_id为马达序号，取值包括1或者2，分别表示M1/M2
== 板载LED彩灯控制 ==
===设置彩灯颜色===
    m.set_rgb(r, g, b, index)
参数r、g、b分别为红色、绿色、蓝色分量，取值范围为0~255

参数index指定哪一盏灯，从左到右分别为0、1、2，如果index=-1或缺省，则表示对全部三盏灯生效。
===关闭彩灯===
    m.set_rgb_off(index)
参数index指定关闭哪一盏灯，从左到右分别为0、1、2，如果index=-1或缺省，则表示关闭全部三盏灯。
== OLED显示控制 ==
===在指定行显示文本===
    m.oled_display_line(text, line)
参数text为需要显示的字符串，可以包括中英文，遇中文标点符号会转换为英文标点符号。

line参数为显示的行号，包括1、2、3、4
===在指定位置显示文本===
    m.oled_display_text(text, x, y)
参数text为需要显示的字符串，可以包括中英文，遇中文标点符号会转换为英文标点符号。

参数x、y为OLED屏幕坐标，坐标原点为左上角，右为x正方向，下为右、正方向。x取值范围为0~127，y取值为0~63
===清除OLED屏所有显示信息===
    m.oled_clear()
===清除OLED屏指定行的显示信息===
    m.oled_clear_line(line)
line参数为显示的行号，包括1、2、3、4
===在OLED屏指定位置绘制或擦除点===
    m.oled_draw_point(x, y, mode)
参数x、y为OLED屏幕坐标，坐标原点为左上角，右为x正方向，下为右、正方向。x取值范围为0~127，y取值为0~63

参数mode默认值是1，即绘制。如果要擦除，则需要指定mode=0
===在OLED屏绘制或擦除连接线===
    m.oled_draw_line(x1, y1, x2, y2, mode)
x1,y1与x2,y2分别表示连接线的起始坐标与结束坐标。

参数mode默认值是1，即绘制。如果要擦除，则需要指定mode=0
===在OLED屏指定位置绘制或擦除指定长度的水平线或垂直线===
    m.oled_draw_vhline(x, y, len, dir, mode)
参数x、y为起始点的屏幕坐标

len为线段长度，以像素为单位

dir参数默认值为'h'，即水平线，如果dir='v'则表示绘制垂直线

参数mode默认值是1，即绘制。如果要擦除，则需要指定mode=0
===在OLED屏中绘制或擦除矩形===
    m.oled_draw_rectangle(x, y, w, h, fill, mode)
参数x、y为矩形的左上角的屏幕坐标

参数w、h分别为矩形的宽和高

fill默认为0，即表示不填充（空心），如果fill=1则表示填充（实心）

参数mode默认值是1，即绘制。如果要擦除，则需要指定mode=0
===在OLED屏中绘制或擦除圆===
    m.oled_draw_circle(x, y, r, fill, mode)
参数x、y为圆心的屏幕坐标

参数r为圆的半径

fill默认为0，即表示不填充（空心），如果fill=1则表示填充（实心）

参数mode默认值是1，即绘制。如果要擦除，则需要指定mode=0
===在OLED屏中绘制或擦除三角形===
    m.oled_draw_triangle(x1, y1, x2, y2, x3, y3, fill, mode)
x1,y1、x2,y2、x3,y3分别表示三角形的三个顶点坐标

fill默认为0，即表示不填充（空心），如果fill=1则表示填充（实心）

参数mode默认值是1，即绘制。如果要擦除，则需要指定mode=0
== 蜂鸣器发声 ==
===发出特定频率声音===
    m.play_tone(pitch)
参数pitch表示发出声音的频率，一般频率取值范围为20~20000赫兹
===播放单个音符===
    m.play_note(note)
参数note表示一个音符，比如"C3:1"

===停止发出声音（静音）===
    m.stop_music()

== 获取板载传感器值 ==
===获取三轴加速度值===
    acc = m.get_acceleration(axis)
参数axis表示获取哪个方向上的加速度值，可取值为 'X'、'Y'、'Z'

加速度的返回值单位为重力加速度g，一般g值可以取9.8m/s^2
===获取光线传感器值===
    val = m.get_light()
返回值表示环境光线值的强弱
===获取声音传感器值===
    val = m.get_sound()
返回值表示环境声音的强弱

== 获取按键状态 ==
===获取按键A/B/P/Y/T/H/O/N状态===
    status = m.get_button(button)
参数button指定哪个按键，可接受参数包括：'P', 'Y', 'T', 'H', 'O', 'N', 'A', 'B'

返回值为按键的状态，1表示按下，0表示释放
== 事件回调 ==
　　事件回调用于“当掌控板怎么样”的时候让程序处理什么事情，支持的事件包括：
    on_a_pressed()    # A 键按下事件
    on_a_released()   # A 键释放事件
    on_b_pressed()    # B 键按下事件
    on_b_released()   # B 键释放事件
    on_p_pressed()    # P 键按下事件
    on_p_released()   # P 键释放事件
    on_y_pressed()    # Y 键按下事件
    on_y_released()   # Y 键释放事件
    on_t_pressed()    # T 键按下事件
    on_t_released()   # T 键释放事件
    on_h_pressed()    # H 键按下事件
    on_h_released()   # H 键释放事件
    on_o_pressed()    # O 键按下事件
    on_o_released()   # O 键释放事件
    on_n_pressed()    # N 键按下事件
    on_n_released()   # N 键释放事件
    on_shaken()       # 掌控板摇晃事件
    on_jumped()       # 掌控板抛起事件
    on_tilt_forward() # 掌控板向前倾斜事件
    on_tilt_back()    # 掌控板向后倾斜事件
    on_tilt_left()    # 掌控板向左倾斜事件
    on_tilt_right()   # 掌控板向右倾斜事件
    on_tilt_none()    # 掌控板平放事件（默认不触发，只在其他倾斜事件发生后才触发）
===事件回调示例：===
    from mpython_conn import controller
    import time
    m = controller()
    def shake():
        m.oled_display_line('摇一摇', 1)
        m.set_rgb(255, 0, 0)
        time.sleep(1)
        m.set_rgb_off()
    m.on_shaken = shake		#事件绑定
　　以上程序运行后，当掌控板摇晃时，会在OLED屏上显示“摇一摇”，并让所有的板载LED彩灯亮起1秒钟。

== 断开连接 ==
    m.disconnect()