The IP address(es) of Bela - BelaPlatform/Bela GitHub Wiki

This material has been superseded. Visit learn.bela.io for the maintained version.

Bela shows up as a network interface on the host computer. Through this network interface you can access the IDE, and ssh on to the board. Starting from Bela image v0.3.5, released in July 2018, it actually shows up as one or even two network interfaces. Each of these interfaces will have a distinct range of IP addresses: 192.168.7.x or 192.168.6.x. On each of these networks, the IP of the host (your computer!) will end with 1, while the IP address of the board will end with 2. The boards can also be found (assuming your OS has the relevant mDNS/Bonjour/Avahi services installed) at the hostname bela.local (though sometimes to get it to work on the browser you need the full path: http://bela.local/).

Changelog

Versions of the Bela image < 0.3.5 will only show up at 192.168.7.2, only through a RNDIS interface, so they will need the HORNDiS drivers on macos. Versions >= 0.3 should work on Windows without drivers. Versions < 0.3 will not respond at the bela.local address. Versions v0.3.5 and v0.3.5a were affected by a bug, and you should upgrade.

Why multiple interfaces?

Well, it turns out that macos and Windows both support a specific class of USB networking devices out of the box, without the need for installing additional drivers. As you'd expect, this means that they support without drivers two different classes of the device. An RNDIS device will work on Windows without drivers, or on Mac using the HORNDiS driver; an ECM device will work without drivers on macos >=10.9. By providing two separate interfaces via USB, we can guarantee that at least one of the two will work fine on the host operating system without need for drivers, except for rare cases (e.g.: macos < 10.9).

OS / interfaces:

On Linux, both interfaces should show up as two separate interfaces, so both 192.168.7.x and 192.168.6.x. In many cases it will also work as http://bela.local/ .

On macos 10.9 and above and below macos 10.15(Catalina), without the HORNDiS drivers installed, the 192.168.7.x will show up without need for drivers. On any version of macos (that we could test, probably as far back as 10.7), with a working HORNDiS driver installed, it will (also?) show up as 192.168.6.x. In both cases it should always works at http://bela.local/.

On Windows (Vista and above) it will show up as 192.168.6.x, without need for drivers. It may work at http://bela.local/ if a suitable discovery service is running (e.g.: Apple Bonjour).

The magic in the numbers

IPs

On the board (again, after image v0.3.5), the RNDIS device will show up as network interface usb0, while the ECM device will be usb1. The IP addresses of the boards on each of the usbX networks are set in /etc/network/interfaces:

# USB RNDIS gadget (Windows / Linux compatible)
auto usb0
iface usb0 inet static
    address 192.168.6.2
    netmask 255.255.255.0
    network 192.168.6.0

# USB ECM gadget (macOS / Linux compatible)
auto usb1
iface usb1 inet static
    address 192.168.7.2
    netmask 255.255.255.0
    network 192.168.7.0

As well as self-assigning an IP address, the board runs a DHCP server, to be able to assign an IP address to the host computer. This is set in /etc/dhcp/dhcpd.conf, for each subnetwork corresponding to the separate interfaces:

subnet 192.168.7.0 netmask 255.255.255.0 {
        range 192.168.7.1;
}

subnet 192.168.6.0 netmask 255.255.255.0 {
        range 192.168.6.1;
}

Who's who?

The USB driver creates one (or two, it both the above are supported by the host operating system) local network between Bela and the host computer, where each of the two devices has a different IP.

The host computer will always be 192.168.7.1 or 192.168.6.1 (assigned by the DHCP server on the board in /etc/dhcp/dhcpd.conf, see above)
The Bela board will always be 192.168.7.2 or 192.168.6.2 (self-assigned by the board in /etc/network/interfaces, see above)

As usual, each device can talk to itself via the network at the IP address 127.0.0.1, or equivalently the named server localhost (this is definitely true for the Bela board, and should be the default for most hosts).

MAC addresses

The MAC addresses for the network devices on the host and client side are generated (from v0.3.5b onwards) by /opt/Bela/bela_mac.sh in such a way that they are unique for each device (thanks to a unique value stored in the EEPROM), and consistent at every reboot. The generated addresses are then loaded into the driver by /opt/Bela/bela_gadget.sh. The MAC addresses on the host side start with BE:1A (...). When two devices show up on the host, the RNDIS device will have the smaller of the two MAC address, and the ECM one will have the higher ( the one of the RNDIS one +4).

How to change the IP address(es)

From the above it should now be clear that in order to change the IP address of the board, and still have it play well with the host, you have to make changes in at least two places: /etc/network/interfaces, to change the self-assigned address, and /etc/dhcp/dhcpd.conf to change the range of IP addresses given out by the DHCP server.

For instance, if you want a board to show up at 192.168.8.2 on the ECM interface usb1 (the interface automatically recognized on modern versions of macos), and the host to be assigned 192.168.8.1, you would do something like this: edit the relevant part of /etc/network/interfaces, turning all the 192.168.7. into 192.168.8.:

# USB ECM gadget (macOS / Linux compatible)
auto usb1
iface usb1 inet static
    address 192.168.8.2
    netmask 255.255.255.0
    network 192.168.8.0

and similarly for /etc/dhcp/dhcpd.conf:

subnet 192.168.8.0 netmask 255.255.255.0 {
        range 192.168.8.1;
}

Using multiple Bela boards at the same time

If you want to use multiple Belas at the same time, you should make sure that each of them responds to a different IP address and that its DHCP server is set appropriately as explained above. If your operating system's driver can handle multiple devices of the same class then, you should be able to access them together. Under macos you should use the ECM -class devices (the HORNDiS driver does not support multiple devices at the same time). Not sure about the RNDIS driver on Windows or both drivers on Linux?

Notes

DHCP

You don't actually need the DHCP server. As an advanced setting, you could even disable the DHCP server altogether and simply set your host to a fixed IP address (by changing your network settings on the host). One reason why you may want to do this is to get the board to show up more quickly on the host after boot, especially if under heavy CPU load (e.g.: with a Bela program running at startup).

A short-lived bug

On v0.3.5 and v0.3.5a, the two interfaces would show up with a new MAC address at each reboot (see issue). This would cause the interface count on the host to increase every time, as the network interfaces were always recognized as "new" ones. The primary consequence of this was that it was not possible to store settings for each network interface (e.g.: in case you wanted to set them to a static address), however this is likely to have not affected many users, as it is a pretty advanced use case. On macos this also meant that the file /Library/Preferences/SystemConfiguration/preferences.plist would keep growing, and so would the displayed interfaces in System Preferences -> Networks. As a consequence of this, (possibly for a macos bug?) some users experienced a very long wait time before after the network interfaces on the host were assigned an IP address. A quick fix was to enforce macos to go and ask the DHCP server for an IP on the interface enXXX:

sudo ipconfig set enXXX dhcp

this would almost immediately end up with the device having the correct IP address assigned. As an alternative, you could also manually set the IP address:

sudo ifconfig enXXX up 192.168.7.1

Both of these fixes are temporary until the board is plugged in again.

A more lasting fix, besides the obvious one of updating the Bela image, was to put in /opt/Bela/bela_gadget.sh this updated version of the file and also add https://github.com/BelaPlatform/bela-image-builder/blob/master/misc/rootfs/opt/Bela/bela_mac.sh in /opt/Bela/bela_mac.sh.

After the more lasting fix, it is convenient to delete /Library/Preferences/SystemConfiguration/preferences.plist on the host, and reboot. This would discard all the stored settings for specific network interfaces (e.g.: static IP configurations), and forget all the interface MAC addresses that proliferated because of plugging in the bugged device multiple times. Note that this will not delete stored wifi networks and passwords.