/
README
658 lines (448 loc) · 22.4 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
Introduction
============
This directory contains Device Tree overlays. Device Tree makes it possible
to support many hardware configurations with a single kernel and without the
need to explicitly load or blacklist kernel modules. Note that this isn't a
"pure" Device Tree configuration (c.f. MACH_BCM2835) - some on-board devices
are still configured by the board support code, but the intention is to
eventually reach that goal.
On Raspberry Pi, Device Tree usage is controlled from /boot/config.txt. By
default, the Raspberry Pi kernel boots with device tree enabled. You can
completely disable DT usage (for now) by adding:
device_tree=
to your config.txt, which should cause your Pi to revert to the old way of
doing things after a reboot.
In /boot you will find a .dtb for each base platform. This describes the
hardware that is part of the Raspberry Pi board. The loader (start.elf and its
siblings) selects the .dtb file appropriate for the platform by name, and reads
it into memory. At this point, all of the optional interfaces (i2c, i2s, spi)
are disabled, but they can be enabled using Device Tree parameters:
dtparam=i2c=on,i2s=on,spi=on
However, this shouldn't be necessary in many use cases because loading an
overlay that requires one of those interfaces will cause it to be enabled
automatically, and it is advisable to only enable interfaces if they are
needed.
Configuring additional, optional hardware is done using Device Tree overlays
(see below).
raspi-config
============
The Advanced Options section of the raspi-config utility can enable and disable
Device Tree use, as well as toggling the I2C and SPI interfaces. Note that it
is possible to both enable an interface and blacklist the driver, if for some
reason you should want to defer the loading.
Modules
=======
As well as describing the hardware, Device Tree also gives enough information
to allow suitable driver modules to be located and loaded, with the corollary
that unneeded modules are not loaded. As a result it should be possible to
remove lines from /etc/modules, and /etc/modprobe.d/raspi-blacklist.conf can
have its contents deleted (or commented out).
Using Overlays
==============
Overlays are loaded using the "dtoverlay" directive. As an example, consider the
popular lirc-rpi module, the Linux Infrared Remote Control driver. In the
pre-DT world this would be loaded from /etc/modules, with an explicit
"modprobe lirc-rpi" command, or programmatically by lircd. With DT enabled,
this becomes a line in config.txt:
dtoverlay=lirc-rpi
This causes the file /boot/overlays/lirc-rpi-overlay.dtb to be loaded. By
default it will use GPIOs 17 (out) and 18 (in), but this can be modified using
DT parameters:
dtoverlay=lirc-rpi,gpio_out_pin=17,gpio_in_pin=13
Parameters always have default values, although in some cases (e.g. "w1-gpio")
it is necessary to provided multiple overlays in order to get the desired
behaviour. See the list of overlays below for a description of the parameters and their defaults.
The Overlay and Parameter Reference
===================================
N.B. When editing this file, please preserve the indentation levels to make it simple to parse
programmatically. NO HARD TABS.
Name: <The base DTB>
Info: Configures the base Raspberry Pi hardware
Load: <loaded automatically>
Params:
audio Set to "on" to enable the onboard ALSA audio
interface (default "off")
i2c_arm Set to "on" to enable the ARM's i2c interface
(default "off")
i2c_vc Set to "on" to enable the i2c interface
usually reserved for the VideoCore processor
(default "off")
i2c An alias for i2c_arm
i2c_arm_baudrate Set the baudrate of the ARM's i2c interface
(default "100000")
i2c_vc_baudrate Set the baudrate of the VideoCore i2c interface
(default "100000")
i2c_baudrate An alias for i2c_arm_baudrate
i2s Set to "on" to enable the i2s interface
(default "off")
spi Set to "on" to enable the spi interfaces
(default "off")
random Set to "on" to enable the hardware random
number generator (default "off")
uart0 Set to "off" to disable uart0 (default "on")
watchdog Set to "on" to enable the hardware watchdog
(default "off")
act_led_trigger Choose which activity the LED tracks.
Use "heartbeat" for a nice load indicator.
(default "mmc")
act_led_activelow Set to "on" to invert the sense of the LED
(default "off")
act_led_gpio Set which GPIO to use for the activity LED
(in case you want to connect it to an external
device)
(default "16" on a non-Plus board, "47" on a
Plus or Pi 2)
pwr_led_trigger
pwr_led_activelow
pwr_led_gpio
As for act_led_*, but using the PWR LED.
Not available on Model A/B boards.
N.B. It is recommended to only enable those interfaces that are needed.
Leaving all interfaces enabled can lead to unwanted behaviour (i2c_vc
interfering with Pi Camera, I2S and SPI hogging GPIO pins, etc.)
Note also that i2c, i2c_arm and i2c_vc are aliases for the physical
interfaces i2c0 and i2c1. Use of the numeric variants is still possible
but deprecated because the ARM/VC assignments differ between board
revisions. The same board-specific mapping applies to i2c_baudrate,
and the other i2c baudrate parameters.
Name: ads7846
Info: ADS7846 Touch controller
Load: dtoverlay=ads7846,<param>=<val>
Params: cs SPI bus Chip Select (default 1)
speed SPI bus speed (default 2Mhz, max 3.25MHz)
penirq GPIO used for PENIRQ. REQUIRED
penirq_pull Set GPIO pull (default 0=none, 2=pullup)
swapxy Swap x and y axis
xmin Minimum value on the X axis (default 0)
ymin Minimum value on the Y axis (default 0)
xmax Maximum value on the X axis (default 4095)
ymax Maximum value on the Y axis (default 4095)
pmin Minimum reported pressure value (default 0)
pmax Maximum reported pressure value (default 65535)
xohms Touchpanel sensitivity (X-plate resistance)
(default 400)
penirq is required and usually xohms (60-100) has to be set as well.
Apart from that, pmax (255) and swapxy are also common.
The rest of the calibration can be done with xinput-calibrator.
See: github.com/notro/fbtft/wiki/FBTFT-on-Raspian
Device Tree binding document:
www.kernel.org/doc/Documentation/devicetree/bindings/input/ads7846.txt
Name: bmp085_i2c-sensor
Info: Configures the BMP085/BMP180 digital barometric pressure and temperature
sensors from Bosch Sensortec
Load: dtoverlay=bmp085_i2c-sensor
Params: <None>
Name: dht11
Info: Overlay for the DHT11/DHT21/DHT22 humidity/temperature sensors
Also sometimes found with the part number(s) AM230x.
Load: dtoverlay=dht11,<param>=<val>
Params: gpiopin GPIO connected to the sensor's DATA output.
(default 4)
[ The ds1307-rtc overlay has been deleted. See i2c-rtc. ]
Name: enc28j60
Info: Overlay for the Microchip ENC28J60 Ethernet Controller (SPI)
Load: dtoverlay=enc28j60,<param>=<val>
Params: int_pin GPIO used for INT (default 25)
speed SPI bus speed (default 12000000)
Name: gpio-poweroff
Info: Drives a GPIO high or low on reboot
Load: gpio-poweroff,<param>=<val>
Params: gpiopin GPIO for signalling (default 26)
active_low Set if the power control device requires a
high->low transition to trigger a power-down.
Note that this will require the support of a
custom dt-blob.bin to prevent a power-down
during the boot process, and that a reboot
will also cause the pin to go low.
Name: hifiberry-amp
Info: Configures the HifiBerry Amp and Amp+ audio cards
Load: dtoverlay=hifiberry-amp
Params: <None>
Name: hifiberry-dac
Info: Configures the HifiBerry DAC audio card
Load: dtoverlay=hifiberry-dac
Params: <None>
Name: hifiberry-dacplus
Info: Configures the HifiBerry DAC+ audio card
Load: dtoverlay=hifiberry-dacplus
Params: <None>
Name: hifiberry-digi
Info: Configures the HifiBerry Digi audio card
Load: dtoverlay=hifiberry-digi
Params: <None>
Name: hy28a
Info: HY28A - 2.8" TFT LCD Display Module by HAOYU Electronics
Default values match Texy's display shield
Load: dtoverlay=hy28a,<param>=<val>
Params: speed Display SPI bus speed
rotate Display rotation {0,90,180,270}
fps Delay between frame updates
debug Debug output level {0-7}
xohms Touchpanel sensitivity (X-plate resistance)
resetgpio GPIO used to reset controller
ledgpio GPIO used to control backlight
Name: hy28b
Info: HY28B - 2.8" TFT LCD Display Module by HAOYU Electronics
Default values match Texy's display shield
Load: dtoverlay=hy28b,<param>=<val>
Params: speed Display SPI bus speed
rotate Display rotation {0,90,180,270}
fps Delay between frame updates
debug Debug output level {0-7}
xohms Touchpanel sensitivity (X-plate resistance)
resetgpio GPIO used to reset controller
ledgpio GPIO used to control backlight
Name: i2c-rtc
Info: Adds support for a number of I2C Real Time Clock devices
Load: dtoverlay=i2c-rtc,<param>
Params: ds1307 Select the DS1307 device
ds3231 Select the DS3231 device
mcp7941x Select the MCP7941x device
pcf2127 Select the PCF2127 device
pcf8523 Select the PCF8523 device
pcf8563 Select the PCF8563 device
Name: i2s-mmap
Info: Enables mmap support in the bcm2708-i2s driver
Load: dtoverlay=i2s-mmap
Params: <None>
Name: iqaudio-dac
Info: Configures the IQaudio DAC audio card
Load: dtoverlay=iqaudio-dac
Params: <None>
Name: iqaudio-dacplus
Info: Configures the IQaudio DAC+ audio card
Load: dtoverlay=iqaudio-dacplus
Params: <None>
Name: lirc-rpi
Info: Configures lirc-rpi (Linux Infrared Remote Control for Raspberry Pi)
Consult the module documentation for more details.
Load: dtoverlay=lirc-rpi,<param>=<val>,...
Params: gpio_out_pin GPIO for output (default "17")
gpio_in_pin GPIO for input (default "18")
gpio_in_pull Pull up/down/off on the input pin
(default "down")
sense Override the IR receive auto-detection logic:
"0" = force active-high
"1" = force active-low
"-1" = use auto-detection
(default "-1")
softcarrier Turn the software carrier "on" or "off"
(default "on")
invert "on" = invert the output pin (default "off")
debug "on" = enable additional debug messages
(default "off")
Name: mcp2515-can0
Info: Configures the MCP2515 CAN controller on spi0.0
Load: dtoverlay=mcp2515-can0,<param>=<val>
Params: oscillator Clock frequency for the CAN controller (Hz)
spimaxfrequency Maximum SPI frequence (Hz)
interrupt GPIO for interrupt signal
Name: mcp2515-can1
Info: Configures the MCP2515 CAN controller on spi0.1
Load: dtoverlay=mcp2515-can1,<param>=<val>
Params: oscillator Clock frequency for the CAN controller (Hz)
spimaxfrequency Maximum SPI frequence (Hz)
interrupt GPIO for interrupt signal
Name: mmc
Info: Selects the bcm2835-mmc SD/MMC driver, optionally with overclock
Load: dtoverlay=mmc,<param>=<val>
Params: overclock_50 Clock (in MHz) to use when the MMC framework
requests 50MHz
force_pio Disable DMA support
Name: mz61581
Info: MZ61581 display by Tontec
Load: dtoverlay=mz61581,<param>=<val>
Params: speed Display SPI bus speed
rotate Display rotation {0,90,180,270}
fps Delay between frame updates
txbuflen Transmit buffer length (default 32768)
debug Debug output level {0-7}
xohms Touchpanel sensitivity (X-plate resistance)
[ The pcf2127-rtc overlay has been deleted. See i2c-rtc. ]
[ The pcf8523-rtc overlay has been deleted. See i2c-rtc. ]
[ The pcf8563-rtc overlay has been deleted. See i2c-rtc. ]
Name: piscreen
Info: PiScreen display by OzzMaker.com
Load: dtoverlay=piscreen,<param>=<val>
Params: speed Display SPI bus speed
rotate Display rotation {0,90,180,270}
fps Delay between frame updates
debug Debug output level {0-7}
xohms Touchpanel sensitivity (X-plate resistance)
Name: pitft28-resistive
Info: Adafruit PiTFT 2.8" resistive touch screen
Load: dtoverlay=pitft28-resistive,<param>=<val>
Params: speed Display SPI bus speed
rotate Display rotation {0,90,180,270}
fps Delay between frame updates
debug Debug output level {0-7}
Name: pps-gpio
Info: Configures the pps-gpio (pulse-per-second time signal via GPIO).
Load: dtoverlay=pps-gpio,<param>=<val>
Params: gpiopin Input GPIO (default "18")
Name: pwm
Info: Configures a single PWM channel
Legal pin,function combinations for each channel:
PWM0: 12,4(Alt0) 18,2(Alt5) 40,4(Alt0) 52,5(Alt1)
PWM1: 13,4(Alt0) 19,2(Alt5) 41,4(Alt0) 45,4(Alt0) 53,5(Alt1)
N.B.:
1) Pin 18 is the only one available on all platforms, and
it is the one used by the I2S audio interface.
Pins 12 and 13 might be better choices on an A+, B+ or Pi2.
2) The onboard analogue audio output uses both PWM channels.
3) So be careful mixing audio and PWM.
4) Currently the clock must have been enabled and configured
by other means.
Load: dtoverlay=pwm-2chan,<param>=<val>
Load: dtoverlay=pwm,<param>=<val>
Params: pin Output pin (default 18) - see table
func Pin function (default 2 = Alt5) - see above
clock PWM clock frequency (informational)
Name: pwm-2chan
Info: Configures both PWM channels
Legal pin,function combinations for each channel:
PWM0: 12,4(Alt0) 18,2(Alt5) 40,4(Alt0) 52,5(Alt1)
PWM1: 13,4(Alt0) 19,2(Alt5) 41,4(Alt0) 45,4(Alt0) 53,5(Alt1)
N.B.:
1) Pin 18 is the only one available on all platforms, and
it is the one used by the I2S audio interface.
Pins 12 and 13 might be better choices on an A+, B+ or Pi2.
2) The onboard analogue audio output uses both PWM channels.
3) So be careful mixing audio and PWM.
4) Currently the clock must have been enabled and configured
by other means.
Load: dtoverlay=pwm-2chan,<param>=<val>
Params: pin Output pin (default 18) - see table
pin2 Output pin for other channel (default 19)
func Pin function (default 2 = Alt5) - see above
func2 Function for pin2 (default 2 = Alt5)
clock PWM clock frequency (informational)
Name: raspidac3
Info: Configures the RaspiDAV Rev.3x audio card
Load: dtoverlay=raspidac3
Params: <None>
Name: rpi-dac
Info: Configures the RPi DAC audio card
Load: dtoverlay=rpi-dac
Params: <None>
Name: rpi-display
Info: RPi-Display - 2.8" Touch Display by Watterott
Load: dtoverlay=rpi-display,<param>=<val>
Params: speed Display SPI bus speed
rotate Display rotation {0,90,180,270}
fps Delay between frame updates
debug Debug output level {0-7}
xohms Touchpanel sensitivity (X-plate resistance)
Name: rpi-ft5406
Info: Official Raspberry Pi display touchscreen
Load: dtoverlay=rpi-ft5406
Params: <None>
Name: rpi-proto
Info: Configures the RPi Proto audio card
Load: dtoverlay=rpi-proto
Params: <None>
Name: rpi-sense
Info: Raspberry Pi Sense HAT
Load: dtoverlay=rpi-sense
Params: <None>
Name: sdhost
Info: Selects the bcm2835-sdhost SD/MMC driver, optionally with overclock
Load: dtoverlay=sdhost,<param>=<val>
Params: overclock_50 Clock (in MHz) to use when the MMC framework
requests 50MHz
force_pio Disable DMA support (default off)
pio_limit Number of blocks above which to use DMA
(default 1)
debug Enable debug output (default off)
Name: sdio
Info: Selects the bcm2835-sdhost SD/MMC driver, optionally with overclock,
and enables SDIO via GPIOs 22-27.
Load: dtoverlay=sdio,<param>=<val>
Params: overclock_50 Clock (in MHz) to use when the MMC framework
requests 50MHz
force_pio Disable DMA support (default off)
pio_limit Number of blocks above which to use DMA
(default 1)
debug Enable debug output (default off)
Name: smi
Info: Enables the Secondary Memory Interface peripheral. Uses GPIOs 2-25!
Load: dtoverlay=smi
Params: <None>
Name: smi-dev
Info: Enables the userspace interface for the SMI driver
Load: dtoverlay=smi-dev
Params: <None>
Name: smi-nand
Info: Enables access to NAND flash via the SMI interface
Load: dtoverlay=smi-nand
Params: <None>
Name: spi-bcm2708
Info: Selects the bcm2708-spi SPI driver
Load: dtoverlay=spi-bcm2708
Params: <None>
Name: spi-bcm2835
Info: Selects the bcm2835-spi SPI driver
Load: dtoverlay=spi-bcm2835
Params: <None>
Name: spi-dma
Info: enables dma modes for spi-bcm2835
Load: dtoverlay=spi-dma
Params: <None>
Name: tinylcd35
Info: 3.5" Color TFT Display by www.tinylcd.com
Options: Touch, RTC, keypad
Load: dtoverlay=tinylcd35,<param>=<val>
Params: speed Display SPI bus speed
rotate Display rotation {0,90,180,270}
fps Delay between frame updates
debug Debug output level {0-7}
touch Enable touch panel
touchgpio Touch controller IRQ GPIO
xohms Touchpanel: Resistance of X-plate in ohms
rtc-pcf PCF8563 Real Time Clock
rtc-ds DS1307 Real Time Clock
keypad Enable keypad
Examples:
Display with touchpanel, PCF8563 RTC and keypad:
dtoverlay=tinylcd35,touch,rtc-pcf,keypad
Old touch display:
dtoverlay=tinylcd35,touch,touchgpio=3
Name: uart1
Info: Enable uart1 in place of uart0
Load: dtoverlay=uart1,<param>=<val>
Params: txd1_pin GPIO pin for TXD1 (14, 32 or 40 - default 14)
rxd1_pin GPIO pin for RXD1 (15, 33 or 41 - default 15)
Name: vga666
Info: Overlay for the Fen Logic VGA666 board
This uses GPIOs 2-21 (so no I2C), and activates the output 2-3 seconds
after the kernel has started.
Load: dtoverlay=vga666
Params: <None>
Name: w1-gpio
Info: Configures the w1-gpio Onewire interface module.
Use this overlay if you *don't* need a GPIO to drive an external pullup.
Load: dtoverlay=w1-gpio,<param>=<val>
Params: gpiopin GPIO for I/O (default "4")
pullup Non-zero, "on", or "y" to enable the parasitic
power (2-wire, power-on-data) feature
Name: w1-gpio-pullup
Info: Configures the w1-gpio Onewire interface module.
Use this overlay if you *do* need a GPIO to drive an external pullup.
Load: dtoverlay=w1-gpio-pullup,<param>=<val>,...
Params: gpiopin GPIO for I/O (default "4")
pullup Non-zero, "on", or "y" to enable the parasitic
power (2-wire, power-on-data) feature
extpullup GPIO for external pullup (default "5")
Troubleshooting
===============
If you are experiencing problems that you think are DT-related, enable DT
diagnostic output by adding this to /boot/config.txt:
dtdebug=on
and rebooting. Then run:
sudo vcdbg log msg
and look for relevant messages.
Further reading
===============
This is only meant to be a quick introduction to the subject of Device Tree on
Raspberry Pi. There is a more complete explanation here:
http://www.raspberrypi.org/documentation/configuration/device-tree.md