BeagleBoard/GSoC/Serial-Terminal-Server

=BeagleBone Serial Terminal Server=

The BeagleBones have 4 capable UARTs and the goal of this project is to provide the end user an image to configure, access and control the UART devices using a user friendly interface or SSH directly into the BBB to take control of the UART device.

Student: Saumitra Kapoor Mentors: Michael Welling Code: https://github.com/ServerProcessor Wiki: http://elinux.org/BeagleBoard/GSoC/Serial-Terminal-Server GSoC: GSoC Proposal

=Status= This project is currently just a proposal.

=Proposal=

About you
IRC: ServerProcessor Github: ServerProcessor School: BITS Pilani LinkedIn: Saumitra Kapoor Programming Languages: C, C++, Python, Serial Programming Hardware Skills: Arduino, RasPi, BBB, Cape Design, Computer networking Country: India Primary language English, Hindi Typical work hours 2PM-9PM and 1AM-4AM IST

About your project
Project name: BeagleBone-based Serial Terminal Server

Tasks

 * Cross Compilation task completed : https://github.com/jadonk/gsoc-application/pull/73
 * I have well equipped myself with Device Drivers and Device tree Blobs : https://github.com/ServerProcessor/Device-Driver-Assignments and http://saumitra.co/embedded-4/
 * Learning Computer Networking and have to update all articles on the blog : saumitra.co

Description
A serial terminal server provides out of band access for multiple devices and is a central point to access the console parts of many devices. It eliminates the need of backup scenarios like modems for every device. A serial server may have serial cables, each of which runs to a different server. It controls all other servers via a console.

There are two key points to approach this project. First, SSH into the BBB to control the UART devices. Second, create a deployable image to easily configure the UART devices. To enable the BBB to take control of UART devices and to issue commands to it using a serial connection:
 * 1) Use of simple system management daemons such as Systemd can be used which is the first daemon process to execute on BBB.
 * 2) Obtain a full list of services running (systemctl list-units -t service |grep tty)
 * 3) Get the status of the current serial service (systemctl status )
 * 4) Replace the serial service with a custom application service by disabling the current serial service (sudo systemctl stop ) and then disable it from boot
 * 5) Deploy your own design serial service.

Let us discuss the underlying steps to setup a serial terminal server allowing reliable device connections one at a time -


 * Transmission of bytes : The AM335x first sends the byte to the IO address of the serial port. The serial port then takes the byte and sends it one bit at at a time. This is an upper level abstraction and let us dive further. The serial device driver program (running on the CPU) sends a byte to the serial port's IO address (explaining it with a byte but does depend on the FIFO buffer size) which gets into the transmit shift register in the serial port. From the shift register, bits are taken and sent out one by one on the serial line. The 16 byte FIFO buffer should have many bytes to supply it to the register which is done by sending voltage interrupts by putting voltage on a dedicated line. Unless the AM335x is doing something important, the interrupt stops it and runs a program to force it to send another byte to the buffer. The custom serial device driver (which also maintains a IO address to the tty mapping) will check the registers at that IO address to see what happened. If the buffer needs more bytes, it sends it.
 * Receiving : It is also interrupt driven. The interrupt is sent to the CPU after 14 bytes (for a 16 byte buffer) are in receive buffer. The serial driver also does limited filtering of data passing across these buffers.If the amount of received data hasn't reached the receiver trigger level value, then when will the UART issue an interrupt which is solved by timeouts. The length of the timeout is different for different UART designs.

Improving the UART's FIFO buffer : Correct configuration is required for smooth communication behaviour. The frequency with which the interrupts are issued can be controlled by adjusting the receive trigger level value. When the amount of received data reaches the RTL, the UART will issue an interrupt. The 16 byte FIFO supports 4 RTL levels: 1,4,8,14 which means that an interrupt will be issued when the UART FIFO receives 1,4,8,14 bytes of data. Also, there is always a "pick one" scenario in case of latency and throughput. There is a need to configure the UART to highest RTL value for apps involving firmware downloads whereas for other applicaiions, disable the FIFO for a better latency. Appropriate changes have to be made in the software image for such conditions. Now, when we have discussed the pitfalls on receiving data but we also need to control how data is transmitted. Transmitting more bytes will result in a higher throughput. The solution is to transmit one byte for each interrupt, which increases the lag between two bytes and gives the device more processing time. Detailed analysis of the application or software can prevent problems and result in better communication with the serial device.
 * 1) Good Rx latency can be achieved by disabling the FIFO or set the Rx trigger level to 1
 * 2) Data overflow for small buffers or slow serial devices can be avoided by disabling the FIFO or setting RTL to 1 and sending 1 byte for each interrupt
 * 3) Better Rx throughput and improving Rx lag can be done by using advanced UART with RBH and RBL(low water level) and set the RBL to a nonzero value. The same goes for achieving a better Tx and improving Tx lag by using TBH instead of RBH and set TBL to a nonzero value
 * 4) To avoid data overflow while using XON/XOFF flow control is to try disabling the FIFO

The BBB needs to communicate with the serial port, the system must know that each serial port exists and the IO address(where it is) and the IRQ number to request service from the BBB's AM335x. The dev/ directory names (ttySx) are mapped to the physical serial port and the mapped table is maintained by the serial driver. Mapping may be set and viewed by Setserial. When the serial port receives a number of bytes into the FIFO buffer, it signals the processing unit to fetch them. The interrupt will also be sent if there is an unexpected delay while waiting for the next byte to arrive. Each interrupt conductor will have a IRQ and serial port and a list of them can be viewed by using Setserial. This has to be done in a timely manner since the buffer can hold only 16 incoming bytes and there may be buffer overrun. The appropriate interrupt tells the interrupt controller to signal the processing unit which then runs interrupt service routine(which is also a part of serial driver). If feasible, it would be better to use hardware flow control to slow down the flow of bytes by soldering two separate dedicated start/stop signal wires or the software implementation which uses the ASCII control characters should be used for this purpose but software flow control is slower. If a program is unable to set flow control in the serial driver, then it can be done with stty command. Also, it needs to be in a file that runs at start-up because the driver will not remember the setting after linux stops. The serial driver should ensure that IRQ and address space have been allocated. Then, the modification in the application program have to be made to set the port speed, flow control,etc. by using a menu or configuration file.

Linux Programs to monitor various control lines(versions might change) :


 * Serial monitoring and diagonostics - Serlook to snoop on serial line traffic and send/receive on a serial line.
 * Changing interrupt policy - irqtune to give serial port interrupts higher priority to improve performance. hdparm for hard-disk tuning.
 * Setserial allows one to talk to the concerned serial software. It deals with lower-level configuring of the serial port such as IRQs and port addresses. If a serial module gets unloaded, the changes previously made by setserial will be forgotten by the driver.
 * stty does much of the configuration of the serial port and since a getty program often handles it, there seems less need of it. it is handy when problems for setting up a serial port arise. Setserial deals only with the actual serial ports, stty is used both for the serial ports and virtual terminals and for virtual terminals such as standard linux text interface.
 * crtscts for hardware flow control and ixon,ixoff,ixany for software flow control. Ixany is mainly for terminals. Hitting any key will restart the flow-control step. If you stop scrolling with the "stop scroll" key then hitting any key will resume scrolling.
 * Ixon enables the port to listen fro xoff and to stop transmitting when it gets an xoff.
 * ixoff enables the port to send the xoff signal out the transmit line when it buffers in main memory are nearly full.
 * Ser2net is a linux program which will connect to a network to the serial port. It could be a bridge between the ethernet cable and the serial port.
 * isapnp - to configure plug and play devices and includes isapnptools.

Timeline
2017-06-06: Milestone #1 2017-06-13: Milestone #2 2017-06-20: Milestone #3 2017-06-27: Milestone #4 2017-07-04: Milestone #5 2017-07-11: Milestone #6 2017-07-18: Milestone #7 2017-07-25: Milestone #8 2017-08-01: Milestone #9 2017-08-08: Milestone #10 2017-08-15: Milestone #11

To be updated after final compilation.

Experience and approach

 * 1) Prior knowledge of embedded systems, soldering, device drivers, C and have worked with BBB, RaspberryPi and ESPs.
 * 2) I run my open source website to teach basic electronics and device drivers at : http://saumitra.co/
 * 3) Before the start of the project, I have well equipped myself with the necessary tools and skills to start off.

Contingency

 * 1) Talk to people on IRC and Mailing list
 * 2) Talk to the BBB community
 * 3) Read AM335x documentation
 * 4) Look up for data sheets and online resources like - http://www.tronisoft.com/rs232info/ASCII_serial_port_crib_sheets.pdf

Suggestions
Yes. I'm interested in developing the hardware for the project too since I'm passionate about electronics and would love to work on the same. I have previously worked on arduino shields PCB. I will be updating detailed weekly report on the group and on my blog. I started working early on the BBB to prepare myself in advance and it took a lot of time to get well equipped with BB, Device Drivers , PRUs and networking. At this stage, I want to invest my complete time in the project and have kept my summers free for the same. Also, I have shared my work of open source contribution via my "open source website" and Github and look forward to continue the same.