FriendlyThings APIs
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 APIs
Applicable Platforms: All
API 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
API 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 Onboad LED APIs
Applicable Platforms: FriendlyElec's Tiny and Smart CPU boards e.g. Tiny4412, Smart4412, Smart4418 and etc
API Name Parameters and Return Value Function int setLedState( int ledID, int ledState )
Parameters:
ledID: LED index(value range: 0 ~ 3)
ledState: 1 means on and 0 means off
Return Value:
Returns 0 if it is a success or returns -1 if it is a failure.
Turns on/off LED.
2.4 PWM Buzzer APIs
Applicable Platforms: All FriendlyElec's Tiny and Smart carrier boards which have a PWM buzzer, e.g. Tiny4412, Smart4412 ,Smart4418 and etc
API Name Parameters and Return Value Function int PWMPlay(int frequency);
Parameter:
frequency: sound frequency
Return Value:
Returns 0 if it is a success or returns -1 if it is a failure
Turns on a PWM buzzer to make sounds at a set frequency
int PWMStop();
Parameter:
No
Return Value:
Returns 0 if it is a success or returns -1 if it is -1
Turn off a PWM buzzer.
2.5 ADC APIs
Applicable Platforms: 6410, 210 and 4412
API Name Parameters and Return Value Function int readADC()
Parameter:
No
Return Value:
Returns a value if it is a success otherwise returns -1
Reads the value of the first channel of ADC.
int readADCWithChannel(int channel)
Parameters:
channel: ADC channel
Return Value:
Returns a value if it is a success otherwise returns -1
Reads the value of a specified channel of ADC
int[] readADCWithChannels(int[] channels);
Parameter:
channels: array of channels
Return Value:
Returns an array of values from specified channels if it is a success otherwise returns NULL.
Reads values of an array of channels
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
