Difference between revisions of "Android Hardware Access-APIs/zh"

Revision as of 07:55, 22 October 2018

1 快速使用入门

1.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;

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

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

1.2.1 修改AndroidManifest.xml

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

android:sharedUserId="android.uid.system"

1.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)

1.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

1.4 一个Android Studio的示例项目

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

2 函数库(libfriendlyarm-hardware.so)接口说明

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

2.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: 要关闭的文件描述符 返回值说明： 无	关闭指定的文件描述符

2.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 关闭串口。

2.3 板载LED的接口说明

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

接口名称	参数与返回值说明	功能说明
int setLedState( int ledID, int ledState )	参数说明： ledID： 指定要开关哪一个LED (取值0~3) ledState: 1表示亮，0表示灭 返回值说明： 成功返回0，失败返回-1	该接口用于开关LED灯。

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

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

接口名称	参数与返回值说明	功能说明
int PWMPlay(int frequency);	参数说明： frequency: 要发声的频率 返回值说明： 成功返回0，失败返回-1	按指定的频率让蜂鸣器发声
int PWMStop();	参数说明： 无 返回值说明： 成功返回0，失败返回-1	让蜂鸣器停止发声

2.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结果（数组），错误返回空	一次性读取多个频道的结果，性能好

2.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设备指定的位置读一个字节的数据，并等待指定的时间(毫秒)

2.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设备读取多个字节

2.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表示输出，失败返回负数	查询引脚功能 (为输出或者输入)

2.9 查询开发板型号

接口名称	参数与返回值说明	功能说明
int getBoardType()	成功返回一个代表开发板型号的数字， 数字的含义在 BoardType.java 中定义， 如果开发板无法识别，将失败负数	查询开发板型号, 调用示例: private int mBoardType = HardwareControler.getBoardType(); if (mBoardType == BoardType.NanoPC_T4) { // do something... }