Serial

MicroEJ provides a Java foundation library to configure and communicate over serial port. This chapter documents how to use it. Note that the library must be ported to your Virtual Execution Environment to interact with your target’s IO, refer to the Serial VEE porting guide.

Principle

The Serial Foundation Library provides support for serial port communication. It allows MicroEJ Applications to configure, receive and send data on serial links (including, but not limited to, UARTs or USB-CDC virtual ports).

Open / Close

A serial port is opened (reserved) by instantiating a SerialConnection identified by a port name. The returned connection implements AutoCloseable and provides input and output streams for bidirectional data transfer. The port name is VEE port specific, refer to its documentation to find the supported ports.

The port should be closed (released) explicitly (try-with-resources, close()). The garbage collector will ensure that the serial port is closed when the instance of SerialConnection becomes unreachable but you should never rely on it to close the serial port in a timely fashion. There is no guarantee that the garbage collector will run before your application tries to re-open the port.

Configure serial line

The line parameters may have to be configured using the configure method. This method lets you configure:

baud rate

The rate at which individual bits are sent at the physical level. For example, if the port offers RS232 communication, the baud rate includes signaling bits such as the start bit, optional parity bit, and stop bit(s). The API accepts any positive integer.

word length

The length of the data word in bits. The API accepts the constants DATABITS_N defined in SerialConnection, with N ∈ [5..9]. The supported values are VEE port dependent.

parity

Enable parity check of the transmitted data. The API accepts the constants PARITY_NONE, PARITY_EVEN, and PARITY_ODD defined in SerialConnection.

stop bits

Control the number of stop bits used to signal the end of a data frame. The API accepts the constants STOPBITS_1, STOPBITS_1_5, and STOPBITS_2 defined in SerialConnection.

configure() may throw a SerialConfigurationException to reject valid arguments that are unsupported by the VEE port.

The requirement to call configure() is VEE port dependent and may vary from one serial port to another. For example:

  • a virtualized serial link over USB will not need a configuration step as there is no physical serial line to configure.

  • a VEE port may enforce the line parameters for on-board peripherals and reject configuration requests.

SerialConnection does not offer a method to configure flow control.

Read / Write

SerialConnection implements blocking IO operations on InputStream and OutputStream. SerialConnection owns a single instance of each stream, which can be obtained with dedicated getter methods.

Thread-Safety

SerialConnection and its streams are not thread-safe: concurrent access to the same stream must be synchronized by the application. However, close() may be called from any thread to release the port and unblock a pending read or write operation on another thread.

Javadoc

The programming interface is documented in the package’s Javadoc.

Serial Mock

In the simulation environment, no native driver is required. The Serial Mock handles communication for all serial ports and can redirect each port to one of the following:

  • A host serial port: any serial port available on the host computer can be used. The line parameters (baud rate, data bits, parity, and stop bits) are forwarded to the actual port.

  • A TCP socket: a server socket is opened on the specified port. You can connect to it using tools like netcat to interact with the simulated application.

  • Files: input and output can each be redirected to a different file. This is useful for sending precomputed data and analyzing output offline.

Mock Configuration

Each serial port mock is configured using system properties with the prefix s3.mock.uart.com. For a port identified by its ID or name, the following properties are available:

Mock Properties

Property suffix

Description

mode

The mock mode: 0 for host serial port, 1 for file, 2 for socket.

name

The name of the mocked serial port (as used in the application).

mapping

The name of the host serial port to use (mode 0).

file.input

Path to the input file (mode 1).

file.output

Path to the output file (mode 1).

socket.port

The TCP port number for the server socket (mode 2).

socket.timeout

The server socket accept timeout in milliseconds (mode 2, default: 10000).

socket.reconnect

If true, the socket mock waits for a new connection when the previous one is closed (mode 2).

Example: Host serial port mode

s3.mock.uart.com0.mode=0
s3.mock.uart.com0.name=UART7
s3.mock.uart.com0.mapping=COM0

Example: File mode

s3.mock.uart.com3.mode=1
s3.mock.uart.com3.name=/dev/tty10
s3.mock.uart.com3.file.input=/absolute/path/to/input.txt
s3.mock.uart.com3.file.output=/absolute/path/to/output.txt

Example: Socket mode

s3.mock.uart.com6.mode=2
s3.mock.uart.com6.name=COM4
s3.mock.uart.com6.socket.port=5555

When using socket and file modes, there is no simulation of UART baud rate or flow control. On a file, data is always available for reading and is written without delay. On a socket, data transfer speed is limited only by the network interface.

Use

The Serial API Module must be added to the Application project build file to use the Serial library:

implementation("ej.api:serial:3.0.0")