 |
Morse Micro IoT SDK
2.10.4
|
|
Morse Micro IoT SDK
2.10.4
|
This getting started guide walks through the process of using the MM-IoT-SDK Framework. This will go through the process of setting up the software infrastructure, building the ping example for the MM6108-EKH05 device, and loading firmware onto the device. For more information about the SDK tools and source see SDK Overview.
Whilst we are using a MM6108-EKH05 for this example, the exact same steps will work for an MM8108 based platform such as the MM8108-EKH05, adjusting the commands appropriately for the different platform.
Note that the MM-IoT-SDK Framework is meant for more advanced users. For a simpler experience it is suggested to use PlatformIO. See Platform IO + MM IoT SDK User Guide for details.
MM6108-EKH05.The first step is to create an appropriate directory and unzip the software package into it.
For example:
unzip mm-iot-sdk-2.10.4.zip -d mm-iot-sdk-2.10.4 cd mm-iot-sdk-2.10.4/framework
-d parameter when unzipping or unzip into an empty directory.The instructions below assume that the current working directory is mm-iot-sdk-2.10.4/framework.
Use the setup script in the SDK to install the pre-requisite software:
./tools/setupscripts/ubuntu-setup.sh
This script installs some packages in /opt/morse. If you have already connected the development board, unplug the USB cable for 5 seconds and plug it in again after running the script. This will cause the new device permissions to take effect. A shell script is provided that adds the necessary directories to the PATH. This can be sourced as follows:
. ./tools/setupscripts/env.sh
The above script needs to be run for every terminal instance. For a more permanent solution, you can add this to the initialization script for your shell, in which case it will not need to be run manually. For example, if you are using the default shell (bash) on Ubuntu 22.04, you can run the following to append it to your .bashrc (make sure to replace <path-to-sdk> as appropriate):
echo ". /path-to-sdk/mm-iot-sdk-2.10.4/framework/tools/setupscripts/env.sh" >> ~/.bashrc
After making the above change to .bashrc you will need to close and reopen your terminal for this to take effect.
The virtualenv used for the SDK is defined by the Pipfile located in the mm-iot-sdk-2.10.4/framework directory. To install the Morse Micro Python environment run:
pipenv sync
Open On-Chip Debugger (OpenOCD) is an open-source application that provides debugging, in-system programming and boundary-scan testing for embedded target devices. We will be using it to configure and program the host processor.
To verify that the correct OpenOCD is in the path, execute the following command:
which openocd
You should get:
/opt/morse/xpack-openocd-0.12.0-2/bin/openocd
If not, re-run the setup script found in Development PC setup and ensure it successfully install OpenOCD.
To launch OpenOCD, first open a new terminal and navigate into the IoT SDK (framework) directory. Execute:
cd ./framework openocd -c "set CONNECT_ASSERT_SRST 1" -f ./src/platforms/mm-mm6108-ekh05/openocd.cfg
Leave OpenOCD running as we will be using it in the next step.
Note that the
openocd.cfgwill vary for each platform.
Each application has a number of configuration variables that modify the behavior of the application. These configurations are maintained through the config store on device Flash, and are power-cycle and firmware-load persistent.
For this example we are going to prepare values using the mm-iot-sdk-2.10.4/examples/ping/config.hjson configuration file then write them to the device. Most config store fields have default values specified in firmware, but there are two important fields that must be specified explicitly:
| Configuration Params | Description |
|---|---|
wlan.country_code | Two character country code for your applicable regulatory domain. For an up-to-date list of supported country codes see the reference implementation mmregdb.c. |
bcf_file | The path to the appropriate board configuration .mbin file to use. |
Modify the configuration file by removing the leading // from in front of the wlan.country_code and bcf_file values, and replacing them with appropriate values for your country and device. Also update the wlan.ssid and wlan.password fields of the config file with the ssid and password of your AP.
To see the full list of configuration values for the ping example, see Application Configuration.
.mbin (Morse binary) format as opposed to the .bin format, so you cannot use those BCFs here.We can now load our new config values onto the device:
pipenv run ./tools/platform/program-configstore.py -H localhost write-json ../examples/ping/config.hjson
To confirm that the correct values have been loaded the following command can be run to dump the contents of the Morse Micro Persistent Configuration Store section.
pipenv run ./tools/platform/program-configstore.py -H localhost -d
The expected output (note the exact contents will vary slightly depending on BCF and country).
2023-10-23 16:06:13 WARNING: Failed to read config store partition 1 at 0x08006000: Invalid signature found Partition 0 (current) ===================== Version 1 Key | Value ---------------------------------|-------- wlan.ssid | MorseMicro wlan.password | 12345678 wlan.security | sae wlan.country_code | AU ip.dhcp_enabled | false ip.ip_addr | 192.168.1.2 ip.netmask | 255.255.255.0 ip.gateway | 192.168.1.1 ip6.autoconfig | true ping.target | 192.168.1.1 ping.count | 10 ping.interval | 1000 ping.size | 56 bcf_file | 008004004d4d424300812801efbeadde7e66a50e04000200180100000000 ...
The above process should only need to be performed once, since the sectors used by Morse Micro Persistent Configuration Store should not be affected by normal application programming. Note, that these values may need to be updated if you update the version of the Morse Micro IoT SDK used, in which case the bcf_file will most likely need to be updated.
If you are using an STM32WB55 based platform such as mm-ekh08-wb55, see Additional steps for mm-ekh08-wb55 and mm-ekh18-wb55 platforms before continuing.
We will be building for the
MM6108-EKH05platform but the same steps apply for all platforms. Just run make from the corresponding directory.
To build the ping example application, first change into the example directory, mm-iot-sdk-2.10.4/examples/ping/targets/mm-mm6108-ekh05 then invoke the following command:
make -j$(nproc)
will evaluate to the number of parallel threads capable by your machine.
The result of the above command will be a ping.elf file in the build/ directory
The following commands are to be run from the
mm-iot-sdk-2.10.4/frameworkdirectory.
To program, configure, and monitor the system we will be using an ST-LINK debugger/programmer operating over USB. The ST-LINK provides both a debug interface and a USB serial port, the latter of which is used for log messages.
Connect the ST-LINK to the development PC following the instructions on the Morse Micro IoT Reference Platforms page. To verify that it has enumerated, run lsub as follows:
lsusb | grep STM
This should result in output similar to the following:
Bus 003 Device 081: ID 0483:374e STMicroelectronics STLINK-V3
Miniterm is a Python-based console application that allows us to monitor and interact with a serial interface. There are many other options such as Minicom or PuTTY that you can use if you so wish. However, your mileage may vary if you decided to use another application.
Open a new terminal and execute the following command to find the path to the ST-LINK serial port:
ls /dev/serial/by-id/usb-STMicroelectronics_*
This will list the ST-LINK serial port devices connected to the PC.
To start Miniterm, execute the following command, substituting XXX for the actual value from the output of the ls command above:
miniterm /dev/serial/by-id/usb-STMicroelectronics_XXX 115200
Leave Miniterm running, this is where we will view the output from the application after programing the device.
For the new configuration to take effect first close OpenOCD by pressing CTRL+C, then launch OpenOCD using the following command:
openocd -c "set MM_PROGRAM 1" -f src/platforms/mm-mm6108-ekh05/openocd.cfg -c "program ../examples/ping/targets/mm-mm6108-ekh05/build/ping.elf verify reset exit"
This will attach OpenOCD, load the ping example, start execution, and exit OpenOCD.
As the firmware runs, it will boot the Morse Micro transceiver and attempt to connect to the configured AP and ping it. A successful result will output something like the following in Miniterm:
Note: This firmware has been built with debug in stop mode enabled. This will impact power consumption and should be disabled for production firmware.
Morse Ping Demo (Built Sep 19 2025 10:51:20) ----------------------------------- BCF API version: 12.1.0 BCF build version: 4cdf808 07f9d31 BCF board description: mf08551 Morselib version: 2.6.1 Morse firmware version: 2.8.2 Morse chip ID: 0x0306 Morse chip name: MM6108A1 ----------------------------------- Initialize IPv4 with static IP: 192.168.1.2... Initialize IPv6 using Autoconfig... Morse LwIP interface initialised. MAC address 0c:bf:74:00:01:2b Attempting to connect to MorseMicro with passphrase 12345678 This may take some time (~30 seconds) WLAN STA connecting WLAN STA connected Link is up. Time: 8294 ms, IP: 192.168.1.2, Netmask: 255.255.255.0, Gateway: 192.168.1.1 Ping 192.168.1.1 56(64) bytes of data. (192.168.1.1) packets transmitted/received = 1/1, round-trip min/avg/max = 34/34/34 ms (192.168.1.1) packets transmitted/received = 2/2, round-trip min/avg/max = 4/19/34 ms (192.168.1.1) packets transmitted/received = 3/2, round-trip min/avg/max = 4/19/34 ms (192.168.1.1) packets transmitted/received = 3/3, round-trip min/avg/max = 4/17/34 ms (192.168.1.1) packets transmitted/received = 4/3, round-trip min/avg/max = 4/17/34 ms (192.168.1.1) packets transmitted/received = 4/4, round-trip min/avg/max = 4/15/34 ms (192.168.1.1) packets transmitted/received = 5/5, round-trip min/avg/max = 1/12/34 ms (192.168.1.1) packets transmitted/received = 6/6, round-trip min/avg/max = 1/11/34 ms (192.168.1.1) packets transmitted/received = 7/6, round-trip min/avg/max = 1/11/34 ms (192.168.1.1) packets transmitted/received = 7/7, round-trip min/avg/max = 1/11/34 ms (192.168.1.1) packets transmitted/received = 8/7, round-trip min/avg/max = 1/11/34 ms (192.168.1.1) packets transmitted/received = 8/8, round-trip min/avg/max = 1/11/34 ms (192.168.1.1) packets transmitted/received = 9/8, round-trip min/avg/max = 1/11/34 ms (192.168.1.1) packets transmitted/received = 9/9, round-trip min/avg/max = 1/11/34 ms (192.168.1.1) packets transmitted/received = 10/9, round-trip min/avg/max = 1/11/34 ms (192.168.1.1) packets transmitted/received = 10/10, round-trip min/avg/max = 1/12/34 ms --- 192.168.1.1 ping statistics --- 10 packets transmitted, 10 packets received, 0.000% packet loss round-trip min/avg/max = 1/12/34 ms WLAN STA disabled Link is down. Time: 28727 ms
From here you can try out the other Example Applications.
For more information about debugging your software, see Debugging with GDB.
The following message in the console log...
Unable to find BCF file entry in config store (memory range 0x81e0000-0x8200000) Please see the Getting Started Guide for more information.
The above message will be displayed if a Morse Micro Board Configuration File (BCF file) file has not been programmed to the config store. See Setting Config Store for steps on how to do this.
You are unable to connect to the MCU when you run the 'openocd -f openocd.cfg' commands.
This may look like one of the following
% openocd -f openocd.cfg
xPack OpenOCD x86_64 Open On-Chip Debugger 0.12.0+dev-01312-g18281b0c4-dirty (2023-09-04-22:31)
Licensed under GNU GPL v2
For bug reports, read
http://openocd.org/doc/doxygen/bugs.html
Info : The selected transport took over low-level target control. The results might differ compared to plain JTAG/SWD
Info : DEPRECATED target event trace-config; use TPIU events {pre,post}-{enable,disable}
Info : Listening on port 6666 for tcl connections
Info : Listening on port 4444 for telnet connections
Info : clock speed 500 kHz
Info : STLINK V3J8M3 (API v3) VID:PID 0483:374E
Info : Target voltage: 0.003198
Error: target voltage may be too low for reliable debugging
Error: init mode failed (unable to connect to the target)
% openocd -f openocd.cfg
xPack OpenOCD x86_64 Open On-Chip Debugger 0.12.0+dev-01312-g18281b0c4-dirty (2023-09-04-22:31)
Licensed under GNU GPL v2
For bug reports, read
http://openocd.org/doc/doxygen/bugs.html
Info : The selected transport took over low-level target control. The results might differ compared to plain JTAG/SWD
Info : DEPRECATED target event trace-config; use TPIU events {pre,post}-{enable,disable}
Info : Listening on port 6666 for tcl connections
Info : Listening on port 4444 for telnet connections
Info : clock speed 500 kHz
Info : STLINK V3J8M3 (API v3) VID:PID 0483:374E
Info : Target voltage: 3.303398
Error: init mode failed (unable to connect to the target)
The voltage (VDD) or current measurement (IDD) jumpers are not attached on your development board.
For the ST Nucleo U575 development board VDD is JP4 and IDD is JP5. See Morse Micro IoT Reference Platforms for details of your specific platform.
The ST-Link debugger is unable to communicate with the host processor because it is in deep sleep. It may be necessary to hold the chip in reset while attaching to it. This can be achieved by adding -c "set CONNECT_ASSERT_SRST 1" to the OpenOCD command line before including openocd.cfg. For example:
% openocd -c "set CONNECT_ASSERT_SRST 1" -f openocd.cfg
See Debugging during deep sleep for more information.
This is not relevant for other platforms
The MM6108-EKH08-05US-01 Platform (mm-ekh08-wb55) is slightly more complex in that it has a main CPU (M4) as well as a second CPU (M0+) that is used for its RF functionality. The chip will reserve a portion of the flash for exclusive use by CPU2. This means that the position of the last sector (available to CPU1) may change.
By default it is assumed that CPU2 will not be used and any FW will be deleted, moving the last available flash sector to offset 0xF3. To ensure this is the case you will need to use the STM32CubeProgrammer to delete any CPU2 firmware that may have been loaded onto the device. The following steps will assume you have the MM6108-EKH08-05US-01 Platform (mm-ekh08-wb55) connected to the same machine and OpenOCD is not running so as not to conflict with the st-link access.
Navigate into the STM32CubeProgrammer/bin directory and run the following:
./STM32_Programmer_CLI -c port=swd -startfus ./STM32_Programmer_CLI -c port=swd -fwdelete
If all the operations were successful the value of the SFSA register (which defines the start of the flash address space that is protected for CPU2 use) should now be 0xF4. This can be checked by running:
./STM32_Programmer_CLI -c port=swd -ob displ