K210 上手（避坑）指南

K210
避坑指南
上手指南

2023-03-03

更新历史

日期	版本	作者	更新内容
2023-03-03	v0.3	lyx	补充应用案例以及细节
2023-02-03	v0.2	lyx	整理框架补充内容
2022-12-30	v0.1	lyx	初次编写文档

新版 MaixPy (v4) 已经上线，完整 Python3 支持，功能更强大，请看: wiki.sipeed.com/maixpy

全新硬件产品 MaixCAM，性能大升级，请看: https://wiki.sipeed.com/maixcam

淘宝速卖通

Maix-I K210 系列正在被逐渐淘汰，如果你正准备购买 K210, 请立刻选择 MaixCAM;
也欢迎 K210 用户升级到 MaixCAM

前言

在 22 年的最后两天终于有时间开始整理填坑了，顶鸽逃跑（不是故意的）看见很多新手小白还是在文档海里扑腾找不到 K210 的资料文档，那就由这篇 K210 的避坑指南让小白的使用之路更顺利一点吧！

这篇文档以 SIPEED MaixDuino 的使用为示例说明，并且大部分内容通用于 K210 系列开发板，可供购入 K210 系列顾客参考使用，MaixDuino 相关介绍参数点击查询，选购开发板指南可参考选购指南。

maixduino_0

以下为 MaixDuino 全引脚标注图

基础知识

在使用板子上手之前，我们需要先掌握一些基础知识（有基础的小伙伴可跳过）由于 MaixPy 是基于 MicroPython 之上进行开发构建的，提供给用户最终的接口是 Micropython，所以在使用 MaixPy 之初我们需要熟悉下 MicroPython 的基础知识与语法以及常用的 Git 与 Github。

MaixPy 语法基础知识：点击查看
Git 和 Github 介绍：点击查看

以下是图像及音频的背景知识，有需要或感兴趣的小伙伴可以查看。

图像处理背景知识：点击查看
音频处理背景知识：点击查看

准备工作

无论是新手小白还是开发者在踏入 K210 系列开发板 学习之路前，做好充足的准备工作在一定程度上可以在使用途中避免踩坑。这篇文档是以一份避坑上手步骤的指南为核心来构写的，所以切记！！新手小白千万不可以跳着看，下图是示例硬件 MaixDuino 开发板、摄像头、屏幕、以及 USB Type-c 数据线。

maixduino

上手流程图

避坑指南可以搭配上手流程图一起使用更佳~

steps

硬件接线

USB Type-C 数据线

自行准备质量可靠或者是手机附赠的数据线，质量差的数据线会因电压问题造成开发板处于非正常工作状态导致后续影响使用，有些 Type-C 线只能供电。

type-c

Micro SD/TF 卡（可选）

在 K210 开发板上不使用 Micro SD 卡也可操作文件, 我们在内部 Flash 上保留了一部分作为文件系统, 只是 Flash 速度很慢，为了操作方便的话可以选购 Micro SD/TF 卡，以下图例为 SD 卡安装卡槽。

如何选购 SD/TF 卡传送门：点击前往

注意：MaixPy 不支持挂载文件系统到电脑！！！K210 芯片没有 USB 功能无法模拟 U 盘设备！！！
不要再问为什么没有 U 盘或者是显示 SD 卡了！那不是 K210 那是 M2dock 跟 openmv!

屏幕及摄像头接线

当我们收到开发板后，首先对硬件进行检查是否有外表损坏，接着再根据屏幕以及摄像头的排线丝印安装到开发板上，即排线上的数字 “1” 和板子卡座边上引脚丝印 “1” 方位对应接上。

安装 MaixPy IDE

因 MaixPy IDE 需要一定的下载时间，我们可以提前先挂在后台下载节约小伙伴们的时间。
首先要清楚明白 MaixPy 使用 Micropython 脚本语法，所以不像 C 语言 一样需要编译，我们可以在电脑上进行实时的编辑、运行、保存、观看摄像头效果的操作，故而对新手小白比较友好。

MaixPy IDE 下载传送门：点击前往
MaixPy IDE 安装与使用例程：点击前往

maixpy_logo

MaixPy IDE 支持 Linux、Windows、Macos 等系统如出现安装报错现象请前往 MaixPy 常见问题 FAQ 或 BBS【超实用】常见问题汇总贴排查问题。

给板子通电

先使用准备的 USB type-c 数据线两端分别接入板子及电脑端进行上电操作，方便后续更新固件等使用。
如果是新购买出厂的开发板的话，上电后会显示红色屏幕。

red_lcd

上电后出现白屏、黄屏、绿屏、蓝屏、闪屏等更多报错现象请前往 MaixPy 常见问题 FAQ 或 BBS【超实用】常见问题汇总贴排查问题。

安装驱动

因 K210 没有 USB 硬件支持功能需通过 USB 转串口与电脑连接，所以用户需安装串口搭建板子与电脑的连接桥梁，点击文档链接根据板子的型号下载相对应的驱动，安装成功后设备管理器会显示（COMx）端口。

串口驱动下载传送门：点击前往

com

如果出现安装失败、安装后设备接入 PC 端的设备管理器不显示 COM 端口的现象，需要检查系统是不是正版或更新下（Win7 Win8）系统，部分盗版系统会导致驱动安装失败或是安装后不显示。

更多的不显示 COM 端口参考解决方法：点击前往

如何升级固件（必看）

升级固件对 K210 系列板子来说至关重要，快速避免掉用户在使用中无限踩雷影响体验感，例如常见的 MaxiPy IDE 连接失败、屏幕白屏/黄屏等现象，所以板子到手后更新固件成了必不可少的一件事情。

怎么去判定自己需要的什么固件？

如果是第一次使用 k210 系列版更新固件，请无脑看图选标准固件（序号：15）！
如果是因为应用需要特殊固件，看应用文档需要什么下载什么！其余一律看功能尾缀！功能尾缀！选择固件。
K210 Amigo 开发板固件与以上不通用，固件请在（序号 3-6）里选择下载。

bin

参考上方描述选择（日期最新）所需的固件并下载到本地，使用 kflash_gui 烧录工具对板子进行升级固件。

bin_two

如何正确烧录固件示例可参考：升级固件示例文档可搭配 MaixPy 存储系统一起食用更佳。

注意：因 MaixPy 系列的开发板中 MaixDuino 板载了一块 ESP32 WIFI SOC，一般情况下不推荐更新板载的 ESP32 模块，如在使用途中出现 bug 可以参考更新板载 ESP32 固件进行更新固件

上手运行程序

使用 MaixPy IDE 进行调试操作的话，板子需烧录固件而且版本必须是 v0.3.1 以上, 否则 MaixPy IDE 会出现连接不上的现象。

使用 MaixPy IDE 运行程序（含测试程序）

根据下图将 K210 开发板连接 MaixPy IDE 软件，连接成功后步骤 3 的图标会变成红色，接下来运行 helloworld.py 测试摄像头及屏幕是否可用，运行后开发板屏幕以及软件会显示摄像头画面。

maixpyide

MaixPy 软件使用例程：点击前往 / 测试屏幕及摄像头源码：点击前往
如出现软件无画面的话，请参考步骤 5 是否被缩放了，更详细的连接过程请参考下文链接，测完后可在文件里新建文件夹编辑自己的代码并运行。

maixpy_run

使用串口终端运行程序

如果是有基础的用户较推荐使用终端来调试，MaixPy IDE 虽然运行报错会显示但信息可能不完整，而终端会输出更详细的报错信息方便排错。如果出现串口连接终端失败的现象，看看串口是否被占用。

使用前可以先点击了解串口定义是什么？方便我们理解后续使用更方便。文档提供了多种串口连接工具供用户使用，有 MaixPy IDE 终端工具、Mobaxterm、mpfshell-lite 等在 Windows 环境下的工具，以及 Linux 下的使用方法。

这里我们更推荐使用 MaixPy IDE 串口终端，以下时连接以及运行示例。

点击 MaixPy IDE 软件页面上方的 工具->打开终端->新终端->连接到串口->确定默认串口号->波特率：115200 确定自动连接，连接后按复位即可正常编辑。

maixpy_tty
tty_usage

运行 hello maixpy 终端会输出打印结果，更详细的资料以及更多连接串口方式请点击下文链接查看。

print("hello maixpy") #命令
#hello maixpy  #终端打印结果

adb

MobaXterm 下载及使用方法：点击前往
MaixPy IDE 终端使用方法：点击前往
mpfshell-lite 工具介绍及用法：点击前往
mpfshell-lite 使用手册：点击前往

如何编辑代码并运行

上文我们简单介绍了在 MaixPy IDE 上如何运行代码以及使用串口终端，但实际这些运行都是一次性并不保存到设备里，我们更希望代码保存在文件系统，这样不需要再次敲代码可直接运行程序更为便利快捷，小伙伴们可以参考以下的示例方法进行操作。

如何编辑并保存文件请参考以下示例：

方法一：使用内置编辑器 Micropython Editor(pye)
方法二：使用 MaixPy IDE
方法三：使用工具 uPyLoader 读取到 PC（电脑)上编辑后再保存到开发板
 方法四：使用工具 rshell 读取到 PC（电脑)上编辑后再保存到开发板

如何执行文件请参考以下示例：

方法一：使用 import 执行
 方法二：使用 exec() 函数来执行
 方法三：使用 MaixPy IDE 来执行
方法四：使用 uPyLoader 来执行：连接好后选中文件, 点击 excute 按钮来执行文件
方法五：使用 ampy 来直接运行电脑上的文件：执行命令 ampy run file_in_PC.py 来执行位于电脑上的文件（文件不会保存到开发板）

如何上传代码到开发板

我们可以通过多种方式打开编辑器来直接编辑文件系统中的文件，但如果出现代码量庞大或需要高亮支持的情况就不适用了，这时可以在电脑上写完代码放入开发板的文件系统内。

可参考以下几种方法示例进行操作：

方法一：使用图形工具 uPyLoader 上传、运行脚本
 方法二：使用命令行工具运行脚本
方法三：SD（TF）直接运行：拷贝到 SD 卡后，在终端中执行 import 文件名或者 exec() 来运行脚本
方法四：SD 卡自动拷贝到 Flash 文件系统

如何开机自动运行代码

如何配置开机自启动脚本相关：点击查看

定制专属固件

出于满足部分小伙伴对内存的需求，可通过源码编译所需固件。

为何需要固件定制
 源码编译

存储系统介绍

MaixPy 中的存储介质主要由 Flash、SD 卡组成，并分为三块区域分别是 MaixPy.bin 固件区、xxx.kmodel 模型区、文件系统区：Flash 上为 spiffs（SPI Flash File System）、SD 卡为 Fatfs（FAT file system) 后续方便小伙伴们使用模型或烧写固件时参考，注意烧写时的不同区域防止报错或烧写失败。

存储系统介绍：点击查看

更多功能应用

这篇文档完全是按新手小白的使用步骤一步一步来写的，在【更多功能应用】里编写的是 MaixPy 的应用案例以及使用方式，如果是没有接触过 Python 以及 MicroPython 的小伙伴们一定要先学会基础的语法知识，切记！没有基础的小伙伴不可以跳过上文！！！更多功能应用是基于上文的基础下写的，可以搭配 API 文档和MaixPy 例程仓库一同学习。

【更多功能应用】分为五大部分：系统基础功能、外设模块拓展、图像处理基础（image）、传统算法应用、神经网络应用（AI）因示例较多，这里列举几种常用的可点击可前往更多功能应用目录下查看所需要的示例。

系统基础功能：

包含了 CPU & RAM、GUI 支持、网络支持、媒体功能、游戏模拟。

外设模块拓展：

包含了片上外设、SP-MOD、Grove、其他外设。

图像处理基础（image）

包含了获取图像、显示图像、图像处理基础、如何在图像上写字、硬件加速图像模块。

传统算法应用

传统算法应用里包含了图像处理、音频处理。

神经网络应用（AI）

包含了深度神经网络基础、KPU 硬件加速介绍、AI 图像处理、AI 音频处理、如何训练模型。

如何正常使用 SD 卡

在【更多功能应用】里的部分示例里需要用到 SD 卡存储模型或固件等，很多小伙伴会遇见 SD 卡文件读取不到，先判断路径是否正确，再判断是否挂载成功了。

查询是否挂载成功的方法如下：

import os
print(os.listdir("/"))
>>['flash'] # 没有挂载 SD 卡

>>['flash', 'sd'] # 挂载 SD 卡成功

如果挂载不成功的话请根据 MaixPy 常见问题 FAQ 排查相关错误再进行再次挂载尝试使用。

如何进行配置开发板

在使用 外设模块拓展 的示例时，K210 系列板子因硬件引脚的不同需要进行不同的配置写入，可参考 Board文档进行配置。

如何连接麦克风阵列

麦克风阵列例程

K210 系列板卡连接麦克风阵列有以下两种方式供参考：

推荐：使用杜邦线连接板子与麦克风阵列的引脚，在使用例程提供的代码实现声源定位。
使用麦克风阵列标配排线搭配转接板连接板子

如何获取开发板（机器码）

在【更多功能应用】里的 神经网络应用（AI） 讲述了如何获取并运行 AI 模型的，但在获取模型的操作中有一步是需要机器码才能下载相关的模型，机器码是一机一码的一种加密方式，用于模型文件的加密。如果使用别的机器码去加密或者下载以 smodel 为文件后缀的模型文件，开发板是无法使用该模型文件的。

参考以下示例步骤获取机器码：

将 key_gen.bin 这个固件通过 Kflash 烧录到开发板上。烧录这个机器码固件之后，开发板是处于一个不能使用的状态，上电屏幕只会变成一个白屏。
这时将开发板通过 USB 连接到电脑上，利用【串口连接】中的方式来连接开发板。注：IDE 中的串口终端和 IDE 的连接方式相对独立的，而且串口不能通过多种方式进行连接
利用串口软件连接上开发板，这时按下开发板上的 reset 的按键，就会出现一串字符在终端窗口上，这就机器码。

机器码固件：key_gen-v1.2.bin

key

注意：烧录过 key_gen.bin 之后的开发板将永久禁用 K210 的 JTAG 调试功能。

如何获取 AI 模型

除了在示例文档中给出的模型，用户还可在 MaixHub 模型库中查找标签为 nncase 相关的 AI 模型供 k210 系列板子使用。

如何训练模型及数据集

云端训练以及相关文档介绍：MaixHub

什么是人工智能(AI)和机器学习
 常见代码框架和工具
 部署模型到 Maix-I(M1) K210 系列开发板
 MaixHub 训练调优方法

MaixHub 提供模型训练功能和模型分享功能以及视频教学，用户不需要搭建训练环境以及代码，只需要准备好需要训练的数据集上传训练数据即可快速训练出模型，方便快速制作你的 AI 应用。

本地训练：Windows - 环境配置、Windows - 使用教程、Linux - 使用教程。
如果是没有任何开发基础的同学们请谨慎使用本地训练，出现问题请自行解决。

库函数 API 手册

API 手册只罗列几种分类出来，如有需要更详细的请点击前往各分类查看下一级目录，可搭配上文【更多功能应用】使用更佳!

库函数 API 手册 - 标准库
 库函数 API 手册 - machine
库函数 API 手册 - Maix
库函数 API 手册 - helper
库函数 API 手册 - media
库函数 API 手册 - extend

如何编译与开发

对于想尝试开发 K210 的用户们我们也准备了相对应的文档供大家参考：

代码框架结构
 如何编译 MaixPy 工程
 如何用 C 添加一个 MaixPy 模块
 打包文件系统

MaixPy 源码：点击查看
相关原厂 K210 SDK：点击查看

以下是裸机开发可参考文章：

K210裸机开发（〇）简介及准备

学会使用文档（资源）

为什么会写 学会使用文档 呢，众所周知 K210 系列的板卡已经是 2019 年的产物了，各方面的文档也好例程也好早已经是成熟的了，该踩的坑基本都在前几年就被踩完了，现在更多的新手小白踩坑可能都是因为性能上的不足或者是自身使用环境的乱导致出问题。这篇文档的初衷是想要让大家在使用的过程中避坑，但我们还是要学会把文档资源利用起来。