0
# Serial Communication
1
2
Serial port communication for connecting to Arduino boards over USB or RS-232. The serial module provides cross-platform native library support with automatic port discovery and reliable message framing using start/stop bytes and escape sequences.
3
4
## Capabilities
5
6
### Serial Arduino Connection
7
8
Main class for serial port communication implementing the observer pattern for asynchronous message handling.
9
10
```java { .api }
11
class Serial4JArduino implements JArduinoClientObserver, JArduinoSubject {
12
// Message framing constants
13
static final byte START_BYTE = 0x12;
14
static final byte STOP_BYTE = 0x13;
15
static final byte ESCAPE_BYTE = 0x7D;
16
17
// Constructor
18
Serial4JArduino(String port);
19
20
// Communication methods
21
void receiveMsg(byte[] msg);
22
void register(JArduinoObserver observer);
23
void unregister(JArduinoObserver observer);
24
void close();
25
26
// Static utility methods
27
static HashSet<CommPortIdentifier> getAvailableSerialPorts();
28
static void registerPort(String port);
29
static String selectSerialPort();
30
static void main(String[] args);
31
}
32
```
33
34
### Native Library Utilities
35
36
Utility class for managing native serial port libraries across different operating systems.
37
38
```java { .api }
39
class NativeLibUtil {
40
static void copyFile(InputStream in, String to);
41
}
42
```
43
44
## Usage Examples
45
46
### Basic Serial Connection
47
48
```java
49
import org.sintef.jarduino.comm.Serial4JArduino;
50
import org.sintef.jarduino.observer.JArduinoObserver;
51
import org.sintef.jarduino.*;
52
53
public class SerialExample {
54
public static void main(String[] args) {
55
// Create serial connection (Windows example)
56
Serial4JArduino arduino = new Serial4JArduino("COM3");
57
58
// Register observer for Arduino responses
59
arduino.register(new JArduinoObserver() {
60
@Override
61
public void receiveMsg(byte[] msg) {
62
FixedSizePacket packet = JArduinoProtocol.createMessageFromPacket(msg);
63
System.out.println("Arduino response: " + packet.toString());
64
}
65
});
66
67
// Send commands to Arduino
68
FixedSizePacket pinMode = JArduinoProtocol.createPinMode(DigitalPin.PIN_13, PinMode.OUTPUT);
69
arduino.receiveMsg(pinMode.getPacket());
70
71
FixedSizePacket digitalWrite = JArduinoProtocol.createDigitalWrite(DigitalPin.PIN_13, DigitalState.HIGH);
72
arduino.receiveMsg(digitalWrite.getPacket());
73
74
// Clean up
75
arduino.close();
76
}
77
}
78
```
79
80
### Automatic Port Discovery
81
82
```java
83
import org.sintef.jarduino.comm.Serial4JArduino;
84
import java.util.HashSet;
85
import gnu.io.CommPortIdentifier;
86
87
public class PortDiscoveryExample {
88
public static void main(String[] args) {
89
// Get all available serial ports
90
HashSet<CommPortIdentifier> availablePorts = Serial4JArduino.getAvailableSerialPorts();
91
92
System.out.println("Available serial ports:");
93
for (CommPortIdentifier port : availablePorts) {
94
System.out.println("- " + port.getName());
95
}
96
97
// Interactive port selection (opens dialog)
98
String selectedPort = Serial4JArduino.selectSerialPort();
99
if (selectedPort != null) {
100
Serial4JArduino arduino = new Serial4JArduino(selectedPort);
101
// ... use arduino connection
102
}
103
}
104
}
105
```
106
107
### Custom Port Registration
108
109
```java
110
// Register custom serial port (useful for non-standard ports)
111
Serial4JArduino.registerPort("/dev/ttyUSB0"); // Linux
112
Serial4JArduino.registerPort("COM10"); // Windows
113
114
// Create connection to registered port
115
Serial4JArduino arduino = new Serial4JArduino("/dev/ttyUSB0");
116
```
117
118
### Command Line Usage
119
120
```bash
121
# Run the serial communication main method
122
java -cp jarduino-serial.jar org.sintef.jarduino.serial.Serial4JArduino
123
124
# The main method provides interactive serial port selection and basic testing
125
```
126
127
## Platform Support
128
129
The serial communication module includes native libraries for:
130
131
- **Windows**: 32-bit and 64-bit support
132
- **Linux**: x86, x64, ARM support
133
- **Mac OS X**: Universal binary support
134
135
Native libraries are automatically extracted and loaded at runtime through the `NativeLibUtil` class.
136
137
## Message Framing Protocol
138
139
Serial communication uses a binary framing protocol for reliable message transmission:
140
141
- **START_BYTE (0x12)**: Marks beginning of message
142
- **STOP_BYTE (0x13)**: Marks end of message
143
- **ESCAPE_BYTE (0x7D)**: Escapes special bytes in payload
144
145
This framing ensures message boundaries are correctly identified even with noisy serial connections or partial reads.
146
147
## Error Handling
148
149
The serial implementation handles common serial communication issues:
150
151
- **Port busy/in use**: Throws appropriate exceptions
152
- **Connection lost**: Observer pattern allows detection of communication failures
153
- **Message corruption**: Framing protocol enables detection and recovery
154
- **Cross-platform differences**: Native library abstraction handles OS-specific serial behavior
155
156
## Dependencies
157
158
- **RXTX Library**: `org.kevoree.extra.osgi.rxtx` for cross-platform serial port access
159
- **JArduino Core**: `org.sintef.jarduino.core` for protocol and message classes