FriendlyThings APIs

From FriendlyELEC WiKi
Revision as of 04:49, 28 December 2018 by Yftan (Talk | contribs)

Jump to: navigation, search

查看中文

1 Introduction

FriendlyThings is an Android SDK developed by FriendlyElec to access hardware. Users can use it to access various hardware resources Uart, SPI, I2C, GPIO etc on a FriendlyElec ARM board under Android. This SDK is based on Android-NDK. Users can use it to develop popular IoT applications without directly interacting with drivers.


Template:FriendlyThings Installation Guides

2 APIs in libfriendlyarm-things.so Library

Here is a list of HardwareControler APIs and these APIs are class interfaces and can be used directly, and you don't need to create a HardwareControler instance:

2.1 GPIO Interface

Applicable Platforms: All

Interface Name Parameters and Return Values Function
int open(
String devName
, int flags)

Parameters:
devName: device that data will be written to
flags: access mode, e.g. read-only,read/write etc. You can refer to FileCtlEnum.java

Return Value:
Returns a file descriptor if it is a success or returns -1 if it is a failure.

Opens a device

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

Parameters:
fd: device's file descriptor
cmd: ioctl command
value: parameter that will be used by the command. It can only be an integer.

Return Value:
Returns 0 if it is a success or returns -1 if it is a failure.

Commands ioctl operations

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

Parameters:
fd: device's file descriptor
cmd: ioctl command
buf: parameter that will be used by the command

Return Value:
Returns 0 if it is a success or returns -1 if it is a failure.

Commands ioctl operations
if ioctl is a struct
you need to convert the struct to a byte stream

int write(
int fd,
byte[] data)

Parameters:
fd: device's file descriptor
data: data to be written to device

Return Value:
Returns the number of bytes written to the device if it is a success or returns -1 if it is a failure.

Writes characters to an opened device or file.

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

Parameters:
fd: device's file descriptor
buf: buffer to store data
len: number of bytes to be read

Return Value:
Returns the number of bytes that are read from the device if it is a success or returns -1 if it is a failure. Returns 0 if the file pointer already points to the end of the file.

Reads data from an opened device or file.

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

Parameters:
fd: file descriptor
sen: wait time in second
usec: wait time in nanosecond

Return Value:
If the file has data it returns 1. If the file doesn't have data it returns 0. If this operation fails it returns -1.

Checks if an opened device or file has data for reading.

void close(int fd)

Parameters:
fd: file descriptor.

Return Value:
No

Closes a file

2.2 APIs for Serial Communication

Applicable Platforms: All

Interface Name Parameters and Return Value Function
int openSerialPortEx(
String devName,
long baud,
int dataBits,
int stopBits,
String parityBit,
String flowCtrl
)

Parameters:
devName: device name
baud: baud rate
dataBits: databits(range of value: 5 ~ 8, 8 by default)
stopBits: stopbits(range of value: 1 ~ 2, 1 by default)
parityBit: paritybit(range of value: O means odd check, E means even check and N means no check)
flowCtrl: flow control(range of value: H means hardware flow control, S means software flow control and N means no flow control.)
Return Value:
Returns a file descriptor if it is a success. This file descriptor can be used in the functions of read, write, select and etc. It returns -1 if it is a failure.

Opens a serial device and returns a file descriptor.

Comments:

You need to open a serial device by invoking the openSerialPortEx function, poll the device's status by invoking the select function and read data from it if the device has data.

To write data to a device you can invoke the write function.
If no operations need to be performed on the device you need to invoke the close function to close it.

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

3 示例程序

3.1 Android8.1

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

3.2 Android7.1.2

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

3.3 Earlier version of Android

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