Difference between revisions of "FriendlyThings APIs"
| Line 175: | Line 175: | ||
flowCtrl: flow control(range of value: H means hardware flow control, S means software flow control and N means no flow control.)<br /> | flowCtrl: flow control(range of value: H means hardware flow control, S means software flow control and N means no flow control.)<br /> | ||
Return Value:<br /> | Return Value:<br /> | ||
| − | + | 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.<br /> | |
|| | || | ||
| − | + | Opens a serial device and returns a file descriptor. | |
|- | |- | ||
|} | |} | ||
| − | + | Comments:<br /> | |
<br /> | <br /> | ||
| − | + | 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.<br /> | |
<br /> | <br /> | ||
| − | + | To write data to a device you can invoke the write function.<br /> | |
| − | + | If no operations need to be performed on the device you need to invoke the close function to close it.<br /> | |
<br /> | <br /> | ||
Revision as of 04:49, 28 December 2018
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/exportint unexportGPIOPin(int pin)
参数说明：
pin: GPIO引脚编号
返回值说明：
成功返回0，失败返回负数
通知系统取消导出某个GPIO引脚，
相当于执行命令 echo pin > /sys/class/gpio/unexportint 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 GPIO 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 RTC Watch dog SPI
3.2 Android7.1.2
3.2.1 Applicable Boards
- NanoPC-T4/NanoPi-M4/NanoPi-NEO4
Android7.1.2 Demos Serial Port GPIO 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 RTC Watch dog SPI
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
