小龟机器人Python开发手册——扩展应用

HCSR-04超声波距离传感器 

概要

小龟小车支持最常见的HCSR-04超声波距离探测传感器。

探测距离(hcsr04)

语法：

car.hcsr04(pin_trig, pin_echo)

说明：

对接在pin_trig和pin_echo管脚上的超声波传感器执行测量距离任务。如果测试结果是0的话，请检查管脚连接是否正确。

参数：

pin_trig      对应超声波传感器的Trig管脚。

pin_echo    对应超声波传感器的Echo管脚。

返回值        测量的距离值，单位厘米(cm)

范例：

#测量Trig接在A1，Echo接在A2管脚的超声波前方障碍物的距离

distance = car.hcsr04(A1, A2)

print(distance)

WS2812全彩灯 

概要

小龟小车可以编程控制WS2812全彩灯、灯带与矩阵。

点亮一颗WS2812全彩灯

语法：

car.ws2812.write(pin, colors)

说明：

点亮接在管脚pin上的WS2812全彩灯。

参数：

pin       连接WS2812的DI管脚。

colors   RGB色彩代码

返回值        无

范例：

#点亮A1管脚的WS2812灯并显示颜色为绿色

car.ws2812.write(A1, [0x00FF00])

点亮多颗WS2812全彩灯

语法：

car.ws2812.write(pin, [colors，......])

说明：

点亮接在管脚pin上的多颗WS2812全彩灯。

参数：

pin             对应第一颗WS2812 的DI管脚。

返回值        无

范例：

#点亮A1管脚的3颗WS2812灯，并依次显示颜色红、绿、蓝

car.ws2812.write(A1, [0xFF0000，0x00FF00，0x0000FF])

关闭WS2812全彩灯

语法：

car.ws2812.clear(pin)

说明：

关闭接在管脚pin上的WS2812全彩灯。

参数：

pin             连接第一颗WS2812的DI管脚。

返回值        无

范例：

#关闭A1管脚的WS2812灯

car.ws2812.clear(A1)

查询灯珠数目(count)

语法：

car.ws2812.count(pin)

说明：

查询当前已经输出的灯珠数目。

参数：

pin         炫彩灯连接的管脚。

范例：

#查询当前A1管脚已经输出的灯珠数目

car.ws2812.count(A1)

SSD1306屏

概要

小龟小车主控板支持一枚SSD1306芯片做为系统屏幕(I2C协议)，使用的时候将屏幕模块的四根管脚插入系统I2C总线对应的管脚即可。在执行显示输出前，如不使用car.screen.open接口配置屏幕的特征的话，小车系统会议默认的参数初始化屏幕。

打开屏幕(open)

语法：

car.screen.open(width:int, height:int, i2c_addr:int)->bool

car.screen.open()

说明：

初始化SSD1306屏幕，如不进行初始化，在首次使用相关的屏幕输出接口的时候，会以默认配置初始化屏幕。默认配置：128像素宽、64像素高、I2C地址60。

参数：

width      屏幕宽度，单位像素。如不填，则默认128像素。

height     屏幕高度，单位像素。如不填，则默认64像素。

i2c_addr  屏幕模块的I2C地址，如不填，则默认60。

返回值     处理是否成功。

范例：

#打开屏幕，并向系统登记屏幕大小为128*64，I2C地址60

car.screen.open(128, 64, 60)

调节屏幕亮度(brightness)

语法：

car.screen.brightness(level:int)->bool

说明：

调节屏幕亮度。

参数：

level    亮度级别 0到255，0最暗，255最亮。

范例：

#调节屏幕到最亮

car.screen.brightness(255)

清空屏幕(clear)

语法：

car.screen.clear()

说明：

清空屏幕上所有内容。

参数：

无

范例：

#清空屏幕

car.screen.clear()

关闭屏幕(close)

语法：

car.screen.close()

说明：

关闭屏幕，屏幕上的显示内容也会被同步清空。

范例：

car.screen.close()

旋转屏幕(rotate)

语法：

car.screen.rotate(mode:str)->bool

说明：

旋转屏幕，因为屏幕可以自由的安装到主控板任意一面或者外壳的任何地方，如果显示内容的方向不对，则可以通过本函数接口旋转屏幕。

参数：

mode        旋转方式：B-180旋转，空格是默认模式。

返回值       处理是否成功。

范例：

#旋转屏幕180度

car.screen.rotate("B")

查询屏幕尺寸(size)

语法：

car.screen.size()->(width, height)

说明：

查询返回当前屏幕的宽和高。

参数：

返回值   tuple数组， (width, height)。

范例：

#查询登记的屏幕大小

car.screen.size()

绘制点(point)

语法：

car.screen.point(x:int, y:int, v:int)->bool

说明：

对屏幕上指定XY坐标的某一点设置或者清空显示。。

参数：

x       屏幕上指定点的横坐标（从0开始，到屏幕宽减一结束）。

y       屏幕上指定点的纵坐标（从0开始，到屏幕高减一结束）。

v       0代表清空该点的显示，1代表该点点亮显示出来。

返回  处理是否成功。

范例：

#给屏幕上x=5, y=6的点设置开启

car.screen.point(5, 6, 1)

打印文本(print)

语法：

car.screen.print(text:str, x:int, y:int)->bool

说明：

在屏幕上指定XY坐标的位置开始打印text文本。本接口在打印内容超过屏幕边界以后，会忽略后续打印，不会自动换行到下一行。

参数：

text        需要被打印的文本内容，支持UTF-8编码格式的各种中文外文字符。

x            屏幕上指定点的X坐标。

y            屏幕上指定点的Y坐标。

返回       处理是否成功。

范例：

#在屏幕上x=1, y=2处打印ABC三个字母

car.screen.print("ABC", 1, 2)

绘制像素图基于字节(draw)

语法：

car.screen.draw(image:str, width:int, height:int, x:int, y:int)->bool

说明：

在屏幕上指定XY坐标的位置开始绘制image。

参数：

image  代表图像的字符串，一个字节代表一个像素（空格是该像素不显示，其它字符显示）

width   图像自身的宽度 (缺省值：屏幕宽)

height  图像自身的高度 (缺省值：屏幕高)

x           图像绘制到屏幕上左上角对 应点的X坐标(缺省值：0)。

y           图像绘制到屏幕上左上角对应点的Y坐标(缺省值：0)。

返回      处理是否成功。

范例：

#在屏幕x=0, y=0处绘制一条14个像素的虚线

car.screen.draw("  **  **  **  ", 14, 1, 0, 0)

绘制像素图基于位(draw_bits)

语法：

car.screen.draw_bits(image:str, width:int, height:int, x:int, y:int)->bool

说明：

在屏幕上指定XY坐标的位置开始绘制image。

参数：

image  代表图像的字符串，一个字节里的每一个位(bit)代表一个像素（0不显示，1则显示），每一行最后一个像素如果不能抽满一个字节，则补全一个字节。下一行的第一个像素从新的字节开始。

width   图像自身的宽度(缺省值：屏幕宽)

height  图像自身的高度(缺省值：屏幕高)

x           图像绘制到屏幕上左上角对应点的X坐标(缺省值：0)。

y           图像绘制到屏幕上左上角对应点的Y坐标(缺省值：0)。

返回      处理是否成功。

范例：

#在屏幕x=0,y=0处绘制一条16个像素的实线

car.screen.draw_bits(b"\xFF\xFF", 16, 1, 0, 0)

刷新屏幕(flush)

语法：

car.screen.flush()->bool

说明：

重绘屏幕。在进行类似绘制点的操作，不会立刻看到效果，而需要执行这个flush输出绘制结果。

参数：

返回值       处理是否成功。

范例：

car.screen.flush()

汉字显示工具

工具链接：

OLED-LCD展示(SSD1306)一辆好玩能编程的小车http://guidan.com/appssd1306/

说明：

在输入框输入要显示的汉字，复制下方生成的代码到小龟小车Python编辑器，执行程序。

文字滚动效果选择。

参数：

返回值       屏幕文字显示。

OV2640摄像头

概要

小龟主控板支持摄像头模块，用户可以通过主控板的摄像头接口接入摄像头。

目前小龟主控板只支持OV2640芯片的摄像头模块。

摄像头模式说明

为了节省CPU的计算量，我们为摄像头设计了两种模式：视频模式和视觉模式。用户可以根据自己的需求进行模式的切换。视频模式下，可以进行全彩色的视频遥控图传，也支持多种摄像头分辨率。视觉模式下，仅仅用于车载视觉，不再进行全彩色的视频图传，同时摄像头的分辨率会降低。

重新启动摄像头

语法：

car.camera.reload()

说明：

重新加载摄像头

参数：

返回值    加载是否成功

范例：

#重装摄像头car.camera.reload()

摄像头参数读写

语法：

car.camera.sccb(reg)  读取摄像头参数

car.camera.sccb(reg, val)  修改摄像头参数

说明：

摄像头芯片读写接口，可以通过摄像头芯片支持的sccb协议说明书来读 取或者修改摄像头参数。

参数：

返回值 

读取模式，返回读取的值

修改模式，返回修改是否成功。

范例：

#读取摄像头芯片参数car.camera.sccb(25)
#修改摄像头芯片参数car.camera.sccb(25, 15)

视觉接口

视觉模式需要开关专门打开。为了节约CPU的计算量，小龟小车的视觉模式的图像被限制为240个像素宽，160个像素高，每个像素值是8位(一个字节，256色模式）。小龟小车固件集成了一些简单的视觉识别接口，比如水平线段查找等。

大部分视觉处理，都会按照下面的基本流程进行：

1. 用car.vision.snap()采样一帧图像，
2. 用car.vision.row()或者car.vision.point()等进行具体的图像数据分析，
3. 执行相应的动作
4. 如果是动态跟踪一类处理，则循环进行前面的动作。

色彩空间与通道

小龟相信很多小伙伴都清楚RGB三色原理。这个RGB就是一个色彩空间，而其中单个的R、单个的G、单个的B是三个独立的通道。小龟小车的视觉模式目前仅仅支持一个色彩空间里的一个通道。因为视觉处理的最基础工作就是选择最合适的色彩空间和通道，所以小龟小车也支持下面这些色彩空间和通道。

RGB色彩空间（R-红色通道、G-绿色通道、B-蓝色通道）

YCbCr色彩空间（Y-灰度通道，Cb-蓝绿通道，Cr-红绿通道）

HSL色彩空间（H-色相通道）

Python接口中涉及到通道配置的参数，则使用上面黄颜色背景字母做为通道名称来配置调用。

一、car.vision.on(channel)->bool

小车开机后默认处于视频监控模式，需要通过这个接口来切换到视觉模式。

参数：

channel    需要使用的色彩空间的通道名称。

返回值       处理是否成功。

范例：

#打开视觉模式，并选择YCbCr色彩空间的Y(灰度)通道
car.vision.on('Y')#打开视觉模式，并选择RGB色彩空间的B(蓝色)通道car.vision.on('B')

二、car.vision.off()->bool

小车的视觉模式，回到默认的视频监控模式。

#关闭视觉模式car.vision.off()

三、car.vision.channel()->str

返回小车当前视觉模式选择的色彩空间通道名称。

car.vision.channel()#>>Y

四、car.vision.frame_id()->int

返回当前抓取的样本帧的编号。

五、car.vision.height()->int

视觉模式图像的宽度（单位：像素），固定为160像素。

六、car.vision.line_find([rows], min, max, min_width, noise)->(x, y, width)

寻找当前采样图像中的符合要求的水平线段，调用本函数前需要先执行采样一帧的命令。

参数：

rows    指定寻找的水平行，比如80代表寻找第80行，[70, 80]代表依次寻找第70行、第80行。

min      指定的寻找范围的最小值

max     指定的寻找范围的最大值

min_width    指定的寻找水平线段的最小长度

noise   噪点范围，0代表无噪点，3代表忽略间隔小于等于3的噪点。

返回值  x和y代表符合的线段中心点的x和y坐标，width代表符合的线程长度；如果本接口没有找线段到则返回None。

范例：

#寻找第80行，范围在80-125之间长度大于15个像素的水平线段，允许间隔噪点1个像素car.vision.snap()car.vision.line_find(80, 80, 125, 15, 1)#>> (48, 80, 20)  #找到了符合要求的水平线段，线段中心位置x=48, y=80,宽度20个像素。
#依次在第80、70、90行寻找范围在80-125之间长度大于15个像素的水平线段，允许间隔噪点0个像素
car.vision.line_find([80, 70, 90], 80, 125, 15)
#>> None    #没有找到符合要求的水平线段

七、car.vision.point(x, y)->int

返回当前采样图片里指定坐标位置的值，调用本函数前需要先执行采样一帧的命令。

参数：

 x         水平坐标位置，范围等于大于0，到小于240。

 y         垂直坐标位置，范围等于大于0，到小于160。

返回值  指定位置的值，单字节数值等于大于0到小于256。

范例：

#确定 (x=5, y=10)的像素点是否为白色(0xFF)，它下方的点是否为暗红色(0x00)car.vision.snap()if car.vision.point(5, 10)==0xFF && car.vision.point(5, 11)==0x00):    print("find")

八、car.vision.row(row_index)->list

返回当前采样图片里指定行的全部点的值，调用本函数前需要先执行采样一帧的命令。

参数：

row_index        指定行的索引，范围等于大于0到小于160。

返回值  指定行的所以点值的列表

范例：

#从第80行依次查找，直到遇到值为0xFF的点car.vision.snap()data = car.vision.row(80)for i in range(240):    if data[i]==0xFF: print("find")

九、car.vision.snap()->int

采样一帧图像用于后续处理。各种视觉处理的第一步就是先执行这个采样接口，采样一帧。采样后，该帧数据会被冻结在内存中供后续各种图像处理，但是图传显示的图片还会继续更新的。如需查看该冻结的采样帧，可以使用页面访问接口。

十、car.vision.width()->int

视觉模式图像的宽度（单位：像素），固定为240像素。

DHT11温湿度传感器接口

概要

机器人主控板支持对DHT11温湿度传感器模块的支持，您可以通过以下命令快速获得传感器对应的测量值。

传感器接口

获取当前温度湿度测量值(read)

语法：

car.dht11.read(管脚) -> (湿度, 温度)

说明：

获取DHT11模块当前温度湿度的测量值。

参数：

返回值    (湿度值, 温度值)，测量异常的场合返回None。

范例：

#获取连接在A1管脚上的DHT11传感器的值car.dht11.read(A1)#结果 (7.0, 21.01)  代表湿度是7.0， 温度是21.01摄氏度