Android串口开发实战：JNI+NDK编译与调试全解析-北京尧图网络

简介一份面向安卓硬件开发者的串口通信示例源码聚焦JNIJava本地接口在底层串口访问中的关键作用解决安卓应用与C语言、C代码交互时遇到的权限申请、串口开关、数据读写及线程阻塞等常见问题。资源内置完整的JNI接口文件、Java层串口封装类以及波特率、数据位、停止位等参数配置示例可快速搭建串口通信框架用于传感器、微控制器等外部设备的数据交互。包体共一百零五个文件整体约四点八一兆字节覆盖源码、扩展标记语言配置、动态链接库、依赖包、编译产物及安装包工程目录完整并附可直接运行的安装包。已有一百六十九人参与学习下载。通过该示例可理清JNI调用链掌握安卓串口通信标准流程参考权限声明、后台线程及错误处理写法降低物联网、嵌入式调试中的硬件接入门槛。1. 串口开发Demo是什么Android串口开发从这一包开始做Android串口开发的人手里大概率会躺着一个名为“安卓Android源码——串口开发的demo里面包含JNI文件.zip”的压缩包。这包东西看起来不大里面却藏着Android串口通信最核心的底料一个带JNI文件的完整工程以及儿时熟悉的串口打开、读写、关闭逻辑。说白了Android应用程序层没法直接去操作/dev/ttyS开头的硬件节点必须靠JNI层用C代码把Linux系统调用包装一遍再让Java层通过native方法去调用。这个demo的价值就是把这层最脏最累的活帮你干完。这篇文章会告诉你怎么把这个zip变成能用的串口工具从编译到上线会遇到哪些坑以及哪些参数值得你仔细调。2. 拆解串口Demo的工程结构JNI文件在Android串口开发里的角色2.1 为什么Android串口通信必须走JNIAndroid的应用层跑在Java虚拟机里本身不具备直接访问内核设备节点的能力。串口设备节点比如/dev/ttyS1、/dev/ttyMT1本质上是一个字符设备文件读写它需要调用open、read、write这些Linux系统调用。Java层没有直接暴露这些接口所以必须通过JNIJava Native Interface让C代码去执行真正的系统调用再把读到的字节流送回Java层。这个demo里最关键的就是JNI目录下的C文件。一般来说里面会实现几个方法open、close、read、write外加一个配置串口参数的ioctl封装。Java层声明native方法然后通过System.loadLibrary加载编译出来的so库两者通过JNI的命名规则关联起来。如果缺少了JNI这一层上层写再多Java代码也碰不到硬件反过来说如果只给你一个C文件而没有Java的native声明那这个so一样跑不起来。串口开发选这条路几乎是唯一的。用纯Java想绕过JNI去操作串口节点除非你拿到的是已经root并且有系统签名的设备再用Runtime.exec去调用shell的echo和cat命令。那种方式实时性差、没有流控做做玩具还行真到了读条码枪、控制云台、和设备握手这种场景还是老老实实走JNI。2.2 工程目录结构与JNI文件的对应关系正常拿到这个zip解压之后你会看到一套相对完整的Android工程。我用最常见的目录结构来举例说明你可以对照着自己手里那份看SerialPortDemo/ ├── app/ │ ├── src/main/ │ │ ├── java/com/example/serialport/ │ │ │ ├── SerialPort.java │ │ │ ├── SerialPortManager.java │ │ │ └── MainActivity.java │ │ ├── jni/ │ │ │ ├── serial_port.c │ │ │ ├── serial_port.h │ │ │ └── Android.mk │ │ └── libs/ │ │ └── arm64-v8a/ │ │ └── libserial_port.so └── build.gradlejni目录里那个serial_port.c是整个demo的灵魂。它内部会定义类似Java_com_example_serialport_SerialPort_open这样的函数名Java层的包名和类名必须和这个命名完全一致。如果Java层的包名改过或者SerialPort类换过位置JNI方法就找不到运行时会抛UnsatisfiedLinkError。libs目录下一般已经预编译了几个CPU架构的so文件比如armeabi-v7a、arm64-v8a。如果你手里的zip只有源码没有so那也没关系说明作者希望你用NDK自己编一遍。后面第三部分会讲完整编译流程。2.3 把源码导入Android Studio环境准备与两个坑拿到zip第一件事不是急着跑先把整个项目导入Android Studio。用Open方式选中解压后的目录等Gradle同步。这里有两个经常翻车的点。第一个坑是NDK路径没配好。新版Android Studio为每个项目单独指定NDK版本你需要在local.properties里写清楚ndk.dir或者直接在SDK Manager里装好NDK。如果项目用的老版本Gradle和AS不兼容同步时会卡在Plugin too old。我一般会先看一眼build.gradle里的gradle版本手头用的是AGP 7系就配对应的NDK r21以上别盲选最新版。第二个坑是so文件被7zip解压出来后没有执行权限。Windows下解压zip会把Unix文件权限弄丢导入IDE后可能报“libserial_port.so: is not a valid ELF”或者找不到。解决办法是把libs目录删掉重新用NDK编译一版或者用git bash的tar命令重新解压保留权限位。导入成功之后你会看到SerialPort.java里有类似这样的代码public class SerialPort { static { System.loadLibrary(serial_port); } public native int open(String device, int baudRate, int flags); public native void close(); public native int read(byte[] buffer, int length); public native int write(byte[] buffer, int length); }这段代码里的System.loadLibrary加载的就是JNI目录下用NDK编出来的so。注意库名不带lib前缀也不带.so后缀C文件里的函数命名则要对应SerialPort这个类的全限定名。做到这一步demo的工程就算在IDE里站稳了。3. 用NDK把JNI串口代码编译成so库完整步骤与参数说明3.1 安装NDK与CMake版本选择与配置把JNI文件变成可加载的so过程绕不开NDK。NDK提供了一套交叉编译工具链让你在电脑上编译出能在Android设备ARM架构CPU上运行的代码。下载NDK直接在Android Studio的SDK Manager里勾选版本我建议选r21到r23之间的稳定版太老的版本对新的AGP不友好太新的版本会把编译警告当成错误老工程容易卡住。老式工程用ndk-build方式目录里只需要放Android.mk和Application.mk。新式工程用CMake方式在build.gradle里配置externalNativeBuild。两种方式都能把serial_port.c编成so但工程配置差别不小。如果你手里的demo带jni/Android.mk我建议沿用ndk-build改动最小。确认NDK装好之后先看工程根目录下有没有local.properties没有就新建内容至少要有sdk.dirD:/Android/Sdk ndk.dirD:/Android/Sdk/ndk/21.4.7075529路径换成你机器上的实际位置。这里强调一下ndk.dir指向的是NDK具体版本文件夹不是NDK的父目录。填错了Gradle会直接报NDK not configured。3.2 编写Android.mk与Application.mk关键编译参数jni目录下的Android.mk是ndk-build的构建脚本核心。一个能正常编译串口demo的Android.mk大致长这样LOCAL_PATH : $(call my-dir) include $(CLEAR_VARS) LOCAL_MODULE : serial_port LOCAL_SRC_FILES : serial_port.c LOCAL_LDLIBS : -llog include $(BUILD_SHARED_LIBRARY)LOCAL_MODULE决定so的名字最后生成的是libserial_port.so。LOCAL_SRC_FILES只列C源文件头文件不需要写进去编译时会自动找。LOCAL_LDLIBS加-llog是因为串口出错时要调用Android的log输出到logcat不加这条链接会报undefined reference。同目录下的Application.mk控制编译出的指令集架构APP_ABI : arm64-v8a armeabi-v7a APP_PLATFORM : android-21APP_ABI指的就是目标CPU架构现在新设备基本都是arm64-v8a老设备还有armeabi-v7a。两个都编能扩大兼容范围代价是包体积变大。APP_PLATFORM是API级别串口操作用到的大多是POSIX标准接口android-21足够。如果打开JNI文件发现里面还用了POSIX的tcgetattr、tcsetattr那在Android.mk里不需要额外加库libc自带。但注意别在C文件里用了老的串口头文件写法比如把B115200宏直接当int用Android的termios头文件定义和Linux桌面版略有差异。3.3 ndk-build与CMake两种构建方式自己选哪种很多串口demo源码包里只有Android.mk没有CMakeLists.txt。这时候直接用ndk-build最省事。在Android Studio的Terminal窗口里执行cd app/src/main/jni ndk-build如果没有把ndk-build加入PATH可以用NDK目录下的完整路径执行。命令跑完jni目录下会出现obj和libs两个新目录so文件就在libs/ /下面。再把libs目录里的so复制或链接到app/src/main/libs/Gradle打包时才会打进去。新工程推荐CMake。在app的build.gradle里加一段android { defaultConfig { externalNativeBuild { cmake { cppFlags } } } externalNativeBuild { cmake { path src/main/cpp/CMakeLists.txt } } }CMakeLists.txt里至少这样写cmake_minimum_required(VERSION 3.10) project(serial_port) add_library(serial_port SHARED src/main/jni/serial_port.c) target_link_libraries(serial_port log)两种方式没有绝对好坏。ndk-build胜在简单直接适合老工程CMake胜在IDE集成好Android Studio能直接显示编译错误跳转到C源码行数。我个人的做法是如果demo自带Android.mk先用ndk-build快速验证确认编译没问题后再看有没有必要换成CMake。别一上来就折腾构建系统串口的核心逻辑不在编译方式上。3.4 生成so后Java层如何声明native方法编译成功后so文件已经躺在libs目录里了。但这还不够Java层得有一套和C函数签名完全匹配的native声明。C文件的函数命名必须遵循规则Java_包名_类名_方法名包名里的点换成下划线。比如Java包是com.example.serialport类名是SerialPortopen方法的C函数名就是Java_com_example_serialport_SerialPort_open。如果你改过Java类的位置或者重命名过方法C函数名必须同步改否则运行时根本找不到。这里有个偷懒技巧在Java工程里写好native声明后用javac生成.h头文件命令是javac -h . SerialPort.java生成的头文件里就有标准的JNI函数签名复制到C文件里绝对不会出错。这个命令能省掉无数个“UnsatisfiedLinkError”的排错时间属于典型的后悔药式做法。Java层的SerialPort类里open方法需要把设备路径、波特率传给C层。C层拿到路径后调open系统调用拿到文件描述符再通过ioctl配置波特率。这一步是串口开发最核心的逻辑下一部分专门展开讲。4. Java层调用串口打开、读写、关闭的封装套路4.1 串口设备节点与权限打开哪些设备、什么时候去打开Android设备上的串口节点通常是/dev/ttyS0到/dev/ttyS3也有/ dev/ttyMT1、/dev/ttyXRUSB这种厂商自定名称。demo里一般会在SerialPort.java的构造方法里接收一个device路径参数Activity里把这个路径传进去。打开设备之前必须先确认权限。普通App没有访问/dev/ttyS*的权限这是串口开发最容易卡住的地方。常用的方案有几种设备是root过的可以在C层打开前先执行su并chmod 666或者固件本身给了串口节点权限又或者App被置为系统应用用system UID运行。demo默认不处理权限的话你要么在设备上提前执行adb root adb shell chmod 666 /dev/ttyS1要么在自己的产品固件里通过ueventd.rc把节点权限配好。权限不解决后面所有读写都会报Permission denied这一步没有捷径。打开串口时C层代码一般会做几件事open设备文件、判断文件描述符合法性、保存fd供后续读写、调用串口参数配置函数。Java层的open方法返回int通常返回文件描述符或者返回一个boolean告诉你是否成功。如果打开失败务必把log用System.loadLibrary时链接的Log.i写到logcat里不然你只能瞎猜。4.2 用JNI回调把串口数据送到Java层从监听线程到进度条更新串口是流式数据读取不能只在界面上等着用户点“读”。更现实的套路是C层开一个线程循环读或者Java层自己起一个线程去反复调native read方法。这两者各有取舍。常见做法是Java层维护一个串口读取线程。线程里用一个阻塞队列接数据读到的字节流通过Handler发到主线程更新UI。这样写的好处是逻辑都在Java层调试时能看到每一步坏处是native方法调用本身有开销高频读写时线程切换会损耗性能。demo里如果只提供了最原始的read方法签名public native int read(byte[] buffer, int length);那在Java层典型用法是Thread readerThread new Thread(() - { byte[] buffer new byte[256]; while (running) { int len serialPort.read(buffer, buffer.length); if (len 0) { byte[] data new byte[len]; System.arraycopy(buffer, 0, data, 0, len); handler.obtainMessage(MSG_RECEIVE, data).sendToTarget(); } Thread.sleep(20); } }); readerThread.start();这里的read是一个阻塞型调用C层里调用read(fd, buf, length)从串口读字节没有数据时线程会卡住等待。sleep(20)是为了防止CPU飙高代价是响应会慢20毫秒。如果要更精细的控制可以在C层用poll或select做超时Java层就不用sleep了。如果你做的是带进度的上位机场景——比如通过串口读取下位机传输的日志更新界面上的Android进度条——数据量会比较大。建议在Java层用缓冲区分包每条消息里带一个进度值Handler里拿到后先更新进度条再刷新日志列表。串口分包没有绝对边界下位机最好在数据头尾加帧头帧尾不然你到岗后天天断包。4.3 串口参数波特率、数据位、校验位的JNI设置串口通信的前提是双方参数一致。C层配置串口参数用的函数是tcgetattr和tcsetattr这两个函数在termios.h头文件里。demo的serial_port.c里一般会有一段类似这样的代码int setup_port(int fd, int baud_rate) { struct termios options; tcgetattr(fd, options); cfsetispeed(options, baud_rate); cfsetospeed(options, baud_rate); options.c_cflag | (CLOCAL | CREAD); options.c_cflag ~CSIZE; options.c_cflag | CS8; options.c_cflag ~PARENB; options.c_cflag ~CSTOPB; options.c_cflag ~CRTSCTS; tcsetattr(fd, TCSANOW, options); return 0; }这段配置的意思是把波特率设为八位数据位、无校验、一位停止位、禁用硬件流控。修改数据位就把CS8改成CS7同时还要改c_cflag的其他掩码想开校验位就把PARENB加上。不同参数组合是串口联调的第一排查点下位机上报乱码多半就是波特率不匹配而不是代码逻辑错。波特率的值不是直接传整数那么简单。C层的cfsetispeed要求传入B115200、B9600这种宏而不是115200这种裸数字。JNI层收到Java传过来的波特率后需要做一个宏映射表。常见的映射逻辑是int baudrate_to_constant(int baudrate) { switch(baudrate) { case 9600: return B9600; case 19200: return B19200; case 38400: return B38400; case 57600: return B57600; case 115200: return B115200; default: return B9600; } }如果你看到demo处理不了非标准波特率比如2000000这种多半是映射表里没加。很多执法记录仪、车载调试口就喜欢用奇怪波特率遇到这种就把对应宏加到switch里。5. 串口开发常见问题排查与避坑从打不开到乱码5.1 现象一打开串口报Permission denied这个坑排在串口开发所有问题第一名太经典了。现象是Java层调用open马上返回-1logcat里能看到“open /dev/ttyS1: Permission denied”或者只显示open fail没细看原因就关掉了。原因有两类。第一类是设备节点权限不足普通App没有权限访问硬件串口。第二类是节点存在但SELinux策略拦截Android加固的SELinux在enforcing模式下连打开都不让。解决方法是先用adb验证权限边界。执行adb root然后adb shell ls -l /dev/ttyS1看看属主和权限位。如果确认是权限问题直接在设备上chmod 666临时验证。如果你的产品要走正式发布必须在init.rc或ueventd.rc里给串口节点配好chmod并且写selinux te策略。直接改chmod的方式顶多调试用重启设备权限又会丢。如果SELinux拦截现象会是即便root了也打不开。调试时需要临时setenforce 0切到permissive模式确认能打开之后再固化策略。这种问题没有银弹只能一个节点一个节点地配。5.2 现象二JNI找不到native方法运行App一进串口页面就闪退logcat里报“java.lang.UnsatisfiedLinkError: No implementation found for void com.example.serialport.SerialPort.open”。原因基本就是C函数名和Java声明的全限定名对不上或某个字母下划线写错。这类问题在改过包名之后发生概率极高而且项目里多个开发者各自建包很容易冲突。解决方式是不要手抄函数名。用一个快速验证法Java声明写好后编译一遍工程在build的classess目录下执行javah或者javac -h生成头文件把JNIEXPORT的函数签名复制到C代码里。做一次之后就能确认签名匹配。另外要注意如果你在Java里新增了一个native方法但C文件没实现同样会报这个错排查时先数一下Java里声明了多少个native方法逐个核对C文件里有没有对应实现。5.3 现象三读数据乱码或丢字节串口连通了数据也读到了但内容乱得没法看或者偶尔丢一个字节。先说乱码九成是波特率不匹配。下位机用的是115200你代码里配置的是9600读出来的数据必然花屏。先检查setup_port里波特率映射表返回值是不是对的再检查设备里能不能用stty命令确认实际波特率。如果波特率没错但还是偶尔乱码要看数据位和校验位。有的设备用偶校验你按无校验去读字节内容会受校验位干扰。另一个隐蔽因素是每个串口设备驱动对数据缓冲区的处理不同read调用返回的长度可能小于你请求的长度处理时如果按固定长度续传就会错位。我一般是把read返回的len当作真实有效长度后续解析时按帧头帧尾重新对齐不依赖首包就是完整帧。丢字节的情况比较复杂常见于设备背板有多路串口或USB转串口桥接。USB转串口的丢字节很多时候是流控没配。如果接线里没有CTS/RTSC层配置里就不要开CRTSCTS不然硬件流控把数据堵在缓冲区里。另外读取线程睡眠时间太长也会导致下位机连续发数据时你没及时读出来被驱动丢弃。把read线程的sleep改成1毫秒或调成阻塞模式丢字节情况会缓解很多。5.4 现象四so库被裁剪或找不到在真机上跑起来一连串“dlopen failed: library libserial_port.so not found”或者编译时正常但一运行就报类库缺失。排查时先看打印出的ABI。手机是arm64你却只在libs/armeabi-v7a下放so系统就找不到。Android Studio打包时默认只打arm64-v8a和armeabi-v7a两种如果你的工程里还设置了abiFilters漏了架构就一定出问题。在app的build.gradle的defaultConfig里加一段ndk { abiFilters arm64-v8a, armeabi-v7a }确保so的目录名和abiFilters一致。另一个翻车点是把so文件用copy命令塞进了src/main/jniLibs/artifactId这类目录注意路径一定得是src/main/jniLibs/arm64-v8a/libserial_port.so。命名上lib前缀必须带Java层的loadLibrary只写serial_port这个对应关系不要搞混。如果以上都检查了还报not found用zip解压apk看看lib目录下到底能不能看到so文件。看不到就是打包阶段没打进去看一眼build.gradle里有没有sourceSets把jniLibs.srcDirs指错了。5.5 现象五设备节点不存在打开/dev/ttyS1时报No such file or directory。这种问题在平板方案、定制开发板和某些国产主控上特别常见。原因往往是设备节点由内核驱动创建对应的UART口在硬件上没使能或者驱动没加载。你可以先查串口节点列表adb shell ls -l /dev/ttyS* /dev/ttyMT* /dev/ttyUSB* 2/dev/null如果没有任何节点输出说明内核里对应的串口控制器没有注册。去板级设备树或内核config里找对应宏比如CONFIG_SERIAL_8250_DW。如果是USB转串口节点通常在/dev/ttyUSB0或/dev/ttyACM0得看设备插上后有没有内核日志。排这种问题拿串口线去接一个USB转TTL模块先确认硬件到底通了没有别在代码里空转。另外某些设备节点名不是ttyS开头而是ttyMT、ttyHSL这类拿到设备后第一件事是去/proc/tty/drivers看内核注册了哪些串口驱动再对照硬件原理图找节点路径。6. 让这个Demo变成可上线工程的三个进阶改造6.1 用串口做异步读取换成回调接口而不是裸线程demo里最原始的写法是Java层开一个Thread循环读数据。这个能做但上不了台面。更好的做法是定义串口数据回调接口Reader线程读到的数据统一推给回调Activity通过接口实现类接收。这样多个页面都能起串口监听不会出现每个页面都写一套循环读逻辑的重复代码。我用这种方式重写过好几个项目后面加协议解析、加日志上报都只要在回调里做文章。6.2 串口参数动态配置从配置文件读取而不是写死大多数demo把波特率写死在打开串口那一步数据分析时想改一下就得重新编App。改造方向是把设备路径、波特率、数据位这些参数放到SharedPreferences或assets里的配置文件中。App启动时先读取配置再调用open。这样拿到新串口设备不用动代码直接改配置文件就能跑。我做过一个工业手持机的串口调试工具这类设备型号多、波特率杂这个改造直接救了大命。6.3 验证方法用USB转串口做回环测试最后一个习惯强烈建议养成把pin 2和pin 3短接或者买一个USB转TTL模块自己发数据做回环验证。回环测试的流程是写一个循环发送线程每隔一秒发一个递增字节读线程把收到的字节打印出来如果收到的和发出去的一致说明驱动层没问题。这个测试还能验证流控和缓冲区大小上线前跑一遍能挡掉很多低级错误。我在串口项目里养成的一个习惯是所有参数和错误码都打印到logcat里带时间戳。串口问题最难的就是复现没有日志基本只能靠猜。后来每次联调我都是先把完整log拉下来定位到第一个异常点再动手改代码。如果你现在准备拿着这个demo开始一个正式项目先别急着改功能把日志系统、读取线程、参数配置这三件事做好后面会感谢自己。希望帮到你。本文还有配套的精品资源点击获取

Android串口开发实战：JNI+NDK编译与调试全解析

相关推荐

注意力机制原理与实战：从基础到Transformer应用

OpenProp v3.3.4开源螺旋桨设计工具链实战指南

现代CMake核心原则与工程实践指南

更多资讯

插入排序、希尔排序、选择排序底层原理与工程选型

SUMO多模式交通仿真技术与智慧城市应用

Access 2007数据分析：从Excel导入到SQL查询与交叉表实战

SUMO交通仿真软件系统集成技术解析

交通灯识别系统实战：小目标检测与颜色分类的工程化方案

2026年大模型行业薪资现状与职业发展分析

今日更新

Agent-Reach：打通大模型触达外部系统的最后一公里

深度学习图像隐写分析实战：从CNN原理到毕设源码全解析

AI赋能知识产权供需匹配：专利评估、需求挖掘与多路召回工程实践

本周精选

防幻觉智能体架构：电源硬件设计中的大模型编排与工具化实践

OpenGL面试核心考点：渲染管线、矩阵变换与性能排查全解析

全国计算机二级C语言真题PDF高效刷题指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？