Bela as a UART adapter

Bela can be used as a UART adapter, on this page we explain how.

Table of contents

  1. Picking a UART port
  2. Enabling the UART port
  3. Connecting to the UART port
  4. A practical example: using Bela to connect via UART to another Bela board
    1. Preparing Bela2
    2. Wiring
    3. Remote connection

Sometimes you desperately need a way to interface over UART to a device and you have no dedicated FTDI cable around. Well, despair not: if you have a Bela around, you can use it as a UART adapter! After all, you have command-line access to this little computer, which comes with a number of UART ports, ideal to be interfaced directly with any 3.3V UART device. DO NOT interface directly to 5V UART devices: you will need external components for that.

Picking a UART port

A number of UART ports are available on the BeagleBone (Bela) and Pocket Beagle (BelaMini), however the corresponding pins are often used by parts of the Bela board (see here for the complete pinouts and the pins used on each board). Port UART4 is available for use on both Bela and BelaMini, so we will use this for this example. The corresponding pins are (straight off the pinouts documents above):

  • on Bela:
    • UART4_RXD: P9_11
    • UART4_TXD: P9_13
  • on BelaMini (also marked on the bottom of the board):
    • UART4_RXD: P2_05
    • UART4_TXD: P2_07

Enabling the UART port

In order to enable the UART port, you have to load a device tree overlay that takes care of enabling the peripheral and multiplexing the pins. This is explained in detail here, using the very UART4 port as an example.

Connecting to the UART port

The UART ports are showing up as device files on the Bela board:

  • On Bela image older than v0.3.0
    • the UART ports can be found at /dev/ttyGx, where x is the number of the UART port. Port 4, for instance, would be /dev/ttyG4.
  • On Bela v0.3.0 or newer
    • the UART ports can be found at /dev/ttySx, where x is the number of the UART port. Port 4, for instance, would be /dev/ttyS4.

You can then use the regular Linux interface to connect to the port, for instance with open(), read() and write(), close() operations on the device file from a C program, or directly from the terminal, for instance using the screen command. The approach you chose depends on the device you are connecting to and the operations you need to perform.

A practical example: using Bela to connect via UART to another Bela board

Once you have a Bela properly configured as above (let’s call it Bela1), you can for instance try to connect into another Bela board (Bela2). This can be useful for troubleshooting Bela2, especially in the case when it does not boot properly, or it does not show up as a network interface on the host. Each Bela board by default uses the UART0 port to spit out the system log and to provide remote access over UART.

Preparing Bela2

If Bela2 is a Bela board on a BeagleBone, there is no software preparation needed. However, you will need to remove the Bela cape in order to access the UART0 pins, which are on a header on the BeagleBone itself. You will then need socket-to-pin jumper wires.

If Bela2 is a BelaMini, no hardware setup is needed, but you will have to make sure that the pins for UART0 are multiplexed properly. This is because, by default, those pins are multiplexed as GPIOs, once Linux boots, in order to be used as Bela Digital I/O pins. The easiest way to restore the default functions for those pins is to disable the Bela device tree overlay:

  • insert the SD card on a computer
  • make a backup copy of the uEnv.txt file in the BELABOOT partition
  • edit the uEnv.txt file on the BELABOOT partition by commenting out (prepending a #) to the following line:

    so that it becomes

  • safely eject the SD card, insert on BelaMini and boot

Note that this will temporarily prevent the Bela programs from running, and you will have to reverse the change and reboot the board in order for the Bela programs to work again.


  • Identify the pins corresponding to UART4 on the Bela1.
    • see above for the UART4 pins.
    • additionally, you will need a GND pin (e.g.: P9_01 on the BeagleBone/Bela and P1_16 on PocketBeagle/BelaMini.
  • Identify the pins corresponding to UART0 on the Bela2.
    • If Bela2 is a BeagleBone/Bela, the pins are on the J1 male header on the BeagleBone. The relevant pins are:
      • GND: pin 1
      • UART0_RX: pin 4
      • UART0_TX: pin 5
    • If Bela2 is a PocketBeagle/BelaMini, the relevant pins are:
      • GND: P1_22
      • UART0_RX: P1_32
      • UART0_TX: P1_30
  • Using the appropriate type of jumper wire, connect:
    • GND on Bela1 to GND on Bela2
    • UART4_RX on Bela1 to UART0_TX on Bela2
    • UART4_TX on Bela1 to UART0_RX on Bela2
    • note that the RX pin at one end goes to the TX pin at the other end

Remote connection

Once all the above preparation steps are done, you can then use UART4 on Bela1 to log into Bela2, or see its system log.

  • turn off Bela2
  • Run the following command on Bela1:
    screen /dev/ttyS4 115200

    (or use /dev/ttyG4 if you are on Bela image earlier than v0.3.0).

  • turn on Bela2

  • You will see first the u-boot log. If there is a problem with starting Linux, you will see an error and the log will stop. If Linux starts successfully, you will see the Linux log, until you get prompted with a login screen.
  • Enter root as the user, no password is needed.
  • You are now logged into Bela2.
  • If you are here to troubleshoot the network connection over the USB port to the host, start off with ip a: do the usb0 and usb1 devices show up and have an IP address? Then check with lsmod that modules libcomposite, usb_f_ecm, usb_f_rndis are loaded. If they are not there, Check the system log dmesg for any errors regarding these modules.
  • Once you are done, to exit from the screen, do ctrl-a(to switch to command mode) and type :quit.