Maix Bit（K210）保姆级入门上手教程系列

Maix Bit（K210）保姆级入门上手教程—环境搭建

这是K210快速上手系列文章，主要内容是，介绍K210的基本外设的使用、通过简单介绍一两个基本的硬件使用来掌握K210的外设开发（K210GPIO使用教程、K210串口使用教程）

阅读本文的前提：读者具有基本的硬件认知，接触过类似STM32，C51，Arduino等。如果还没接触过类似硬件的，本文可能并不适合读者。

一、K210硬件基本介绍

Maix py片上外设支持GPIO、I2C、PWM、I2S、SPI、UART、TIMER、WDT、network等（Maix py只是一个项目，移植到K210上面，他的功能是支持python开发，但使用到的硬件是K210）。

K210使用FPIOA (现场可编程 IO 阵列， Field Programmable Input and Output Array)技术，通过这个技术就可以让引脚随便设置为上面的功能等。如下图，引脚1既可以设为（映射）GPIO，也可以设为（映射）UART，也可以设为（映射）PWM。由于硬件是有限的，不能同时设为同一个硬件。比如有三个GPIO，引脚1使用了GPIO1，引脚2就不能够使用GPIO1。

简化图示：

这里和单片机那种是不一样的，单片机是某个引脚的功能是设计芯片的时候已经固定了，只能设为固定好的功能。比如STM32某个引脚已经被设为具有串口发送的功能。那这个引脚具有的功能除了基础的GPIO的功能外（每个引脚都具有），就只剩串口发送的功能可以设置。

我们已经知道了，任意一个引脚都可以设为（映射）为GPIO、UART等功能，那到到底可以设置什么功能？什么引脚又已经使用了一些功能？可以看官方的外设表，下面我就简单介绍会有什么功能。

可以映射为：JTAG、SPI0、UARTHS、RESV6、CLK_SP、GPIOHS、GPIO、UART、SPI、I2S、CMOS、TIMER，具体介绍可以看官网的外设表。

以下GPIOHS已经被使用，也就是GPIOHS4/5/27/28/29尽量不要使用这些功能。

如果是使用到SD卡、sensor、LCD、REPL功能时，以下使用到以下外设功能和引脚都需要注意。

基本引出引脚资源图，此图来自于官方文档

二、GPIO使用简单教程

1、使用GPIO的前提知识

a：FPIOA

上面提到了我们可以随便设置引脚的功能，我们可以通过FPIOA这个模块来设置引脚映射。

设置引脚对应的外设功能

set_function(pin, func)

pin： 引脚编号，取值 [0, 47]，具体看Maix bit资料下载：包含原理图和上面某些已经用到的引脚
func：这里功能具体看官方的外设功能设置

代码

from Maix import FPIOA # FPIOA模块
from fpioa_manager import fm # 注册芯片内部功能和引脚
LED_G=14
fpioa = FPIOA() #设置类
fpioa.set_function(LED_G, fm.fpioa.GPIOHS0) #设置引脚14为高速GPIO模式

b：fpioa_manager

在Maix py中，我们通常不直接使用fpioa.set_function去设置引脚的功能，而是使用register(pin, func, force)这个函数来控制引脚分配

上面已经简单了解过FPIOA的功能了，但是有一个简单的模块能够帮助我们管理FPIOA，这个就是上面fm模块。

函数：引脚映射

register(pin, func, force)

功能：将pin上的引脚映射为某个功能
参数介绍：

• pin: 功能映射引脚
• function : 设置外设的功能
• force: 强制分配，如果为True，则可以多次对同一个引脚注册;False则不允许同一引脚多次注册。

这里的pin，官方文档并没有说是不是取值 [0, 47]，但我猜应该是的（参考官方set_function使用的例程和register使用的例程，pin的数值都一样），而且这个fm模块本身就是为了管理fpioa的，应该只能用到fpioa的功能。

这里function和set_function里的参数是一样的。也就是说set_function和register功能是类似的，前两个参数也是一样的。

函数：引脚释放

unregister(pin)

功能：释放pin上绑定的功能
参数：

• pin，[0,47]

返回值：无

简单的代码

from fpioa_manager import fm
LED_G=14
fm.register(LED_G, fm.fpioa.GPIO0, force=True)#强制设置某个Pin14为GPIO0
fm.unregister(LED_G)#释放pin14绑定的GPIO0的功能

更多具体的功能看官方文档

2、GPIO外设使用

a：GPIO初探

GPIO是一个类，我们通常操作这个类来设则GPIO，高速GPIO同理

函数：申请一个GPIO类

class GPIO(ID, MODE, PULL, VALUE)

功能：注册一个GPIO类
参数：

• GPIO ID：GPIOx，GPIOHSx，选择哪个GPIO
• MODE：GPIO模式，输入/输出，GPIO.IN/GPIO.OUT
• PULL：GPIO上下拉模式，上/下/不设置模式，GPIO.PULL_UP/GPIO.PULL_DOWN/GPIO.PULL_NONE
• VALUE：设置GPIO状态

返回值：无

函数：设置GPIO状态

GPIO.value([value])

功能：设置GPIO状态
参数：value可一设为1（高电平）/0（低电平）
返回值：如果value为空则返回当前GPIO状态

了解完基本的两个GPIO设置就可以点亮小灯了
让我们看原理图，查看LED接在那个引脚上面

从原理图可以知道：LED_B是接在IO14，LED_R是接在IO13，LED_G是接在IO12，而且可以知道当IO输出为低电平的时候小灯点亮。

简单例程：

import utime #与系统时间有关模块
from Maix import GPIO #导入GPIO模块
from fpioa_manager import fm #导入管理FPIOA模块

# 效果，每隔1S亮灭 蓝灯

times=10 #亮灭10次
LED_B=14 #蓝灯IO定义

fm.register(LED_B,fm.fpioa.GPIO0) #注册引脚为GPIO0功能

led_r=GPIO(GPIO.GPIO0,GPIO.OUT)#操作设置GPIO模式

while times:
    utime.sleep_ms(500) #系统休眠0.5s
    led_r.value(0) #点亮
    utime.sleep_ms(500)
    led_r.value(1) #熄灭
    times=times-1
del led_r    # 释放类
fm.unregister(LED_B) #释放LED_B绑定的GPIO0

直接放到IDE上面就可以直接运行啦~

运行效果如下：蓝色小灯循环点亮

b：GPIO简单进阶

这里GPIO进阶简单介绍通过中断触发GPIO，不包括GPIO唤醒的功能（Maix Py好像不支持），而且只有GPIOHS才支持中断触发。

函数：GPIO中断设置

GPIO.irq(CALLBACK_FUNC,TRIGGER_CONDITION,GPIO.WAKEUP_NOT_SUPPORT,PRORITY)

功能：设置GPIO中断
参数介绍：

• CALLBACK_FUNC：回调函数，注意支持K210支持7个中断，而且共用一个中断管理器，也就是所设置的中断都触发同一个中断函数。可以在中断回调函数查看是哪个GPIO读取到的中断，具体看下面例程。
• TRIGGER_CONDITION：触发方式。有上升沿触发/下降沿触发/上升沿下降沿都触发，GPIO.IRQ_RISING/GPIO.IRQ_FALLING/GPIO.IRQ_BOTH
• PRORITY：为中断优先级，可以设置1~7级别
  返回值：无

函数：
GPIO关闭中断设置

GPIO.disirq()

返回值：无
简单使用例程：

import utime
from Maix import GPIO
from fpioa_manager import fm

LED_B=14 #蓝灯IO定义
KEY=16 #开发板上RST的按键IO
times=10

led_status=0
def test_irq(pin_num):
    print(pin_num) # pin_num GPIO 类，不是常规的Pin类
    if pin_num==GPIO(0): # 判断不同GPIO 控制中断输入
        global led_r
        global led_status
        if led_r.value()==0: # 读取LED引脚电平状态
            led_r.value(1)
        else:
            led_r.value(0)
        
fm.register(LED_B,fm.fpioa.GPIO0) #注册引脚为GPIO0功能
    
led_r=GPIO(GPIO.GPIO0,GPIO.OUT)#操作设置GPIO模式

fm.register(KEY, fm.fpioa.GPIOHS0)
key = GPIO(GPIO.GPIOHS0, GPIO.IN, GPIO.PULL_NONE)
key.irq(test_irq, GPIO.IRQ_RISING, GPIO.WAKEUP_NOT_SUPPORT,1)
#print("Gpio irq test")
while times:
    utime.sleep_ms(1000) # 在 3 秒内等待触发
    times=times-1
key.disirq() # 禁用中断
fm.unregister(KEY)

运行效果：点击开发板上RST，小灯状态转换

吐槽一句真的是服了官方的Sipeed 的文档，不全的，只说一部分，一些函数还得自己看芯片手册和官方的K210编程手册。

三、UART使用简单教程

在了解UART的使用流程，就是引脚映射，使用相关类来控制UART的状态，UART这里先介绍一个board_info这个用户层面板级配置模块。

1、了解board_info

这个board_info的作用就是帮助我们管理引脚，比如哪个引脚使用了，使用了什么功能，可以进行设置和查看。

在了解board_info之前，首先得下载配置board_info，固件里面原本就配置好，没修改的代码如下。这是使用javascript对象编写的文本，核心就是config这个的内容，我们先看到config 中的 board_info，我们要设置的就是这个，其他的不用改。
这里config的意思是：
config对象包着type和board_info两个key，value，type是字符串类型，board_info是对象类型，board_info对象的属性全是整形

import json 

config = {
  "type": "bit",
  "board_info": {
      'BOOT_KEY': 16,
      'LED_R': 13,
      'LED_G': 12,
      'LED_B': 14,
      'MIC0_WS': 19,
      'MIC0_DATA': 20,
      'MIC0_BCK': 18,
  }
}

cfg = json.dumps(config)
print(cfg)

try:
  with open('/flash/config.json', 'rb') as f:
    tmp = json.loads(f.read())
    print(tmp)
    if tmp["type"] != config["type"]:
      raise Exception('config.json no exist')
except Exception as e:
  with open('/flash/config.json', "w") as f:
    f.write(cfg)
  import machine
  machine.reset()

看代码运行结果简单了解模块的作用：

from board import board_info 
print(board_info.LED_R)
print(board_info.LED_B)
print(board_info.LED_G)

输出数字：14、13、12

从输出的结果，在简单看看源码，意思就是将LED_R与14连接起来，效果类似LED_R=14

2、简单修改board_info

这里先简单修改board_info，设置UART发送和接受。

import json 

config = {
  "type": "bit",
  "board_info": {
      'BOOT_KEY': 16,
      'LED_R': 13,
      'LED_G': 12,
      'LED_B': 14,
      'UART_TX': 1,
      'UART_RX': 2,      
      'MIC0_WS': 19,
      'MIC0_DATA': 20,
      'MIC0_BCK': 18,
  }
}

cfg = json.dumps(config)
print(cfg)

try:
    with open('/flash/config.json', 'rb') as f:
        tmp = json.loads(f.read())
        print(tmp)
        if tmp["type"] != config["type"]:
            raise Exception('config.json no exist')
except Exception as e:
    with open('/flash/config.json', "w") as f:
        f.write(cfg)
import machine
machine.reset()

将文件直接复制到IDE上面运行，IDE就会修改/flash/config.json中的配置文件（永久的），然后我们运行看看效果

实际上运行github的代码修改不了，通过mpfs查看内容，并没有写进去，打印出来的信息任然是默认信息。但是能够在sd卡上进行修改，证明代码没错，应该是flash受到什么保护了，权限不够。

mpfs [/sd]> cat /flash/config.json
{
    "board_info": 
    {
        "LED_B": 14, 
        "MIC0_DATA": 20, 
        "LED_G": 12,
        "MIC0_BCK": 18, 
        "BOOT_KEY": 16, 
        "LED_R": 13, 
        "MIC0_WS": 19,
        "UART_TX": 1,
        "UART_RX": 2
    
    }, "type": "bit"
}

我把文件拉到PC上面，修改写完就是下面的这个jsscript文件的内容，再把/flash/cofig.json删除，重新上传在改好的/flash/cofig.json文件，这里使用mpfs文件传送文件，当然IDE也是可以的。如果不懂，点这里包含mpfs基本安装和使用

实际上修改后的cofig.json里面的内容就是这个样子

{
    "board_info": 
    {
        "LED_B": 14, 
        "MIC0_DATA": 20, 
        "LED_G": 12,
        "MIC0_BCK": 18, 
        "BOOT_KEY": 16, 
        "LED_R": 13, 
        "MIC0_WS": 19,
        "UART_TX": 1,
        "UART_RX": 2
    
    }, "type": "bit"
}

替换之后显示显示就正常了

mpfs [/flash]> cat config.json
{
"board_info": 
	{
	 "MIC0_DATA": 20,
	 "MIC0_BCK": 18,
	  "LED_B": 14, 
	  "MIC0_WS": 19, 
	  "LED_R": 13, 
	  "UART_TX": 1, 
	  "BOOT_KEY": 16, 
	  "LED_G": 12, 
	  "UART_RX": 2
	  }, 
	  "type": "bit"
}

通过以下代码测试获取到正确设置的值：

from board import board_info

print("\nboard_info.UART_TX is",board_info.UART_TX)
print("board_info.UART_TX is",board_info.UART_RX)

特别注意，如果使用board_info这个模块，config.json文件可能会修改修改不了，需要自己手动替换文件内容。替换方式一般有两种，一种是直接在PC上修改源文件内容，然后拉进Maix Bit当中。另外一种是，写到flash外，比如sd卡，然后将sd卡中的文件移动到flash中

3、machine模块介绍

machine模块是运行操作K210上硬件的库，这个库支持PWM、I2S、SPI、UART、Timer、WDT、network的访问。

不过我看例程下来，通过这个库操作硬件是方便了，但是并没有单片机灵活，有利有弊吧。

常用的machine函数介绍：

machine.reset()

函数功能：重置设备，类似重启功能

构造函数：

machine.xxx()，xxx可以为PWM、I2S、SPI、UART、Timer、WDT

例如:

from machine import WDT
wdt0 = WDT(id=1, timeout=4000, callback=on_wdt, context={}) # 申请一个看门狗类

from machine import UART
uart = UART(uart,baudrate,bits,parity,stop,timeout, read_buf_len) # 申请一个串口类

4、UART基本使用

这里仅仅是利用USB转串口模块，将PC与Maix bit通过串口进行连接，用到的之前配置好的config.json文件。

如果识别不了串口，连接好线之后发现识别不了串口，可能是驱动没装好，自己看看自己的USB转串口模块用的什么芯片，然后装上对于的驱动，比如CH340/CH341。

a：基本函数介绍

函数：串口构造

UART(uart,baudrate,bits,parity,stop,timeout, read_buf_len)

功能：申请一个UART
参数介绍：

• uart：串口号，UART.UART1，UART.UART2等，
  具体看官方附录表有什么外设可以使用
• bits：UART 数据宽度，支持 5/6/7/8 (默认的 REPL 使用的串口（UARTHS）只支持 8 位模式)， 默认 8
• parity: 奇偶校验位，支持
  None,machine.UART.PARITY_ODD,machine.UART.PARITY_EVEN （默认的 REPL
  使用的串口（UARTHS）只支持 None）， 默认 None
• stop: 停止位， 支持 1， 1.5, 2， 默认 1
• timeout: 串口接收超时时间
• read_buf_len： 串口接收缓冲，串口通过中断来接收数据，如果缓冲满了，将自动停止数据接收

返回值：无

函数：读取串口缓冲区数据

uart.read(num)

功能：读取串口缓冲区数据
参数：

• num为读取的大小，单位bype

返回值：返回读取到的内容，类型是bype

函数：串口写入数据

uart.write(buf)

参数：

• buf为往串口写入的内容
  返回值：写入的数据量

函数：注销串口

uart.deinit()

参数：无
返回值：无

b：简单的串口收发代码

from machine import UART
from board import board_info
from fpioa_manager import fm

# 收发次数
rece_time = 3

# 引脚映射
fm.register(board_info.UART_TX, fm.fpioa.UART1_TX, force=True) # UART_TX是PIN1
fm.register(board_info.UART_RX, fm.fpioa.UART1_RX, force=True) # UART_RX是PIN2


uart_1 = UART(UART.UART1, 115200, 8, 0, 0, timeout=1000, read_buf_len=4096) # 申请串口
print("UART TX/RX TEST ON")                                                                                                                                                                                                                                                                          
while rece_time:
    read_data=uart_1.read()
    if read_data:# 判断是否读取到数据
        read_str = read_data.decode('utf-8')
        uart_1.write(read_str+"\n")# 将读取到的数据+\n发送到上位机
        rece_time=rece_time-1
print("UART TX/RX TEST OFF")
uart_1.deinit()
del uart_1

运行结果：

b：串口收发代码控制LED

由于涉及到数据的收发与处理，这里提供两个版本，一个是简单的单线程模式，一个多线程模式，我看文档说_thread模块并不稳定，而且Maix py 并不支持threading。

单线程模式：上位机输入LED ON就打开LED，输入LED OFF就关闭LED

from machine import UART
from Maix import GPIO 
from board import board_info
from fpioa_manager import fm

# 引脚映射
fm.register(board_info.UART_TX, fm.fpioa.UART1_TX, force=True) # UART_TX是PIN1
fm.register(board_info.UART_RX, fm.fpioa.UART1_RX, force=True) # UART_RX是PIN2
fm.register(board_info.LED_B,fm.fpioa.GPIO0)                   

led_r=GPIO(GPIO.GPIO0,GPIO.OUT)#操作设置GPIO模式

uart_1 = UART(UART.UART1, 115200, 8, 0, 0, timeout=1000, read_buf_len=4096) # 申请串口
print("UART TX/RX TEST ON")                                                                                                                                                                                                                                                                          
while 1:
    read_data=uart_1.read()
    if read_data:# 判断是否读取到数据
        read_str = read_data.decode('utf-8')
        if read_str=="LED ON":
            led_r.value(0) #点亮
            uart_1.write("LED ON\n")
        elif read_str=="LED OFF":
            led_r.value(1) #熄灭
            uart_1.write("LED OFF\n")
        elif read_str=="quit" or read_str=="exit":
            uart_1.write("quit the test\n")
        else:
            uart_1.write("input data error please inpue LED ON or LED OFF\n")
print("UART TX/RX TEST OFF")
fm.unregister(LED_B) #释放LED_B绑定的GPIO0

uart_1.deinit()
del uart_1
del led_r   

运行结果就是这个样子，这个是最简单的指令控制硬件的方式，之后想要K210与其他单片机通信原理也是一样的，配置好串口就行。

多线程：下面编写的思路可简单看看，但是改代码并不能运行，原因是不持支threading这个库

from machine import UART
from Maix import GPIO 
from board import board_info
from fpioa_manager import fm

import threading


read_str=""
class led_thread (threading.Thread):
    def __init__(self, threadID, name):
        threading.Thread.__init__(self)
        self.threadID = threadID
        self.name = name
    
    def run(self,led_r,uart_1):
        with condLock:   # 条件锁 自动上锁
            condLock.wait()  # 暂停线程运行、等待唤醒
            global read_str # 共享数据区
            read_str = read_data.decode('utf-8')
            if read_str=="LED ON":
                led_r.value(0) #点亮
                uart_1.write("LED ON\n")
            elif read_str=="LED OFF":
                led_r.value(1) #熄灭
                uart_1.write("LED OFF\n")
            elif read_str=="quit" or read_str=="exit":
                uart_1.write("quit the test\n")
            else:
                uart_1.write("input data error please inpue LED ON or LED OFF\n")
             

class uart_thread (threading.Thread):
    def __init__(self, threadID, name):
        threading.Thread.__init__(self)
        self.threadID = threadID
        self.name = name
        self.delay = delay
    def run(self,uart_1):
        with condLock:   # 条件锁 自动上锁
            global read_str # 共享数据区
            read_data=uart_1.read()
            if read_data:# 判断是否读取到数据
                read_str = read_data.decode('utf-8')
                condLock.notify()  # 放行
         

if __name__ == "__main__":
    # 引脚映射
    fm.register(board_info.UART_TX, fm.fpioa.UART1_TX, force=True) # UART_TX是PIN1
    fm.register(board_info.UART_RX, fm.fpioa.UART1_RX, force=True) # UART_RX是PIN2
    fm.register(board_info.LED_B,fm.fpioa.GPIO0)                   
    
    led_r=GPIO(GPIO.GPIO0,GPIO.OUT)#操作设置GPIO模式
    
    uart_1 = UART(UART.UART1, 115200, 8, 0, 0, timeout=1000, read_buf_len=4096) # 申请串口
    print("UART TX/RX TEST ON")    

    condLock = threading.Condition() # 条件锁对象
    # 设置线程
    Led_Thread = led_thread(1, "Led_thread", args=(led_r,uart_1,))
    Uart_Thread =uart_thread(2,"uart_thread",args=(uart_1,))
    
    Led_Thread.star()
    Uart_Thread.start()
    
    Led_Thread.join()
    Uart_Thread.join()    

    print("UART TX/RX TEST OFF")
    
    fm.unregister(board_info.LED_B) #释放LED_B绑定的GPIO0
    
    uart_1.deinit()
    del uart_1
    del led_r   

四、总结

操作K210的硬件IO往往需要先通过一个映射操作来映射需要操作的功能，而映射操作的功能是有fm库提供的。想要操作GPIO需要使用Maix模块中的GPIO模块，使用UART/PWM/I2C等用到的则是machine模块。

Maix py的多线程操作比较捞，并不支持threading，所以不建议使用。

五、参考资料

Mirco py 文档
Sipeed官方文档
py threading锁使用