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#

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:

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.

Summary of cape interfaces#

Note

Legend

  • D : Digital general purpose input and output (GPIO)

  • I : Inter-integrated circuit bus (I2C) 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 101 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

This is an alternate starting point template that should be fully encompasing with indexes. It is a bit overwhelming, so I’m not making it visible.

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 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

Digital GPIO#

The compatibility layer comes with simple reference nodes for attaching the Linux 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 14 Example device tree overlay to enable LED driver on header P8 pin 3#
1/dts-v1/;
2/plugin/;
3
4&bone_led_P8_03 {
5    status = "okay";
6}

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 102 GPIO pins#

P9

P8

Functions

odd

even

Functions

Functions

odd

even

Functions

3

4

P8_03

3

4

P8_04

5

6

P8_05

5

6

P8_06

7

8

P8_07

7

8

P8_08

9

10

P8_09

9

10

P8_10

P9_11

11

12

P9_12

P8_11

11

12

P8_12

P9_13

13

14

P9_14

P8_13

13

14

P8_14

P9_15

15

16

P9_15

P8_15

15

16

P8_16

P9_17

17

18

P9_18

P8_17

17

18

P8_18

P9_19

19

20

P9_20

P8_19

19

20

P8_20

P9_21

21

22

P9_22

P8_21

21

22

P8_22

P9_23

23

24

P9_24

P8_23

23

24

P8_24

P9_25

25

26

P9_26

P8_25

25

26

P8_26

P9_27

27

28

P9_28

P8_27

27

28

P8_28

P9_29

29

30

P9_30

P8_29

29

30

P8_30

P9_31

31

32

P8_31

31

32

P8_32

33

34

P8_33

33

34

P8_34

35

36

P8_35

35

36

P8_36

37

38

P8_37

37

38

P8_38

39

40

P8_39

39

40

P8_40

P9_41

41

42

P9_42

P8_41

41

42

P8_42

43

44

P8_43

43

44

P8_44

45

46

P8_45

45

46

P8_46

Table 103 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 [7]

gpio0_19

NA

NA

I2C#

Cape interface specification provides I2C controller device links for userspace interaction and defined device tree entries for creating compatible overlays for any compliant board and OS image. The device tree node are named as bone_i2c_#.

I2C pins#

Table 104 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]

I2C port mapping#

Table 105 I2C port mapping#

Links

DT symbol

Black

AI

AI-64

SCL

SDA

Overlay

/dev/bone/i2c/0

bone_i2c_0

I2C0

I2C1

WKUP_I2C0

On-board

BONE-I2C0

/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

n/a

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 I2C 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 I2C drivers from userspace.

I2C overlay example#

Listing 15 Example device tree overlay to enable I2C driver#
 1/dts-v1/;
 2/plugin/;
 3
 4&bone_i2c_1 {
 5    status = "okay";
 6    accel@1c {
 7        compatible = "fsl,mma8453";
 8        reg = <0x1c>;
 9    };
10}

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.

I2C userspace example#

See Using I2C with Linux drivers for examples on using the userspace links to load appropriate Linux kernel drivers.

SPI#

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

Table 106 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 107 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

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

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 16 Example device tree overlay to enable SPI driver#
 1/dts-v1/;
 2/plugin/;
 3
 4&bone_spi_0 {
 5    status = "okay";
 6     pressure@0 {
 7         compatible = "bosch,bmp280";
 8         reg = <0>;      /* CS0 */
 9         spi-max-frequency = <5000000>;
10     };
11}

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 108 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 109 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 110 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 111 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 112 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 113 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 114 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

PWM pins#

Table 115 PWM pins#

P9

P8

Functions

odd

even

Functions

Functions

odd

even

Functions

13

14

1 A

2 B

13

14

15

16

1 B

15

16

17

18

17

18

19

20

2 A

19

20

0 B

21

22

0 A

21

22

PWM port mapping#

Table 116 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

/dev/bone/pwm/1

bone_pwm_0

PWM1

PWM3

PWM2

P9.14

P9.16

BONE-PWM1

/dev/bone/pwm/2

bone_pwm_0

PWM2

PWM2

PWM0

P8.19

P8.13

BONE-PWM2

PWM overlay example#

Listing 17 Example device tree overlay to enable PWM driver#
1/dts-v1/;
2/plugin/;
3
4&bone_pwm_0 {
5    status = "okay";
6}

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

PWM userspace example#

See Fading an External LED and Motors for examples on using the userspace links to use the PWMs.

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 117 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 118 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

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

Table 119 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 120 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 121 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 122 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#

SDIO is popular to connect various WiFi modules. The interface can also be used to connect MMC cards.

Important

On Black, the SDIO pins are consumed by default by the on-board eMMC which must be disabled to utilize the SDIO capability. On AI and AI-64, the on-board eMMC does not consume these pins.

Table 123 Bone MMC/SD/SDIO/eMMC#

Header pin

Description

P8.3

DAT6 [9]

P8.4

DAT7 [9]

P8.5

DAT2

P8.6

DAT3

P8.20

CMD

P8.21

CLK

P8.22

DAT5 [9]

P8.23

DAT4 [9]

P8.24

DAT1

P8.25

DAT0

Table 124 Bone SDIO Overlay#

Black

AI

overlay

MMC2

MMC3

BONE-SDIO

LCD#

Table 125 16bit LCD interface#

Header pin

Black

AI

RGB565

P8_27

lcd_vsync

vout1__vsync

VSYNC

P8_28

lcd_pclk

vout1_pclk

PCLK

P8_29

lcd_hsync

vout1_hsync

HSYNC

P8_30

lcd_ac_bias_en

vout1_de

DE

P8_32

lcd_data15

vout1_d15

R4

P8_31

lcd_data14

vout1_d14

R3

P8_33

lcd_data13

vout1_d13

R2

P8_35

lcd_data12

vout1_d12

R1

P8_34

lcd_data11

vout1_d11

R0

P8_36

lcd_data10

vout1_d10

G5

P8_38

lcd_data9

vout1_d9

G4

P8_37

lcd_data8

vout1_d8

G3

P8_40

lcd_data7

vout1_d7

G2

P8_39

lcd_data6

vout1_d6

G1

P8_42

lcd_data5

vout1_d5

G0

P8_41

lcd_data4

vout1_d4

B4

P8_44

lcd_data3

vout1_d3

B3

P8_43

lcd_data2

vout1_d2

B2

P8_46

lcd_data1

vout1_d1

B1

P8_45

lcd_data0

vout1_d0

B0

Table 126 16bit LCD interface Overlay#

Black

AI

overlay

lcdc

dss

I2S#

Todo

Describe I2S and ALSA

I2S pins#

Table 127 I2S pins#

P9

P8

Functions

odd

even

Functions

Functions

odd

even

Functions

11

12

0 SCK_IN

11

12

13

14

13

14

15

16

15

16

17

18

17

18

19

20

19

20

21

22

21

22

23

24

23

24

0 HCLK

25

26

25

26

0 WS_IN

27

28

0 SDO0

27

28

0 WS

29

30

0 SDI0

29

30

0 SCK

31

32

0 SDO1 [8]

31

32

33

34

0 SDI1 [8]

33

34

Important

I2S 0 is used by HDMI audio on Black.

I2S port mapping#

Table 128 I2S port mapping#

I2S

Header pin

Black

AI

AI-64

HCLK

P9.25

mcasp0_ahclkx

mcasp1_ahclkx

AUDIO_EXT_REFCLK2

SCLK

P9.31

mcasp0_aclkx

mcasp1_aclkx

MCASP0_ACLKX

SCLK_IN

P9.12

mcasp0_aclkr_mux3

mcasp1_aclkr

MCASP0_ACLKR

WS

P9.29

mcasp0_fsx

mcasp1_fsx

MCASP0_AFSX

WS_IN

P9.27

mcasp0_fsr

mcasp1_fsr

MCASP0_AFSR

SDO0

P9.28

mcasp0_axr2

mcasp1_axr11

MCASP0_AXR0

SDI0

P9.30

mcasp0_axr0

mcasp1_axr10

MCASP0_AXR1

SDO1

P8.31

mcasp0_axr1

SDI1

P8.33

mcasp0_axr3

Table 129 I2S port mapping link and overlay#

Link

Overlays

/dev/bone/i2s/0

BONE-I2S0

I2S overlay example#

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 UIO or RemoteProc.

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

Table 130 Bone PRU eCAP#

Header Pin

Black

AI

P8.15

pr1_ecap0

pr1_ecap0

P8.32

pr2_ecap0

P9.42

pr1_ecap0

Table 131 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 132 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

Dynamic overlays#

Todo

Document dynamic DT overlays

Dynamic pinmux control#

Todo

Document dynamic pinmux control

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#

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.

References#