doc.txt

Library: RS-232
Author:  Teunis van Beelen
Url:     http://www.teuniz.net/RS-232/
E-mail:  teuniz@gmail.com
License: GPLv3

Last revision: July 10, 2016



int RS232_OpenComport(int comport_number, int baudrate, const char * mode)

  Opens the comport, comportnumber starts with 0 (see the list of numbers).
  Baudrate is expressed in baud per second i.e 115200 (see the list of possible baudrates).
  Mode is a string in the form of "8N1", "7E2", etc.
  8N1 means eight databits, no parity, one stopbit. If in doubt, use 8N1 (see the list of possible modes).
  Returns 1 in case of an error.
  In case the comport is already opened (by another process),
  it will not open the port but raise an error instead.

int RS232_PollComport(int comport_number, unsigned char *buf, int size)

  Gets characters from the serial port (if any). Buf is a pointer to a buffer
  and size the size of the buffer in bytes.
  Returns the amount of received characters into the buffer.
  After succesfully opening the COM-port, connect this function to a timer.
  The timer should have an interval of approx. 20 to 100 milliSeconds.
  Do not forget to stop the timer before closing the COM-port.
  Allways check the return value! The return value tells you how many bytes
  are actually received and present in your buffer!

int RS232_SendByte(int comport_number, unsigned char byte)

  Sends a byte via the serial port. Returns 1 in case of an error.

int RS232_SendBuf(int comport_number, unsigned char *buf, int size)

  Sends multiple bytes via the serial port. Buf is a pointer to a buffer
  and size the size of the buffer in bytes.
  Returns -1 in case of an error, otherwise it returns the amount of bytes sent.
  This function blocks (it returns after all the bytes have been processed).

void RS232_CloseComport(int comport_number)

  Closes the serial port.

void RS232_cputs(int comport_number, const char *text)

  Sends a string via the serial port. String must be null-terminated.

int RS232_GetPortnr(const char *devname)

  Returns the comport number based on the device name e.g. "ttyS0" or "COM1".
  (Doesn't mean the device actually exists!)
  Returns -1 when not found.


The following functions are normally not needed but can be used to set or check the status of the control-lines:
================================================================================================================

void RS232_enableDTR(int comport_number)

  Sets the DTR line high (active state).

void RS232_disableDTR(int comport_number)

  Sets the DTR line low (non active state).

void RS232_enableRTS(int comport_number)

  Sets the RTS line high (active state).

void RS232_disableRTS(int comport_number)

  Sets the RTS line low (non active state).

int RS232_IsDSREnabled(int comport_number)

  Checks the status of the DSR-pin. Returns 1 when the the DSR line is high (active state), otherwise 0.

int RS232_IsCTSEnabled(int comport_number)

  Checks the status of the CTS-pin. Returns 1 when the the CTS line is high (active state), otherwise 0.

int RS232_IsDCDEnabled(int comport_number)

  Checks the status of the DCD-pin. Returns 1 when the the DCD line is high (active state), otherwise 0.


The following functions are normally not needed but can be used to empty the rx/tx buffers:
===========================================================================================

("discards data written to the serial port but not transmitted, or data received but not read")

void RS232_flushRX(int comport_number)

  Flushes data received but not read.

void RS232_flushTX(int comport_number)

  Flushes data written but not transmitted.

void RS232_flushRXTX(int comport_number)

  Flushes both data received but not read, and data written but not transmitted.



Notes:

You don't need to call RS232_PollComport() when you only want to send characters.
Sending and receiving do not influence eachother.

The os (kernel) has an internal buffer of 4096 bytes (for traditional onboard serial ports).
USB/Serial-converter drivers use much bigger buffers (multiples of 4096).
If this buffer is full and a new character arrives on the serial port,
the oldest character in the buffer will be overwritten and thus will be lost.

After a successfull call to RS232_OpenComport(), the os will start to buffer incoming characters.

tip: To get access to the serial port on Linux, you need to be a member of the group "dialout".

Note: Traditional (on-board) UART's usually have a speed limit of max. 115200 baud.
            Special cards and USB to Serial converters can usually be set to higher baudrates.


List of comport numbers, possible baudrates and modes:

  Linux   windows
0   ttyS0   COM1
1   ttyS1   COM2
2   ttyS2   COM3
3   ttyS3   COM4
4   ttyS4   COM5
5   ttyS5   COM6
6   ttyS6   COM7
7   ttyS7   COM8
8   ttyS8   COM9
9   ttyS9   COM10
10  ttyS10  COM11
11  ttyS11  COM12
12  ttyS12  COM13
13  ttyS13  COM14
14  ttyS14  COM15
15  ttyS15  COM16
16  ttyUSB0   n.a.
17  ttyUSB1   n.a.
18  ttyUSB2   n.a.
19  ttyUSB3   n.a.
20  ttyUSB4   n.a.
21  ttyUSB5   n.a.
22  ttyAMA0   n.a.
23  ttyAMA1   n.a.
24  ttyACM0   n.a.
25  ttyACM1   n.a.
26  rfcomm0   n.a.
27  rfcomm1   n.a.
28  ircomm0   n.a.
29  ircomm1   n.a.
  FreeBSD
30  cuau0     n.a.
31  cuau1     n.a.
32  cuau2     n.a.
33  cuau3     n.a.
34  cuaU0     n.a.
35  cuaU1     n.a.
36  cuaU2     n.a.
37  cuaU3     n.a.

Linux   windows
50  n.a.
75  n.a.
110   110
134   n.a.
150   n.a.
200   n.a.
300   300
600   600
1200  1200
1800  n.a.
2400  2400
4800  4800
9600  9600
19200   19200
38400   38400
57600   57600
115200  115200
230400  128000
460800  256000
500000  500000
576000  n.a.
921600  n.a.
1000000   1000000
1152000   n.a.
1500000   n.a.
2000000   n.a.
2500000   n.a.
3000000   n.a.
3500000   n.a.
4000000   n.a.

Mode
8N1
8O1
8E1
8N2
8O2
8E2
7N1
7O1
7E1
7N2
7O2
7E2
6N1
6O1
6E1
6N2
6O2
6E2
5N1
5O1
5E1
5N2
5O2
5E2