Difference between revisions of "FriendlyThings APIs/zh"

From FriendlyELEC WiKi
Jump to: navigation, search
(Created page with "test")
 
(updated by API)
 
(6 intermediate revisions by the same user not shown)
Line 1: Line 1:
−
test
+
[[FriendlyThings APIs|English]]
 +
 
 +
{{FriendlyThings Introduction/zh}}
 +
{{FriendlyThings Installation Guide/zh}}
 +
 
 +
==函数库(libfriendlyarm-things.so)接口说明==
 +
下面中列出HardwareControler类中的接口的定义，这些接口都是类方法，因此不需要创建HardwareControler对象实例：
 +
=== 通用的输入输出接口 ===
 +
'''支持平台：全平台'''
 +
::{| class="wikitable"
 +
|-
 +
| style="background: PaleTurquoise; color: black" | '''接口名称'''
 +
| style="background: PaleTurquoise; color: black" |'''参数与返回值说明'''
 +
| style="background: PaleTurquoise; color: black" |'''功能说明'''
 +
|-
 +
|
 +
<syntaxhighlight lang="java">
 +
int open(
 +
String devName
 +
, int flags)
 +
</syntaxhighlight>
 +
||
 +
参数说明：<br />
 +
devName: 要写入数据的<br />
 +
flags: 打开文件的方式，例如可读可写还是只读打开，可选值需参考 FileCtlEnum.java<br />
 +
<br />
 +
返回值说明：<br />
 +
成功返回文件描述符，出错返回-1。<br />
 +
||
 +
打开设备。
 +
|-
 +
 
 +
|-
 +
|
 +
<syntaxhighlight lang="java">
 +
int ioctlWithIntValue (
 +
int fd,
 +
int cmd,
 +
int value)
 +
</syntaxhighlight>
 +
||
 +
参数说明：<br />
 +
fd:设备文件描述符<br />
 +
cmd: ioctl命令<br />
 +
value:命令参数，限整数<br />
 +
<br />
 +
返回值说明：<br />
 +
成功返回0，出错返回-1。<br />
 +
||
 +
执行设备的ioctl操作
 +
|-
 +
 
 +
|-
 +
|
 +
<syntaxhighlight lang="java">
 +
ioctl(int fd,
 +
int cmd
 +
, byte[] buf)
 +
</syntaxhighlight>
 +
||
 +
参数说明：<br />
 +
fd:设备文件描述符<br />
 +
cmd: ioctl命令<br />
 +
buf:命令的参数<br />
 +
<br />
 +
返回值说明：<br />
 +
成功返回0，出错返回-1。<br />
 +
||
 +
执行设备的ioctl操作, <br />
 +
如果 ioctl是一个结构体，<br />
 +
你需要将结构体的数据转换成字节流 <br />
 +
|-
 +
 
 +
|-
 +
|
 +
<syntaxhighlight lang="java">
 +
int write(
 +
int fd,
 +
byte[] data)
 +
</syntaxhighlight>
 +
||
 +
参数说明：<br />
 +
fd: 要写入数据的文件描述符<br />
 +
data: 要写入的数据<br />
 +
<br />
 +
返回值说明：<br />
 +
成功返回写入的字节数，出错返回-1。<br />
 +
||
 +
向打开的设备或文件中写数据。
 +
|-
 +
 
 +
|-
 +
|
 +
<syntaxhighlight lang="java">
 +
int read(
 +
int fd,
 +
byte[] buf,
 +
int len)
 +
</syntaxhighlight>
 +
||
 +
参数说明：<br />
 +
fd: 要读出数据的文件描述符<br />
 +
buf: 存储数据的缓冲区<br />
 +
len: 要读取的字节数<br />
 +
<br />
 +
返回值说明：<br />
 +
成功返回读取的字节数，出错返回-1，如果在调read之前已到达文件末尾，则这次read返回0。<br />
 +
||
 +
从打开的设备或文件中读取数据。
 +
|-
 +
 
 +
|-
 +
|
 +
<syntaxhighlight lang="java">
 +
int select(
 +
int fd,
 +
int sec,
 +
int usec)
 +
</syntaxhighlight>
 +
||
 +
参数说明：<br />
 +
fd: 要查询的文件描述符<br />
 +
sen: 阻塞等待数据多长时间（单位：秒）<br />
 +
usec: 阻塞等待数据多长时间 （单位：纳秒，1毫秒=1000纳秒）<br />
 +
<br />
 +
返回值说明：<br />
 +
如果fd有数据可读，返回1, 如果没有数据可读，返回0，出错时返回-1。<br />
 +
||
 +
查询打开的设备或文件是否有数据可读。
 +
|-
 +
 
 +
|-
 +
|
 +
<syntaxhighlight lang="java">
 +
void close(int fd)
 +
</syntaxhighlight>
 +
||
 +
参数说明：<br />
 +
fd: 要关闭的文件描述符<br />
 +
<br />
 +
返回值说明：<br />
 +
无<br />
 +
||
 +
关闭指定的文件描述符
 +
|-
 +
 
 +
 
 +
|}
 +
=== 串口通讯的接口说明 ===
 +
'''支持平台：全平台'''
 +
::{| class="wikitable"
 +
|-
 +
| style="background: PaleTurquoise; color: black" | '''接口名称'''
 +
| style="background: PaleTurquoise; color: black" |'''参数与返回值说明'''
 +
| style="background: PaleTurquoise; color: black" |'''功能说明'''
 +
|-
 +
|
 +
<syntaxhighlight lang="java">
 +
int openSerialPortEx(
 +
String devName,
 +
long baud,
 +
int dataBits,
 +
int stopBits,
 +
String parityBit，
 +
String flowCtrl
 +
)
 +
</syntaxhighlight>
 +
||
 +
参数说明：<br />
 +
devName: 串口设备文件名<br />
 +
baud:    波特率 <br />
 +
dataBits: 数据位 (取值 5~8，一般用8 )<br />
 +
stopBits: 停止位 (取值 1~2，一般用1 )<br />
 +
parityBit: 奇偶校验位(取值为单个字母，O表示奇校验，E表示偶校验，N表示无校验)<br />
 +
flowCtrl: 数据流控制(取值为单个字母，H表示硬件流控制，S表示软件流控制，N表示不使用数据流控制)<br />
 +
返回值说明：<br />
 +
成功打开串口时，将返回串口的文件描述符，用该描述符可进行 read、write和select等操作，如果打开失败，则返回 -1<br />
 +
||
 +
打开指定的串口设备，并返回文件描述符。
 +
|-
 +
|}
 +
接口的使用说明：<br />
 +
<br />
 +
先通过调用openSerialPortEx 打开串口设备，然后可以在线程中、或者用 timer 通过调用 select 接口轮询串口设备是否有数据到来，如果有，则调用 read 接口读取数据。<br />
 +
<br />
 +
要往串口中写入数据，调用 write 接口即可。<br />
 +
串口使用完毕后，需要调用 close 关闭串口。<br />
 +
<br />
 +
 
 +
=== 板载LED的接口说明 ===
 +
'''支持平台：此接口仅适用于Tiny和Smart系列的核心板，例如Tiny4412,Smart4412,Smart4418'''
 +
::{| class="wikitable"
 +
|-
 +
| style="background: PaleTurquoise; color: black" | '''接口名称'''
 +
| style="background: PaleTurquoise; color: black" |'''参数与返回值说明'''
 +
| style="background: PaleTurquoise; color: black" |'''功能说明'''
 +
|-
 +
|
 +
<syntaxhighlight lang="java">
 +
int setLedState(
 +
int ledID,
 +
int ledState )
 +
</syntaxhighlight>
 +
||
 +
参数说明：<br />
 +
ledID： 指定要开关哪一个LED (取值0~3)<br />
 +
ledState: 1表示亮，0表示灭<br />
 +
<br />
 +
返回值说明：<br />
 +
成功返回0，失败返回-1<br />
 +
||
 +
该接口用于开关LED灯。
 +
|-
 +
|}
 +
 
 +
=== 让PWM蜂鸣器发声和停止发声的接口说明 ===
 +
'''支持平台：此接口仅适用于带蜂鸣器的Tiny和Smart系列底板，例如Tiny4412,Smart4412,Smart4418'''
 +
::{| class="wikitable"
 +
|-
 +
| style="background: PaleTurquoise; color: black" | '''接口名称'''
 +
| style="background: PaleTurquoise; color: black" |'''参数与返回值说明'''
 +
| style="background: PaleTurquoise; color: black" |'''功能说明'''
 +
|-
 +
|
 +
<syntaxhighlight lang="java">
 +
int PWMPlay(int frequency);
 +
</syntaxhighlight>
 +
||
 +
参数说明：<br />
 +
frequency: 要发声的频率<br />
 +
<br />
 +
返回值说明：<br />
 +
成功返回0，失败返回-1<br />
 +
||
 +
按指定的频率让蜂鸣器发声
 +
|-
 +
 
 +
|-
 +
|
 +
<syntaxhighlight lang="java">
 +
int PWMStop();
 +
</syntaxhighlight>
 +
||
 +
参数说明：<br />
 +
无<br />
 +
<br />
 +
返回值说明：<br />
 +
成功返回0，失败返回-1<br />
 +
||
 +
让蜂鸣器停止发声
 +
|-
 +
|}
 +
 
 +
=== 读取ADC的转换结果的接口说明 ===
 +
'''支持平台：仅适用于三星平台的开发板，包括6410、210、4412'''
 +
::{| class="wikitable"
 +
|-
 +
| style="background: PaleTurquoise; color: black" | '''接口名称'''
 +
| style="background: PaleTurquoise; color: black" |'''参数与返回值说明'''
 +
| style="background: PaleTurquoise; color: black" |'''功能说明'''
 +
|-
 +
|
 +
<syntaxhighlight lang="java">
 +
int readADC()
 +
</syntaxhighlight>
 +
||
 +
参数说明：<br />
 +
无<br />
 +
<br />
 +
返回值说明：<br />
 +
成功返回ADC转换的结果，失败返回-1<br />
 +
||
 +
读取第一个通道的ADC转换结果
 +
|-
 +
 
 +
|-
 +
|
 +
<syntaxhighlight lang="java">
 +
int readADCWithChannel(int channel)
 +
</syntaxhighlight>
 +
||
 +
参数说明：<br />
 +
channel: 读取指定通道的ADC的值<br />
 +
<br />
 +
返回值说明：<br />
 +
成功返回ADC转换的结果，失败返回-1<br />
 +
||
 +
读取指定通道的ADC转换的结果
 +
|-
 +
 
 +
|-
 +
|
 +
<syntaxhighlight lang="java">
 +
int[] readADCWithChannels(int[] channels);
 +
</syntaxhighlight>
 +
||
 +
参数说明：<br />
 +
channels: 要读取通道的ADC频道数组<br />
 +
<br />
 +
返回值说明：<br />
 +
成功返回多个ADC结果（数组），错误返回空<br />
 +
||
 +
一次性读取多个频道的结果，性能好
 +
|-
 +
|}
 +
 
 +
=== I2C接口说明 ===
 +
'''支持平台：全平台'''
 +
在使用如下接口之前，首先需要使用open接口打开I2C设备，如下所示, 操作完成后，记得用HardwareControler.close关闭：<br />
 +
<syntaxhighlight lang="java">
 +
int fd = HardwareControler.open("/dev/i2c-0", FileCtlEnum.O_RDWR);
 +
</syntaxhighlight>
 +
以下接口需要该fd作来参数进行操作：<br />
 +
::{| class="wikitable"
 +
|-
 +
| style="background: PaleTurquoise; color: black" | '''接口名称'''
 +
| style="background: PaleTurquoise; color: black" |'''参数与返回值说明'''
 +
| style="background: PaleTurquoise; color: black" |'''功能说明'''
 +
|-
 +
|
 +
<syntaxhighlight lang="java">
 +
int setI2CSlave(int fd, int slave);
 +
</syntaxhighlight>
 +
||
 +
参数说明：<br />
 +
fd: I2C设备的文件描述符<br />
 +
slave: I2C设备地址，例如EEPROM设备一般是0x50<br />
 +
<br />
 +
返回值说明：<br />
 +
成功返回0，失败返回-1<br />
 +
||
 +
设置要操作的I2C设备地址，例如EEPROM设备一般是0x50
 +
|-
 +
 
 +
|-
 +
|
 +
<syntaxhighlight lang="java">
 +
int setI2CTimeout(int fd, int timeout)
 +
</syntaxhighlight>
 +
||
 +
参数说明：<br />
 +
fd: I2C设备的文件描述符<br />
 +
timeout: 超时时间<br />
 +
<br />
 +
返回值说明：<br />
 +
成功返回0，失败返回-1<br />
 +
<br />
 +
||
 +
设置超时时间(ioctl I2C_TIMEOUT)
 +
|-
 +
 
 +
|-
 +
|
 +
<syntaxhighlight lang="java">
 +
int setI2CRetries(int fd, int retries)
 +
</syntaxhighlight>
 +
||
 +
参数说明：<br />
 +
fd: I2C设备的文件描述符<br />
 +
retries: 重试次数<br />
 +
<br />
 +
返回值说明：<br />
 +
成功返回0，失败返回-1<br />
 +
<br />
 +
||
 +
设置重试次数(ioctl I2C_RETRIES)
 +
|-
 +
 
 +
|-
 +
|
 +
<syntaxhighlight lang="java">
 +
int writeByteToI2C(int fd
 +
, int pos
 +
byte byteData
 +
, int wait_ms)
 +
</syntaxhighlight>
 +
||
 +
参数说明：<br />
 +
fd: I2C设备的文件描述符<br />
 +
pos: 字节位置<br />
 +
byteData:要写入的数据<br />
 +
wait_ms: 等待指定的时间(毫秒)<br />
 +
<br />
 +
返回值说明：<br />
 +
成功返回0，失败返回-1<br />
 +
<br />
 +
||
 +
写一个字节的数据到I2C设备的指定位置,并等待指定的时间(毫秒)
 +
|-
 +
 
 +
|-
 +
|
 +
<syntaxhighlight lang="java">
 +
int readByteFromI2C(int fd
 +
, int pos
 +
, int wait_ms);
 +
</syntaxhighlight>
 +
||
 +
参数说明：<br />
 +
fd: I2C设备的文件描述符<br />
 +
pos: 字节位置<br />
 +
wait_ms: 等待指定的时间(毫秒)<br />
 +
<br />
 +
返回值说明：<br />
 +
成功返回0，失败返回-1<br />
 +
<br />
 +
||
 +
从I2C设备指定的位置读一个字节的数据，并等待指定的时间(毫秒)
 +
|-
 +
 
 +
|}
 +
 
 +
=== SPI接口说明 ===
 +
'''支持平台：全平台'''
 +
在使用如下接口之前，首先需要使用open接口打开SPI设备，如下所示, 操作完成后，记得用HardwareControler.close关闭：<br />
 +
<syntaxhighlight lang="java">
 +
int spi_fd = HardwareControler.open("/dev/spidev1.0", FileCtlEnum.O_RDWR );
 +
</syntaxhighlight>
 +
以下接口需要该spi_fd作来参数进行操作：<br />
 +
::{| class="wikitable"
 +
|-
 +
| style="background: PaleTurquoise; color: black" | '''接口名称'''
 +
| style="background: PaleTurquoise; color: black" |'''参数与返回值说明'''
 +
| style="background: PaleTurquoise; color: black" |'''功能说明'''
 +
|-
 +
|
 +
<syntaxhighlight lang="java">
 +
int setSPIWriteBitsPerWord( int spi_fd, int bits )
 +
</syntaxhighlight>
 +
||
 +
参数说明：<br />
 +
spi_fd: SPI设备的文件描述符<br />
 +
bits: 字长，单位是比特<br />
 +
<br />
 +
返回值说明：<br />
 +
成功返回0，失败返回负数<br />
 +
<br />
 +
||
 +
设置每次读SPI设备的字长，单位是比特。<br />
 +
虽然大部分SPI接口的字长是8或者16，仍然会有一些特殊的例子。<br />
 +
需要说明的是，如果这个成员为零的话，默认使用8作为字长(ioctl SPI_IOC_WR_BITS_PER_WORD)
 +
|-
 +
 
 +
|-
 +
|
 +
<syntaxhighlight lang="java">
 +
int setSPIReadBitsPerWord( int spi_fd
 +
, int bits )
 +
</syntaxhighlight>
 +
||
 +
参数说明：<br />
 +
spi_fd: SPI设备的文件描述符<br />
 +
bits: 字长，单位是比特<br />
 +
<br />
 +
返回值说明：<br />
 +
成功返回0，失败返回负数<br />
 +
<br />
 +
||
 +
设置每次写SPI设备的字长，单位是比特 (ioctl SPI_IOC_RD_BITS_PER_WORD)
 +
|-
 +
 
 +
|-
 +
|
 +
<syntaxhighlight lang="java">
 +
int setSPIBitOrder( int spi_fd
 +
, int order)
 +
</syntaxhighlight>
 +
||
 +
参数说明：<br />
 +
spi_fd: SPI设备的文件描述符<br />
 +
order: 传SPIEnum.MSBFIRST或SPIEnum.LSBFIRST<br />
 +
<br />
 +
返回值说明：<br />
 +
成功返回0，失败返回负数<br />
 +
||
 +
设备SPI传输时是先传输低比特位还是高比特位，可选的参数有SPIEnum.MSBFIRST和SPIEnum.LSBFIRST
 +
|-
 +
 
 +
|-
 +
|
 +
<syntaxhighlight lang="java">
 +
int setSPIClockDivider( int spi_fd
 +
, int divider)
 +
</syntaxhighlight>
 +
||
 +
参数说明：<br />
 +
spi_fd: SPI设备的文件描述符<br />
 +
divider: 分频系数，传入在SPIEnum.java中定义的以SPI_CLOCK_开头的常量，例如:<br />
 +
SPIEnum.SPI_CLOCK_DIV128<br />
 +
<br />
 +
返回值说明：<br />
 +
成功返回0，失败返回负数<br />
 +
||
 +
设置SPI的分频系数
 +
|-
 +
 
 +
|-
 +
|
 +
<syntaxhighlight lang="java">
 +
int setSPIDataMode( int spi_fd
 +
, int mode)
 +
</syntaxhighlight>
 +
||
 +
参数说明：<br />
 +
spi_fd: SPI设备的文件描述符<br />
 +
mode: SPI设备的模式，可传入SPIEnum.SPI_MODE0 ~ SPIEnum.SPI_MODE3<br />
 +
<br />
 +
返回值说明：<br />
 +
成功返回0，失败返回负数<br />
 +
||
 +
设置SPI设备的模式
 +
|-
 +
 
 +
|-
 +
|
 +
<syntaxhighlight lang="java">
 +
int SPItransferOneByte( int spi_fd
 +
, byte byteData
 +
, int spi_delay
 +
, int spi_speed
 +
, int spi_bits)
 +
</syntaxhighlight>
 +
||
 +
参数说明：<br />
 +
spi_fd: SPI设备的文件描述符<br />
 +
byteData:要写入SPI设备的数据<br />
 +
spi_delay:延时<br />
 +
spi_speed:传输速度<br />
 +
spi_bits:字长，单位是比特<br />
 +
<br />
 +
返回值说明：<br />
 +
成功返回读到的数据，失败返回负数<br />
 +
<br />
 +
||
 +
同时发送与接收一个字节的数据，调用示例：
 +
int byteRet = SPItransferOneByte(spi_fd
 +
, 0xAA
 +
, 0 /*delay*/
 +
, 500000/*speed*/
 +
,8/*bits*/)
 +
;
 +
|-
 +
 
 +
|-
 +
|
 +
<syntaxhighlight lang="java">
 +
int SPItransferBytes(int spi_fd
 +
, byte[] writeData
 +
, byte[] readBuff
 +
, int spi_delay
 +
, int spi_speed
 +
, int spi_bits)
 +
</syntaxhighlight>
 +
||
 +
参数说明：<br />
 +
spi_fd: SPI设备的文件描述符<br />
 +
writeData:要写入的数据<br />
 +
readBuff: 存放读取数据的缓冲区<br />
 +
spi_delay:延时<br />
 +
spi_speed:传输速度<br />
 +
spi_bits:字长，单位是比特<br />
 +
<br />
 +
返回值说明：<br />
 +
成功返回0，失败返回负数<br />
 +
<br />
 +
||
 +
同时发送与接收多个字节的数据
 +
|-
 +
 
 +
|-
 +
|
 +
<syntaxhighlight lang="java">
 +
int writeBytesToSPI(int spi_fd
 +
, byte[] writeData
 +
, int spi_delay
 +
, int spi_speed
 +
, int spi_bits)
 +
</syntaxhighlight>
 +
||
 +
参数说明：<br />
 +
spi_fd: SPI设备的文件描述符<br />
 +
writeData:要写入的数据<br />
 +
spi_delay:延时<br />
 +
spi_speed:传输速度<br />
 +
spi_bits:字长，单位是比特<br />
 +
<br />
 +
返回值说明：<br />
 +
成功返回0，失败返回负数<br />
 +
<br />
 +
||
 +
写多个字节的数据到SPI设备
 +
|-
 +
 
 +
|-
 +
|
 +
<syntaxhighlight lang="java">
 +
int readBytesFromSPI(int spi_fd
 +
, byte[] readBuff
 +
, int spi_delay
 +
, int spi_speed
 +
, int spi_bits)
 +
</syntaxhighlight>
 +
||
 +
参数说明：<br />
 +
readBuff: 存放读取数据的缓冲区<br />
 +
spi_delay:延时<br />
 +
spi_speed:传输速度<br />
 +
spi_bits:字长，单位是比特<br />
 +
<br />
 +
返回值说明：<br />
 +
成功返回0，失败返回负数<br />
 +
<br />
 +
||
 +
从SPI设备读取多个字节
 +
|-
 +
|}
 +
 
 +
 
 +
=== GPIO接口说明 ===
 +
'''支持平台：全平台'''
 +
::{| class="wikitable"
 +
|-
 +
| style="background: PaleTurquoise; color: black" | '''接口名称'''
 +
| style="background: PaleTurquoise; color: black" |'''参数与返回值说明'''
 +
| style="background: PaleTurquoise; color: black" |'''功能说明'''
 +
 
 +
|-
 +
|
 +
<syntaxhighlight lang="java">
 +
int exportGPIOPin(int pin)
 +
</syntaxhighlight>
 +
||
 +
参数说明：<br />
 +
pin: GPIO引脚编号<br />
 +
<br />
 +
返回值说明：<br />
 +
成功返回0，失败返回负数<br />
 +
||
 +
通知系统需要导出控制的GPIO引脚编号，<br />
 +
相当于执行命令 echo pin > /sys/class/gpio/export
 +
|-
 +
 
 +
|-
 +
|
 +
<syntaxhighlight lang="java">
 +
int unexportGPIOPin(int pin)
 +
</syntaxhighlight>
 +
||
 +
参数说明：<br />
 +
pin: GPIO引脚编号<br />
 +
<br />
 +
返回值说明：<br />
 +
成功返回0，失败返回负数<br />
 +
||
 +
通知系统取消导出某个GPIO引脚，<br />
 +
相当于执行命令 echo pin > /sys/class/gpio/unexport
 +
|-
 +
 
 +
|-
 +
|
 +
<syntaxhighlight lang="java">
 +
int setGPIOValue(int pin, int value)
 +
</syntaxhighlight>
 +
||
 +
参数说明：<br />
 +
pin: GPIO引脚编号<br />
 +
value: 传入GPIOEnum.LOW表示输出低电平，传入GPIOEnum.HIGH表示输出高电平<br />
 +
<br />
 +
返回值说明：<br />
 +
成功返回0，失败返回负数<br />
 +
||
 +
对某个引脚输出高或低电平
 +
|-
 +
 
 +
|-
 +
|
 +
<syntaxhighlight lang="java">
 +
int getGPIOValue(int pin)
 +
</syntaxhighlight>
 +
||
 +
参数说明：<br />
 +
pin: GPIO引脚编号<br />
 +
<br />
 +
返回值说明：<br />
 +
成功返回GPIOEnum.LOW表示输出低电平，<br />
 +
返回GPIOEnum.HIGH表示输出高电平，失败返回负数<br />
 +
||
 +
查询某个引脚的状态（高或低电平）
 +
|-
 +
 
 +
|-
 +
|
 +
<syntaxhighlight lang="java">
 +
int setGPIODirection(int pin, int direction)
 +
</syntaxhighlight>
 +
||
 +
参数说明：<br />
 +
pin: GPIO引脚编号<br />
 +
direction: 传入GPIOEnum.IN表示输入， <br />
 +
GPIOEnum.OUT表示输出<br />
 +
<br />
 +
返回值说明：<br />
 +
成功返回0，失败返回负数<br />
 +
||
 +
配置引脚功能为输出或者输入
 +
|-
 +
 
 +
|-
 +
|
 +
<syntaxhighlight lang="java">
 +
int getGPIODirection(int pin)
 +
</syntaxhighlight>
 +
||
 +
参数说明：<br />
 +
pin: GPIO引脚编号<br />
 +
<br />
 +
成功返回GPIOEnum.IN表示输入，<br />
 +
返回 GPIOEnum.OUT表示输出，失败返回负数<br />
 +
||
 +
查询引脚功能 (为输出或者输入)
 +
|-
 +
|}
 +
 
 +
=== 查询开发板型号 ===
 +
::{| class="wikitable"
 +
|-
 +
| style="background: PaleTurquoise; color: black" | '''接口名称'''
 +
| style="background: PaleTurquoise; color: black" |'''参数与返回值说明'''
 +
| style="background: PaleTurquoise; color: black" |'''功能说明'''
 +
|-
 +
|
 +
<syntaxhighlight lang="java">
 +
int getBoardType()
 +
</syntaxhighlight>
 +
||
 +
成功返回一个代表开发板型号的数字，<br />
 +
数字的含义在 BoardType.java 中定义，<br />
 +
如果开发板无法识别，将失败负数 <br />
 +
||
 +
查询开发板型号, 调用示例:<br />
 +
<syntaxhighlight lang="java">
 +
private int mBoardType = HardwareControler.getBoardType();
 +
if (mBoardType == BoardType.NanoPC_T4) {
 +
    // do something...
 +
}
 +
</syntaxhighlight>
 +
|-
 +
|}
 +
 
 +
== 示例程序 ==
 +
{{FriendlyThings Android8 Demos}}
 +
{{FriendlyThings Android7 Demos}}
 +
{{FriendlyThings Earlier version of Android Demos}}

Latest revision as of 06:38, 16 November 2018

English

1 简介

FriendlyThings是友善电子开发的一套安卓硬件开发SDK（函数库），安卓软件开发者可以通过它在Android应用程序中编程访问和控制ARM主板上的各种硬件资源，比如Uart, SPI, I2C, GPIO等接口，它基于Android-NDK技术开发，开发者无需掌握底层的嵌入式知识（尤其是驱动程序），就可以构建基于安卓系统的各种IoT物联网应用。


2 快速使用入门

2.1 (第1步) 集成libfriendlyarm-things.so到你的app

克隆以下仓库到本地: 

git clone https://github.com/friendlyarm/friendlythings-sdk

接着复制 libs 目录下的所有内容到你的工程目录下，然后在你的Android项目的src目录下创建com/friendlyarm目录，将java/FriendlyThings目录拷贝进去即可，最后的目录的结构看上去是这样的 (注：AndroidStudio的项目可能会稍有不同，但大致如此)：

YourProject/
├── AndroidManifest.xml
├── libs
│   ├── arm64-v8a
│   │   └── libfriendlyarm-things.so
│   └── armeabi
│       └── libfriendlyarm-things.so
├── src
│   └── com
│       └── friendlyarm
│           ├── FriendlyThings
│           │   ├── BoardType.java
│           │   ├── FileCtlEnum.java
│           │   ├── GPIOEnum.java
│           │   ├── HardwareControler.java
│           │   ├── SPIEnum.java
│           │   ├── SPI.java
│           │   └── WatchDogEnum.java

使用以下方法导入它们，主要的接口都集中在 HardwareControler.java文件中： 

import com.friendlyarm.FriendlyThings.HardwareControler;
import com.friendlyarm.FriendlyThings.SPIEnum;
import com.friendlyarm.FriendlyThings.GPIOEnum;
import com.friendlyarm.FriendlyThings.FileCtlEnum;
import com.friendlyarm.FriendlyThings.BoardType;

2.2 (第2步) 让你的app拥有system权限

你的app需要拥有system权限，才能访问硬件资源;
请参考下面的方法修改你 app 的 AndroidManifest.xml 和 Android.mk这两个文件;
并且最好将你的app放到Android源码中去编译，这一步不是必需的，但是建议这么做，如果你的app在外部编译，你需要对apk进行签名才能让你的app拥有system权限（新手不太建议，过程比较繁琐）。

2.2.1 修改AndroidManifest.xml

在应用程序的AndroidManifest.xml中的manifest节点中加入以下属性： 

android:sharedUserId="android.uid.system"

2.2.2 修改Android.mk

编写一个Android.mk文件(最简单的方法就是拷贝示例中的Android.mk文件)，修改Android.mk文件，加入LOCAL_CERTIFICATE := platform这一行: 

LOCAL_PATH:= $(call my-dir)
include $(CLEAR_VARS)
 
LOCAL_SRC_FILES := $(call all-subdir-java-files)
 
LOCAL_PACKAGE_NAME := 你的项目名
 
LOCAL_CERTIFICATE := platform
LOCAL_MODULE_TAGS := optional
LOCAL_CFLAGS := -lfriendlyarm-hardware
 
include $(BUILD_PACKAGE)

2.3 (最后1步) 在 Android源代码中编译你的app

先在 Android源代码根目录调用 setenv.sh 导出环境变量，然后进入你的 app 目录，使用mm命令编译;
例子：编译 GPIO_LED_Demo，以RK3399平台为例: 

cd rk3399-android-8.1
. setenv.sh
cd vendor/friendlyelec/apps/GPIO_LED_Demo
mm

2.4 一个Android Studio的示例项目

https://github.com/friendlyarm/AndroidStudio-GPIODemo

3 函数库(libfriendlyarm-things.so)接口说明

下面中列出HardwareControler类中的接口的定义，这些接口都是类方法，因此不需要创建HardwareControler对象实例：

3.1 通用的输入输出接口

支持平台：全平台

接口名称 参数与返回值说明 功能说明 
int open(
String devName
, int flags)

参数说明：
devName: 要写入数据的
flags: 打开文件的方式，例如可读可写还是只读打开，可选值需参考 FileCtlEnum.java

返回值说明：
成功返回文件描述符，出错返回-1。

打开设备。 

int ioctlWithIntValue (
int fd,
int cmd,
int value)

参数说明：
fd:设备文件描述符
cmd: ioctl命令
value:命令参数，限整数

返回值说明：
成功返回0，出错返回-1。

执行设备的ioctl操作 

ioctl(int fd, 
int cmd
, byte[] buf)

参数说明：
fd:设备文件描述符
cmd: ioctl命令
buf:命令的参数

返回值说明：
成功返回0，出错返回-1。

执行设备的ioctl操作,
如果 ioctl是一个结构体，
你需要将结构体的数据转换成字节流 

int write(
int fd,
byte[] data)

参数说明：
fd: 要写入数据的文件描述符
data: 要写入的数据

返回值说明：
成功返回写入的字节数，出错返回-1。

向打开的设备或文件中写数据。 

int read(
int fd, 
byte[] buf, 
int len)

参数说明：
fd: 要读出数据的文件描述符
buf: 存储数据的缓冲区
len: 要读取的字节数

返回值说明：
成功返回读取的字节数，出错返回-1，如果在调read之前已到达文件末尾，则这次read返回0。

从打开的设备或文件中读取数据。 

int select(
int fd, 
int sec, 
int usec)

参数说明：
fd: 要查询的文件描述符
sen: 阻塞等待数据多长时间（单位：秒）
usec: 阻塞等待数据多长时间 （单位：纳秒，1毫秒=1000纳秒）

返回值说明：
如果fd有数据可读，返回1, 如果没有数据可读，返回0，出错时返回-1。

查询打开的设备或文件是否有数据可读。 

void close(int fd)

参数说明：
fd: 要关闭的文件描述符

返回值说明：
无

关闭指定的文件描述符

3.2 串口通讯的接口说明

支持平台：全平台

接口名称 参数与返回值说明 功能说明 
int openSerialPortEx(
String devName,
long baud,
int dataBits,
int stopBits,
String parityBit，
String flowCtrl
)

参数说明：
devName: 串口设备文件名
baud: 波特率
dataBits: 数据位 (取值 5~8，一般用8 )
stopBits: 停止位 (取值 1~2，一般用1 )
parityBit: 奇偶校验位(取值为单个字母，O表示奇校验，E表示偶校验，N表示无校验)
flowCtrl: 数据流控制(取值为单个字母，H表示硬件流控制，S表示软件流控制，N表示不使用数据流控制)
返回值说明：
成功打开串口时，将返回串口的文件描述符，用该描述符可进行 read、write和select等操作，如果打开失败，则返回 -1

打开指定的串口设备，并返回文件描述符。

接口的使用说明：

先通过调用openSerialPortEx 打开串口设备，然后可以在线程中、或者用 timer 通过调用 select 接口轮询串口设备是否有数据到来，如果有，则调用 read 接口读取数据。

要往串口中写入数据，调用 write 接口即可。
串口使用完毕后，需要调用 close 关闭串口。

3.3 板载LED的接口说明

支持平台：此接口仅适用于Tiny和Smart系列的核心板，例如Tiny4412,Smart4412,Smart4418

接口名称 参数与返回值说明 功能说明 
int setLedState( 
int ledID, 
int ledState )

参数说明：
ledID： 指定要开关哪一个LED (取值0~3)
ledState: 1表示亮，0表示灭

返回值说明：
成功返回0，失败返回-1

该接口用于开关LED灯。

3.4 让PWM蜂鸣器发声和停止发声的接口说明

支持平台：此接口仅适用于带蜂鸣器的Tiny和Smart系列底板，例如Tiny4412,Smart4412,Smart4418

接口名称 参数与返回值说明 功能说明 
int PWMPlay(int frequency);

参数说明：
frequency: 要发声的频率

返回值说明：
成功返回0，失败返回-1

按指定的频率让蜂鸣器发声 

int PWMStop();

参数说明：
无

返回值说明：
成功返回0，失败返回-1

让蜂鸣器停止发声

3.5 读取ADC的转换结果的接口说明

支持平台：仅适用于三星平台的开发板，包括6410、210、4412

接口名称 参数与返回值说明 功能说明 
int readADC()

参数说明：
无

返回值说明：
成功返回ADC转换的结果，失败返回-1

读取第一个通道的ADC转换结果 

int readADCWithChannel(int channel)

参数说明：
channel: 读取指定通道的ADC的值

返回值说明：
成功返回ADC转换的结果，失败返回-1

读取指定通道的ADC转换的结果 

int[] readADCWithChannels(int[] channels);

参数说明：
channels: 要读取通道的ADC频道数组

返回值说明：
成功返回多个ADC结果（数组），错误返回空

一次性读取多个频道的结果，性能好

3.6 I2C接口说明

支持平台：全平台 在使用如下接口之前，首先需要使用open接口打开I2C设备，如下所示, 操作完成后，记得用HardwareControler.close关闭：

int fd = HardwareControler.open("/dev/i2c-0", FileCtlEnum.O_RDWR);

以下接口需要该fd作来参数进行操作：

接口名称 参数与返回值说明 功能说明 
int setI2CSlave(int fd, int slave);

参数说明：
fd: I2C设备的文件描述符
slave: I2C设备地址，例如EEPROM设备一般是0x50

返回值说明：
成功返回0，失败返回-1

设置要操作的I2C设备地址，例如EEPROM设备一般是0x50 

int setI2CTimeout(int fd, int timeout)

参数说明：
fd: I2C设备的文件描述符
timeout: 超时时间

返回值说明：
成功返回0，失败返回-1

设置超时时间(ioctl I2C_TIMEOUT) 

int setI2CRetries(int fd, int retries)

参数说明：
fd: I2C设备的文件描述符
retries: 重试次数

返回值说明：
成功返回0，失败返回-1

设置重试次数(ioctl I2C_RETRIES) 

int writeByteToI2C(int fd
, int pos
 byte byteData
 , int wait_ms)

参数说明：
fd: I2C设备的文件描述符
pos: 字节位置
byteData:要写入的数据
wait_ms: 等待指定的时间(毫秒)

返回值说明：
成功返回0，失败返回-1

写一个字节的数据到I2C设备的指定位置,并等待指定的时间(毫秒) 

int readByteFromI2C(int fd
, int pos
, int wait_ms);

参数说明：
fd: I2C设备的文件描述符
pos: 字节位置
wait_ms: 等待指定的时间(毫秒)

返回值说明：
成功返回0，失败返回-1

从I2C设备指定的位置读一个字节的数据，并等待指定的时间(毫秒)

3.7 SPI接口说明

支持平台：全平台 在使用如下接口之前，首先需要使用open接口打开SPI设备，如下所示, 操作完成后，记得用HardwareControler.close关闭：

int spi_fd = HardwareControler.open("/dev/spidev1.0", FileCtlEnum.O_RDWR );

以下接口需要该spi_fd作来参数进行操作：

接口名称 参数与返回值说明 功能说明 
int setSPIWriteBitsPerWord( int spi_fd, int bits )

参数说明：
spi_fd: SPI设备的文件描述符
bits: 字长，单位是比特

返回值说明：
成功返回0，失败返回负数

设置每次读SPI设备的字长，单位是比特。
虽然大部分SPI接口的字长是8或者16，仍然会有一些特殊的例子。
需要说明的是，如果这个成员为零的话，默认使用8作为字长(ioctl SPI_IOC_WR_BITS_PER_WORD) 

int setSPIReadBitsPerWord( int spi_fd
, int bits )

参数说明：
spi_fd: SPI设备的文件描述符
bits: 字长，单位是比特

返回值说明：
成功返回0，失败返回负数

设置每次写SPI设备的字长，单位是比特 (ioctl SPI_IOC_RD_BITS_PER_WORD) 

int setSPIBitOrder( int spi_fd
, int order)

参数说明：
spi_fd: SPI设备的文件描述符
order: 传SPIEnum.MSBFIRST或SPIEnum.LSBFIRST

返回值说明：
成功返回0，失败返回负数

设备SPI传输时是先传输低比特位还是高比特位，可选的参数有SPIEnum.MSBFIRST和SPIEnum.LSBFIRST 

int setSPIClockDivider( int spi_fd
, int divider)

参数说明：
spi_fd: SPI设备的文件描述符
divider: 分频系数，传入在SPIEnum.java中定义的以SPI_CLOCK_开头的常量，例如:
SPIEnum.SPI_CLOCK_DIV128

返回值说明：
成功返回0，失败返回负数

设置SPI的分频系数 

int setSPIDataMode( int spi_fd
, int mode)

参数说明：
spi_fd: SPI设备的文件描述符
mode: SPI设备的模式，可传入SPIEnum.SPI_MODE0 ~ SPIEnum.SPI_MODE3

返回值说明：
成功返回0，失败返回负数

设置SPI设备的模式 

int SPItransferOneByte( int spi_fd
, byte byteData
, int spi_delay
, int spi_speed
, int spi_bits)

参数说明：
spi_fd: SPI设备的文件描述符
byteData:要写入SPI设备的数据
spi_delay:延时
spi_speed:传输速度
spi_bits:字长，单位是比特

返回值说明：
成功返回读到的数据，失败返回负数

同时发送与接收一个字节的数据，调用示例： int byteRet = SPItransferOneByte(spi_fd , 0xAA , 0 /*delay*/ , 500000/*speed*/ ,8/*bits*/) 

int SPItransferBytes(int spi_fd
, byte[] writeData
, byte[] readBuff
, int spi_delay
, int spi_speed
, int spi_bits)

参数说明：
spi_fd: SPI设备的文件描述符
writeData:要写入的数据
readBuff: 存放读取数据的缓冲区
spi_delay:延时
spi_speed:传输速度
spi_bits:字长，单位是比特

返回值说明：
成功返回0，失败返回负数

同时发送与接收多个字节的数据 

int writeBytesToSPI(int spi_fd
, byte[] writeData
, int spi_delay
, int spi_speed
, int spi_bits)

参数说明：
spi_fd: SPI设备的文件描述符
writeData:要写入的数据
spi_delay:延时
spi_speed:传输速度
spi_bits:字长，单位是比特

返回值说明：
成功返回0，失败返回负数

写多个字节的数据到SPI设备 

int readBytesFromSPI(int spi_fd
, byte[] readBuff
, int spi_delay
, int spi_speed
, int spi_bits)

参数说明：
readBuff: 存放读取数据的缓冲区
spi_delay:延时
spi_speed:传输速度
spi_bits:字长，单位是比特

返回值说明：
成功返回0，失败返回负数

从SPI设备读取多个字节


3.8 GPIO接口说明

支持平台：全平台

接口名称 参数与返回值说明 功能说明 
int exportGPIOPin(int pin)

参数说明：
pin: GPIO引脚编号

返回值说明：
成功返回0，失败返回负数

通知系统需要导出控制的GPIO引脚编号，
相当于执行命令 echo pin > /sys/class/gpio/export 

int unexportGPIOPin(int pin)

参数说明：
pin: GPIO引脚编号

返回值说明：
成功返回0，失败返回负数

通知系统取消导出某个GPIO引脚，
相当于执行命令 echo pin > /sys/class/gpio/unexport 

int setGPIOValue(int pin, int value)

参数说明：
pin: GPIO引脚编号
value: 传入GPIOEnum.LOW表示输出低电平，传入GPIOEnum.HIGH表示输出高电平

返回值说明：
成功返回0，失败返回负数

对某个引脚输出高或低电平 

int getGPIOValue(int pin)

参数说明：
pin: GPIO引脚编号

返回值说明：
成功返回GPIOEnum.LOW表示输出低电平，
返回GPIOEnum.HIGH表示输出高电平，失败返回负数

查询某个引脚的状态（高或低电平） 

int setGPIODirection(int pin, int direction)

参数说明：
pin: GPIO引脚编号
direction: 传入GPIOEnum.IN表示输入，
GPIOEnum.OUT表示输出

返回值说明：
成功返回0，失败返回负数

配置引脚功能为输出或者输入 

int getGPIODirection(int pin)

参数说明：
pin: GPIO引脚编号

成功返回GPIOEnum.IN表示输入，
返回 GPIOEnum.OUT表示输出，失败返回负数

查询引脚功能 (为输出或者输入)

3.9 查询开发板型号

接口名称 参数与返回值说明 功能说明 
int getBoardType()

成功返回一个代表开发板型号的数字，
数字的含义在 BoardType.java 中定义，
如果开发板无法识别，将失败负数

查询开发板型号, 调用示例:

private int mBoardType = HardwareControler.getBoardType();
if (mBoardType == BoardType.NanoPC_T4) {
    // do something...
}

4 示例程序

4.1 Android8.1

4.1.1 Applicable Boards

  • NanoPC-T4/NanoPi-M4/NanoPi-NEO4
Android8.1 Demos
Serial Port

https://gitlab.com/friendlyelec/rk3399-android-8.1/tree/master/vendor/friendlyelec/apps/SerialPortDemo

GPIO

https://gitlab.com/friendlyelec/rk3399-android-8.1/tree/master/vendor/friendlyelec/apps/GPIO_LED_Demo

ADC

https://gitlab.com/friendlyelec/rk3399-android-8.1/tree/master/vendor/friendlyelec/apps/ADCDemo

PWM

https://gitlab.com/friendlyelec/rk3399-android-8.1/tree/master/vendor/friendlyelec/apps/PWMDemo

I2C

https://gitlab.com/friendlyelec/rk3399-android-8.1/tree/master/vendor/friendlyelec/apps/I2C_LCD1602_Demo

RTC

https://gitlab.com/friendlyelec/rk3399-android-8.1/tree/master/vendor/friendlyelec/apps/RTC_Demo-RK3399

Watch dog

https://gitlab.com/friendlyelec/rk3399-android-8.1/tree/master/vendor/friendlyelec/apps/WatchDogDemo-RK3399

SPI

https://gitlab.com/friendlyelec/rk3399-android-8.1/tree/master/vendor/friendlyelec/apps/SPI_OLED_Demo

4.2 Android7.1.2

4.2.1 Applicable Boards

  • NanoPC-T4/NanoPi-M4/NanoPi-NEO4
Android7.1.2 Demos
Serial Port

https://gitlab.com/friendlyelec/rk3399-nougat/tree/nanopc-t4-nougat/vendor/friendlyelec/apps/SerialPortDemo

GPIO

https://gitlab.com/friendlyelec/rk3399-nougat/tree/nanopc-t4-nougat/vendor/friendlyelec/apps/GPIO_LED_Demo

ADC

https://gitlab.com/friendlyelec/rk3399-nougat/tree/nanopc-t4-nougat/vendor/friendlyelec/apps/ADCDemo

PWM

https://gitlab.com/friendlyelec/rk3399-nougat/tree/nanopc-t4-nougat/vendor/friendlyelec/apps/PWMDemo

I2C

https://gitlab.com/friendlyelec/rk3399-nougat/tree/nanopc-t4-nougat/vendor/friendlyelec/apps/I2C_LCD1602_Demo

RTC

https://gitlab.com/friendlyelec/rk3399-nougat/tree/nanopc-t4-nougat/vendor/friendlyelec/apps/RTC_Demo-RK3399

Watch dog

https://gitlab.com/friendlyelec/rk3399-nougat/tree/nanopc-t4-nougat/vendor/friendlyelec/apps/WatchDogDemo-RK3399

SPI

https://gitlab.com/friendlyelec/rk3399-nougat/tree/nanopc-t4-nougat/vendor/friendlyelec/apps/SPI_OLED_Demo

4.3 Earlier version of Android

4.3.1 Applicable Boards & OS

  • NanoPC-T3/NanoPi-M3: Android 5
  • Smart4418 SDK/SOM-4418/NanoPC-T2/NanoPi-M2/NanoPi S2: Android 5, Android 4.4
  • Tiny4412: Android 4.2, Android 5
  • Tiny210/Smart210/Mini210: Android 4.2
  • Tiny6410/Mini6410: Android 2.3
Earlier version of Android Demos
Serial Port

https://github.com/friendlyarm/friendlythings-examples/tree/master/SerialPortDemo

GPIO

https://github.com/friendlyarm/friendlythings-examples/tree/master/GPIO_LED_Demo

ADC

https://github.com/friendlyarm/friendlythings-examples/tree/master/ADCDemo

PWM

https://github.com/friendlyarm/friendlythings-examples/tree/master/PWMDemo

I2C

https://github.com/friendlyarm/friendlythings-examples/tree/master/I2C_LCD1602_Demo

SPI

https://github.com/friendlyarm/friendlythings-examples/tree/master/SPI_OLED_Demo

Retrieved from "https://wiki.friendlyelec.com/wiki/index.php?title=FriendlyThings_APIs/zh&oldid=16848"