How to use WILC3000 on SAM development boards

Introduction

This page describes how WILC3000 devices could be used on SAM development boards.

Supported devices

The following table specifies the boards where WILC3000 is soldered and the boards where WILC3000 could be soldered.

Board Name Socket Present SAM9X60-EK U24 N* SAMA5D27-WLSOM1-EK1 U4 Y SAMA5D2-ICP U32 N*

*) WILC3000 could be soldered on the corresponding socket

Kernel support

The driver that is used to control the WILC3000 devices is WILC1000 driver. The compatible strings available for these devices are:

"microchip,wilc1000"
"microchip,wilc3000

Overlay support

For boards where WILC3000 module is already soldered on, there is no need to follow the instructions in this chapter.

For boards where WILC3000 module is soldered, the proper device tree overlay should be loaded from U-Boot. To check the available WILC device tree overlays, check the files *_wilc.dtso in the dt-overlay-mchp repository.

To load WILC overlay, follow the next steps:
1. Enter U-Boot prompt by hitting enter when Hit any key to stop autoboot message appears on console:

U-Boot 2019.04-linux4sam_6.2 (Oct 25 2019 - 03:10:23 +0000)

CPU: SAM9X60
Crystal frequency:       24 MHz
CPU clock        :      600 MHz
Master clock     :      200 MHz
DRAM:  256 MiB
MMC:   sdhci-host@80000000: 0
Loading Environment from FAT... OK
In:    serial
Out:   serial
Err:   serial
Net:   eth0: ethernet@f802c000
Hit any key to stop autoboot:  3

2. Edit bootcmd U-Boot environment variable and add #wilc string at the end:

U-Boot> edit bootcmd
edit: fatload mmc 0:1 0x24000000 sam9x60ek.itb; bootm 0x24000000#kernel_dtb#wilc

3. Enter boot command. The Linux kernel would be loaded using the WILC device tree overlay:

U-Boot> boot
4508836 bytes read in 225 ms (19.1 MiB/s)
## Loading kernel from FIT Image at 24000000 ...
   Using 'kernel_dtb' configuration
   Trying 'kernel' kernel subimage
     Description:  Linux4SAM Linux kernel
     Type:         Kernel Image
     Compression:  uncompressed
     Data Start:   0x240000d8
     Data Size:    4447104 Bytes = 4.2 MiB
     Architecture: ARM
     OS:           Linux
     Load Address: 0x22000000
     Entry Point:  0x22000000
     Hash algo:    crc32
     Hash value:   2c706949
     Hash algo:    sha1
     Hash value:   d8d72f7fb8603a35a39a6803d9b418abebbca9a5
   Verifying Hash Integrity ... crc32+ sha1+ OK
## Loading fdt from FIT Image at 24000000 ...
   Using 'kernel_dtb' configuration
   Trying 'base_fdt' fdt subimage
     Description:  SAM9X60-EK Flattened Device Tree blob
     Type:         Flat Device Tree
     Compression:  uncompressed
     Data Start:   0x2443dd90
     Data Size:    28407 Bytes = 27.7 KiB
     Architecture: ARM
     Load Address: 0x23000000
     Hash algo:    crc32
     Hash value:   b8c3d3b7
     Hash algo:    sha1
     Hash value:   b538fc9f410be576b6bba6e18add7010e68f6f7b
   Verifying Hash Integrity ... crc32+ sha1+ OK
   Loading fdt from 0x2443dd90 to 0x23000000
## Loading fdt from FIT Image at 24000000 ...
   Using 'wilc' configuration
   Trying 'fdt_wilc' fdt subimage
     Description:  Device Tree blob WILC3000 overlay
     Type:         Flat Device Tree
     Compression:  uncompressed
     Data Start:   0x2444b168
     Data Size:    1572 Bytes = 1.5 KiB
     Architecture: ARM
     Load Address: 0x23180000
     Hash algo:    crc32
     Hash value:   e8fbf3b2
     Hash algo:    sha1
     Hash value:   e36920209c1e758e6e67207b4a1646896b3a8784
   Verifying Hash Integrity ... crc32+ sha1+ OK
   Loading fdt from 0x2444b168 to 0x23180000
   Booting using the fdt blob at 0x23000000
   Loading Kernel Image ... OK
   Loading Device Tree to 2feeb000, end 2fef51c8 ... OK

Starting kernel ...

Configuration steps

Kernel module

To be able to use the WILC devices, the following kernel needs to be inserted after kernel boots:

cfg80211.ko
pwrseq_sd8787.ko
wilc-sdio.ko

Check that the above modules are inserted by running lsmod command:

root@sama5d27-wlsom1-ek-sd:~# lsmod                                                                                                             
Module                  Size  Used by                                                                                                          
pwrseq_sd8787          12288  1                                                                                                                 
cfg80211              311296  0                                                                                                                
usb_f_acm             12288  1                                                                                                                
u_serial               16384  1 usb_f_acm                                                                                                       
g_serial              12288  0                                                                                                                
libcomposite           40960  2 g_serial,usb_f_acm                                                                                             
atmel_usba_udc         20480  0                                                                                                                
autofs4                24576  0  

If one of the above modules is missing, try inserting them using insmod or modprobe command. In the above example, the wilc-sdio.ko module is missing. To insert it:

root@sama5d27-wlsom1-ek-sd:~# insmod /lib/modules/$(uname -r)/kernel/drivers/net/wireless/microchip/wilc1000/wilc-sdio.ko
wilc_sdio mmc1:0001:1: Driver Initializing success

In case the other modules are missing, try inserting them using insmod or modprobe commands:

insmod /lib/modules/$(uname -r)/kernel/net/wireless/cfg80211.ko
insmod /lib/modules/$(uname -r)/kernel/drivers/mmc/core/pwrseq_sd8787.ko
insmod /lib/modules/$(uname -r)/kernel/drivers/net/wireless/microchip/wilc1000/wilc-sdio.ko

After all kernel modules are installed, the wlan0 interface should appear in ifconfig:

root@sama5d27-wlsom1-ek-sd:~# ifconfig -a
eth0      Link encap:Ethernet  HWaddr 54:10:ec:ff:fa:16  
          UP BROADCAST MULTICAST  MTU:1500  Metric:1
          RX packets:0 errors:0 dropped:0 overruns:0 frame:0
          TX packets:0 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:1000 
          RX bytes:0 (0.0 B)  TX bytes:0 (0.0 B)
          Interrupt:30 Base address:0x8000 

lo        Link encap:Local Loopback  
          inet addr:127.0.0.1  Mask:255.0.0.0
          inet6 addr: ::1/128 Scope:Host
          UP LOOPBACK RUNNING  MTU:65536  Metric:1
          RX packets:2 errors:0 dropped:0 overruns:0 frame:0
          TX packets:2 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:1000 
          RX bytes:140 (140.0 B)  TX bytes:140 (140.0 B)

p2p0      Link encap:Ethernet  HWaddr 00:00:00:00:00:00  
          BROADCAST MULTICAST  MTU:1500  Metric:1
          RX packets:0 errors:0 dropped:0 overruns:0 frame:0
          TX packets:0 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:1000 
          RX bytes:0 (0.0 B)  TX bytes:0 (0.0 B)

sit0      Link encap:UNSPEC  HWaddr 00-00-00-00-00-00-00-00-00-00-00-00-00-00-00-00  
          NOARP  MTU:1480  Metric:1
          RX packets:0 errors:0 dropped:0 overruns:0 frame:0
          TX packets:0 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:1000 
          RX bytes:0 (0.0 B)  TX bytes:0 (0.0 B)

wlan0     Link encap:Ethernet  HWaddr 00:00:00:00:00:00  
          BROADCAST MULTICAST  MTU:1500  Metric:1
          RX packets:0 errors:0 dropped:0 overruns:0 frame:0
          TX packets:0 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:1000 
          RX bytes:0 (0.0 B)  TX bytes:0 (0.0 B)

From here on, the WILC device could be used in either direct WiFi client mode, Access Point mode or BT.

Configuration modes using systemd

Client mode

In this mode, a WILC device would behave as a WiFi client by connecting to an Access Point device and requesting from it IP addresses, DNS etc.

Step-by-step configuration

To work in this mode, create or edit the /etc/wpa_supplicant.conf file. The content of file should be as follows:

ctrl_interface=/var/run/wpa_supplicant
update_config=1
network={
    ssid="access-point-name"
    psk="access-point-password"
}

Where the SSID and PSK variables keep the access point name and password, the WILC device will be connected. Save the file.

Stop the hostapd service using the following command (if it is already running ):

systemctl stop hostapd@<Configured authentication mode>

where Configured authentication mode might be any one of open, wpa or wep.

Replace network configurations from existing examples in rootfs and start the WPA supplicant service using the following commands:

For Buildroot:

cp /usr/lib/systemd/system/wpa_supplicant.service.example /etc/systemd/system/wpa_supplicant.service
cp /usr/lib/systemd/network/80-wifi-station.network.example /etc/systemd/network/wlan0.network
systemctl restart wpa_supplicant.service

For Yocto Project:

cp /lib/systemd/network/80-wifi-station.network.example /etc/systemd/network/wlan0.network
systemctl restart wpa_supplicant.service

Reload the network configuration using the following command:

networkctl reload

At this point, an IP address should be assigned to the WLAN interface, and IP connectivity should be active.

Pre-defined script

Starting with the Linux4SAM-2020.04 release, for boards where WILC devices are soldered, the Buildroot root file system provides a demo script that allows configuring WILC devices in STA mode by running just one command. To do this, run the following script:

 /root/Start_STA.sh 

Note: Starting with the Linux4SAM-2024.04 release, the Yocto Project also includes the predefined scripts in root filesystem.

Provisioning mode

Starting with the Linux4SAM-2020.04 release for boards where WILC devices are soldered, the Buildroot root file system provides a provisioning mechanism that allows the configuration of WILC devices in STA mode.

To start provisioning, execute the script /root/Start_Provision.sh:

/root/Start_Provision.sh

This will reboot the board. After reboot, the WILC device will enter SoftAP mode with name wilc_SoftAP and IP 192.168.0.1. This allow connecting to the WILC device using any Wi-Fi device for provisioning. Connecting to 192.168.0.1 will allow the configuration for Access Point to connect to. The meaning of fields in the opened web page are as follows:

Network Name: The Access Point name that WILC in STA mode should connect to
Pass phrase: The Access Point password
Device Name: The name of the WILC device

After filling in the above fields and pressing the Connect button, the board will reboot, and the WILC device will start in STA mode and connect to the configured access point.

Access Point mode

WILC device could work in Access Point mode in different configurations depending on the level of security. This could be Open, WEP, or WPA, where the default access point names for Yocto Project would be wilc_OpenAP (No Password), wilc_WepAP (Password = 1234567890) and wilc_WpaAP (Password = 12345678) respectively.

To configure custom ssid names and passphrases, one can edit hostapd configuration files available in the /etc/* directory, where the configuration file could be one of the following:

/etc/wilc_hostapd_open.conf
/etc/wilc_hostapd_wep.conf
/etc/wilc_hostapd_wpa.conf

Note: Starting with the Linux4SAM-2024.04 release, both Buildroot and the Yocto Project root filesystem include the required hostapd configuration files in the /etc/* directory itself.

Stop the wpa_supplicant service using the following command( if it is already running):

systemctl stop wpa_supplicant.service

Replace network configurations from existing examples in rootfs and reload network configurations using the following commands:

For Buildroot:

cp /usr/lib/systemd/system/hostapd@.service.example /etc/systemd/system/hostapd@.service
cp /usr/lib/systemd/network/80-wifi-softap.network.example /etc/systemd/network/wlan0.network
networkctl reload

For Yocto Project:

cp /lib/systemd/network/80-wifi-softap.network.example /etc/systemd/network/wlan0.network
networkctl reload

Bring up the wlan0 interface using the following command:

networkctl up wlan0

Start Access Point

To start WILC working in Access Point:

Start the hostapd service with any one of the following commands, depending on authentication:

systemctl start hostapd@open.service

or

systemctl start hostapd@wpa.service

or

systemctl start hostapd@wep.service

This will start the WILC device in the corresponding access point mode.Connect from an WiFi client to the newly created access point and try a ping.

To switch between different authentication modes in run time, make sure the current hostapd service stopped properly using systemctl stop command and wilc-sdio module need to be reloaded using insmod or modprobe command.

Note: Default build support for WEP Authentication was removed from the hostapd 2.10 version, so this test will fail by default. (CONFIG_WEP=y can be used to enable it if needed).

Configuration modes using SysVinit

Client mode

In this mode, a WILC device would behave as a WiFi client by connecting to an Access Point device and requesting from it IP addresses, DNS, etc.

Step by step configuration

To work in this mode, create or edit the /etc/wpa_supplicant.conf file. The content of file should be as follows:

ctrl_interface=/var/run/wpa_supplicant
update_config=1
network={
    ssid="access-point-name"
    psk="access-point-password"
}

Where the SSID and PSK variables keep the access point name and password, the WILC device will be connected. Save the file.

Start the WPA supplicant service using the following command:

wpa_supplicant -B -iwlan0 -Dnl80211 -c /etc/wpa_supplicant.conf &

Initiate a DHCP request so that a proper IP address and DNS settings can be installed for the WILC device:

udhcpc -i wlan0 &

At this point, an IP address should be assigned to the WLAN interface, and IP connectivity should be active.

Access Point mode

WILC device could work in Access Point mode in different configurations depending on the level of security. This could be Open, WEP, WPA.

Open Access Point configuration

For this mode, create or edit the /etc/wilc_hostapd_open.conf file as follows:

interface=wlan0
driver=nl80211
ctrl_interface=/var/run/hostapd
ssid=wilc_OpenAP
dtim_period=2
beacon_int=100
channel=7
hw_mode=g
max_num_sta=8
ap_max_inactivity=300 

Where the Access Point name would be wilc_OpenAP.

WEP Access Point configuration

For this mode, create or edit the /etc/wilc_hostapd_wep.conf file as follows:

interface=wlan0
driver=nl80211
ctrl_interface=/var/run/hostapd
ssid=wilc_WepAP
dtim_period=2
beacon_int=100
channel=7
hw_mode=g
max_num_sta=8
ap_max_inactivity=300
ieee80211n=1
auth_algs=1

######### WEP ###########
wep_default_key=0
wep_key0=1234567890
wep_key1="vwxyz"
wep_key2=0102030405060708090a0b0c0d
wep_key3=".2.4.6.8.0.23"
wep_key_len_broadcast=5
wep_key_len_unicast=5
wep_rekey_period=300

Where the access point name would be wilc_WepAP and password =1234567890.

Note: Default build support for WEP Authentication was removed from the hostapd 2.10 version, so this test will fail by default. (CONFIG_WEP=y can be used to enable it if needed).

WPA Access Point configuration

For this mode, create or edit the /etc/wilc_hostapd_wpa.conf file as follows:

interface=wlan0
driver=nl80211
ctrl_interface=/var/run/hostapd
ssid=wilc_WpaAP
dtim_period=2
beacon_int=100
channel=7
hw_mode=g
max_num_sta=8
ap_max_inactivity=300
ieee80211n=1
auth_algs=1

######### WPA/WPA2 ###########
wpa=3
wpa_passphrase=12345678
wpa_key_mgmt=WPA-PSK
wpa_pairwise=TKIP CCMP
rsn_pairwise=CCMP

Where the Access Point name would be wilc_WpaAP and password would be 12345678.

DHCP server configuration

To enable offering IPs to WiFi clients DHCP server service have to be enabled.

Create or edit* /etc/dhcp/dhcpd.conf with the following content (if the image is based on Buildroot):

option domain-name "tecmint.lan";
option domain-name-servers ns1.tecmint.lan, ns2.tecmint.lan;
default-lease-time 3600;
max-lease-time 7200;
authoritative;

subnet 192.168.1.0 netmask 255.255.255.0 {
        option routers                  192.168.1.1;
        option subnet-mask              255.255.255.0;
        option domain-search            "tecmint.lan";
        option domain-name-servers      192.168.1.1;
        range   192.168.1.10   192.168.1.100;
        range   192.168.1.110   192.168.1.200;
}

If the image is based on the Yocto Project, Create or edit* /etc/kea/kea-dhcp4.conf with the contents below:

{
  "Dhcp4": {
    "interfaces-config": {
      "interfaces": ["wlan0"]
    },
    "subnet4": [
      {
        "subnet": "192.168.1.0/24",
        "pools": [
          { "pool": "192.168.1.100 - 192.168.1.200" }
        ],
        "option-data": [
          { "code": 3, "data": "192.168.1.1" },
          { "code": 6, "data": "192.168.1.1, 8.8.8.8" }
        ]
      }
    ]
  }
}

Start Access Point

To start WILC working in Access Point: 1. Start hostapd service with file configured above:

hostapd -B <configuration file>

where the configuration file could be one of the following:

/etc/wilc_hostapd_open.conf
/etc/wilc_hostapd_wep.conf
/etc/wilc_hostapd_wpa.conf

2. Configure an IP address for the wlan0 interface:

ifconfig wlan0 192.168.1.1 netmask 255.255.255.0 up

3. Start DHCP server:

For Buildroot:

dhcpd -cf /etc/dhcp/dhcpd.conf

For Yocto Project:

keactrl start

This will start WILC device in Open Access Point mode.

4. Connect from an WiFi client to newly created access point and try a ping.

Bluetooth mode

To be able to use WILC device in Bluetooth mode on devices where WILC device is not soldered to the board, user has to wire WILC BT serial with one of the serials supported by SoC. The table below specifies what serial pins could be used on SAM boards. On boards where WILC device is soldered, there is no need for extra wires and the table specifies NA in connector and connector pins columns.

Board Name Serial Connector Connector Pins SAM9X60-EK ttyS1 J14 TX, RX SAMA5D2-ICP ttyS3 J22 TX, RX SAMA5D2-Xplained ttyS1 J17 27, 28 SAMA5D4-Xplained ttyS5 J17 9, 10 SAMA5D27-SOM1-EK ttyS1 J25 3, 4 SAMA5D27-WLSOM1-EK1 ttyS1 J19 TX, RX SAMA5D3-Xplained ttyS1 NA NA SAMA5D2-PTC-EK ttyS1 J15 3, 4

Step-by-step configuration

Insert the next commands to configure WILC device in Bluetooth mode:

echo BT_SDIO_INIT > /dev/wilc_bt
echo BT_POWER_UP > /dev/wilc_bt
echo BT_FW_CHIP_WAKEUP > /dev/wilc_bt
echo BT_DOWNLOAD_FW > /dev/wilc_bt
echo BT_FW_CHIP_ALLOW_SLEEP > /dev/wilc_bt
hciattach <bluetooth-serial> any 115200 noflow # see table at the beginning of this chapter
hciconfig hci0 up
ln -svf /usr/libexec/bluetooth/bluetoothd /usr/sbin
bluetoothd -p time -n &

If the last command returns a D-Bus error, check if the bluetooth daemon is already started. If yes, kill it and retry the last command:

kill bluetoothd
bluetoothd -p time -n &

Check bluetooth interface status:

hciconfig -a

Enable LE activity:

hciconfig hci0 leadv

Try to scan and connect to a device.

bluetoothctl
scan on
connect <identifier-listed-by-scan>

If scan fails, run the following command:

power on

Pre-defined script

Starting with Linux4SAM-2020.04 release for boards where WILC device are soldered, Buildroot root file system provides a demo script that allows configuring WILC device in Bluethoot mode by running just one command. To do this, run the following script:

/root/Start_BT.sh

This will start WILC device in Bluetooth mode.

References

The above documentation is inspired from documentation already present on Microchip WILC3000 webpage, more precisely the ATWILC1000/ATWILC 3000 Wi-Fi Link Controller Linux User Guide.