0
# Digital I/O Operations
1

2
Digital pin control for reading and writing binary states with support for input/output mode configuration and real-time change monitoring.
3

4
## Capabilities
5

6
### Pin Mode Configuration
7

8
Configure Arduino pins for input or output operations.
9

10
```javascript { .api }
11
/**
12
 * Set pin mode for digital I/O operations
13
 * Must be called before using digitalRead() or digitalWrite()
14
 * @param pin - Pin number (0-13 for most Arduino boards)
15
 * @param mode - Pin mode: ArduinoFirmata.INPUT (0) or ArduinoFirmata.OUTPUT (1), or boolean true/false
16
 * @param callback - Optional callback function called when mode is set
17
 */
18
pinMode(pin: number, mode: number|boolean, callback?: Function): void;
19
```
20

21
**Mode Values:**
22
- `ArduinoFirmata.INPUT` (0) or `false` - Configure pin as input
23
- `ArduinoFirmata.OUTPUT` (1) or `true` - Configure pin as output
24

25
**Usage Examples:**
26

27
```javascript
28
// Set pin as output using constant
29
arduino.pinMode(13, ArduinoFirmata.OUTPUT);
30

31
// Set pin as input using constant
32
arduino.pinMode(7, ArduinoFirmata.INPUT);
33

34
// Using boolean values
35
arduino.pinMode(13, true);  // Output
36
arduino.pinMode(7, false);  // Input
37

38
// With callback
39
arduino.pinMode(13, ArduinoFirmata.OUTPUT, function() {
40
  console.log('Pin 13 configured as output');
41
});
42
```
43

44
### Digital Output
45

46
Write binary values to Arduino output pins.
47

48
```javascript { .api }
49
/**
50
 * Write digital value to an output pin
51
 * Automatically sets pin mode to OUTPUT if not already configured
52
 * @param pin - Pin number to write to
53
 * @param value - Digital value: true/ArduinoFirmata.HIGH (1) or false/ArduinoFirmata.LOW (0)
54
 * @param callback - Optional callback function called when value is written
55
 */
56
digitalWrite(pin: number, value: boolean|number, callback?: Function): void;
57
```
58

59
**Value Options:**
60
- `true` or `ArduinoFirmata.HIGH` (1) - Set pin to high/on
61
- `false` or `ArduinoFirmata.LOW` (0) - Set pin to low/off
62

63
**Usage Examples:**
64

65
```javascript
66
// Turn on LED on pin 13
67
arduino.digitalWrite(13, true);
68

69
// Turn off LED on pin 13
70
arduino.digitalWrite(13, false);
71

72
// Using constants
73
arduino.digitalWrite(13, ArduinoFirmata.HIGH);
74
arduino.digitalWrite(13, ArduinoFirmata.LOW);
75

76
// With callback
77
arduino.digitalWrite(13, true, function() {
78
  console.log('LED turned on');
79
});
80

81
// Blinking LED example
82
let ledState = true;
83
setInterval(function() {
84
  arduino.digitalWrite(13, ledState);
85
  ledState = !ledState;
86
}, 500);
87
```
88

89
### Digital Input
90

91
Read binary values from Arduino input pins.
92

93
```javascript { .api }
94
/**
95
 * Read current digital value from an input pin
96
 * Pin must be configured as INPUT before reading
97
 * @param pin - Pin number to read from
98
 * @returns Current pin state: true (HIGH) or false (LOW)
99
 */
100
digitalRead(pin: number): boolean;
101
```
102

103
**Usage Examples:**
104

105
```javascript
106
// Configure pin 7 as input and read its value
107
arduino.pinMode(7, ArduinoFirmata.INPUT);
108
const buttonState = arduino.digitalRead(7);
109

110
if (buttonState) {
111
  console.log('Button is pressed (HIGH)');
112
} else {
113
  console.log('Button is not pressed (LOW)');
114
}
115

116
// Read multiple pins
117
for (let pin = 2; pin <= 7; pin++) {
118
  arduino.pinMode(pin, ArduinoFirmata.INPUT);
119
  const state = arduino.digitalRead(pin);
120
  console.log(`Pin ${pin}: ${state ? 'HIGH' : 'LOW'}`);
121
}
122
```
123

124
### Real-time Digital Change Monitoring
125

126
Monitor digital pin state changes in real-time using events.
127

128
```javascript { .api }
129
// Event: digitalChange
130
// Fired when a digital pin state changes
131
// Event object properties:
132
interface DigitalChangeEvent {
133
  pin: number;        // Pin number that changed
134
  value: boolean;     // New pin value (true = HIGH, false = LOW)
135
  old_value: boolean; // Previous pin value
136
}
137
```
138

139
**Usage Example:**
140

141
```javascript
142
// Configure pins as inputs for monitoring
143
arduino.pinMode(7, ArduinoFirmata.INPUT);
144
arduino.pinMode(8, ArduinoFirmata.INPUT);
145

146
// Listen for digital pin changes
147
arduino.on('digitalChange', function(event) {
148
  console.log(`Pin ${event.pin} changed from ${event.old_value ? 'HIGH' : 'LOW'} to ${event.value ? 'HIGH' : 'LOW'}`);
149

150
  // Example: Respond to button press on pin 7
151
  if (event.pin === 7 && event.value === true) {
152
    console.log('Button on pin 7 was pressed!');
153
    arduino.digitalWrite(13, true); // Turn on LED
154
  }
155

156
  // Example: Respond to button release on pin 7
157
  if (event.pin === 7 && event.value === false) {
158
    console.log('Button on pin 7 was released!');
159
    arduino.digitalWrite(13, false); // Turn off LED
160
  }
161
});
162
```
163

164
### Complete Digital I/O Example
165

166
```javascript
167
const ArduinoFirmata = require('arduino-firmata');
168
const arduino = new ArduinoFirmata();
169

170
arduino.connect();
171

172
arduino.on('connect', function() {
173
  console.log('Arduino connected');
174

175
  // Setup: Configure pins
176
  arduino.pinMode(13, ArduinoFirmata.OUTPUT); // LED output
177
  arduino.pinMode(7, ArduinoFirmata.INPUT);   // Button input
178

179
  // Monitor button state changes
180
  arduino.on('digitalChange', function(event) {
181
    if (event.pin === 7) {
182
      // Mirror button state to LED
183
      arduino.digitalWrite(13, event.value);
184
      console.log(`Button ${event.value ? 'pressed' : 'released'}, LED turned ${event.value ? 'on' : 'off'}`);
185
    }
186
  });
187

188
  // Initial LED blink to show connection
189
  setTimeout(() => {
190
    arduino.digitalWrite(13, true);
191
    setTimeout(() => arduino.digitalWrite(13, false), 500);
192
  }, 100);
193
});
194
```
195

196
## Constants
197

198
```javascript { .api }
199
// Pin modes for digital I/O
200
ArduinoFirmata.INPUT = 0;   // Configure pin as input
201
ArduinoFirmata.OUTPUT = 1;  // Configure pin as output
202

203
// Digital values
204
ArduinoFirmata.LOW = 0;     // Digital low/off state
205
ArduinoFirmata.HIGH = 1;    // Digital high/on state
206
```
207

208
## Pin Numbering
209

210
Digital pins are typically numbered from 0 to 13 on most Arduino boards:
211

212
- **Pins 0-1**: Usually reserved for serial communication (RX/TX)
213
- **Pins 2-12**: General purpose digital I/O pins
214
- **Pin 13**: Often has a built-in LED, commonly used for status indication
215
- **Pins 14-19** (A0-A5): Analog pins that can also be used as digital pins
216

217
## Digital Pin Capabilities
218

219
Each digital pin can be configured as either input or output:
220

221
- **Input mode**: Pin reads digital signals (0V = LOW/false, 5V = HIGH/true)
222
- **Output mode**: Pin can drive digital signals (LOW = 0V, HIGH = 5V)
223
- **Pull-up resistors**: Internal pull-up resistors are handled by the Arduino firmware
224

225
## Event System Integration
226

227
Digital I/O operations integrate with the event system for real-time monitoring. See [Event System](./events.md) for complete event documentation including:
228

229
- Setup requirements for event monitoring
230
- Event handler registration
231
- Digital change event details