Repository files navigation

A Java terminal IO library designed to communicate and control the serial (RS232) drivers.

Serial4j is a terminal I/O library primarily built on top of POSIX base file API<fcntl> for file control operations,<unistd> for Unix std R/W operations,<dirent> for directory entry dir operations, and<sys/ioctl> for controlling modem bits.

• Full control on the serial devices over the terminal I/O.
• Full control on the serial port, the original RS-232 DB-25 port.
• SerialMonitor API.
• Human Interface Device (HID) API providing a serial-device abstraction, and common devices standardizations.
• Powered by a variety of examples and tech-demos.

Preface: The binding library consists of the main packageserial4j.core.terminal which houses the terminal control facilities for opening, reading and writing toa terminal device in addition to setting the terminal line speed (baud rate), controlling the input and output queues and controlling the UI of the terminal driver.

• The APIserial4j.core.terminal houses the terminal IO control and the native IO streams, it is considered the backbone of the Serial4j framework, the monitor API widely utilizes it.
• The APIserial4j.core.serial houses the serial monitor and the serial port that is internally manipulated using the terminal IO API.
• The APIserial4j.core.flag houses the interface for the appendable bit masks.
• The APIserial4j.core.modem houses the modem bits (pins) controller based on the standard DB-25 RS232 port driver, with the help of the Terminal API, a developer acquires full control on the serial ports.
• The APIserial4j.core.errno houses an interpreter pattern that parses native runtime caught errno codes, and convert them into Java exception thrown against the JRE, a developer is capable of catching them and recovering based on their preferences.

An average daily code should directly interact withserial4j.core.serial API, particularly theSerialMonitor API.Custom setups will usually require the use of the terminal API, too. Of note that each serial monitor instance is associated with a terminal device instancewhich is available with a single indirection operation viaSerialMonitor#getTerminalDevice(), and available from the serial monitor entities (read/write entities),as well.

The Java Native Interface API is a private API, and subjected to breaking changes in the contemporary future releases. Developers arediscouraged to utilize it via the Java Reflection API, you are very welcome to open an issue and explain the library defects that forcedyou to utilize the native API.

# building and assembling┌─[pavl-machine@pavl-machine]─[/home/twisted/GradleProjects/Serial4j-v1]└──╼ $./gradlew :serial4j:build&&        ./gradlew :serial4j-native:compileX86_64&&        ./gradlew :serial4j-native:copyBinaries&&        ./gradlew :serial4j-native:assemble&&        ./gradlew :serial4j-native:copyToExample# selectively running an example ┌─[pavl-machine@pavl-machine]─[/home/twisted/GradleProjects/Serial4j-v1] └──╼ $./gradlew :serial4j-examples:run \       --args="com.serial4j.example.jme.RollingTheMonkey  /dev/ttyUSB0"

• The packagecom.serial4j.core.hid contains the core base APIHumanInterfaceDevice that houses a report descriptorHumanInterfaceDevice.ReportDescriptorand a decoder interfaceHumanInterfaceDevice.ReportDescriptor.Decoder, and an event handler interfaceHumanInterfaceDevice.ReportDescriptor.DecoderListenerthat is dispatched when the decoding algorithm defined by the decoder interface has finished-up decoding input data.
• The abstractionStandardSerialDevice is a base implementation that associates aTerminalDevice to the abstract interfaceHumanInterfaceDevice, furtherstandardization or specifications of the serial-based HID interfaces should extend this class, and its own decoder and data registry data structures.
• The rest of the packages are standard examples for theStandardSerialDeivce, theDataFrameDevice is a standardization that provides the abilityto dynamically read data separated by the line feed character (LF-'\n'), and accumulate it into a dataframe buffer without the need to specify a reportlength to the report descriptor object.
• ThisSerial-HID API is based primarily on theusb.org-hid-2001-specification,and thelinux-kernel-hid-intro.

Contents	Redirections
The Linux Programming Interface & The Man Page
Advanced Programming in the Unix Environment by Richard Stevens
Java & JNI

For C/C++ references, find a language reference, either theIBM's or theGNU's, choose whichever suits you.

And, I will leave you with my gems (controlling a jMonkeyEngine vehicle using JoystickModule connected to the ADC unit of the ATMega328p 8-bit MCU):

• The jMonkeyEngine Platform
• Minie Bullet Physics By Stephen Gold
• GNU/Linux Interfaces
• Linux Kernel Userspace APIs
• Universal Serial Bus Human-Interface-Device (HID)
• IBM C Language Reference
• The Java Platform and JNI
• The GitHub Hosting Services.