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. After research, I found that large systems from Sun, IBM still use serial consoles.

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 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. When the device is ready to receive data it asserts RTS by putting a positive voltage on the RTS pin. When the device is unable to receive any more bytes,it negates RTS by putting a negative voltage on the pin. 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.

I also plan on making User Interface to control different UART devices and filtering them. I plan on implementing backend services using Node.js since external C scripts can be hooked with the backend(Node.js being C compatible).

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 from 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.
 * For creating a serial terminal server (maybe with a cisco switch or HP equipment), installing ser2net which will connect a network to the serial port. For instance, someone could connect to the BBB via ethernet port using SSH and login remotely. However, it is better if there is no need of login and using the custom created software but instead immediately connect to the serial port. As per the past discussion above, we could use TCP/IP packets on the serial line too. Setting it up requires specifying which network ports will connect to which serial ports.

Timeline
Before Project Start


 * Community bonding with all the mentors and students, then create a final timeline of the project.
 * Understand the internal structure of device drivers for serial ports and how they perform a variety of services.
 * Write blog posts on http://saumitra.co/ about my development process and milestones for the coming period.
 * Discuss any modifications on existing features.

2017-06-06: Milestone #1 -  I plan to spend one week to create the basic layouts for all the activities and fragments.

2017-06-13: Milestone #2 -  Compilation of a final list of features (like Baud Rate,Parity Bit,Hex Reader,etc) to be included in the UI and kickstarting the development of C modules and overlays which are meant to be integrated with the server.

2017-06-20: Milestone #3 -  Continuing the development of C modules and writing UART dts files for configuring pinmux.

2017-06-27: Milestone #4 -  This week will be spent on testing the C modules functionality with a UART device and bug fixing.

2017-07-04: Milestone #5  Implementing changes according to the feedback.

2017-07-11: Milestone #6 

2017-07-18: Milestone #7 

2017-07-25: Milestone #8 -  Making UI elements for the web app.

2017-08-01: Milestone #9  Implementation of the backend on Node.js. Schema will be prepared and views will be integrated with the frontend.

2017-08-08: Milestone #10 -  Hooking external C scripts in the backend for the computation purposes. Testing the web-service and working on the review provided by the mentors.

2017-08-15: Milestone #11 -  Last week to be spent on completing the documentation of the project and compensate for the elongated goals.

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 as stated in the "tasks" tab above.

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 and http://retired.beyondlogic.org/serial/serial.htm
 * 5) man pages for serial program troubleshooting

Benefit
Following is the value proposition this project offers to the community :


 * 1) Systems administration of remote device and easy configuring - SSHing into the BBB may work but there are times when access to the console is the only way to diagnose and correct software failures.
 * 2) High density clustering of computers/devices - It seems that monitor and keyboard switch is a good solution but VGA signal to the monitor is small, so even with the switch the monitor cannot be placed very far away from the rack. Hence,it is desirable to allow the consoles to be monitored in the room of the device center.
 * 3) Recording console messages - Kernel developers are often faced with a kernel error message that is displayed a split second before the device reboots. A serial console can be used to record that message.
 * 4) Terminal for telecommunications equipment - Most telecommunications equipment is remotely managed and people need to access the equipment to test installation changes and check fault reports. The serial console makes a good craft interface.

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 no commitments for the summer except BBB. Also, I have shared my work of open source contribution via my "open source website" and Github and look forward to continue the same.