This is the latest (main) BeagleBoard documentation. If you are looking for stable releases, use the drop-down menu on the bottom-left and select the desired version.

BeagleBone cape interface spec¶

This page is a fork of BeagleBone cape interface spec page on elinux. This is the new official home.

Background and overview¶

Important

Resources

Note

Below, when mentioning “Black”, this is true for all AM3358-based BeagleBone boards. “AI” is AM5729-based. “AI-64” is TDA4VM-based.

The device tree symbols for the BeagleBone Cape Compatibility Layer are provided in BeagleBoard-DeviceTrees at:

Black: bbb-bone-buses.dtsi
AI: bbai-bone-buses.dtsi
AI-64: k3-j721e-beagleboneai-64-bone-buses.dtsi

The udev rules used to create the userspace symlinks for the BeagleBone Cape Compatibility Layer are provided in usr-customizations at:

More details can be found in Methodology.

Note

Legend

D : Digital general purpose input and output (GPIO)
I : Inter-integrated circuit bus (I²C) ports
S : Serial peripheral interface (SPI) ports
U : Universal asynchronous reciever/transmitter (UART) serial ports
C : CAN
A : Analog inputs
E : PWM
Q : Capture/EQEP
M : MMC/SD/SDIO
B : I2S/audio serial ports
L : LCD
P : PRU
Y : ECAP

Table 70 Overall¶
P9				P8
Functions	odd	even	Functions	Functions	odd	even	Functions
USB D+	E1	E2	USB D-
5V OUT	E3	E4	GND
GND	1	2	GND	GND	1	2	GND
3V3 OUT	3	4	3V3 OUT	D M	3	4	D M
5V IN	5	6	5V IN	D M C	5	6	D M C
5V OUT	7	8	5V OUT	D C	7	8	D C
PWR BUT	9	10	RESET	D C	9	10	D C
D U	11	12	D	D Q P	11	12	D Q P
D U	13	14	D E	D E	13	14	D
D	15	16	D E	D P	15	16	D P
D I S	17	18	D I S	D	17	18	D
D I C	19	20	D I C	D E	19	20	D M P
D E S U	21	22	D E S U	D M P	21	22	D M Q
D S	23	24	D I U C	D M	23	24	D M
D P	25	26	D I U C	D M	25	26	D
D P Q	27	28	D S P	D L P	27	28	D L P U
D E S P	29	30	D S P	D L P U	29	30	D L P
D E S P	31	32	ADC VDD REF OUT	D L	31	32	D L
A	33	34	ADC GND	D L Q	33	34	D E L
A	35	36	A	D L Q	35	36	D E L
A	37	38	A	D L U	37	38	D L U
A	39	40	A	D L P	39	40	D L P
D P	41	42	D Q S U P	D L P Q	41	42	D L P Q
GND	43	44	GND	D L P	43	44	D L P
GND	45	46	GND	D E L P	45	46	D E L P

Digital GPIO¶

The compatibility layer comes with simple reference nodes for attaching the Linuuux gpio-leds or gpio-keys to any cape header GPIO pin. This provides simple userspace general purpose input or output with various trigger modes.

The format followed for the gpio-leds nodes is bone_led_P8_## / bone_led_P9_##. The gpio-leds driver is used by these reference nodes internally and allows users to easily create compatible led nodes in overlays for Black, AI and AI-64.

Listing 3 Example device tree overlay to enable LED driver on header P8 pin 3¶

/dts-v1/;
/plugin/;

&bone_led_P8_03 {
    status = "okay";
}

In Example device tree overlay to enable LED driver on header P8 pin 3, it is possible to redefine the default label and other properties defined in the gpio-leds schema.

Table 71 GPIO pins¶
P9				P8
Functions	odd	even	Functions	Functions	odd	even	Functions
GND	1	2	GND	GND	1	2	GND
3V3 OUT	3	4	3V3 OUT	D M	3	4	D M
5V IN	5	6	5V IN	D M C4t	5	6	D M C4r
5V OUT	7	8	5V OUT	D C2r	7	8	D C2t
PWR BUT	9	10	RESET	D C3r	9	10	D C3t
D U4r	11	12	D	D P0o Q2b	11	12	D Q2a P0o
D U4t	13	14	D E1a	D E2b	13	14	D
D	15	16	D E1b	D P0i	15	16	D P0i
D I1c S00	17	18	D I1d S0o	D	17	18	D
C0r D I2c	19	20	C0t D I2d	D E2a	19	20	D M P1
D E0b S0i U2t	21	22	D E0a S0c U2r	D M P1	21	22	D M Q2b
D S01	23	24	C1r D I3c U1t	D M	23	24	D M
D P0	25	26	C1t D I3d U1r	D M	25	26	D
D P0 Q0b	27	28	D P0 S10	D L P1	27	28	D L P1 U6r
D E S1i P0	29	30	D P0 S1o	D L P1 U6t	29	30	D L P1
D E S1c P0	31	32	ADC VDD	D L	31	32	D L
A 4	33	34	ADC GND	D L Q1b	33	34	D E L
A 6	35	36	A 5	D L Q1a	35	36	D E L
A 2	37	38	A 3	D L U5t	37	38	D L U5r
A 0	39	40	A 1	D L P1	39	40	D L P1
D P0	41	42	D Q0a S11 U3t P0	D L P1 Q4a	41	42	D L P1 Q4b
GND	43	44	GND	D L P1	43	44	D L P1
GND	45	46	GND	D E L P1	45	46	D E L P1

Table 72 Bone GPIO LEDs interface¶
SYSFS link	Header pin	Black	AI	AI-64
/sys/class/leds/P8_03	P8_03	gpio1_6	gpio1_24	gpio0_20
/sys/class/leds/P8_04	P8_04	gpio1_7	gpio1_25	gpio0_48
/sys/class/leds/P8_05	P8_05	gpio1_2	gpio7_1	gpio0_33
/sys/class/leds/P8_06	P8_06	gpio1_3	gpio7_2	gpio0_34
/sys/class/leds/P8_07	P8_07	gpio2_2	gpio6_5	gpio0_15
/sys/class/leds/P8_08	P8_08	gpio2_3	gpio6_6	gpio0_14
/sys/class/leds/P8_09	P8_09	gpio2_5	gpio6_18	gpio0_17
/sys/class/leds/P8_10	P8_10	gpio2_4	gpio6_4	gpio0_16
/sys/class/leds/P8_11	P8_11	gpio1_13	gpio3_11	gpio0_60
/sys/class/leds/P8_12	P8_12	gpio1_12	gpio3_10	gpio0_59
/sys/class/leds/P8_13	P8_13	gpio0_23	gpio4_11	gpio0_89
/sys/class/leds/P8_14	P8_14	gpio0_26	gpio4_13	gpio0_75
/sys/class/leds/P8_15	P8_15	gpio1_15	gpio4_3	gpio0_61
/sys/class/leds/P8_16	P8_16	gpio1_14	gpio4_29	gpio0_62
/sys/class/leds/P8_17	P8_17	gpio0_27	gpio8_18	gpio0_3
/sys/class/leds/P8_18	P8_18	gpio2_1	gpio4_9	gpio0_4
/sys/class/leds/P8_19	P8_19	gpio0_22	gpio4_10	gpio0_88
/sys/class/leds/P8_20	P8_20	gpio1_31	gpio6_30	gpio0_76
/sys/class/leds/P8_21	P8_21	gpio1_30	gpio6_29	gpio0_30
/sys/class/leds/P8_22	P8_22	gpio1_5	gpio1_23	gpio0_5
/sys/class/leds/P8_23	P8_23	gpio1_4	gpio1_22	gpio0_31
/sys/class/leds/P8_24	P8_24	gpio1_1	gpio7_0	gpio0_6
/sys/class/leds/P8_25	P8_25	gpio1_0	gpio6_31	gpio0_35
/sys/class/leds/P8_26	P8_26	gpio1_29	gpio4_28	gpio0_51
/sys/class/leds/P8_27	P8_27	gpio2_22	gpio4_23	gpio0_71
/sys/class/leds/P8_28	P8_28	gpio2_24	gpio4_19	gpio0_72
/sys/class/leds/P8_29	P8_29	gpio2_23	gpio4_22	gpio0_73
/sys/class/leds/P8_30	P8_30	gpio2_25	gpio4_20	gpio0_74
/sys/class/leds/P8_31	P8_31	gpio0_10	gpio8_14	gpio0_32
/sys/class/leds/P8_32	P8_32	gpio0_11	gpio8_15	gpio0_26
/sys/class/leds/P8_33	P8_33	gpio0_9	gpio8_13	gpio0_25
/sys/class/leds/P8_34	P8_34	gpio2_17	gpio8_11	gpio0_7
/sys/class/leds/P8_35	P8_35	gpio0_8	gpio8_12	gpio0_24
/sys/class/leds/P8_36	P8_36	gpio2_16	gpio8_10	gpio0_8
/sys/class/leds/P8_37	P8_37	gpio2_14	gpio8_8	gpio0_106
/sys/class/leds/P8_38	P8_38	gpio2_15	gpio8_9	gpio0_105
/sys/class/leds/P8_39	P8_39	gpio2_12	gpio8_6	gpio0_69
/sys/class/leds/P8_40	P8_40	gpio2_13	gpio8_7	gpio0_70
/sys/class/leds/P8_41	P8_41	gpio2_10	gpio8_4	gpio0_67
/sys/class/leds/P8_42	P8_42	gpio2_11	gpio8_5	gpio0_68
/sys/class/leds/P8_43	P8_43	gpio2_8	gpio8_2	gpio0_65
/sys/class/leds/P8_44	P8_44	gpio2_9	gpio8_3	gpio0_66
/sys/class/leds/P8_45	P8_45	gpio2_6	gpio8_0	gpio0_79
/sys/class/leds/P8_46	P8_46	gpio2_7	gpio8_1	gpio0_80
/sys/class/leds/P9_11	P9_11	gpio0_30	gpio8_17	gpio0_1
/sys/class/leds/P9_12	P9_12	gpio1_28	gpio5_0	gpio0_45
/sys/class/leds/P9_13	P9_13	gpio0_31	gpio6_12	gpio0_2
/sys/class/leds/P9_14	P9_14	gpio1_18	gpio4_25	gpio0_93
/sys/class/leds/P9_15	P9_15	gpio1_16	gpio3_12	gpio0_47
/sys/class/leds/P9_16	P9_16	gpio1_19	gpio4_26	gpio0_94
/sys/class/leds/P9_17	P9_17	gpio0_5	gpio7_17	gpio0_28
/sys/class/leds/P9_18	P9_18	gpio0_4	gpio7_16	gpio0_40
/sys/class/leds/P9_19	P9_19	gpio0_13	gpio7_3	gpio0_78
/sys/class/leds/P9_20	P9_20	gpio0_12	gpio7_4	gpio0_77
/sys/class/leds/P9_21	P9_21	gpio0_3	gpio3_3	gpio0_39
/sys/class/leds/P9_22	P9_22	gpio0_2	gpio6_19	gpio0_38
/sys/class/leds/P9_23	P9_23	gpio1_17	gpio7_11	gpio0_10
/sys/class/leds/P9_24	P9_24	gpio0_15	gpio6_15	gpio0_13
/sys/class/leds/P9_25	P9_25	gpio3_21	gpio6_17	gpio0_127
/sys/class/leds/P9_26	P9_26	gpio0_14	gpio6_14	gpio0_12
/sys/class/leds/P9_27	P9_27	gpio3_19	gpio4_15	gpio0_46
/sys/class/leds/P9_28	P9_28	gpio3_17	gpio4_17	gpio1_11
/sys/class/leds/P9_29	P9_29	gpio3_15	gpio5_11	gpio0_53
/sys/class/leds/P9_30	P9_30	gpio3_16	gpio5_12	gpio0_44
/sys/class/leds/P9_31	P9_31	gpio3_14	gpio5_10	gpio0_52
/sys/class/leds/P9_33	P9_33	n/a	n/a	gpio0_50
/sys/class/leds/P9_35	P9_35	n/a	n/a	gpio0_55
/sys/class/leds/P9_36	P9_36	n/a	n/a	gpio0_56
/sys/class/leds/P9_37	P9_37	n/a	n/a	gpio0_57
/sys/class/leds/P9_38	P9_38	n/a	n/a	gpio0_58
/sys/class/leds/P9_39	P9_39	n/a	n/a	gpio0_54
/sys/class/leds/P9_40	P9_40	n/a	n/a	gpio0_81
/sys/class/leds/P9_41	P9_41	gpio0_20	gpio6_20	gpio1_0
/sys/class/leds/P9_42	P9_42	gpio0_7	gpio4_18	gpio0_123
/sys/class/leds/A15	A15	gpio0_19	NA	NA

I²C¶

Compatibility layer provides simple I2C bone bus nodes for creating compatible overlays for Black, AI and AI-64. The format followed for these nodes is bone_i2c_#.

Table 73 I2C pins¶
P9
Functions	odd	even	Functions
1 SCL	17	18	1 SDA
2 SCL	19	20	2 SDA
4 SCL [4] [5]	21	22	4 SDA [4] [5]
	23	24	3 SCL [3]
	25	26	3 SDA [3]

Table 74 I2C port mapping¶
SYSFS link	DT symbol	Black	AI	AI-64	SCL	SDA	Overlay
/dev/bone/i2c/0	bone_i2c_0	I2C0	I2C1	TBD	On-board
/dev/bone/i2c/1	bone_i2c_1	I2C1	I2C5	MAIN_I2C6	P9.17	P9.18	BONE-I2C1
/dev/bone/i2c/2	bone_i2c_2	I2C2	I2C4	MAIN_I2C3	P9.19	P9.20	BONE-I2C2
/dev/bone/i2c/3	bone_i2c_3	I2C1	I2C3	MAIN_I2C4	P9.24	P9.26	BONE-I2C3
/dev/bone/i2c/4	bone_i2c_4	I2C2	n/a	MAIN_I2C3	P9.21	P9.22	BONE-I2C4

Important

In the case the same controller is used for 2 different bone bus nodes, usage of those nodes is mutually-exclusive.

Note

The provided pre-compiled overlays enable the I²C bus driver only, not a specific device driver. Either a custom overlay is required to load the device driver or usermode device driver loading can be performed, depending on the driver. See Using I2C with Linux drivers for information on loading I²C drivers from userspace.

Listing 4 Example device tree overlay to enable I2C driver¶

/dts-v1/;
/plugin/;

&bone_i2c_1 {
    status = "okay";
    accel@1c {
        compatible = "fsl,mma8453";
        reg = <0x1c>;
    };
}

In Example device tree overlay to enable I2C driver, you can specify what driver you want to load and provide any properties it might need.

SPI¶

SPI bone bus nodes allow creating compatible overlays for Black, AI and AI-64.

Table 75 SPI pins¶
P9
Functions	odd	even	Functions
0 CS0	17	18	0 SDO
	19	20
0 SDI	21	22	0 CLK
0 CS1	23	24
	25	26
	27	28	1 CS0
1 SDI	29	30	1 SDO
1 CLK	31	32
	33	34
	35	36
	37	38
	39	40
	41	42	1 CS1

Table 76 SPI port mapping¶
Bone bus	DT symbol	Black	AI	AI-64	SDO	SDI	CLK	CS	Overlay
/dev/bone/spi/0.0	bone_spi_0	SPI0	SPI2	MAIN_SPI6	P9.18	P9.21	P9.22	P9.17 (CS0)	BONE-SPI0_0
/dev/bone/spi/0.1	bone_spi_0	SPI0	SPI2	MAIN_SPI6	P9.18	P9.21	P9.22	P9.23 (CS1)	BONE-SPI0_1
/dev/bone/spi/1.0	bone_spi_1	SPI1	SPI3	MAIN_SPI7	P9.30	P9.29	P9.31	P9.28 (CS0)	BONE-SPI1_0
/dev/bone/spi/1.1	bone_spi_1	SPI1	SPI3	MAIN_SPI7	P9.30	P9.29	P9.31	P9.42 (CS1)	BONE-SPI1_1

Note

The provided pre-compiled overlays enable the “spidev” driver using the “rohm,dh2228fv” compatible string. See https://stackoverflow.com/questions/53634892/linux-spidev-why-it-shouldnt-be-directly-in-devicetree for more background. A custom overlay is required to overload the compatible string to load a non-spidev driver.

Todo

figure out if BONE-SPI0_0 and BONE-SPI0_1 can be loaded at the same time

Note

Some boards may implement CS using a GPIO.

Listing 5 Example device tree overlay to enable SPI driver¶

/dts-v1/;
/plugin/;

&bone_spi_0 {
    status = "okay";
     pressure@0 {
         compatible = "bosch,bmp280";
         reg = <0>;      /* CS0 */
         spi-max-frequency = <5000000>;
     };
}

In Example device tree overlay to enable SPI driver, you can specify what driver you want to load and provide any properties it might need.

UART¶

UART bone bus nodes allow creating compatible overlays for Black, AI and AI-64.

Table 77 UART pins¶
P9				P8
Functions	odd	even	Functions	Functions	odd	even	Functions
4 RX [6]	11	12			11	12
4 TX [6]	13	14			13	14
	15	16			15	16
	17	18			17	18
	19	20			19	20
2 TX	21	22	2 RX		21	22	7 RX
	23	24	1 TX		23	24
	25	26	1 RX		25	26
	27	28			27	28	6 RX
	29	30		6 TX	29	30
	31	32			31	32
	33	34			33	34	7 TX
	35	36			35	36
	37	38		5 TX	37	38	5 RX
	39	40			39	40
	41	42	3 TX		41	42

Important

RTSn and CTSn mappings are not compatible across boards in the family and are therefore not part of the cape specification.

Table 78 UART port mapping¶
Bone bus	DT symbol	Black	AI	AI-64	TX	RX	Overlay
/dev/bone/uart/0	bone_uart_0	UART0	UART1	MAIN_UART0	Console debug header pins
/dev/bone/uart/1	bone_uart_1	UART1	UART10	MAIN_UART2	P9.24	P9.26	BONE-UART1
/dev/bone/uart/2	bone_uart_2	UART2	UART3	n/a	P9.21	P9.22	BONE-UART2
/dev/bone/uart/3	bone_uart_3	UART3	n/a	n/a	P9.42	n/a	BONE-UART3
/dev/bone/uart/4	bone_uart_4	UART4	UART5	MAIN_UART0 [6]	P9.13	P9.11	BONE-UART4
/dev/bone/uart/5	bone_uart_5	UART5	UART8	MAIN_UART5	P8.37	P8.38	BONE-UART5
/dev/bone/uart/6	bone_uart_6	n/a	n/a	MAIN_UART8	P8.29	P8.28	BONE-UART6
/dev/bone/uart/7	bone_uart_7	n/a	n/a	MAIN_UART2	P8.34	P8.22	BONE-UART7

Important

In the case the same controller is used for 2 different bone bus nodes, usage of those nodes is mutually-exclusive.

CAN¶

CAN bone bus nodes allow creating compatible overlays for Black, AI and AI-64.

Table 79 CAN pins¶
P9				P8
Functions	odd	even	Functions	Functions	odd	even	Functions
	5	6		4 TX	5	6	4 RX
	7	8		2 RX	7	8	2 TX
	9	10		3 RX	9	10	3 TX
	11	12			11	12
	13	14			13	14
	15	16			15	16
	17	18			17	18
0 RX	19	20	0 TX		19	20
	21	22			21	22
	23	24	1 RX		23	24
	25	26	1 TX		25	26

Table 80 CAN port mapping¶
Bone bus	Black	AI	AI-64	TX	RX	Overlays
/dev/bone/can/0	CAN0	n/a	MAIN_MCAN0	P9.20	P9.19	BONE-CAN0
/dev/bone/can/1	CAN1	CAN2	MAIN_MCAN4	P9.26	P9.24	BONE-CAN1
/dev/bone/can/2	n/a	CAN1 [1]	MAIN_MCAN5	P8.08	P8.07	BONE-CAN2
/dev/bone/can/3	n/a	n/a	MAIN_MCAN6	P8.10	P8.09	BONE-CAN3
/dev/bone/can/4	n/a	n/a	MAIN_MCAN7	P8.05	P8.06	BONE-CAN4

ADC¶

Todo

We need a udev rule to make sure the ADC shows up at /dev/bone/adc! There’s nothing for sure that IIO devices will show up in the same place.

Todo

I think we can also create symlinks for each channel based on which device is there, such that we can do /dev/bone/adc/Px_y

Todo

I believe a multiplexing IIO driver is the future solution

Table 81 ADC pins¶
P9				P8
Functions	odd	even	Functions	Functions	odd	even	Functions
USB D+	E1	E2	USB D-
5V OUT	E3	E4	GND
GND	1	2	GND	GND	1	2	GND
3V3 OUT	3	4	3V3 OUT	D M	3	4	D M
5V IN	5	6	5V IN	D M C4t	5	6	D M C4r
5V OUT	7	8	5V OUT	D C2r	7	8	D C2t
PWR BUT	9	10	RESET	D C3r	9	10	D C3t
D U4r	11	12	D	D P0o	11	12	D Q2a P0o
D U4t	13	14	D E1a	D E2b	13	14	D
D	15	16	D E1b	D P0i	15	16	D P0i
D I1c S00	17	18	D I1d S0o	D	17	18	D
C0r D I2c	19	20	C0t D I2d	D E2a	19	20	D M P1
D E0b S0i U2t	21	22	D E0a S0c U2r	D M P1	21	22	D M Q2b
D S01	23	24	C1r D I3c U1t	D M	23	24	D M
D P0	25	26	C1t D I3d U1r	D M	25	26	D
D P0 Q0b	27	28	D P0 S10	D L P1	27	28	D L P1 U6r
D E S1i P0	29	30	D P0 S1o	D L P1 U6t	29	30	D L P1
D E S1c P0	31	32	ADC VDD	D L	31	32	D L
A 4	33	34	ADC GND	D L Q1b	33	34	D E L
A 6	35	36	A 5	D L Q1a	35	36	D E L
A 2	37	38	A 3	D L U5t	37	38	D L U5r
A 0	39	40	A 1	D L P1	39	40	D L P1
D P0	41	42	D Q0a S11 U3t P0	D L P1	41	42	D L P1
GND	43	44	GND	D L P1	43	44	D L P1
GND	45	46	GND	D E L P1	45	46	D E L P1

Table 82 Bone ADC¶
Index	Header pin	Black/AI-64	AI
0	P9_39	in_voltage0_raw	in_voltage0_raw
1	P9_40	in_voltage1_raw	in_voltage1_raw
2	P9_37	in_voltage2_raw	in_voltage3_raw
3	P9_38	in_voltage3_raw	in_voltage2_raw
4	P9_33	in_voltage4_raw	in_voltage7_raw
5	P9_36	in_voltage5_raw	in_voltage6_raw
6	P9_35	in_voltage6_raw	in_voltage4_raw

Table 83 Bone ADC Overlay¶
Black	AI	AI-64	overlay
Internal	External (STMPE811)	TBD	BONE-ADC.dts

PWM¶

Todo

remove deep references to git trees

PWM bone bus nodes allow creating compatible overlays for Black, AI and AI-64. For the definitions, you can see bbai-bone-buses.dtsi#L415 & bbb-bone-buses.dtsi#L432

Table 84 PWM pins¶
P9				P8
Functions	odd	even	Functions	Functions	odd	even	Functions
USB D+	E1	E2	USB D-
5V OUT	E3	E4	GND
GND	1	2	GND	GND	1	2	GND
3V3 OUT	3	4	3V3 OUT	D M	3	4	D M
5V IN	5	6	5V IN	D M C4t	5	6	D M C4r
5V OUT	7	8	5V OUT	D C2r	7	8	D C2t
PWR BUT	9	10	RESET	D C3r	9	10	D C3t
D U4r	11	12	D	D P0o	11	12	D Q2a P0o
D U4t	13	14	D E1a	D E2b	13	14	D
D	15	16	D E1b	D P0i	15	16	D P0i
D I1c S00	17	18	D I1d S0o	D	17	18	D
C0r D I2c	19	20	C0t D I2d	D E2a	19	20	D M P1
D E0b S0i U2t	21	22	D E0a S0c U2r	D M P1	21	22	D M Q2b
D S01	23	24	C1r D I3c U1t	D M	23	24	D M
D P0	25	26	C1t D I3d U1r	D M	25	26	D
D P0 Q0b	27	28	D P0 S10	D L P1	27	28	D L P1 U6r
D E S1i P0	29	30	D P0 S1o	D L P1 U6t	29	30	D L P1
D E S1c P0	31	32	ADC VDD	D L	31	32	D L
A 4	33	34	ADC GND	D L Q1b	33	34	D E L
A 6	35	36	A 5	D L Q1a	35	36	D E L
A 2	37	38	A 3	D L U5t	37	38	D L U5r
A 0	39	40	A 1	D L P1	39	40	D L P1
D P0	41	42	D Q0a S11 U3t P0	D L P1	41	42	D L P1
GND	43	44	GND	D L P1	43	44	D L P1
GND	45	46	GND	D E L P1	45	46	D E L P1

Table 85 Bone bus PWM¶
SYSFS link	DT symbol	Black	AI	AI-64	A	B	Overlay
/dev/bone/pwm/0	bone_pwm_0	PWM0		PWM1	P9.22	P9.21	BONE-PWM0.dts
/dev/bone/pwm/1	bone_pwm_0	PWM1	PWM3	PWM2	P9.14	P9.16	BONE-PWM1.dts
/dev/bone/pwm/2	bone_pwm_0	PWM2	PWM2	PWM0	P8.19	P8.13	BONE-PWM2.dts

TIMER PWM¶

TIMER PWM bone bus uses ti,omap-dmtimer-pwm driver, and timer nodes that allow creating compatible overlays for Black, AI and AI-64. For the timer node definitions, you can see bbai-bone-buses.dtsi#L449 & bbb-bone-buses.dtsi#L466.

Table 86 Bone TIMER PWMs¶
Bone bus	Header pin	Black	AI	overlay
/sys/bus/platform/devices/bone_timer_pwm_0/	P8.10	timer6	timer10	BONE-TIMER_PWM_0.dts
/sys/bus/platform/devices/bone_timer_pwm_1/	P8.07	timer4	timer11	BONE-TIMER_PWM_1.dts
/sys/bus/platform/devices/bone_timer_pwm_2/	P8.08	timer7	timer12	BONE-TIMER_PWM_2.dts
/sys/bus/platform/devices/bone_timer_pwm_3/	P9.21		timer13	BONE-TIMER_PWM_3.dts
/sys/bus/platform/devices/bone_timer_pwm_4/	P8.09	timer5	timer14	BONE-TIMER_PWM_4.dts
/sys/bus/platform/devices/bone_timer_pwm_5/	P9.22		timer15	BONE-TIMER_PWM_5.dts

Counter¶

A counter function for quadrature encoders is implemented with the EQEP peripheral.

Todo

Additional quadrature encoders can be implemented in PRU firmware.

Table 87 Counter pins¶
P9				P8
Functions	odd	even	Functions	Functions	odd	even	Functions
	11	12		2 B	11	12	2 A
	13	14			13	14
	15	16		3 B	15	16	3 A
	17	18			17	18
	19	20			19	20
	21	22			21	22
	23	24			23	24
	25	26			25	26
0 B	27	28			27	28
	29	30			29	30
	31	32			31	32
	33	34		1 B	33	34
	35	36		1 A	35	36
	37	38			37	38
	39	40			39	40
	41	42	0 A		41	42
	43	44			43	44
	45	46			45	46

On BeagleBone’s without an eQEP on specific pins, consider using the PRU to perform a software counter function.

Table 88 Counter port mapping¶
SYSFS link	DT symbol	Black	AI	AI-64	A	B \| STRB		INDX	Overlay
/dev/bone/counter/0	bone_counter_0	eQEP0	eQEP2	eQEP0	P9.42	P9.27 \| - Black/AI-64: P9.25 - AI: P8.06		Black/AI-64: P9.41 AI: P8.05	BONE-COUNTER0
/dev/bone/counter/1	bone_counter_1	eQEP1	eQEP0	eQEP1	P8.35	P8.33	Black/AI-64: P8.32 AI: P9.21	Black/AI-64: P8.31 AI: ‒	BONE-COUNTER1
/dev/bone/counter/2	bone_counter_2	eQEP2	eQEP1	‒	P8.12	P8.11	Black: P8.15 AI: P8.18	Black: P8.16 AI: P9.15	BONE-COUNTER2
/dev/bone/counter/3	bone_counter_3	eQEP2	‒	‒	P8.41	P8.42	Black: P8.40	Black: P8.39	BONE-COUNTER3
/dev/bone/counter/4	bone_counter_4	‒	‒	‒	P8.16	P8.15			BONE-COUNTER4

eCAP¶

Todo

This doesn’t include any abstraction yet.

Table 89 ECAP pins¶
P9				P8
Functions	odd	even	Functions	Functions	odd	even	Functions
USB D+	E1	E2	USB D-
5V OUT	E3	E4	GND
GND	1	2	GND	GND	1	2	GND
3V3 OUT	3	4	3V3 OUT	D M	3	4	D M
5V IN	5	6	5V IN	D M C4t	5	6	D M C4r
5V OUT	7	8	5V OUT	D C2r	7	8	D C2t
PWR BUT	9	10	RESET	D C3r	9	10	D C3t
D U4r	11	12	D	D P0o	11	12	D Q2a P0o
D U4t	13	14	D E1a	D E2b	13	14	D
D	15	16	D E1b	D P0i	15	16	D P0i
D I1c S00	17	18	D I1d S0o	D	17	18	D
C0r D I2c	19	20	C0t D I2d	D E2a	19	20	D M P1
D E0b S0i U2t	21	22	D E0a S0c U2r	D M P1	21	22	D M Q2b
D S01	23	24	C1r D I3c U1t	D M	23	24	D M
D P0	25	26	C1t D I3d U1r	D M	25	26	D
D P0 Q0b	27	28	D P0 S10	D L P1	27	28	D L P1 U6r
D E S1i P0	29	30	D P0 S1o	D L P1 U6t	29	30	D L P1
D E S1c P0	31	32	ADC VDD	D L	31	32	D L
A 4	33	34	ADC GND	D L Q1b	33	34	D E L
A 6	35	36	A 5	D L Q1a	35	36	D E L
A 2	37	38	A 3	D L U5t	37	38	D L U5r
A 0	39	40	A 1	D L P1	39	40	D L P1
D P0	41	42	D Q0a S11 U3t P0	D L P1	41	42	D L P1
GND	43	44	GND	D L P1	43	44	D L P1
GND	45	46	GND	D E L P1	45	46	D E L P1

Table 90 Black eCAP PWMs¶
Bone bus	Header pin	peripheral	overlay
/sys/bus/platform/drivers/ecap/48302100.ecap	P9.42	eCAP0_in_PWM0_out	BBB-ECAP0.dts
/sys/bus/platform/drivers/ecap/48304100.ecap	P9.28	eCAP2_in_PWM2_out	BBB-ECAP2.dts

Table 91 AI eCAP PWMs¶
Bone bus	Header pin	peripheral	overlay
/sys/bus/platform/drivers/ecap/4843e100.ecap	P8.15	eCAP1_in_PWM1_out	BBAI-ECAP1.dts
/sys/bus/platform/drivers/ecap/48440100.ecap	P8.14	eCAP2_in_PWM2_out	BBAI-ECAP2.dts
/sys/bus/platform/drivers/ecap/48440100.ecap	P8.20	eCAP2_in_PWM2_out	BBAI-ECAP2A.dts
/sys/bus/platform/drivers/ecap/48442100.ecap	P8.04	eCAP3_in_PWM3_out	BBAI-ECAP3.dts
/sys/bus/platform/drivers/ecap/48442100.ecap	P8.26	eCAP3_in_PWM3_out	BBAI-ECAP3A.dts

MMC/SDIO¶

Table 92 Bone eMMC¶
Header pin	Description
P8.3	DAT6
P8.4	DAT7
P8.5	DAT2
P8.6	DAT3
P8.20	CMD
P8.21	CLK
P8.22	DAT5
P8.23	DAT4
P8.24	DAT1
P8.25	DAT0

Table 93 Bone eMMC Overlay¶
Black	AI	overlay
MMC2	MMC3	BONE-eMMC.dts

LCD¶

Table 94 16bit LCD interface¶
Header pin	Description
P8_45	lcd_data0
P8_46	lcd_data1
P8_43	lcd_data2
P8_44	lcd_data3
P8_41	lcd_data4
P8_42	lcd_data5
P8_39	lcd_data6
P8_40	lcd_data7
P8_37	lcd_data8
P8_38	lcd_data9
P8_36	lcd_data10
P8_34	lcd_data11
P8_35	lcd_data12
P8_33	lcd_data13
P8_31	lcd_data14
P8_32	lcd_data15
P8_27	lcd_vsync
P8_29	lcd_hsync
P8_28	lcd_pclk
P8_30	lcd_ac_bias_en

Table 95 16bit LCD interface Overlay¶
Black	AI	overlay
lcdc	dss

McASP¶

Table 96 Bone McASP0¶
Header pin	Description
P9.12	aclkr
P9.25	ahclkx
P9.27	fsr
P9.28	Black: axr2 AI: axr9
P9.29	fsx
P9.30	Black: axr0 AI: axr10
P9.31	aclkx

Table 97 Bone McASP0 Overlay¶
Black	AI	overlay
McASP0	McASP1

PRU¶

The overlay situation for PRUs is a bit more complex than with other peripherals. The mechanism for loading, starting and stopping the PRUs can go through either [https://www.kernel.org/doc/html/latest/driver-api/uio-howto.html UIO] or [https://software-dl.ti.com/processor-sdk-linux/esd/docs/latest/linux/Foundational_Components/PRU-ICSS/Linux_Drivers/RemoteProc_and_RPMsg.html RemoteProc].

/dev/remoteproc/prussX-coreY (AM3358 X = “”, other x = “1|2”)

Table 98 Bone PRU eCAP¶
Header Pin	Black	AI
P8.15	pr1_ecap0	pr1_ecap0
P8.32		pr2_ecap0
P9.42	pr1_ecap0

Table 99 AI PRU UART¶
UART	TX	RX	RTSn	CTSn	Overlays
PRU1 UART0	P8_31	P8_33	P8_34	P8_35
PRU2 UART0	P8_43	P8_44	P8_45	P8_46

Table 100 Bone PRU¶
Header Pin	Black	AI
P8.03		pr2_pru0 10
P8.04		pr2_pru0 11
P8.05		pr2_pru0 06
P8.06		pr2_pru0 07
P8.07		pr2_pru1 16
P8.08		pr2_pru0 20
P8.09		pr2_pru1 06
P8.10		pr2_pru1 15
P8.11	pr1_pru0 15 (Out)	pr1_pru0 04
P8.12	pr1_pru0 14 (Out)	pr1_pru0 03
P8.13		pr1_pru1 07
P8.14		pr1_pru1 09
P8.15	pr1_pru0 15 (In)	pr1_pru1 16
P8.16	pr1_pru0 14 (In)	pr1_pru1 18
P8.17		pr2_pru0 15
P8.18		pr1_pru1 05
P8.19		pr1_pru1 06
P8.20		pr2_pru0 03
P8.21		pr2_pru0 02
P8.22		pr2_pru0 09
P8.23		pr2_pru0 08
P8.24		pr2_pru0 05
P8.25		pr2_pru0 04
P8.26		pr1_pru1 17
P8.27		pr2_pru1 17
P8.28		pr2_pru0 17
P8.29		pr2_pru0 18
P8.30		pr2_pru0 19
P8.31		pr2_pru0 11
P8.32		pr2_pru1 00
P8.33		pr2_pru0 10
P8.34		pr2_pru0 08
P8.35		pr2_pru0 09
P8.36		pr2_pru0 07
P8.37		pr2_pru0 05
P8.38		pr2_pru0 06
P8.39		pr2_pru0 03
P8.40		pr2_pru0 04
P8.41		pr2_pru0 01
P8.42		pr2_pru0 02
P8.43		pr2_pru1 20
P8.44		pr2_pru0 00
P8.45		pr2_pru1 18
P8.46		pr2_pru1 19
P9.11		pr2_pru0 14
P9.13		pr2_pru0 15
P9.14		pr1_pru1 14
P9.15		pr1_pru0 5
P9.16		pr1_pru1 15
P9.17		pr2_pru1 09
P9.18		pr2_pru1 08
P9.19		pr1_pru1 02
P9.20		pr1_pru1 01
P9.24	pr1_pru0 16 (In)
P9.25	pr1_pru0 07	pr2_pru1 05
P9.26	pr1_pru1 16 (In)	pr1_pru0 17
P9.27	pr1_pru0 05	pr1_pru1 11
P9.28	pr1_pru0 03	pr2_pru1 13
P9.29	pr1_pru0 01	pr2_pru1 11
P9.30	pr1_pru0 02	pr2_pru1 12
P9.31	pr1_pru0 00	pr2_pru1 10
P9.41	pr1_pru0 06	pr1_pru1 03
P9.42	pr1_pru0 04	pr1_pru1 10

GPIO¶

Todo

For each of the pins with a GPIO, there should be a symlink that comes from the names

Methodology¶

The methodology for applied in the kernel and software images to expose the software interfaces is to be documented here. The most fundamental elements are the device tree entries, including overlays, and udev rules.

Device Trees¶

Todo

Describe how the Device Trees expose symbols for reuse across boards

For every resource exposed on the cape headers, an indexed symbol should be provided in the base device tree.

udev rules¶

10-of-symlink.rules¶

#From: https://github.com/mvduin/py-uio/blob/master/etc/udev/rules.d/10-of-symlink.rules
# allow declaring a symlink for a device in DT
ATTR{device/of_node/symlink}!="", \
        ENV{OF_SYMLINK}="%s{device/of_node/symlink}"

ENV{OF_SYMLINK}!="", ENV{DEVNAME}!="", \
        SYMLINK+="%E{OF_SYMLINK}", \
        TAG+="systemd", ENV{SYSTEMD_ALIAS}+="/dev/%E{OF_SYMLINK}"

TBD¶

# Also courtesy of mvduin
# create symlinks for gpios exported to sysfs by DT
SUBSYSTEM=="gpio", ACTION=="add", TEST=="value", ATTR{label}!="sysfs", \
                RUN+="/bin/mkdir -p /dev/bone/gpio", \
                RUN+="/bin/ln -sT '/sys/class/gpio/%k' /dev/bone/gpio/%s{label}"

Verification¶

Todo

The steps used to verify all of these configurations is to be documented here. It will serve to document what has been tested, how to reproduce the configurations, and how to verify each major triannual release. All faults will be documented in the issue tracker.

BeagleBone cape interface spec¶

Background and overview¶

Digital GPIO¶

I2C¶

SPI¶

UART¶

CAN¶

ADC¶

PWM¶

TIMER PWM¶

Counter¶

eCAP¶

MMC/SDIO¶

LCD¶

McASP¶

PRU¶

GPIO¶

Methodology¶

Device Trees¶

udev rules¶

10-of-symlink.rules¶

TBD¶

Verification¶

References¶

I²C¶