0
# JArduino
1

2
A comprehensive Java library for interfacing with Arduino boards through serial, Bluetooth, and Ethernet connections. JArduino provides complete control over Arduino hardware including digital/analog I/O, PWM, interrupts, EEPROM operations, and tone generation, with both programmatic APIs and interactive GUI components.
3

4
## Package Information
5

6
- **Package Name**: org.sintef.jarduino
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Installation**: Add to your `pom.xml`:
10

11
```xml
12
<dependency>
13
    <groupId>org.sintef.jarduino</groupId>
14
    <artifactId>org.sintef.jarduino.core</artifactId>
15
    <version>0.1.7-SNAPSHOT</version>
16
</dependency>
17
<!-- For serial communication -->
18
<dependency>
19
    <groupId>org.sintef.jarduino</groupId>
20
    <artifactId>org.sintef.jarduino.serial</artifactId>
21
    <version>0.1.7-SNAPSHOT</version>
22
</dependency>
23
<!-- For GUI components -->
24
<dependency>
25
    <groupId>org.sintef.jarduino</groupId>
26
    <artifactId>org.sintef.jarduino.gui</artifactId>
27
    <version>0.1.7-SNAPSHOT</version>
28
</dependency>
29
<!-- For Bluetooth on Android -->
30
<dependency>
31
    <groupId>org.sintef.jarduino</groupId>
32
    <artifactId>org.sintef.jarduino.bluetooth</artifactId>
33
    <version>0.1.7-SNAPSHOT</version>
34
</dependency>
35
```
36

37
## Core Imports
38

39
```java
40
import org.sintef.jarduino.*;
41
import org.sintef.jarduino.JArduinoProtocol;
42
import org.sintef.jarduino.comm.Serial4JArduino;
43
import org.sintef.jarduino.observer.JArduinoObserver;
44
```
45

46
## Basic Usage
47

48
```java
49
import org.sintef.jarduino.*;
50

51
// Create Arduino program by extending JArduino
52
public class BlinkExample extends JArduino {
53

54
    // Constructor with serial port
55
    public BlinkExample(String port) {
56
        super(port);
57
    }
58

59
    // Setup method called once when program starts
60
    @Override
61
    protected void setup() {
62
        // Initialize pin 13 as output for LED
63
        pinMode(DigitalPin.PIN_13, PinMode.OUTPUT);
64
    }
65

66
    // Loop method called repeatedly while program runs
67
    @Override
68
    protected void loop() {
69
        // Turn LED on
70
        digitalWrite(DigitalPin.PIN_13, DigitalState.HIGH);
71
        delay(1000); // Wait 1 second
72

73
        // Turn LED off
74
        digitalWrite(DigitalPin.PIN_13, DigitalState.LOW);
75
        delay(1000); // Wait 1 second
76
    }
77

78
    public static void main(String[] args) {
79
        // Create and start Arduino program
80
        JArduino arduino = new BlinkExample("COM3");
81
        arduino.runArduinoProcess();
82
    }
83
}
84
```
85

86
## Architecture
87

88
JArduino uses a layered architecture with clear separation of concerns:
89

90
- **Protocol Layer**: `JArduinoProtocol` provides a factory for creating Arduino command messages as `FixedSizePacket` objects
91
- **Communication Layer**: Different transport implementations (`Serial4JArduino`, `AndroidBluetooth4JArduino`, `Udp4JArduino`) handle Arduino communication
92
- **Observer Pattern**: `JArduinoObserver`/`JArduinoSubject` interfaces enable asynchronous message handling
93
- **Message System**: Strongly-typed message classes for each Arduino operation with automatic serialization
94
- **GUI Layer**: Swing-based interactive components for visual Arduino control and monitoring
95

96
The protocol uses binary messaging with start/stop bytes and escape sequences for reliable communication across all transport types.
97

98
## Capabilities
99

100
### Main Arduino API
101

102
Core JArduino programming interface providing Arduino-like methods for pin control, analog I/O, timing, and advanced features. This is the primary API users interact with by extending the JArduino class.
103

104
```java { .api }
105
// Main JArduino class - extend this for Arduino programs
106
abstract class JArduino extends AbstractJArduino {
107
    // Constructors
108
    JArduino();                                    // Default serial
109
    JArduino(String id);                           // Serial with ID
110
    JArduino(String id, JArduinoCom com);         // Custom communication
111
    JArduino(JArduinoCom com);                     // Communication only
112
    JArduino(String id, JArduinoCom com, ProtocolConfiguration prot);
113

114
    // Abstract methods to implement
115
    protected abstract void setup();               // Called once at start
116
    protected abstract void loop();                // Called repeatedly
117
    protected void interrupt0();                   // Override for interrupt handling
118
    protected void interrupt1();                   // Override for interrupt handling
119

120
    // Process control
121
    void runArduinoProcess();                      // Start the Arduino program
122
    void stopArduinoProcess();                     // Stop the Arduino program
123

124
    // Timing utilities
125
    void delay(long millis);                       // Sleep for milliseconds
126
    int map(int value, int l, int h, int nl, int nh); // Map value between ranges
127
}
128

129
// Inherited methods from AbstractJArduino available in JArduino
130
abstract class AbstractJArduino {
131
    // Digital pin operations
132
    void pinMode(DigitalPin pin, PinMode mode);
133
    void digitalWrite(DigitalPin pin, DigitalState value);
134
    DigitalState digitalRead(DigitalPin pin);      // Synchronous read with timeout
135

136
    // Analog operations
137
    void analogReference(AnalogReference type);
138
    short analogRead(AnalogPin pin);               // Synchronous read with timeout
139
    void analogWrite(PWMPin pin, byte value);      // PWM output 0-255
140

141
    // Advanced digital features
142
    void tone(DigitalPin pin, short frequency, short duration);
143
    void noTone(DigitalPin pin);
144
    int pulseIn(DigitalPin pin, DigitalState state, long timeout);
145

146
    // Interrupt handling
147
    void attachInterrupt(InterruptPin interrupt, InterruptTrigger mode);
148
    void detachInterrupt(InterruptPin interrupt);
149

150
    // EEPROM operations
151
    byte eeprom_read(short address);               // Synchronous read with timeout
152
    void eeprom_write(short address, byte value);  // Asynchronous write
153
    boolean eeprom_sync_write(short address, byte value); // Synchronous write with ack
154

155
    // Communication testing
156
    boolean ping();                                // Test Arduino connection with timeout
157
}
158

159
// Communication types
160
enum JArduinoCom { Serial, Ethernet, AndroidBluetooth }
161
```
162

163
### Core Protocol and Hardware Abstraction
164

165
Foundation protocol factory and Arduino hardware abstraction including pin definitions, states, and command creation. Essential for all Arduino communication.
166

167
```java { .api }
168
// Arduino hardware enums - complete definitions
169
enum DigitalPin {
170
    PIN_0, PIN_1, PIN_2, PIN_3, PIN_4, PIN_5, PIN_6, PIN_7,
171
    PIN_8, PIN_9, PIN_10, PIN_11, PIN_12, PIN_13,
172
    A_0, A_1, A_2, A_3, A_4, A_5;
173
    byte getValue();
174
    static DigitalPin fromValue(byte b);
175
}
176

177
enum AnalogPin {
178
    A_0, A_1, A_2, A_3, A_4, A_5;
179
    byte getValue();
180
    static AnalogPin fromValue(byte b);
181
}
182

183
enum PWMPin {
184
    PWM_PIN_3, PWM_PIN_5, PWM_PIN_6, PWM_PIN_9, PWM_PIN_10, PWM_PIN_11;
185
    byte getValue();
186
    static PWMPin fromValue(byte b);
187
}
188

189
enum PinMode {
190
    INPUT, OUTPUT;
191
    byte getValue();
192
    static PinMode fromValue(byte b);
193
}
194

195
enum DigitalState {
196
    LOW, HIGH;
197
    byte getValue();
198
    static DigitalState fromValue(byte b);
199
}
200

201
enum AnalogReference {
202
    DEFAULT, INTERNAL, EXTERNAL;
203
    byte getValue();
204
    static AnalogReference fromValue(byte b);
205
}
206

207
enum InterruptPin {
208
    PIN_2_INT0, PIN_3_INT1;
209
    byte getValue();
210
    static InterruptPin fromValue(byte b);
211
}
212

213
enum InterruptTrigger {
214
    CHANGE, RISING, FALLING, LOW;
215
    byte getValue();
216
    static InterruptTrigger fromValue(byte b);
217
}
218

219
// Main protocol factory
220
class JArduinoProtocol {
221
    static FixedSizePacket createPinMode(DigitalPin pin, PinMode mode);
222
    static FixedSizePacket createDigitalWrite(DigitalPin pin, DigitalState value);
223
    static FixedSizePacket createDigitalRead(DigitalPin pin);
224
    static FixedSizePacket createAnalogRead(AnalogPin pin);
225
    static FixedSizePacket createAnalogWrite(PWMPin pin, byte value);
226
}
227
```
228

229
[Core Protocol](./core-protocol.md)
230

231
### Serial Communication
232

233
Serial port communication for connecting to Arduino boards over USB or RS-232. Provides automatic port discovery and cross-platform native library support.
234

235
```java { .api }
236
class Serial4JArduino implements JArduinoClientObserver, JArduinoSubject {
237
    Serial4JArduino(String port);
238
    void receiveMsg(byte[] msg);
239
    void register(JArduinoObserver observer);
240
    void close();
241
    static HashSet<CommPortIdentifier> getAvailableSerialPorts();
242
    static String selectSerialPort();
243
}
244
```
245

246
[Serial Communication](./serial-communication.md)
247

248
### Bluetooth Communication
249

250
Android Bluetooth communication enabling Arduino control from mobile applications. Supports automatic device pairing and connection management.
251

252
```java { .api }
253
class AndroidBluetooth4JArduino implements JArduinoClientObserver, JArduinoSubject, Runnable {
254
    AndroidBluetooth4JArduino(AndroidBluetoothConfiguration config);
255
    void setAndroidBluetoothSocket(BluetoothSocket socket);
256
    void receiveMsg(byte[] msg);
257
    void register(JArduinoObserver observer);
258
    void run();
259
    void close();
260
}
261
```
262

263
[Bluetooth Communication](./bluetooth-communication.md)
264

265
### Interactive GUI Components
266

267
Swing-based graphical components for interactive Arduino control with visual pin layouts, control panels, and real-time monitoring capabilities.
268

269
```java { .api }
270
class InteractiveJArduinoDataControllerClientAdvanced implements JArduinoObserver, JArduinoClientSubject {
271
    void sendpinMode(PinMode mode, DigitalPin pin);
272
    void senddigitalWrite(DigitalPin pin, DigitalState value);
273
    void senddigitalRead(DigitalPin pin);
274
    void sendanalogRead(AnalogPin pin);
275
    void sendanalogWrite(PWMPin pin, byte value);
276
    void sendping();
277
}
278
```
279

280
[GUI Components](./gui-components.md)
281

282
### Message Handling and Observers
283

284
Observer pattern implementation for asynchronous Arduino message handling with strongly-typed message classes and automatic parsing.
285

286
```java { .api }
287
interface JArduinoObserver {
288
    void receiveMsg(byte[] msg);
289
}
290

291
interface IJArduinoMessageHandler {
292
    void handleDigitalReadResult(DigitalReadResultMsg msg);
293
    void handleAnalogReadResult(AnalogReadResultMsg msg);
294
    void handlePong(PongMsg msg);
295
    void handleInterruptNotification(InterruptNotificationMsg msg);
296
}
297
```
298

299
[Message Handling](./message-handling.md)
300

301
### Advanced Arduino Features
302

303
Specialized Arduino functionality including interrupts, tone generation, pulse measurement, and EEPROM operations for advanced hardware control.
304

305
```java { .api }
306
// Advanced protocol operations - typically used through JArduino methods
307
static FixedSizePacket createAttachInterrupt(InterruptPin interrupt, InterruptTrigger mode);
308
static FixedSizePacket createDetachInterrupt(InterruptPin interrupt);
309
static FixedSizePacket createTone(DigitalPin pin, short frequency, short duration);
310
static FixedSizePacket createNoTone(DigitalPin pin);
311
static FixedSizePacket createPulseIn(DigitalPin pin, DigitalState state);
312
static FixedSizePacket createEeprom_read(short address);
313
static FixedSizePacket createEeprom_write(short address, byte value);
314
static FixedSizePacket createEeprom_sync_write(short address, byte value);
315
static FixedSizePacket createPing();
316
```
317

318
[Advanced Features](./advanced-features.md)
319

320
## Types
321

322
```java { .api }
323
// Core protocol packet for Arduino communication
324
abstract class FixedSizePacket {
325
    byte[] getPacket();                            // Get binary packet data
326
    String toString();                             // String representation
327
    void setSourceAddress(byte address);           // Set source address
328
    byte getSourceAddress();                       // Get source address
329
    void setTargetAddress(byte address);           // Set target address
330
    byte getTargetAddress();                       // Get target address
331
    byte[] getRawData();                           // Get raw packet data
332
}
333

334
// Configuration classes
335
abstract class ProtocolConfiguration {
336
    // Base configuration class
337
}
338

339
class AndroidBluetoothConfiguration extends ProtocolConfiguration {
340
    AndroidBluetoothConfiguration(BluetoothSocket socket);
341
    BluetoothSocket getmSocket();
342
}
343

344
// Observer pattern interfaces for message handling
345
interface JArduinoObserver {
346
    void receiveMsg(byte[] msg);
347
}
348

349
interface JArduinoSubject {
350
    void register(JArduinoObserver observer);
351
    void unregister(JArduinoObserver observer);
352
}
353

354
interface JArduinoClientObserver extends JArduinoObserver {
355
    // Client-specific observer interface
356
}
357
```