0
# Serial Communication
1

2
The `PanamaHitek_Arduino` class provides comprehensive serial communication functionality for connecting Java applications to Arduino devices. It supports configurable connection parameters, multiple communication modes, and port management utilities.
3

4
## Core Communication Class
5

6
```java { .api }
7
public class PanamaHitek_Arduino {
8
    public PanamaHitek_Arduino();
9
}
10
```
11

12
Creates a new Arduino communication object and displays library credits.
13

14
## Connection Configuration
15

16
Configure serial port parameters before establishing a connection:
17

18
```java { .api }
19
public void setParity(int input_Parity);
20
public void setByteSize(int Bytes);
21
public void setStopBits(int Bits);
22
public void setTimeOut(int time);
23
```
24

25
**Parameters:**
26
- `setParity(int)` - Sets parity: 0=None, 1=Odd, 2=Even, 3=Mark, 4=Space
27
- `setByteSize(int)` - Sets byte size: 5-8 bits
28
- `setStopBits(int)` - Sets stop bits: 1-3
29
- `setTimeOut(int)` - Sets timeout in milliseconds
30

31
**Usage Example:**
32

33
```java
34
PanamaHitek_Arduino arduino = new PanamaHitek_Arduino();
35
arduino.setParity(0);      // No parity
36
arduino.setByteSize(8);    // 8 data bits
37
arduino.setStopBits(1);    // 1 stop bit
38
arduino.setTimeOut(2000);  // 2 second timeout
39
```
40

41
## Connection Modes
42

43
### TX-Only (Send Data Only)
44

45
Establishes a transmit-only connection for sending data to Arduino:
46

47
```java { .api }
48
public void arduinoTX(String PORT_NAME, int DATA_RATE) throws ArduinoException;
49
```
50

51
**Parameters:**
52
- `PORT_NAME` - Serial port name (e.g., "COM3", "/dev/ttyUSB0")
53
- `DATA_RATE` - Baud rate (e.g., 9600, 115200)
54

55
**Usage Example:**
56

57
```java
58
try {
59
    arduino.arduinoTX("COM3", 9600);
60
    arduino.sendData("Hello Arduino");
61
} catch (ArduinoException ex) {
62
    System.err.println("Connection failed: " + ex.getMessage());
63
}
64
```
65

66
### RX-Only (Receive Data Only)
67

68
Establishes a receive-only connection with event-driven data reception:
69

70
```java { .api }
71
public void arduinoRX(String PORT_NAME, int DATA_RATE, SerialPortEventListener events)
72
    throws ArduinoException, SerialPortException;
73
```
74

75
**Parameters:**
76
- `PORT_NAME` - Serial port name
77
- `DATA_RATE` - Baud rate
78
- `events` - SerialPortEventListener for handling incoming data
79

80
**Usage Example:**
81

82
```java
83
import jssc.SerialPortEvent;
84
import jssc.SerialPortEventListener;
85
import jssc.SerialPortException;
86

87
SerialPortEventListener listener = new SerialPortEventListener() {
88
    @Override
89
    public void serialEvent(SerialPortEvent event) {
90
        try {
91
            if (arduino.isMessageAvailable()) {
92
                String message = arduino.printMessage();
93
                System.out.println("Received: " + message);
94
            }
95
        } catch (SerialPortException | ArduinoException ex) {
96
            ex.printStackTrace();
97
        }
98
    }
99
};
100

101
arduino.arduinoRX("COM3", 9600, listener);
102
```
103

104
### Bidirectional (Send and Receive)
105

106
Establishes a full-duplex connection for both sending and receiving data:
107

108
```java { .api }
109
public void arduinoRXTX(String PORT_NAME, int DATA_RATE, SerialPortEventListener events)
110
    throws ArduinoException;
111
```
112

113
**Parameters:**
114
- `PORT_NAME` - Serial port name
115
- `DATA_RATE` - Baud rate
116
- `events` - SerialPortEventListener for handling incoming data
117

118
**Usage Example:**
119

120
```java
121
arduino.arduinoRXTX("COM3", 9600, listener);
122

123
// Send data
124
arduino.sendData("GET_SENSOR_DATA");
125

126
// Receive data handled by event listener
127
```
128

129
## Data Transmission
130

131
### Send String Data
132

133
```java { .api }
134
public void sendData(String data) throws ArduinoException, SerialPortException;
135
```
136

137
Sends string data to the Arduino. Can only be used with `arduinoTX()` or `arduinoRXTX()` connections.
138

139
**Usage Example:**
140

141
```java
142
arduino.sendData("LED_ON");
143
arduino.sendData("SERVO_90");
144
arduino.sendData("SENSOR_READ");
145
```
146

147
### Send Byte Data
148

149
```java { .api }
150
public void sendByte(int data) throws ArduinoException, SerialPortException;
151
```
152

153
Sends a single byte value (0-255) to Arduino.
154

155
**Usage Example:**
156

157
```java
158
arduino.sendByte(255);  // Send maximum byte value
159
arduino.sendByte(0);    // Send minimum byte value
160
arduino.sendByte(127);  // Send middle value
161
```
162

163
## Data Reception
164

165
### Receive Raw Data
166

167
```java { .api }
168
public byte[] receiveData() throws ArduinoException, SerialPortException;
169
```
170

171
Receives raw byte data from Arduino. Can only be used with `arduinoRX()` or `arduinoRXTX()` connections.
172

173
### Check Message Availability
174

175
```java { .api }
176
public boolean isMessageAvailable() throws SerialPortException, ArduinoException;
177
```
178

179
Checks if a complete message is available for reading.
180

181
### Get Message as String
182

183
```java { .api }
184
public String printMessage() throws SerialPortException, ArduinoException;
185
```
186

187
Retrieves the received message as a string.
188

189
**Usage Example:**
190

191
```java
192
if (arduino.isMessageAvailable()) {
193
    String message = arduino.printMessage();
194
    System.out.println("Arduino says: " + message);
195
}
196
```
197

198
## Port Management
199

200
### Get Available Ports
201

202
```java { .api }
203
public int getPortsAvailable();
204
public List<String> getSerialPorts();
205
```
206

207
**Usage Example:**
208

209
```java
210
int portCount = arduino.getPortsAvailable();
211
List<String> ports = arduino.getSerialPorts();
212

213
System.out.println("Available ports: " + portCount);
214
for (String port : ports) {
215
    System.out.println("- " + port);
216
}
217
```
218

219
### Buffer Management
220

221
```java { .api }
222
public int getInputBytesAvailable() throws SerialPortException;
223
public void flushSerialPort() throws SerialPortException;
224
```
225

226
**Usage Example:**
227

228
```java
229
// Check buffer status
230
int bytesAvailable = arduino.getInputBytesAvailable();
231
System.out.println("Bytes in buffer: " + bytesAvailable);
232

233
// Clear buffers
234
arduino.flushSerialPort();
235
```
236

237
### Event Listener Management
238

239
```java { .api }
240
public SerialPortEventListener getEventListener() throws ArduinoException;
241
```
242

243
Retrieves the currently registered event listener.
244

245
## Connection Termination
246

247
```java { .api }
248
public void killArduinoConnection() throws ArduinoException;
249
```
250

251
Properly terminates the Arduino connection and releases system resources.
252

253
**Usage Example:**
254

255
```java
256
try {
257
    arduino.killArduinoConnection();
258
    System.out.println("Connection terminated successfully");
259
} catch (ArduinoException ex) {
260
    System.err.println("Error terminating connection: " + ex.getMessage());
261
}
262
```
263

264
## Complete Example
265

266
```java
267
import com.panamahitek.PanamaHitek_Arduino;
268
import com.panamahitek.ArduinoException;
269
import jssc.*;
270

271
public class ArduinoSerialExample {
272
    private PanamaHitek_Arduino arduino;
273

274
    public void setup() {
275
        arduino = new PanamaHitek_Arduino();
276

277
        // Configure connection parameters
278
        arduino.setParity(0);
279
        arduino.setByteSize(8);
280
        arduino.setStopBits(1);
281
        arduino.setTimeOut(2000);
282

283
        try {
284
            // Establish bidirectional connection
285
            arduino.arduinoRXTX("COM3", 9600, new SerialPortEventListener() {
286
                @Override
287
                public void serialEvent(SerialPortEvent event) {
288
                    if (event.isRXCHAR() && event.getEventValue() > 0) {
289
                        try {
290
                            if (arduino.isMessageAvailable()) {
291
                                String message = arduino.printMessage();
292
                                System.out.println("Received: " + message);
293

294
                                // Echo back to Arduino
295
                                arduino.sendData("ECHO: " + message);
296
                            }
297
                        } catch (SerialPortException | ArduinoException ex) {
298
                            ex.printStackTrace();
299
                        }
300
                    }
301
                }
302
            });
303

304
            // Send initial command
305
            arduino.sendData("START");
306

307
        } catch (ArduinoException ex) {
308
            System.err.println("Setup failed: " + ex.getMessage());
309
        }
310
    }
311

312
    public void cleanup() {
313
        try {
314
            arduino.killArduinoConnection();
315
        } catch (ArduinoException ex) {
316
            System.err.println("Cleanup error: " + ex.getMessage());
317
        }
318
    }
319
}
320
```