3. Program Examples 示例程序
All examples have been derived from miniterm.c. The type ahead buffer is limited to 255 characters, just like the maximum string length for canonical input processing (<linux/limits.h> or <posix1_lim.h>).
See the comments in the code for explanation of the use of the different input modes. I hope that the code is understandable. The example for canonical input is commented best, the other examples are commented only where they differ from the example for canonical input to emphasize the differences.
The descriptions are not complete, but you are encouraged to experiment with the examples to derive the best solution for your application.
Don't forget to give the appropriate serial ports the right permissions (e. g.: chmod a+rw /dev/ttyS1)!
所有的示例来自于 miniterm.c. The type ahead 缓存器限制在 255 字节的大小, 这与标准输入(canonical input)进程的字符串最大长度相同 (<linux/limits.h> 或 <posix1_lim.h>).
代码中的注释解释了不同输入模式的使用以希望这些代码能够易于理解。标准输入程序的示例做了最详细的注解, 其它的示例则只是在不同于标准输入示例的地方做了强调。
叙述不是很完整, 但可以激励你对这范例做实验, 以延生出合于你所需应用程序的最佳解.
不要忘记赋予串口正确的权限 (也就是: chmod a+rw /dev/ttyS1)!
3.1. Canonical Input Processing 标准输入模式
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
#include <termios.h>
#include <stdio.h>
/* baudrate settings are defined in <asm/termbits.h>, which is included by <termios.h> */
// 波特率的设置定义在 <asm/termbits.h>. 包含在 <termios.h> 里
#define BAUDRATE B38400
/* change this definition for the correct port */
// 定义您所需要的串口号
#define MODEMDEVICE "/dev/ttyS1"
#define _POSIX_SOURCE 1 /*POSIX compliant source POSIX系统兼容*/
#define FALSE 0
#define TRUE 1
volatile int STOP=FALSE;
main() {
int fd,c, res;
struct termios oldtio,newtio;
char buf[255];
/* Open modem device for reading and writing and not as controlling
tty because we don't want to get killed if linenoise sends CTRL-C.
开启设备用于读写，但是不要以控制 tty 的模式，因为我们并不希望在发送 Ctrl-C
后结束此进程
*/
fd = open(MODEMDEVICE, O_RDWR | O_NOCTTY );
if (fd <0) {perror(MODEMDEVICE); exit(-1); }
tcgetattr(fd,&oldtio); /* save current serial port settings */
// 储存当前的串口设置
bzero(&newtio, sizeof(newtio)); /* clear struct for new port settings */
// 清空新的串口设置结构体
/*
BAUDRATE: Set bps rate. You could also use cfsetispeed and cfsetospeed.
CRTSCTS : output hardware flow control (only used if the cable has all
ecessary lines. See sect. 7 of Serial-HOWTO)
CS8 : 8n1 (8bit,no parity,1 stopbit)
CLOCAL : local connection, no modem contol
CREAD : enable receiving characters
BAUDRATE: 设置串口的传输速率bps, 也可以使用 cfsetispeed 和 cfsetospeed 来设置
CRTSCTS : 输出硬件流控(只能在具完整线路的缆线下工作，参考 Serial-HOWTO 第七节)
CS8 : 8n1 (每一帧8比特数据,无奇偶校验位,1 比特停止位)
CLOCAL : 本地连接，无调制解调器控制
CREAD : 允许接收数据
*/
newtio.c_cflag = BAUDRATE | CRTSCTS | CS8 | CLOCAL | CREAD;
/*
IGNPAR : ignore bytes with parity errors
ICRNL : map CR to NL (otherwise a CR input on the other computer will not
terminate input) otherwise make device raw (no other input processing)
IGNPAR : 忽略奇偶校验出错的字节
ICRNL : 把 CR 映像成 NL (否则从其它机器传来的 CR 无法终止输入)或者就把设备设
为 raw 状态（没有额外的输入处理）
*/
newtio.c_iflag = IGNPAR | ICRNL;
/*
Raw output. Raw 模式输出
*/
newtio.c_oflag = 0;
/*
ICANON : enable canonical input
disable all echo functionality, and don't send signals to calling program
ICANON : 启动 标准输出， 关闭所有回显echo 功能，不向程序发送信号
*/
newtio.c_lflag = ICANON;
/*
initialize all control characters
default values can be found in /usr/include/termios.h, and
are given in the comments, but we don't need them here
初始化所有的控制字符， 默认值可以在 /usr/include/termios.h 找到，
并且做了注解，不过这里我们并不需要考虑这些
*/
newtio.c_cc[VINTR] = 0; /* Ctrl-c */
newtio.c_cc[VQUIT] = 0; /* Ctrl-\ */
newtio.c_cc[VERASE] = 0; /* del */
newtio.c_cc[VKILL] = 0; /* @ */
newtio.c_cc[VEOF] = 4; /* Ctrl-d */
newtio.c_cc[VTIME] = 0; /* inter-character timer unused */
/* 不使用字符间的计时器 */
newtio.c_cc[VMIN] = 1; /* blocking read until 1 character arrives */
/* 阻塞，直到读取到一个字符 */
newtio.c_cc[VSWTC] = 0; /* '\0' */
newtio.c_cc[VSTART] = 0; /* Ctrl-q */
newtio.c_cc[VSTOP] = 0; /* Ctrl-s */
newtio.c_cc[VSUSP] = 0; /* Ctrl-z */
newtio.c_cc[VEOL] = 0; /* '\0' */
newtio.c_cc[VREPRINT] = 0; /* Ctrl-r */
newtio.c_cc[VDISCARD] = 0; /* Ctrl-u */
newtio.c_cc[VWERASE] = 0; /* Ctrl-w */
newtio.c_cc[VLNEXT] = 0; /* Ctrl-v */
newtio.c_cc[VEOL2] = 0; /* '\0' */
/*
now clean the modem line and activate the settings for the port
清空数据线，启动新的串口设置
*/
tcflush(fd, TCIFLUSH);
tcsetattr(fd,TCSANOW,&newtio);
/*
terminal settings done, now handle input
In this example, inputting a 'z' at the beginning of a line will
exit the program.
终端设置完成，现在就可以处理数据了
在本程序中，在一行的开始输入一个 'z' 会终止该程序
*/
while (STOP==FALSE) { /* loop until we have a terminating condition */
// 循环直到满足终止条件
/* read blocks program execution until a line terminating character is
input, even if more than 255 chars are input. If the number
of characters read is smaller than the number of chars available,
subsequent reads will return the remaining chars. res will be set
to the actual number of characters actually read
即使输入超过 255 个字节，读取的程序段还是会一直等到行结束符出现才会停止。
如果读到的字符少于应刚获得的字符数，则剩下的字符串会在下一次读取时读到。
res 用来获得每次真正读到的字节数
*/
res = read(fd,buf,255);
buf[res]=0; /* set end of string, so we can printf */
// 设置字符串结束符，从而可以顺利使用 printf
printf(":%s:%d\n", buf, res);
if (buf[0]=='z') STOP=TRUE;
}
/* restore the old port settings 恢复旧的串口设置 */
tcsetattr(fd,TCSANOW,&oldtio);
}
3.2. Non-Canonical Input Processing 非标准输入模式
In non-canonical input processing mode, input is not assembled into lines and input processing (erase, kill, delete, etc.) does not occur. Two parameters control the behavior of this mode: c_cc[VTIME] sets the character timer, and c_cc[VMIN] sets the minimum number of characters to receive before satisfying the read.
If MIN > 0 and TIME = 0, MIN sets the number of characters to receive before the read is satisfied. As TIME is zero, the timer is not used.
If MIN = 0 and TIME > 0, TIME serves as a timeout value. The read will be satisfied if a single character is read, or TIME is exceeded (t = TIME *0.1 s). If TIME is exceeded, no character will be returned.
If MIN > 0 and TIME > 0, TIME serves as an inter-character timer. The read will be satisfied if MIN characters are received, or the time between two characters exceeds TIME. The timer is restarted every time a character is received and only becomes active after the first character has been received.
If MIN = 0 and TIME = 0, read will be satisfied immediately. The number of characters currently available, or the number of characters requested will be returned. According to Antonino (see contributions), you could issue a fcntl(fd, F_SETFL, FNDELAY); before reading to get the same result.
By modifying newtio.c_cc[VTIME] and newtio.c_cc[VMIN] all modes described above can be tested.
在非标准输入模式中，输入的数据并不组合成行，也不会进行 erase, kill, delete 等输入处理。我们只是用两个参数来控制这种模式的输入行为： c_cc[VTIME] 设定字符输入间隔时间的计时器，而 c_cc[VMIN] 设置满足读取函数的最少字节数。
MIN > 0, TIME = 0 ： 读取函数在读到了 MIN 值的字符数后返回。
MIN = 0, TIME > 0 ： TIME 决定了超时值，读取函数在读到一个字节的字符，或者等待读取时间超过 TIME （t = TIME * 0.1s）以后返回，也就是说，即使没有从串口中读到数据，读取函数也会在 TIME 时间后返回。
MIN > 0, TIME > 0 ： 读取函数会在收到了 MIN 字节的数据后，或者超过 TIME 时间没收到数据后返回。此计时器会在每次收到字符的时候重新计时，也只会在收到第一个字节后才启动。
MIN = 0, TIME = 0 ： 读取函数会立即返回。实际读取到的字符数，或者要读到的字符数，会作为返回值返回。根据 Antonino（参考 conditions）, 可以使用 fcntl(fd, F_SETFL, FNDELAY), 在读取前获得同样的结果。
改变了 nettio.c_cc[VTIME] 和 newtio.c_cc[VMIN], 就可以测试以上的设置了。
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
#include <termios.h>
#include <stdio.h>
#define BAUDRATE B38400
#define MODEMDEVICE "/dev/ttyS1"
#define _POSIX_SOURCE 1 /* POSIX compliant source */
#define FALSE 0
#define TRUE 1
volatile int STOP=FALSE;
main() {
int fd,c, res;
struct termios oldtio,newtio;
char buf[255];
fd = open(MODEMDEVICE, O_RDWR | O_NOCTTY );
if (fd <0) {perror(MODEMDEVICE); exit(-1); }
tcgetattr(fd,&oldtio); /* save current port settings */
bzero(&newtio, sizeof(newtio));
newtio.c_cflag = BAUDRATE | CRTSCTS | CS8 | CLOCAL | CREAD;
newtio.c_iflag = IGNPAR;
newtio.c_oflag = 0;
/* set input mode (non-canonical, no echo,...) */
// 设置输入模式为非标准输入
newtio.c_lflag = 0;
newtio.c_cc[VTIME] = 0; /* inter-character timer unused */
// 不是用字符间隔计时器
newtio.c_cc[VMIN] = 5; /* blocking read until 5 chars received */
//收到5个字符数以后，read 函数才返回
tcflush(fd, TCIFLUSH);
tcsetattr(fd,TCSANOW,&newtio);
while (STOP==FALSE) { /* loop for input */
res = read(fd,buf,255); /* returns after 5 chars have been input */
buf[res]=0; /* so we can printf... */
printf(":%s:%d\n", buf, res);
if (buf[0]=='z') STOP=TRUE;
}
tcsetattr(fd,TCSANOW,&oldtio);
}
3.3. Asynchronous Input 异步输入模式
#include <termios.h>
#include <stdio.h>
#include <unistd.h>
#include <fcntl.h>
#include <sys/signal.h>
#include <sys/types.h>
#define BAUDRATE B38400
#define MODEMDEVICE "/dev/ttyS1"
#define _POSIX_SOURCE 1 /* POSIX compliant source */
#define FALSE 0
#define TRUE 1
volatile int STOP=FALSE;
void signal_handler_IO (int status); /* definition of signal handler */
// 定义信号处理程序
int wait_flag=TRUE; /* TRUE while no signal received */
// TRUE 代表没有受到信号，正在等待中
main() {
int fd,c, res;
struct termios oldtio,newtio;
struct sigaction saio;
/* definition of signal action */
// 定义信号处理的结构
char buf[255];
/* open the device to be non-blocking (read will return immediatly) */
// 是用非阻塞模式打开设备 read 函数立刻返回，不会阻塞
fd = open(MODEMDEVICE, O_RDWR | O_NOCTTY | O_NONBLOCK);
if (fd <0) {perror(MODEMDEVICE); exit(-1); }
/* install the signal handler before making the device asynchronous */
// 在进行设备异步传输前，安装信号处理程序
saio.sa_handler = signal_handler_IO;
saio.sa_mask = 0;
saio.sa_flags = 0;
saio.sa_restorer = NULL;
sigaction(SIGIO,&saio,NULL);
/* allow the process to receive SIGIO */
// 允许进程接收 SIGIO 信号
fcntl(fd, F_SETOWN, getpid());
/* Make the file descriptor asynchronous (the manual page says only
O_APPEND and O_NONBLOCK, will work with F_SETFL...) */
// 设置串口的文件描述符为异步，man上说，只有 O_APPEND 和 O_NONBLOCK 才能使用F_SETFL
fcntl(fd, F_SETFL, FASYNC);
tcgetattr(fd,&oldtio); /* save current port settings */
/* set new port settings for canonical input processing */
// 设置新的串口为标准输入模式
newtio.c_cflag = BAUDRATE | CRTSCTS | CS8 | CLOCAL | CREAD;
newtio.c_iflag = IGNPAR | ICRNL;
newtio.c_oflag = 0;
newtio.c_lflag = ICANON;
newtio.c_cc[VMIN]=1;
newtio.c_cc[VTIME]=0;
tcflush(fd, TCIFLUSH);
tcsetattr(fd,TCSANOW,&newtio);
/* loop while waiting for input. normally we would do something
useful here 循环等待输入，通常我们会在这里做些其它的事情 */
while (STOP==FALSE) {
printf(".\n");usleep(100000);
/* after receiving SIGIO, wait_flag = FALSE, input is availableand can be read */
// 在收到 SIGIO 信号后，wait_flag = FALSE, 表示有输入进来，可以读取了
if (wait_flag==FALSE) {
res = read(fd,buf,255);
buf[res]=0;
printf(":%s:%d\n", buf, res);
if (res==1) STOP=TRUE; /* stop loop if only a CR was input */
wait_flag = TRUE; /* wait for new input 等待新的输入*/
}
}
/* restore old port settings */
tcsetattr(fd,TCSANOW,&oldtio);
}
/***************************************************************************
* signal handler. sets wait_flag to FALSE, to indicate above loop that *
* characters have been received. *
***************************************************************************/
// 信号处理函数，设置 wait_flag 为 FALSE, 以告知上面的循环函数串口收到字符了
void signal_handler_IO (int status) {
printf("received SIGIO signal.\n");
wait_flag = FALSE;
}
3.4. Waiting for Input from Multiple Sources 等待来自多个源的输入
This section is kept to a minimum. It is just intended to be a hint, and therefore the example code is kept short. This will not only work with serial ports, but with any set of file descriptors.
The select call and accompanying macros use a fd_set. This is a bit array, which has a bit entry for every valid file descriptor number. select will accept a fd_set with the bits set for the relevant file descriptors and returns a fd_set, in which the bits for the file descriptors are set where input, output, or an exception occurred. All handling of fd_set is done with the provided macros. See also the manual page select(2).
这一部分的内容很少，只是作为一个提示，因此这段代码也很简短。而且这部分内容不仅适用于串口编程，而且适用于任意的一组文件描述符。
select 调用及其相应的宏，使用 fd_set. 这是一个比特数组，其中每一个比特代表了一个有效的文件描述符号。 select 调用接收一个有效的文件描述符结构，并返回 fd_set 比特数组，如果此比特数组中有某一个位设为1，就表示对应的文件描述符发生了输入，输出或者有例外事件。所有 fg_set 的处理都由宏提供了，具体参考 man select 2 。
Other Sources of Information 其它资源信息
· The Linux Serial-HOWTO describes how to set up serial ports and contains hardware information.
Linux Serial HOWTO 介绍了如何安装串口，并包括了硬件信息。
· Serial Programming Guide for POSIX Compliant Operating Systems, by Michael Sweet.
POSIX 兼容的操作系统上的串口编程
· The manual page termios(3) describes all flags for the termios structure.
man termios 3 介绍了所有 termios 结构里的设置。
