Bring Up WiFi On a Yocto Project Image

Yocto Project images use systemd for startup management instead of Sys-V init. One implication of this change is that interfaces configured in /etc/network/interfaces are not always automatically brought up on boot. As a result, bringing up a WiFi interface on boot in systemd-based images cannot be done in the interfaces file.

These instructions will walk you through enabling WiFi from a terminal on a Yocto Project image.

 A Note On These Instructions

Some Gumstix expansion boards do not have a USB console port on them, meaning shell access for most users will be gained via SSH. Because of this, these instructions aim to allow a user to enable WiFi on any expansion board by editing the root filesystem on a development machine before writing it to microSD.

Get a Yocto Project Image

Visit the downloads page and download a Yocto Project image. These instructions have been tested on both console and desktop images.

Desktop images have Network Manager enabled by default, which conflicts with command line networking tools. Users of desktop images should configure their WiFi via the GUI Network Manager or disable Network Manager before boot (see below).

Create a Bootable MicroSD Card

With the files you have just downloaded, create a bootable microSD using the instructions in the getting started guide, but do not unmount the partitions in the last step.

Install a Custom systemd Service

To bring up the wireless interface on boot, you will need to create and install a custom systemd service on the microSD card.

  1. In the rootfs partition, create a new service script:

    $sudoedit rootfs/etc/systemd/system/network-wireless@.service

    In these instructions rootfs refers to the mount point for your microSD card's rootfs partition. If you followed the instructions in the getting started guide, this is /media/rootfs

  2. Copy and paste the following into the file:
    Description=Wireless network connectivity (%i)
    Wants=network.target
    Before=network.target
    BindsTo=sys-subsystem-net-devices-%i.device
    After=sys-subsystem-net-devices-%i.device
    
    [Service]
    Type=oneshot
    RemainAfterExit=yes
    
    ExecStart=/sbin/ifconfig %i up
    ExecStart=/usr/sbin/wpa_supplicant -B -i %i -c /etc/wpa_supplicant.conf
    ExecStart=/sbin/dhclient %i
    RestartSec=1min
    Restart=on-failure
    
    ExecStop=/sbin/ifconfig %i down
    
    [Install]
    WantedBy=multi-user.target
    
    Save this file.
  3. Because we are editing these files on a development machine, the normal systemd method of enabling services (systemctl) will not work. To enable our new service:
    1. Change into the multi-user.target.wants directory on the root filesystem:
      $cd rootfs/etc/systemd/system/multi-user.target.wants/
    2. Create a symbolic link to enable the service:

      DuoVero Series COMs and Pepper SBC:

      $sudo ln -s ../network-wireless@.service network-wireless@mlan0.service

      Overo Series COMs

      $sudo ln -s ../network-wireless@.service network-wireless@wlan0.service

      If you are using a desktop image, disable the Network Manager service by deleting the symlink in this folder before proceeding:

      $sudo rm -s ./NetworkManager.service
  4. Finally, edit the wpa_supplicant configuration file:
    $sudoedit rootfs/etc/wpa_supplicant.conf
    Change it to look like the following:
    network={
        ssid="Your Network's SSID"
        psk="Your WPA2 Passkey"
    }
    
    Save the file.
  5. Unmount the partitions on the microSD card.

Booting Your System with WiFi

Follow any relevant hardware instructions in the Getting Started Guide. Insert the microSD card into the card reader on your system. At this point, you can also establish a serial connection if your expansion board supports it. Then:

  1. Connect the power adapter to your expansion board; the green light on the COM should come on.
  2. Once WiFi is brought up, the red LED on the COM will begin flashing
    • Constant flashing means WiFi has been brought up and has successfully connected to your network.
    • Intermittent flashing means WiFi has been brought up and it is trying to connect to your network, but is failing for some reason. Power off your system, mount the microSD card on your development machine and check the rootfs/etc/wpa_supplicant.conf file has the correct settings.
  3. You may not see the machine on your network right away because DHCP comes up later in the boot process. If you still cannot see the machine on your network after two minutes, verify that your network configuration is correct for DHCP.

SSH Into Your System

You should now be able to SSH into your system. If you do not know the IP address of the system on your network, you can try the following:

Hostname System E.g.,
duovero.local DuoVero Series COMs
$ssh root@duovero.local
overo.local Overo Series COMs
$ssh root@overo.local
pepper.local Pepper SBC
$ssh root@pepper.local

You should now be connected to your system via SSH.