> For the complete documentation index, see [llms.txt](https://docs.morsemicro.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.morsemicro.com/application-notes/appnote-24-linux-porting-guide.md). # APPNOTE-24 Linux Porting Guide [Download as PDF](https://www.morsemicro.com/resources/appnotes/MM_APPNOTE-24_Linux_Porting_Guide.pdf) ## 1 Scope This guide will demonstrate the steps required to integrate Morse Micro Wi-Fi HaLow into an existing Linux based target platform. This document does not intend to be a tutorial for building Linux based firmware from scratch, nor will it discuss integration details into build systems such as Yocto, OpenWrt, or Buildroot. Additionally, this document focuses on artefacts delivered by Morse Micro, and will not cover how to compile dependencies, and other, general, software utilities which may be required for wireless devices. ## 2 Requirements Before integrating HaLow into a project, a developer should ensure they have the following resources prepared: * a toolchain for the target platform; * the Linux kernel source, checked out to a compatible version; * the Linux kernel configuration, as required for their target; * compiled user space libraries such as OpenSSL and libnl, required for the Morse Micro user space software utilities; * compiled user space applications, such as iw and ip (BusyBox ip is sufficient). Morse Micro will provide: * the MM6108 driver source; * kernel patches for a list targeting compatible kernel versions, below; * hostapd/wpa\_supplicant source modified for 802.11ah support; * morse\_cli source - the user space control utility for MM6108; * MM6108 firmware binaries; * BCF binaries for Morse Micro designed HaLow modules - to be used as a reference. Note that HaLow modules from other manufacturers using MM6108 may require a different BCF. The developer should consult the manufacturer. Devices directly incorporating MM6108 into their design will need to create their own BCF binaries. This guide will use the 1.15.3 driver and associated files, available for download from [https://github.com/MorseMicro](https://www.google.com/url?q=https://github.com/MorseMicro\&sa=D\&source=editors\&ust=1783470657716308\&usg=AOvVaw054g65abgDK4BSczSaOL52). *** The MorseMicro software releases are designed around the following kernels from [https://github.com/raspberrypi/linux](https://www.google.com/url?q=https://github.com/raspberrypi/linux\&sa=D\&source=editors\&ust=1783470657716533\&usg=AOvVaw1Of6k6cqgKbhNhm7cm_B0P): | Version | git tag | | ------- | -------------------------------- | | 4.9.80 | raspberrypi-kernel\_1.20180313-1 | | 4.14.98 | raspberrypi-kernel\_1.20190401-1 | | 4.19.66 | raspberrypi-kernel\_1.20190819-1 | | 5.4.83 | raspberrypi-kernel\_1.20210108-1 | | 5.10.11 | raspberrypi-kernel\_1.20210201-1 | | 5.15.61 | 1.20220830 | | 6.1.21 | 1.20230405 | | 6.6.19 | stable\_20240529 | However, to demonstrate Linux integration more generally, the remainder of this document will provide examples based on a 6.1.137 Linux Kernel and a 1.15.3 Morse Micro software release. *** ## 3 Applying Kernel Modifications Before compiling the Linux kernel, a small number of modifications are required to enable various S1G features. These patches can be seen in the linux repository at: [https://github.com/MorseMicro/linux/](https://www.google.com/url?q=https://github.com/MorseMicro/linux/\&sa=D\&source=editors\&ust=1783470657719135\&usg=AOvVaw3l5VmpOpehX1vh1byHQXNI) Note that there are different branches for different kernel versions, but unless your kernel version is exactly the same you may have to make minor adjustments when integrating them with your kernel. Therefore the easiest path is to build this kernel as you would normally for your platform. However, if you need to apply these changes to your existing kernel, follow one of the sections below. ### 3.1 Existing git repository If you have an existing git repository that is a fork of the normal Linux repository, you can add this repository as a remote and merge the appropriate branch. For instance, if you were using a 6.1 kernel: |

git remote add mmlinux
git fetch mmlinux
git merge mm/linux-6.1.21/1.15.x

| | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | Alternatively, you may wish to cherrypick only the relevant commits, particularly if your kernel tree isn’t based on the normal Linux one: | git cherry-pick v6.1.21..mmlinux/mm/linux-6.1.21/1.15.x | | ------------------------------------------------------- | ### 3.2 Using patch files If you would prefer to apply patch files, you can either use the github web interface to generate them by adding .patch to commit URLs in the history - e.g. [https://github.com/MorseMicro/linux/commit/73969e73764a93bdffa28928c236ac5101ed25d0.patch](https://www.google.com/url?q=https://github.com/MorseMicro/linux/commit/73969e73764a93bdffa28928c236ac5101ed25d0.patch\&sa=D\&source=editors\&ust=1783470657720885\&usg=AOvVaw3b_8PFvYY44y1-XOFkhvId) - or clone the repository and use git format-patch: |

git clone
cd linux
git checkout mm/linux-6.1.21/1.15.x
git format-patch v6.1.21

| | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | This will generate a number of patch files in the same directory which you can apply with git am or patch. ## 4 Compiling the Driver Before compiling the driver, please ensure you’ve compiled your kernel as normal with appropriate ARCH and CROSS\_COMPILE environment variables configured as required. The Morse Micro driver produces two modules. * morse.ko is the core driver for both SPI and SDIO attached devices. It provides core bus communication logic and network device registration. * dot11ah.ko the shim layer, responsible for translating 802.11ah channel and rate information into 802.11ac, including 802.11ah specific frames such as S1G probe requests. If the Morse Micro driver is recompiled, it is strongly recommended to update both modules in the system. Failure to do so can result in significantly reduced throughput or, possibly, a complete communication failure. To compile the driver, execute the following commands |

git clone
cd morse\_driver
git checkout
git submodule update --init --recursive
make KERNEL\_SRC=../linux \
CONFIG\_WLAN\_VENDOR\_MORSE=m \
CONFIG\_MORSE\_USER\_ACCESS=y CONFIG\_MORSE\_VENDOR\_COMMAND=y

| | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | This will compile morse.ko and dot11ah.ko which can be installed into /lib/modules/\/ of the target rootfs. Additional compile time configuration options are available. For an up-to-date list, and detailed descriptions of the fields, inspect the Kconfig file in the source. Notably, to compile the driver for an SDIO or SPI attached device, one would need to use CONFIG\_MORSE\_SDIO=y or CONFIG\_MORSE\_SPI=y. To enable test modes set CONFIG\_MORSE\_ENABLE\_TEST\_MODES=y. ## 5 Firmware Binaries Before the module can be inserted, in a running platform, two binary files need to be installed into /lib/firmware/morse of the rootfs: * the chip firmware; * a board configuration file (BCF) to provide calibration constants. You may need to acquire this from the manufacturer of the module separately, but be aware that if you have an old BCF you may be forced to use an old release of the driver; you should ask the module manufacturer for an up-to-date BCF. \|

mkdir $STAGING\_DIR
curl -sL \
| tar xv
curl -sL \
| tar xv
rm LICENSE

| \| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | On insertion of the morse.ko kernel module, there are three paths the driver might take for selecting which BCF to use. 1. Use the file specified in the bcf module parameter - e.g. bcf=bcf\_mf08651.bin 2. For modules with the board type ID programmed into OTP, use the file with name bcf\_boardtype\_.bin 3. Use bcf\_default.bin Some modules, including MM6108-MF08651-US, are shipped with the board type ID programmed into OTP. To support this it is recommended the developer adds the following symbolic link to their rootfs/target platform. |

ln -s /lib/firmware/morse/bcf\_mf08651.bin \
$STAGING\_DIR/lib/firmware/morse/bcf\_boardtype\_0801.bin

| | ------------------------------------------------------------------------------------------------------------------- | For other modules the developer should run the following command |

ln -s /lib/firmware/morse/$BCF.bin \
$STAGING\_DIR/lib/firmware/morse/bcf\_default.bin

| | ---------------------------------------------------------------------------------------------------- | where $BCF matches the appropriate BCF for the target platform. *** ## 6 User Space Software A device integrating HaLow requires more than just the driver. * wpa\_supplicant - user space wireless client, including 802.11s mesh points * hostapd - user space daemon for access points * morse\_cli - Morse Micro’s user space control utility. It is required that this is installed on the target system for the correct function of hostapd and wpa\_supplicant provided by Morse Micro. * morsectrl - Morse Micro’s advanced user space control utility. This utility provides extra commands useful for testing radio performance. The installation of morsectrl is not recommended for image builds targeting end users, and is not distributed as open source. The above utilities have dependencies on additional software libraries which must be compiled for the target platform. This guide will not provide instructions on how to prepare these dependencies. For hostapd to function correctly at run-time, two cryptographic APIs need to be enabled in the Linux kernel configuration. Also, please also ensure the kernel includes the following configuration. * CONFIG\_CRYPTO\_CCM=y * CONFIG\_CRYPTO\_GCM=y Additionally, standard networking utilities such as iw or ip may be required during bring up. This guide won’t discuss the compilation and installation of these utilities, but a developer should add them to their platform. ### 5.1 hostapd and wpa\_supplicant #### 5.1.1 Dependencies Please ensure the following dependencies are compiled, and if required, installed into the staging directory of your build environment. * libnl-3 (tested with 3.11.0), including libnl-route-3 and libnl-genl-3 * openssl (tested with 3.5.0) #### 5.1.2 Checkout Clone the repository and checkout the appropriate branch using git: |

git clone
cd hostap
git checkout 1.15.3

| | ----------------------------------------------------------------------------------------------- | #### 5.1.2 Configuration The Morse Micro hostap repository provides a default configuration for hostapd and wpa\_supplicant for a minimal release. |

cp wpa\_supplicant/defconfig wpa\_supplicant/.config
cp hostapd/defconfig hostapd/.config

| | --------------------------------------------------------------------------------------------------- | Depending on the application, additional configuration options may need to be enabled. The options available are extensive, and out of scope for this document. Consult the .config file for more information on the available configuration options #### 5.1.3 Compilation Compiling wpa\_supplicant and/or hostapd requires the above mentioned dependencies be made accessible to the build. In this example, libnl-3 and openssl were “installed” into the staging directory with make install. The below command also assumes your CC flag is set appropriately for your target. If additional CFLAGS, LDFLAGS, or other environment variables are required for your platform, add them as required. Compiling wpa\_supplicant: |

CFLAGS="-Wno-error=sign-compare -Wno-error=deprecated-declarations -I $STAGING\_DIR/include/libnl3 -I $STAGING\_DIR/include/" \
LDFLAGS="-L $STAGING\_DIR/lib/ -L $STAGING\_DIR/lib64/" \
DESTDIR="$STAGING\_DIR" BINDIR=/usr/sbin \
make MORSE\_VERSION=rel\_1\_15\_3\_2025\_Apr\_16 -C wpa\_supplicant/

| | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | Compiling hostapd: |

CFLAGS="-Wno-error=sign-compare -I $STAGING\_DIR/include/libnl3 -I $STAGING\_DIR/include/" \
LDFLAGS="-L $STAGING\_DIR/lib/ -L $STAGING\_DIR/lib64/" \
DESTDIR="$STAGING\_DIR" BINDIR=/usr/sbin \
make MORSE\_VERSION=rel\_1\_15\_3\_2025\_Apr\_16 -C hostapd/

| | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | #### 5.1.4 Installation Installation with a staging directory appropriately set is done by adding the install as a target to the above make commands. If performing a manual installation on an existing device, you can install the following binaries into /usr/sbin: * wpa\_supplicant\_s1g * wpa\_cli\_s1g * wpa\_passphrase\_s1g * hostapd\_s1g * hostapd\_cli\_s1g ### 5.3 morse\_cli/morsectrl #### 5.3.1 Dependencies Please ensure the following dependencies are compiled, and if required, installed into the staging directory of your build environment. * libnl-3 (tested with 3.11.0) * libusb (tested with 1.0.28; this may also require libudev) #### 5.3.2 Compilation Compiling morse\_cli requires the above mentioned dependencies be made accessible to the build. In this example, libnl-3 and libusb were installed into the staging directory with make install. The below command also assumes your CC flag is set appropriately for your target. If additional CFLAGS, LDFLAGS, or other environment variables are required for your platform, add them as required. |

git clone
cd morse\_cli
git checkout 1.15.3
CFLAGS="-I$STAGING\_DIR/include/libnl3/ -I$STAGING\_DIR/include/libusb-1.0" \
LDFLAGS="-L $STAGING\_DIR/lib/" \
make CONFIG\_MORSE\_TRANS\_NL80211=1

| | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | If you have the morsectrl source, it can be compiled in a similar way, and will also generate a copy of morse\_cli (morse\_cli contains a subset of morsectrl commands). #### 5.3.3 Installation To install morse\_cli, copy the compiled binary to /usr/bin of your device or target rootfs. *** ## 6 Defining the Hardware for SDIO/SPI ### 6.1 Configuration In order for the driver to detect and communicate with the chip via SDIO or SPI, the hardware must be described to the kernel. This ensures all necessary clocks, pins, power regulators, and necessary host bus peripherals are correctly configured for the target platform. This hardware configuration is described to the kernel using devicetree, which is compiled and passed to the kernel as a binary blob. A developer may choose to modify an existing board devicetree file (.dts), compiling the changes into a single Flattened Device Tree (FDT) binary (.dtb). Alternatively, a device tree “fragment” can be composed and a device tree overlay compiled (.dtbo) allowing that hardware configuration to be changed on boot. Below is a small snippet from the Morse Micro EKH03 devicetree (.dts) file, redacted for brevity and to highlight the required properties and nodes to describe an SDIO connected MM6108. |

...
\&sdhci {
...
cap-sd-highspeed;
cap-mmc-highspeed;
non-removable;
disable-wp;
cap-sdio-irq;
...
mm6108\_sdio: mm6108\_sdio\@0 {
compatible = "morse,mm610x";
reset-gpios = <\&gpio 12 0>;
power-gpios = <\&gpio 7 0>,
<\&gpio 8 0>;
status = "okay";
reg = <2>;
bus-width = <4>;
};
};
...

| | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | For SPI devices, the MM6108 device tree node looks slightly different. The snippet below, taken from the MorseMicro EKH01 EVK, demonstrates how a developer might prepare a devicetree overlay to describe an MM6108 connected to the first SPI bus of the host processor. Of particular note is the different compatible, and the spi-irq-gpios parameter. |

/dts-v1/;
/plugin/;
/ {
compatible = "brcm,bcm2835", "brcm,bcm2836", "brcm,bcm2708", "brcm,bcm2709", "brcm,bcm2711";
fragment\@0 {
target = <\&spi0>;
frag0: **overlay** {
pinctrl-0 = <\&spi0\_pins \&spi0\_cs\_pins>;
cs-gpios = <\&gpio 8 1>;
#address-cells = <1>;
#size-cells = <0>;
status = "okay";
mm6108: mm6108\@0 {
compatible = "morse,mm610x-spi";
reg = <0>; /\* CE0 \*/
reset-gpios = <\&gpio 5 0>;
power-gpios = <\&gpio 3 0>,
<\&gpio 7 0>;
spi-irq-gpios = <\&gpio 25 0>;
spi-max-frequency = <50000000>;
status = "okay";
};
};
};
};

| | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | *** | Property | Note | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | cap-sdio-irq | Enable SDIO IRQ signalling on this bus | | compatible |

Must be “morse,mm610x” in the MM6108 node to correctly probe the SDIO driver
Must be “morse,mm610x-spi” in the MM6108 node to correctly probe the SPI driver.

| | reset-gpios | GPIO descriptor connected to the MM6108 RESET line. | | power-gpios | GPIO descriptor list connected to the MM6108 WAKE and BUSY pins, respectively | | spi-irq-gpios | GPIO descriptor connected to the MM6108 SPI\_INT pin. | | status | Must be “okay” to enable the device! | Due to the target specific requirements of booting a device, there is no one specific approach a developer should use to compile and deploy changes to the device tree. The next 3 subsections describe 3 common methods for which device tree changes may be incorporated into a target platform. ### 6.2 Compilation #### 6.2.1 Example 1 (FDT Blob in KBuild) In some cases, for some targets, the Linux kernel can ease the compilation of and “installation” of the FDT Blob by specifying the device tree file to load in the kernel config. This is useful for targets with limited bootloaders which are unable to hand the FDT blob to the kernel at boot time. As an example, if we wanted to add HaLow support to the VoCore 2 module, we could add the EKH03 device tree change above to arch/mips/boot/dts/ralink/vocore2.dts. A kernel checkout configured for a VoCore 2 will have the following kernel options set: * CONFIG\_BUILTIN\_DTB * CONFIG\_DTB\_VOCORE2 The Kbuild Makefile arch/mips/boot/dts/ralink/Makefile handles compilation of the FDT blob. For the ambitious reader, it’s worth noting again that the EKH03 snippet above is incomplete and will not function as-is when applied to the vocore2.dts file in the kernel tree. Morse Micro recommends consulting the OpenWrt SDK for more complete examples. #### 6.2.2 Example 2 (Out-of-Tree Compilation) Devicetree files may also be composed outside of the kernel build tree. As above, the EKH03 device tree change should be added to an out-of-tree board.dts file. Compilation of the FDT blob will follow steps similar to below |

# preprocess #includes and #defines
$(CPP) -nostdinc -x assembler-with-cpp $(DTS\_CPPFLAGS) \
-I$(LINUX\_DTS\_DIR) -I$(LINUX\_DTS\_DIR)/include \
-I$(LINUX\_DIR)/include -undef -D\_\_DTS\_\_ \
-o board.dtb.tmp board.dts
# compile FDT
$(DTC) -O dtb $(FLAGS) -o board.dtb board.dtb.tmp

| | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | The FDT blob can simply be appended to the kernel image for “installation”, prior to any image compression. | cat board.dtb >> kernel.bin | | --------------------------- | For devices with an FDT aware bootloader, the compiled FDT blob can be handed to the kernel at boot time by the bootloader. The specific details of how this is carried out are platform specific. #### 6.2.3 Example 3 (Devicetree Overlay) If flexibility in the hardware configuration is required, devicetree overlay fragments, similar to the fragment used for the EKH01 shown above, can be loaded by FDT aware bootloaders to modify the behaviour of the device FDT. Steps to compile an overlay fragment into a .dtbo mirror the compilation of the FDT blob. |

# compile FDT overlay
$(DTC) -@ -O dtb $(FLAGS) -o overlay.dtbo overlay.dts

| | ------------------------------------------------------------------------------------- | ## 7 Bring Up The configuration options for hostapd and wpa\_supplicant are extensive. Certain options may also depend on compile time configuration. This guide aims to provide a minimal bring up of the HaLow interface, and recommend a developer look to the hostapd documentation for detailed descriptions of the configuration available. ### 7.1 Interface Before bringing up an access point, ensure the dot11ah and morse kernel modules are inserted. |

modprobe mac80211
modprobe crc7
insmod dot11ah/dot11ah.ko
insmod morse.ko country=AU

| | ---------------------------------------------------------------------------------------------------- | Confirm that your kernel logs show the device being correctly registered. A new phy and associated network device (eg wlan0) should now be registered with the kernel. You can now bring up the interface. If you’re not using a DHCP client daemon, you should also set an IP address on the interface using ip: |

ip addr add 192.168.1.1/24 dev wlan0
ip link set wlan0 up

| | ------------------------------------------------------------------- | Remember to choose a different IP in the same subnet for the AP and the Station. There are a number of module parameters supported by the Morse Micro driver. The full list can be found by querying the driver with modinfo or by inspecting the files in sysfs. However, the following module parameters are often beneficial for testing. * country - adjust the default region for which the device should operate; * spi\_clock\_speed - controls the SPI clock speed requested by the driver; * test\_mode - execute one of the test modes in the table below | test\_mode | Identifier | Description | | ---------- | ---------------------------------- | --------------------------------------------------------------- | | 0 | DISABLED | normal boot | | 1 | DOWNLOAD\_ONLY | downloads the firmware | | 2 | DOWNLOAD\_AND\_GET\_HOST\_TBL\_PTR | downloads the firmware and gets the location of the host table | | 3 | GET\_HOST\_TBL\_PTR\_ONLY | only get the location of the host table | | 4 | RESET | chip reset | | 5 | BUS | perform block reads and writes to profile the communication bus | *** ### 7.2 Access Point Make sure the Morse Micro driver is inserted as described in 7.1 Interface, and make sure morse\_cli is in your path. Then start hostapd\_s1g with the minimal config file below. Make sure to change the name of wlan0 if necessary. | hostapd\_s1g hostapd.conf | | ------------------------- | hostapd.conf: |

ctrl\_interface=/var/run/hostapd\_s1g
interface=wlan0
driver=nl80211
hw\_mode=a
ieee80211ah=1
channel=44
op\_class=71
country\_code=AU
s1g\_prim\_chwidth=1
s1g\_prim\_1mhz\_chan\_index=0
ssid=MorseMicro
beacon\_int=100
dtim\_period=1
ap\_max\_inactivity=65536
s1g\_capab=\[SHORT-GI-ALL]
wpa=2
wpa\_key\_mgmt=SAE
rsn\_pairwise=CCMP
sae\_password=12345678
ieee80211w=2
wnm\_sleep\_mode=1
sae\_pwe=1

| | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | You may find the -B (daemonise) and -s (output logs to syslog) options useful once you’ve confirmed that association is working. *** ### 7.3 Station Make sure the Morse Micro driver is inserted as described in 7.1 Interface. Then start wpa\_supplicant\_s1g with the minimal config file below. Make sure to change the name of wlan0 if necessary. |

wpa\_supplicant\_s1g -D nl80211 -i wlan0 \
-c wpa\_supplicant.conf

| | ------------------------------------------------------------------------------- | wpa\_supplicant.conf |

ctrl\_interface=/var/run/wpa\_supplicant\_s1g
#update\_config=1
pmf=2
sae\_pwe=1
network={
ssid="MorseMicro"
key\_mgmt=SAE
pairwise=CCMP
psk="12345678"
}

| | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | You may find the -B (daemonise) and -s (output logs to syslog) options useful once you’ve confirmed that association is working. ## 8 Revision History | Release Number | Release Date | Release Notes | | -------------- | ------------ | ------------------------------------ | | 01 | 20/08/2024 | Initial release | | 02 | 30/05/2025 | Update for 1.15.3 and github release |