0
# Board Pin Definitions
1

2
Platform-specific pin mappings and hardware interfaces with automatic detection and configuration for 100+ supported development boards. Provides CircuitPython-compatible pin definitions and singleton interfaces with standardized naming conventions across diverse hardware platforms.
3

4
## Capabilities
5

6
### Pin Constants
7

8
Board-specific pin definitions that provide standardized names for GPIO pins, communication interfaces, and specialized functions. Pin constants are automatically imported based on detected hardware platform.
9

10
```python { .api }
11
# Digital GPIO pins (board-specific availability)
12
D0: Pin          # Digital pin 0
13
D1: Pin          # Digital pin 1
14
D2: Pin          # Digital pin 2
15
# ... (continues up to board-specific maximum)
16

17
# I2C pins (if available)
18
SDA: Pin         # I2C data line
19
SCL: Pin         # I2C clock line
20

21
# SPI pins (if available)
22
MOSI: Pin        # SPI Master Out Slave In
23
MISO: Pin        # SPI Master In Slave Out
24
SCLK: Pin        # SPI clock
25
SCK: Pin         # SPI clock (alias)
26
CE0: Pin         # SPI chip enable 0
27
CE1: Pin         # SPI chip enable 1
28

29
# UART pins (if available)  
30
TX: Pin          # UART transmit
31
RX: Pin          # UART receive
32
TXD: Pin         # UART transmit (alias)
33
RXD: Pin         # UART receive (alias)
34

35
# Analog pins (platform-dependent)
36
A0: Pin          # Analog input 0
37
A1: Pin          # Analog input 1
38
# ... (if supported by platform)
39
```
40

41
### Singleton Interface Functions
42

43
Pre-configured communication interfaces using default pin assignments. Automatically use board-appropriate pins for I2C and SPI communication.
44

45
```python { .api }
46
def I2C() -> busio.I2C:
47
    """
48
    Return default I2C interface using board's SDA and SCL pins.
49
    
50
    Returns:
51
        busio.I2C: Pre-configured I2C interface
52
    
53
    Raises:
54
        AttributeError: If SDA/SCL pins not available on this board
55
    """
56

57
def SPI() -> busio.SPI:
58
    """
59
    Return default SPI interface using board's SCLK, MOSI, and MISO pins.
60
    
61
    Returns:
62
        busio.SPI: Pre-configured SPI interface
63
    
64
    Raises:
65
        AttributeError: If SPI pins not available on this board
66
    """
67
```
68

69
### Board Identification
70

71
Constants that provide information about the Blinka library and board detection.
72

73
```python { .api }
74
__version__: str = "0.0.0+auto.0"       # Blinka version string
75
__repo__: str = "https://github.com/adafruit/Adafruit_Blinka.git"  # Repository URL
76
__blinka__: bool = True                  # Always True for Blinka identification
77
```
78

79
## Usage Examples
80

81
### Basic Pin Usage
82

83
```python
84
import board
85
import digitalio
86

87
# Use board-specific pin definitions
88
led = digitalio.DigitalInOut(board.D18)
89
led.direction = digitalio.Direction.OUTPUT
90

91
button = digitalio.DigitalInOut(board.D2)
92
button.direction = digitalio.Direction.INPUT
93
button.pull = digitalio.Pull.UP
94

95
# Read button and control LED
96
led.value = not button.value  # Inverted due to pull-up
97

98
# Cleanup
99
led.deinit()
100
button.deinit()
101
```
102

103
### Default I2C Interface
104

105
```python
106
import board
107
import time
108

109
# Use board's default I2C interface
110
i2c = board.I2C()
111

112
# Scan for devices
113
with i2c:
114
    devices = i2c.scan()
115
    print(f"I2C devices found: {[hex(d) for d in devices]}")
116

117
# Equivalent manual configuration
118
# i2c = busio.I2C(board.SCL, board.SDA)
119

120
i2c.deinit()
121
```
122

123
### Default SPI Interface
124

125
```python
126
import board
127
import digitalio
128

129
# Use board's default SPI interface
130
spi = board.SPI()
131

132
# Setup chip select
133
cs = digitalio.DigitalInOut(board.D5)
134
cs.direction = digitalio.Direction.OUTPUT
135
cs.value = True
136

137
# Use SPI with manual locking
138
while not spi.try_lock():
139
    pass
140

141
try:
142
    spi.configure(baudrate=1000000)
143
    
144
    # Communicate with device
145
    cs.value = False
146
    spi.write(b'\x01\x02\x03')
147
    cs.value = True
148
    
149
finally:
150
    spi.unlock()
151

152
# Cleanup
153
spi.deinit()
154
cs.deinit()
155
```
156

157
### Pin Availability Checking
158

159
```python
160
import board
161

162
# Check for I2C availability
163
if hasattr(board, 'SDA') and hasattr(board, 'SCL'):
164
    print("I2C pins available")
165
    print(f"SDA: {board.SDA}, SCL: {board.SCL}")
166
    
167
    # Use default I2C
168
    i2c = board.I2C()
169
    # ... use I2C
170
    i2c.deinit()
171
else:
172
    print("I2C not available on this board")
173

174
# Check for SPI availability  
175
if hasattr(board, 'SCLK') and hasattr(board, 'MOSI') and hasattr(board, 'MISO'):
176
    print("SPI pins available")
177
    print(f"SCLK: {board.SCLK}, MOSI: {board.MOSI}, MISO: {board.MISO}")
178
    
179
    # Use default SPI
180
    spi = board.SPI()
181
    # ... use SPI
182
    spi.deinit()
183
else:
184
    print("SPI not available on this board")
185

186
# Check for analog pins
187
analog_pins = [attr for attr in dir(board) if attr.startswith('A') and attr[1:].isdigit()]
188
if analog_pins:
189
    print(f"Analog pins available: {analog_pins}")
190
else:
191
    print("No analog pins available on this board")
192
```
193

194
### Platform-Specific Pin Examples
195

196
```python
197
import board
198

199
# Common pin usage patterns across platforms
200
def setup_common_pins():
201
    pins = {}
202
    
203
    # Try to setup LED (common pin numbers)
204
    for pin_name in ['D18', 'D13', 'D2', 'D25']:
205
        if hasattr(board, pin_name):
206
            pins['led'] = getattr(board, pin_name)
207
            break
208
    
209
    # Try to setup button
210
    for pin_name in ['D2', 'D0', 'D16']:
211
        if hasattr(board, pin_name) and pin_name != pins.get('led'):
212
            pins['button'] = getattr(board, pin_name)
213
            break
214
    
215
    return pins
216

217
# Get available pins for this board
218
available_pins = setup_common_pins()
219
print(f"Available pins: {available_pins}")
220

221
# Use pins if available
222
if 'led' in available_pins:
223
    import digitalio
224
    led = digitalio.DigitalInOut(available_pins['led'])
225
    led.direction = digitalio.Direction.OUTPUT
226
    # ... use LED
227
    led.deinit()
228
```
229

230
### Multiple SPI Buses
231

232
```python
233
import board
234
import busio
235

236
# Some boards support multiple SPI buses
237
# Primary SPI bus
238
spi0 = board.SPI()  # Uses SCLK, MOSI, MISO
239

240
# Secondary SPI bus (if available)
241
if hasattr(board, 'SCLK_1') and hasattr(board, 'MOSI_1') and hasattr(board, 'MISO_1'):
242
    spi1 = busio.SPI(board.SCLK_1, board.MOSI_1, board.MISO_1)
243
    print("Secondary SPI bus available")
244
    # ... use secondary SPI
245
    spi1.deinit()
246
else:
247
    print("Only primary SPI bus available")
248

249
spi0.deinit()
250
```
251

252
### Board Information
253

254
```python
255
import board
256
from adafruit_blinka.agnostic import board_id, detector
257

258
# Board identification
259
print(f"Blinka version: {board.__version__}")
260
print(f"Repository: {board.__repo__}")
261
print(f"Is Blinka: {board.__blinka__}")
262

263
# Platform detection information
264
print(f"Board ID: {board_id}")
265
print(f"Chip ID: {detector.chip.id}")
266

267
# List all available pins
268
pins = [attr for attr in dir(board) if not attr.startswith('_') and 
269
        attr not in ['I2C', 'SPI', '__version__', '__repo__', '__blinka__']]
270
print(f"Available pins: {sorted(pins)}")
271

272
# Categorize pins
273
digital_pins = [p for p in pins if p.startswith('D') and p[1:].isdigit()]
274
analog_pins = [p for p in pins if p.startswith('A') and p[1:].isdigit()]
275
special_pins = [p for p in pins if p not in digital_pins + analog_pins]
276

277
print(f"Digital pins: {sorted(digital_pins)}")
278
print(f"Analog pins: {sorted(analog_pins)}")
279
print(f"Special pins: {sorted(special_pins)}")
280
```
281

282
## Platform Considerations
283

284
### Supported Board Categories
285

286
**Single Board Computers:**
287
- **Raspberry Pi**: All models from Pi 1 to Pi 5, including Compute Modules
288
- **BeagleBone**: Black, Blue, Green, AI, PocketBeagle variants
289
- **Orange Pi**: Full range including Zero, PC, 4, 5 series
290
- **Banana Pi**: M2, M4, M5, F3, F5, AI series
291
- **Rock Pi**: 3A, 3C, 4, 5, S, E variants
292
- **Jetson**: TX1, TX2, Xavier, Nano, NX, Orin series
293
- **Odroid**: C2, C4, N2, M1/M1S, XU4
294

295
**Development Boards:**
296
- **FTDI Adapters**: FT232H, FT2232H, FT4232H for USB-to-GPIO
297
- **Microchip**: MCP2221 USB-to-GPIO converter
298
- **Binho Nova**: Multi-protocol USB adapter
299
- **GreatFET One**: USB analysis and hacking tool
300

301
**Specialized Platforms:**
302
- **RP2040 via U2IF**: Pico, Feather, QT Py, ItsyBitsy, MacroPad variants
303
- **Coral**: Edge TPU development boards
304
- **UDOO**: x86 boards with Arduino-compatible GPIO
305

306
### Pin Naming Conventions
307

308
**Standard Digital Pins**: `D0`, `D1`, `D2`, ... (board-specific maximum)
309

310
**Communication Pins**:
311
- I2C: `SDA`, `SCL`
312
- SPI: `MOSI`, `MISO`, `SCLK`/`SCK`, `CE0`, `CE1`
313
- UART: `TX`/`TXD`, `RX`/`RXD`
314

315
**Analog Pins**: `A0`, `A1`, `A2`, ... (platform-dependent availability)
316

317
**Board-Specific Aliases**: Many boards provide alternative names (e.g., `GPIO18` vs `D18`)
318

319
### Platform Detection
320

321
```python
322
from adafruit_blinka.agnostic import detector, board_id
323

324
# Check platform capabilities
325
if detector.board.any_raspberry_pi:
326
    print("Running on Raspberry Pi")
327
elif detector.board.any_beaglebone:
328
    print("Running on BeagleBone")
329
elif detector.board.any_jetson_board:
330
    print("Running on NVIDIA Jetson")
331
elif detector.board.ftdi_ft232h:
332
    print("Using FTDI FT232H adapter")
333

334
# Board-specific features
335
if hasattr(board, 'A0'):
336
    print("Board supports analog input")
337
if hasattr(board, 'SDA'):
338
    print("Board supports I2C")
339
if hasattr(board, 'SCLK'):
340
    print("Board supports SPI")
341
```
342

343
### Error Handling
344

345
```python
346
import board
347

348
try:
349
    # Try to use I2C
350
    i2c = board.I2C()
351
    print("I2C interface created successfully")
352
    i2c.deinit()
353
except AttributeError:
354
    print("I2C pins not available on this board")
355

356
try:
357
    # Try to access specific pin
358
    pin = board.D18
359
    print(f"Pin D18 is available: {pin}")
360
except AttributeError:
361
    print("Pin D18 not available on this board")
362

363
# Safe pin access
364
def get_pin_safe(pin_name, default=None):
365
    """Safely get a pin, returning default if not available"""
366
    return getattr(board, pin_name, default)
367

368
led_pin = get_pin_safe('D18')
369
if led_pin:
370
    print(f"LED pin available: {led_pin}")
371
else:
372
    print("Default LED pin not available")
373
```