View source for Android Hardware Access-APIs/zh

{{libfriendlyarm-hardware.so Installation Guide/zh}}

==函数库(libfriendlyarm-hardware.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>
|-
|}

== 示例 ==
{{libfriendlyarm-hardware.so Android8 Demos}}
{{libfriendlyarm-hardware.so Android7 Demos}}
{{libfriendlyarm-hardware.so Earlier version of Android Demos}}