Basic Usage
Software Development Kits > Platform IO
This section walks you through how to select one of the example applications and configure, compile, upload, and run it on Morse Micro evaluation hardware.
Connecting the evaluation board to PC
The evaluation boards have an integrated STLINK debugger/programmer that is connected to the PC via a USB cable. If this is the first time an STLINK has been attached to the host machine, you may need to install the necessary drivers or configure rules to enable the debugger.
- For Windows, drivers can be found at STSW-LINK009, and should be installed via device manager.
- For Linux, configuration of udev rules may be required, instructions on PlatformIO should be followed.
- For Mac, no additional software or configuration should be required.
The power to the board is supplied via USB. Connect the micro-USB end to the evaluation board (see ”Micro-USB to PC” in Figures 7 and 8) and the USB-A connector to your PC.
Figure 7. EKH08-WB55 evaluation board
Figure 8. EKH08-U575 (left) and EKH08-F429 (right) evaluation boards
Opening an example project
To get started with one of the examples supplied in the MM-IoT-SDK:
- Open Visual Studio Code and click the PlatformIO icon on the activity bar (Figure 9).
- Click Create New Project, or alternatively, select Quick Access → PIO Home → Open.
- From the opened dialog click Project Examples (Figure 10).
The example projects for “Morse Micro IoT Toolkit” will be visible (Figure 11). Select one of the projects (for example, ‘iperf’) and click Import. A copy of the example project is created and it can be freely modified.
Figure 9. Creating new project
Figure 10. Project creation dialog
Figure 11. Importing mm-iot-framework examples
The project will take a few seconds to configure, and may ask you to ‘trust’ the authors of the file and folder. You will need to select “Yes” in order to proceed. Once this has completed, a list of project files on the left in the explorer window pane, and the source code for platform.ini in the main window pane.
At the bottom of Visual Studio Code, in the status bar, it is recommended to “Switch PlatformIO Project Environment” to target your desired board. The “Default” selected refers to the first environment specified in the platform.ini — typically the mm-ekh08-u575.
Figure 12. Switching from the default environment
Additionally, you may want to manually specify the serial port, particularly if there are multiple attached to your PC, so that the serial console works as expected. Click on “Auto” in the status bar and a drop-down at the top of Visual Studio Code will open to select from a list of available serial ports. See the Troubleshooting section for further information if your serial port does not show.
Building and Uploading
To build the project, select the PlatformIO icon from the activity bar, and under the Project Tasks for your platform, select Build (Figure 13).
Building the image can also be triggered by clicking the ‘tick’ in the status bar.
Figure 13. Building from Project Tasks.
The build task will execute, and show progress and status in the terminal output of VS Code (example shown in Figure 14).
Figure 14. Build status terminal output
Once built successfully, the binary can be uploaded to the target platform (note configuration needs to be set up and loaded onto the board as well, see section 4.4 below). This can be executed by selecting Upload from Project Tasks. Alternatively, you can trigger an upload by clicking the right-arrow shortcut in the status bar.
Progress and status of the upload procedure will be shown in the terminal output (example shown in Figure 15).
Figure 15. Upload status terminal output
Preparing the config store partition
The MM-IoT-SDK example applications load configuration from the config store partition, if found on the device. Each example project includes a config.hjson which can be serialised and loaded onto the device.
For the applications demonstrating HaLow capability, they will need to be configured as appropriate for your application before they will run correctly. To modify the configuration, open the config.hjson file from the explorer pane on the left. An example config.hjson snippet is shown in Figure 16.
Some notable configuration fields typically required for the example applications include:
| wlan.ssid | SSID of the HaLow network to connect to |
| wlan.password | Password of the HaLow network if security type is SAE |
| wlan.security | Security type of the HaLow network (sae, owe, or open) |
| wlan.country_code | Two character country code for the applicable regulatory domain |
| ip.dhcp_enabled | true to enable DHCP, or false to use a static IP address |
| ip.ip_addr | Static IP address to use if DHCP is disabled |
| ip.netmask | Netmask to use if DHCP is disabled |
| ip.gateway | Gateway IP address to use if DHCP is disabled |
| bcf_file | Board Configuration File |
In addition, there may be application specific configuration, such as ping.target to specify the target IP address for the ping example application.
Figure 16. config.hjson snippet
Most config store fields have default values specified, but there are two important fields that must be specified explicitly. The wlan.country_code field must be set to the 2 letter code for your applicable regulatory domain and the bcf_file field must specify the path to the appropriate Board Configuration File.
The Board Configuration File (BCF) is a configuration file for the Morse Micro chip that provides board-specific information and is required for the system to function properly. BCFs for Morse Micro modules are included in the MM-IoT-SDK package. Note that these files use a special format that differs from regular Linux BCFs and they are not compatible. These modules can be identified by the part numbers printed on their labels, which take the form MM6108-MFxxxxxx.
BCF files for Morse Micro evaluation boards are provided as part of the SDK in the following locations:
- Windows:
-
C:/Users/<user>/.platformio/platforms/mm_iottoolkit/framework/morsefirmware
-
- macOS
-
/Users/<user>/.platformio/platforms/mm_iottoolkit/framework/morsefirmware
-
- Linux
-
/home/<user>/.platformio/platforms/mm_iottoolkit/framework/morsefirmware
-
For MM-IoT-SDK versions 2.1.x and newer, the variable $MMIOT_ROOT can be specified as part of the file path and this will be substituted with the path to the framework directory. Thus, for the module with part number MM6108-MF082551, the bcf_file config field should be set as follows:
"bcf_file": "$MMIOT_ROOT/morsefirmware/bcf_mf08551.mbin"
Programming the config store partition
Note: for 2.0.x, before programming the config store, it is required to run an Upload, as in Section 'Building and Uploading' to properly synchronise your system’s environment. This is not necessary withMM-IoT-SDK 2.1.x and newer.
After editing the config.hjson, the updated configuration can be pushed to the device by executing the Program configstore custom task. This can be found by navigating to the PlatformIO icon in the VS Code activity bar, and selecting Custom → Program configstore for the desired platform.
Figure 17. Navigation to Custom tasks
The config store is implicitly erased before programming. It can also be explicitly erased by selecting Erase configstore.
Using serial monitor
Open the serial monitor by pressing the power plug icon on the VS Code status bar (Figure 18), or by selecting the Monitor task from the list of Project Tasks. If successful, a long-lived Monitor task will open in a terminal in the VS Code panel. Press the reset button on the evaluation board to restart the application and program output will be displayed in the terminal window.
Figure 18. Serial monitor button
Note that monitor tasks are long-lived. If the monitor task was previously launched the following dialog will pop up:
Figure 19. Duplicate monitoring
As mentioned in Section 4.2, you may want to explicitly select the relevant serial port for your evaluation board. This is particularly important if you have multiple serial ports attached to the host system.
- Click on “Auto” in the status bar (Figure 20)
- This will open a command palette at the top of VS Code containing a list of detected serial ports (Figure 21). Choose the one required for your evaluation board.
Figure 20. Serial Monitor selection
Figure 21. Command Palette showing detected serial ports