Menu

Module Development Environment

In this article:

    The first step in the development process is to set up a computer as a suitable development environment and install the Myriota Software Development Kit (SDK).

    This guide provides step by step instructions to install the SDK and start writing firmware for the Myriota Module.

    Devices must be registered with Device Manager to connect to the Myriota Network. See the Device Manager guide for more details. 

    Supported Development Platforms

    • Ubuntu 22.04, 20.04 and 18.04
      • running natively on a PC with x86-64 architecture (recommended)
      • running on Windows Subsystem for Linux (version 1) (excluding Satellite Simulator usage)
    • macOS 10.15 and above
      • running on a Mac with an Intel chipset (pre-2020); Apple M1 and M2 devices are not supported

    The Myriota SDK requires a number of python tools that are only supported on the specified Linux Ubuntu and macOS operating systems running on x86-64 architecture.

    Ubuntu 22.04 running natively on x86-64 architecture is the recommended development platform as it removes the complexity associated with virtualised Linux environments on Windows. Success has also been achieved by running Ubuntu on a virtual machine (VM) that provides serial USB support. However, VM setup and configuration are beyond the scope of this guide.

    Wondering what x86-64 means? x86-64 architecture refers to the set of machine instructions that processors in most common PCs and pre-2020 Macs use. New Macs use Apple M1 and M2 chips, which use an ARM64 instruction set that is commonly used in phones and other portable devices such as Raspberry Pis. (ARM64 devices are not supported by Myriota development environments.) If you have an Intel-based Mac, or a PC that is capable of running Windows or Linux Ubuntu, then you can use it to develop with Myriota.

    We provide limited support and instructions for development on Windows 10 and above using Windows Subsystem for Linux (WSL) version 2. WSL is Microsoft's solution for enabling Linux development in Windows environments.

    Hardware Requirements

    • Myriota Development Board
    • Micro USB data cable

    Software Requirements

    • git
    • make build tool
    • python, package manager pip, and some additional libraries
    • curl and an internet connection
    • GNU ARM embedded C compiler
    • C/C++ compiler (GCC)
    • rtl-sdr tool

    Other Requirements

    • Myriota Device Manager account credentials (see the Device Manager guide for registration instructions).
    • Internet connection to download the latest Myriota SDK, system image and network information files.

    Download the SDK & Install Software Requirements

    The following instructions walk you through downloading the Myriota SDK and installing the required software for setting up a Myriota development environment on Ubuntu, Windows Subsystem for Linux or macOS. The SDK provides the scripts install.sh to manage installation of the software requirements and install-test.sh to confirm installation success. 

    Ubuntu

    1. Open the Terminal application 
    2. Type the following command to clone the Myriota SDK from Myriota's Github repository; this will create the folder SDK in your current directory.
      • We recommend cloning as this makes it easy to update to the latest version.
      • To be notified of new releases use the GitHub watch feature.
      git clone https://github.com/Myriota/SDK.git
    3. Change to the SDK root directory: 
      cd SDK
    4. Run the install.sh script; this installs the software dependencies and copies files to the /opt/gcc-arm/bin directory. Type the following command. You will be prompted to enter your administrator password multiple times as the script executes.  
      ./install.sh
    5. Add the SDK bin and tools folder to the PATH permanently by editing the user's .profile file. The following command creates a backup of the file.  
      cp ~/.profile ~/.profile.bak
    6. Once you have created a back up of the file, use a text editor to modify the .profile file. Add the following lines to the bottom of the file. This assumes that you have cloned the SDK directory into your user's home directory. If you chose another location for the SDK, you must update the tools folder path appropriately. 
      export PATH="$PATH:~/SDK/tools"
      export PATH="$PATH:/opt/gcc-arm/bin"
    7. Once you have edited and saved the file, enter the following command to reload your modified profile, or restart the terminal application:
      source ~/.profile
    8. Run the following script to test your installation; check the Troubleshooting section of this guide if any of the tests fail.   
      ./install-test.sh
    9. Use the following command to generate a security token to allow you to run SDK scripts without having to enter your Device Manager credentials. You will be prompted for your Device Manager username and password when running this command. The username is your email. A temporary token will be generated after successful login. It remains valid for 30 days. (The -c flag clears the temporary token and generates a new one.)
      tools/myriota_auth.py -c
    10. Follow the steps in the section below to update the Module's system image.

    Windows Subsystem for Linux

    Windows Subsystem for Linux can be installed from the Microsoft store. This section walks you through WSL installation, Ubuntu 22.04 distribution installation, configuring the installation to run in WSL and then installing the SDK. WSL documentation and manual install instructions can be found here. 

    Tip: Right clicking at the cursor in the Linux shell will paste the contents of the Windows clipboard; you can use this to copy and paste the commands directly from this guide.

    1. Search for Windows Subsystem for Linux in the Microsoft Store, click Get to install the application.
    2. Open Admin Windows Command Prompt (via the right click menu on the start button); we will now install the required distribution.
    3. Type the following commands in Command Prompt 
      winget install usbipd
      wsl.exe --install Ubuntu-22.04
    4. Once the first and second installation completes you will be prompted to create a username and password for the Linux Ubuntu distribution. Retain these credentials, they will be required for future operations in the Linux console. Note that passwords are blind typed in the shell; the cursor won't change as you enter your password characters.
    5. Ubuntu will start within the Admin Command Prompt; type exit to close Ubuntu.
    6. Now back at the Windows shell prompt, type the following command to check that the WSL version is set to 2 (current default version available on Microsoft store is version 2, therefore any fresh install would get you version 2): 
      C:\Users\ADL-Spare1> wsl.exe -v
      WSL version: 2.1.5.0
      Kernel version: 5.15.146.1-2
      WSLg version: 1.0.60
      MSRDC version: 1.2.5105
      Direct3D version: 1.611.1-81528511
      DXCore version: 10.0.25131.1002-220531-1700.rs-onecore-base2-hyp
      Windows version: 10.0.22631.3447
      If 1 has been installed by default, type the following command to change the WSL version to 2: 
      wsl.exe --set-version Ubuntu-22.04 2
    7. Open Windows Subsystem for Linux from the Windows start menu; a Linux shell will open.
    8. Type the following command to clone the Myriota SDK from Myriota's Github repository; this will create the folder SDK in your current directory.
      • We recommend cloning as this makes it easy to update to the latest version.
      • To be notified of new releases use the GitHub watch feature.
      git clone https://github.com/Myriota/SDK.git
    9. Change to the SDK root directory: 
      cd SDK
    10. Run the install.sh script; this installs the software dependencies and copies files to the /opt/gcc-arm/bin directory. Type the following command. You will be prompted to enter your Linux password multiple times as the script executes.  
      ./install.sh
    11. Add the SDK bin and tools folder to the PATH permanently by editing the user's .profile file. The following command creates a backup of the file.  
      cp ~/.profile ~/.profile.bak
    12. Once you have created a back up of the file, use a text editor to add the following lines to the bottom of the .profile file. This assumes that you have cloned the SDK directory into your user's home directory. If you chose another location for the SDK, you must update the tools folder path appropriately. 
      export PATH="$PATH:~/SDK/tools"
      export PATH="$PATH:/opt/gcc-arm/bin"
    13. Once you have edited and saved the file, enter the following command to reload your modified profile, or restart the terminal application:
      source ~/.profile
    14. Run the following script to test your installation; check the Troubleshooting section of this guide if any of the tests fail.   
      ./install-test.sh
    15. Generate security token: You may be prompted for your Device Manager username and password when running this command. The username is your email. A temporary token will be generated after successful login. It remains valid for 30 days. To clear the temporary token and generate a new one, use the command
      tools/myriota_auth.py -c
    16. Before proceeding with the steps below, plug in your Myriota device via USB. Switch back to the Admin Windows shell and run the following command to view available usb devices to share with Ubuntu. 
      usbipd list
      You should be able to see an item in the list with matching VID:PID and Device columns. 
      BUSID   VID:PID     DEVICE                  STATE
      1-1     0403:6015   USB Serial Converter    Not shared
      If the state of the device is not currently shared, the command usbipd bind must be used to share the device, allowing it to be attached to WSL. Select the BUS ID of the device you would like to use in WSL (BUS ID is 1-1 in this example) and run the following command 
       usbipd bind --busid 1-1
      To attach the USB device to WSL run the following command in the elevated Windows shell. 
      usbipd attach --wsl --busid 1-1
    17. Follow the steps in the section below to update the Module's system image.
     

    macOS

    The install.sh script checks for and installs the macOS package manager Homebrew if it is not found. The following steps include instructions for using homebrew commands to ensure python and other required packages are installed and linked correctly.

    The following instructions need to be run by a user who is a computer administrator.

    1. Open the Terminal application
    2. Type the following commands to clone the Myriota SDK into your current directory:
      • We recommend cloning as this makes it easy to update to the latest version.
      • To be notified of new releases use the GitHub watch feature.
      git clone https://github.com/Myriota/SDK.git
    3. Change to the SDK root directory: 
      cd SDK
    4. Type the following command to run brew doctor and to check if Homebrew is installed:
      brew doctor
      1. If Homebrew is not installed, the command will return an error indicating brew cannot be found. Continue with step 5.
      2. If Homebrew is found, the brew doctor command will either return a message indicating "you are good to brew" or it will return a list of issues that should be resolved. Follow the Homebrew instructions to resolve any issues, including link errors and warnings.
    5. Run the install.sh script; this installs the software dependencies and copies files to the /opt/gcc-arm/bin directory. Type the following command. You will be prompted to enter your administrator password multiple times as the script executes. 
      ./install.sh
      If required, the script will install Homebrew and will then exit to allow you to resolve any library link issues. If prompted to run brew doctor, return to step 4 above, follow the instructions to resolve all homebrew issues and re-run the install script.
    6. Add the bin and tools folders to the PATH permanently by editing your user's profile file. The file will be located in your user's home directory and called, .profile or .zshrc depending on your Terminal environment. The following command creates a backup. The commands assume you are using the Zsh terminal; if you are using bash, change the filename in the commands from .zshrc to .profile.
      cp ~/.zshrc ~/.zshrc.bak
    7. Add the following lines to the bottom of the .zshrc file. This assumes that you have cloned the SDK directory into your user's home directory. If you chose another location for the SDK, you must update the tools folder path appropriately. 
      export PATH="~/SDK/tools:$PATH"
      export PATH="/opt/gcc-arm/bin:$PATH"
    8. Enter the following command to reload your modified profile, or restart the terminal application:
      source ~/.zshrc
    9. Run the script to test your installation; check the Troubleshooting section of this guide if any of the tests fail.   
      ./install-test.sh
    10. Generate security token: You may be prompted for your Device Manager username and password when running this command. The username is your email. A temporary token will be generated after successful login. It remains valid for 30 days. To clear the temporary token and generate a new one, use the command
      tools/myriota_auth.py -c
    11. Follow the steps in the section below to update the Module's system image.

    Update System Image

    You must update the system image first before programming the device for the first time.

    You only need to program the system image once for each SDK release (you do not need to program the system image each time you update your device application).

    If you are updating from SDK 1.x to SDK 2.0 you may find our migration guide useful.

    Under the SDK root directory, download the system image with:

    ./get_system_image.sh

    Once complete, the Myriota license agreement notification will be displayed and you can then proceed to program the Development Board using the updater.py tool with:

    updater.py -f system.img

    Note:

    • By default, Myriota software tools updater.py and log-util.py try to detect the serial debug port automatically and use it.
    • Once you know the name of the serial debug port, you may use -p option which can be more efficient, especially for the Development Board
      • under Linux and WSL run updater.py -f system.img -p /dev/ttyUSB0
      • Under macOS run updater.py -f system.img -p /dev/cu.usbserial-001 
    • /dev/ttyUSB0 is assumed in the following instructions

    Test With Blinky Example

    You can now test your Development Board by building an example - blinky application.

    cd examples/blinky; make

    This should report no errors and have created a firmware image called blinky.bin. This image can now be written to the Myriota Module using the updater.py tool.

    To program the blinky.bin image issue the command:

    updater.py -u blinky.bin -s

    When programming completes the LED on the Development Board will blink on and off repeatedly. You can view output from the Myriota Module with:

    (stty raw 115200 -echo; cat) < /dev/ttyUSB0

    You should see the text Led On, Led Off printed repeatedly. Alternatively, you can use -l option to get the debug output as soon as the application starts running, e.g. updater.py -u blinky.bin -s -l.

    Note:

    • -s option is to start the application after programming
    • -l option is to print the output from the serial debug port. It can be used just to monitor the device's output, e.g. updater.py -l
    • Run updater.py -h for more usage information

    You are all set up.

    The blinky example uses a sandbox mode that is useful for development but is not suitable for deployment.

    For deployable examples see the Sending Messages and the Module Code Examples guides.

    You may also view the System API and the Hardware Interface API.

    Logging

    The system image logs system events and stats onto the flash. You can add your own user log entries using the LogAdd API call.

    Logging stops when the log partition in the flash is full. You can use log-util.py tool to download, parse, and purge the log. For example:

    log-util.py

    downloads, parses, and prints the log.

    log-util.py -x

    purges the log.

    Since the size of the flash memory for logging is very limited, it is recommended to purge the log before a field trial.

    Similar to updater.py, you can specify debug port, baud rate and etc. For more usage information, run log-util.py -h.

    Troubleshooting

    Install test script failure; command not found for arm-none-eabi-gcc, updater.py, log-util.py etc.

    path_var_error.jpg

    These errors indicate that the gcc and SDK tools folders have not been added to the user's PATH variable correctly, or that the profile file has not been loaded by the user after modification. 

    Review the SDK installation instructions for your development environment's operating system (Ubuntu, Windows Subsystem for Linux, macOS) and ensure you have modified your user's profile file correctly. Try restarting the shell application to ensure the modified profile file has been loaded.

    A useful test to confirm if the modified PATH variable in your profile file is correct is to add the variables only for the current shell session and then re-run the test-install.sh script. Enter the following commands; you must be in the SDK directory, use the command cd to change directory if required:

    PATH=$(pwd)/tools:/opt/gcc-arm/bin:$PATH
    ./install-test.sh

    If the install-test.sh script executes successfully after updating the PATH variable for the session, it indicates that you have not modified the profile file correctly.

    Common errors when adding path variables include incorrect file paths or adding the variables to an old or incorrect profile file. You may need to confirm the shell version you are using to determine the profile file that is in use.

    Install test script failure; python commands not found.

    python_error.jpg

    The SDK uses python3, which refers to using the command python throughout script execution. 

    A useful test is to run the command python --version, for the script to run successfully, this should return a 3.x.x response. If the version is 2.x.x, it indicates that the command python is calling a version that is incompatible with the Myriota SDK. If there is no such file or directory, it indicates that the command python is not known to the development environment.

    To confirm python3 is installed, run the command python3 --version. If python3 is not installed, try running the SDK install.sh script again, or manually install python3. If python3 is installed, follow the suggestions below for your development environment.

    On Ubuntu 20.04 and above, the package python-is-python3 is required (the install script should have installed this package); to update get-apt and install python-is-python3, run the following commands:

    sudo apt-get update
    sudo apt-get install python-is-python3

    On macOS 10.15 and above, use Homebrew to check for Python symlink warnings. Resolve any errors and warnings using the suggestions from homebrew on screen. Type the following command to check for issues:

    brew doctor

     

     

     

     

     

    Related articles