0
# Core Protocol and Hardware Abstraction
1

2
The foundation of JArduino's Arduino communication system, providing hardware abstraction through enums and a protocol factory for creating Arduino command messages. This module defines the complete Arduino hardware model and protocol constants.
3

4
## Capabilities
5

6
### Arduino Hardware Enums
7

8
Strongly-typed enums for all Arduino hardware components providing type safety and easy pin identification.
9

10
```java { .api }
11
enum DigitalPin {
12
    PIN_0, PIN_1, PIN_2, PIN_3, PIN_4, PIN_5, PIN_6, PIN_7,
13
    PIN_8, PIN_9, PIN_10, PIN_11, PIN_12, PIN_13,
14
    A_0, A_1, A_2, A_3, A_4, A_5;
15

16
    byte getValue();
17
    static DigitalPin fromValue(byte b);
18
}
19

20
enum AnalogPin {
21
    A_0, A_1, A_2, A_3, A_4, A_5;
22

23
    byte getValue();
24
    static AnalogPin fromValue(byte b);
25
}
26

27
enum PWMPin {
28
    PWM_PIN_3, PWM_PIN_5, PWM_PIN_6, PWM_PIN_9, PWM_PIN_10, PWM_PIN_11;
29

30
    byte getValue();
31
    static PWMPin fromValue(byte b);
32
}
33

34
enum InterruptPin {
35
    PIN_2_INT0, PIN_3_INT1;
36

37
    byte getValue();
38
    static InterruptPin fromValue(byte b);
39
}
40
```
41

42
### Pin Configuration Enums
43

44
Configuration enums for Arduino pin modes, states, and settings.
45

46
```java { .api }
47
enum PinMode {
48
    INPUT, OUTPUT
49
}
50

51
enum DigitalState {
52
    LOW, HIGH
53
}
54

55
enum AnalogReference {
56
    DEFAULT, INTERNAL, EXTERNAL
57
}
58

59
enum InterruptTrigger {
60
    CHANGE, RISING, FALLING, LOW
61
}
62

63
enum JArduinoCom {
64
    Ethernet, Serial, AndroidBluetooth
65
}
66
```
67

68
### Protocol Command Factory
69

70
The main factory class for creating Arduino command messages. All Arduino operations are created through static methods that return `FixedSizePacket` objects.
71

72
```java { .api }
73
abstract class JArduinoProtocol {
74
    // Protocol constants
75
    static final byte PIN_MODE = 2;
76
    static final byte DIGITAL_READ = 4;
77
    static final byte DIGITAL_WRITE = 3;
78
    static final byte ANALOG_REFERENCE = 6;
79
    static final byte ANALOG_READ = 7;
80
    static final byte ANALOG_WRITE = 9;
81
    static final byte TONE = 10;
82
    static final byte NO_TONE = 11;
83
    static final byte PULSE_IN = 12;
84
    static final byte PING = 66;
85
    static final byte ATTACH_INTERRUPT = 21;
86
    static final byte DETACH_INTERRUPT = 22;
87
    static final byte EEPROM_READ = 31;
88
    static final byte EEPROM_SYNC_WRITE = 34;
89
    static final byte EEPROM_WRITE = 33;
90

91
    // Digital I/O commands
92
    static FixedSizePacket createPinMode(DigitalPin pin, PinMode mode);
93
    static FixedSizePacket createDigitalRead(DigitalPin pin);
94
    static FixedSizePacket createDigitalWrite(DigitalPin pin, DigitalState value);
95

96
    // Analog I/O commands
97
    static FixedSizePacket createAnalogReference(AnalogReference type);
98
    static FixedSizePacket createAnalogRead(AnalogPin pin);
99
    static FixedSizePacket createAnalogWrite(PWMPin pin, byte value);
100

101
    // Audio commands
102
    static FixedSizePacket createTone(DigitalPin pin, short frequency, short duration);
103
    static FixedSizePacket createNoTone(DigitalPin pin);
104

105
    // Timing commands
106
    static FixedSizePacket createPulseIn(DigitalPin pin, DigitalState state);
107

108
    // Communication commands
109
    static FixedSizePacket createPing();
110

111
    // Interrupt commands
112
    static FixedSizePacket createAttachInterrupt(InterruptPin interrupt, InterruptTrigger mode);
113
    static FixedSizePacket createDetachInterrupt(InterruptPin interrupt);
114

115
    // EEPROM commands
116
    static FixedSizePacket createEeprom_read(short address);
117
    static FixedSizePacket createEeprom_sync_write(short address, byte value);
118
    static FixedSizePacket createEeprom_write(short address, byte value);
119

120
    // Result factory methods
121
    static FixedSizePacket createDigitalReadResult(DigitalState value);
122
    static FixedSizePacket createAnalogReadResult(short value);
123
    static FixedSizePacket createPulseInResult(int value);
124
    static FixedSizePacket createPong();
125
    static FixedSizePacket createInterruptNotification(InterruptPin interrupt);
126
    static FixedSizePacket createEeprom_value(byte value);
127
    static FixedSizePacket createEeprom_write_ack();
128

129
    // Message parsing
130
    static FixedSizePacket createMessageFromPacket(byte[] packet);
131
}
132
```
133

134
### Base Message Class
135

136
Abstract base class for all protocol messages providing common functionality for message handling and serialization.
137

138
```java { .api }
139
abstract class FixedSizePacket {
140
    byte[] getPacket();
141
    String toString();
142
    static String toString(byte[] msg);
143

144
    void setSourceAddress(byte address);
145
    byte getSourceAddress();
146
    void setTargetAddress(byte address);
147
    byte getTargetAddress();
148
    void setFrameNumber(byte frame);
149
    byte getFrameNumber();
150
    void setLength(byte length);
151
    byte getLength();
152

153
    byte[] getRawData();
154
    void setRawData(byte[] ndata);
155
}
156
```
157

158
### Protocol Message Classes
159

160
Strongly-typed message classes for each Arduino operation, all extending `JArduinoProtocolPacket` which extends `FixedSizePacket`:
161

162
```java { .api }
163
// Command message classes
164
class PinModeMsg extends JArduinoProtocolPacket;
165
class DigitalReadMsg extends JArduinoProtocolPacket;
166
class DigitalWriteMsg extends JArduinoProtocolPacket;
167
class AnalogReadMsg extends JArduinoProtocolPacket;
168
class AnalogWriteMsg extends JArduinoProtocolPacket;
169
class AnalogReferenceMsg extends JArduinoProtocolPacket;
170
class ToneMsg extends JArduinoProtocolPacket;
171
class NoToneMsg extends JArduinoProtocolPacket;
172
class PulseInMsg extends JArduinoProtocolPacket;
173
class AttachInterruptMsg extends JArduinoProtocolPacket;
174
class DetachInterruptMsg extends JArduinoProtocolPacket;
175
class Eeprom_readMsg extends JArduinoProtocolPacket;
176
class Eeprom_writeMsg extends JArduinoProtocolPacket;
177
class Eeprom_sync_writeMsg extends JArduinoProtocolPacket;
178
class PingMsg extends JArduinoProtocolPacket;
179

180
// Result message classes
181
class DigitalReadResultMsg extends JArduinoProtocolPacket;
182
class AnalogReadResultMsg extends JArduinoProtocolPacket;
183
class PulseInResultMsg extends JArduinoProtocolPacket;
184
class PongMsg extends JArduinoProtocolPacket;
185
class InterruptNotificationMsg extends JArduinoProtocolPacket;
186
class Eeprom_valueMsg extends JArduinoProtocolPacket;
187
class Eeprom_write_ackMsg extends JArduinoProtocolPacket;
188

189
abstract class JArduinoProtocolPacket extends FixedSizePacket;
190
```
191

192
## Usage Examples
193

194
### Basic Pin Control
195

196
```java
197
// Set pin 13 as output
198
FixedSizePacket pinMode = JArduinoProtocol.createPinMode(DigitalPin.PIN_13, PinMode.OUTPUT);
199

200
// Turn on LED (write HIGH to pin 13)
201
FixedSizePacket digitalWrite = JArduinoProtocol.createDigitalWrite(DigitalPin.PIN_13, DigitalState.HIGH);
202

203
// Read digital value from pin 2
204
FixedSizePacket digitalRead = JArduinoProtocol.createDigitalRead(DigitalPin.PIN_2);
205
```
206

207
### Analog Operations
208

209
```java
210
// Set external analog reference
211
FixedSizePacket analogRef = JArduinoProtocol.createAnalogReference(AnalogReference.EXTERNAL);
212

213
// Read analog value from A0
214
FixedSizePacket analogRead = JArduinoProtocol.createAnalogRead(AnalogPin.A_0);
215

216
// Write PWM value (0-255) to pin 9
217
FixedSizePacket analogWrite = JArduinoProtocol.createAnalogWrite(PWMPin.PWM_PIN_9, (byte) 128);
218
```
219

220
### Message Parsing
221

222
```java
223
// Parse incoming message from Arduino
224
byte[] incomingData = // ... received from communication layer
225
FixedSizePacket parsedMessage = JArduinoProtocol.createMessageFromPacket(incomingData);
226
System.out.println("Received: " + parsedMessage.toString());
227
```