Mistake on this page? Email us

Creating or importing a program

Note: Please create an Mbed OS account if you do not already have one, and log into Mbed Studio with it.

You can create new programs as:

  • An empty Mbed OS program with the latest supported version of Mbed OS.
  • An Mbed OS example application with a matching version of Mbed OS.
  • An empty folder with a manually selected version of Mbed OS.

You can import existing programs from:

  • Your local file system.
  • (As a URL) os.mbed.com/code (as a Mercurial repository) or a Git hosting service (GitHub, GitLab or Bitbucket).
  • Your Mbed Online Compiler workspace.

For programs with Mbed OS 5 and above: For new and imported programs, you can use a shared instance of Mbed OS to save hard disk space. See Using a shared instance of Mbed OS across multiple programs below.

Default and custom workspaces

Your workspace is the location in your file system that contains your Mbed programs, both imported and created. Each Mbed program is added as a child directory within your workspace.

When you install Mbed Studio, a workspace (Mbed Programs) is created for you in your home directory. You can change the workspace location if you prefer a different one, or if you want to open Mbed programs that exist in other locations on your disk (see Importing an example from your file system below).

To set a different folder as your workspace, open the File menu and select Open Workspace.... Only one workspace can be open at a time, but you can switch between workspaces quickly with File > Open Recent Workspace...:

File > Open Recent Workspace... shows a list of recently used workspaces for quick selection.

Using a shared instance of Mbed OS across multiple programs

You can save hard disk space by sharing an instance of Mbed OS across multiple programs. You can set a shared instance when creating or importing a program. For existing programs, you can switch from a copy of Mbed OS stored with each program to a shared instance from the Libraries view. When you switch to a shared instance, Mbed Studio deletes the copy of Mbed OS stored with the program.

Notes on the Arm mbed-os repository:

  • Before linking your programs to a shared instance, you must clone the Arm mbed-os GitHub repository on your machine and have it checked out to a version tag of your choice (for example: mbed-os-6.2.0).
  • For Windows users: The Arm mbed-os repository must be stored locally on your machine, it cannot be located in a network shared folder.

Creating a new empty or example program

You can create a new program from an example or an empty program either for Mbed OS 5 or Mbed OS 6.

To create a new program:

  1. Open the File menu and select New Program....

  2. To create:

    • A new Mbed program with no content other than Mbed OS: select empty Mbed OS program under Mbed OS 6 or Mbed OS 5.

    • An example program: select a program from the drop-down list under Mbed OS 6 or Mbed OS 5. Each example has a readme.md file explaining it in details. In summary, to help you choose:

    Name Description Mbed OS 5 Mbed OS 6
    blinky and blinky-bare-metal Blink an LED on the board. This example comes in two versions: blinky for the Mbed OS full profile and blinky-bare-metal for the bare metal profile. Yes Yes
    aws An application that connects to an AWS MQTT broker and publishes a message every 1 second for 10 seconds or until a message is received. Yes
    azure An application that uses the Microsoft Azure SDK to connect to an IoT Hub instance using the MQTT protocol. Yes
    google-iot-cloud An application that uses the Google Cloud IoT device SDK to connect to an IoT core instance using the MQTT protocol. It publishes a message every 3 seconds for 30 seconds or until a message is received. Yes
    mesh-minimal A light control application, where devices can control the LED status of all devices in the network. You can build it for the unsecure 6LoWPAN-ND, Thread or Wi-SUN network. Yes Yes
    pelion Connect your board to Arm Pelion Device Management to manage your devices and do remote firmware updates. Yes
    sockets A simple HTTP client program that brings up an underlying network interface, and uses it to perform an HTTP transaction over a TCPSocket. Yes Yes
    wifi Brings up the Wi-Fi and the underlying network interface, and uses it to scan available networks, connect to a network and print interface and connection details. Yes Yes
  3. In the Program name field, edit the name of the new program or keep the name provided by default.

    Mbed Studio sets the newly created program as the active program by default. Build, run and debug commands only apply to the active program. Clear the checkbox if you do not want to make the new program active.

  4. Select one of these options for the Mbed OS location:

    • Store Mbed OS in the program folder (+1GB): To download a new copy of Mbed OS and store it in your program folder.
    • Link to an existing shared Mbed OS instance: To use a shared Mbed OS instance for your program. Use the default shared instance if one has been set already or click the folder icon to point to the mbed-os repository on your file system and then click Select.
  5. Click Add Program. Mbed Studio creates the program in your workspace.

Note: To set a shared instance of Mbed OS or switch to a copy of Mbed OS stored with your program once your program has been created, see Managing libraries.

Creating a blank program

You can create a completely blank program: no Mbed OS and no standard files such as main.cpp. You must manually add a version of Mbed OS to this program.

  1. Create an empty folder that is not associated with an existing program by right-clicking an empty area in the file list:

    An empty folder is created.

  2. You must add a copy of Mbed OS to make your folder a program.

    1. Right-click the folder name and select Add Library....

    2. In the URL field, enter git@github.com:ARMmbed/mbed-os.git and click Next.

    1. From the drop-down list, select the branch or tag of Mbed OS you want to use. You can use any supported version, including patch versions.

    Tip: Release tags are listed on the Mbed OS releases page.

    1. Click Finish.

The selected branch or tag is added to the folder, and you can now use it as a program.

Note: To set a shared instance of Mbed OS or switch to a copy of Mbed OS stored with your program, go to the Libraries view and click the Switch to shared or Switch to local copy button. See Managing libraries.

Importing

Notes about importing:

  • If you import a program that has an unsupported version of Mbed OS, or that has no mbed-os library in it, you will need to add a supported version of the mbed-os library to use the program in Mbed Studio.

  • Imported programs have an .mbed file storing their settings, such as a default build target and toolchain. The file's settings can override the UI:

    • A target set in .mbed will override the target selection in the UI.
    • If you use Mbed CLI from the terminal, all .mbed settings will override UI settings.

Importing an example from your file system

You may already have Mbed OS programs on your file system. For example, you may have downloaded one from os.mbed.com/code or another online location.

To import a program from your file system:

  • Copy the program to your Mbed Studio workspace (Mbed Programs).
  • Or, if you would like to set the existing program folder as your workspace, use the Open Workspace... option.

Note: To set a shared instance of Mbed OS or switch to a copy of Mbed OS stored with your program, see Managing libraries.

Importing a program from a URL

Tip: You can import from public repositories without setting up your Git credentials. If you want to import from a private repository on Git, please set up Git credentials. Mercurial uses your Mbed account credentials, so you will have access to the same Mercurial repositories you do on os.mbed.com.

To import a program using an HTTPS or SSH URL from os.mbed.com/code or a Git hosting service:

  1. Open the File menu and select Import Program...

  2. Paste the full HTTPS or SSH URL of the relevant web page and (optionally) edit the program name.

    Mbed Studio sets the newly imported program as the active program by default. Build, run and debug commands only apply to the active program. Clear the checkbox if you do not want to make the new program active.

    Note: If your program doesn't have the mbed-os library, Mbed Studio cannot set it as active or use it. Please add a supported version of the library.

  3. Select one of these options for the Mbed OS location:

    • Store Mbed OS in the program folder (+1GB): To download a new copy of Mbed OS and store it in your program folder.
    • Link to an existing shared Mbed OS instance (for programs imported from a Git hosting service only): To use a shared Mbed OS instance for your program. Use the default shared instance if one has been set already or click the folder icon to point to the mbed-os repository on your file system and then click Select.
  4. Click Add Program. If you decided to use a copy of Mbed OS stored with your program, then Mbed Studio imports the program with the version of Mbed OS it was originally created with. If you linked your program to a shared Mbed OS instance, Mbed Studio imports the program and points to the shared instance.

Note: To set a shared instance of Mbed OS or switch to a copy of Mbed OS stored with your program once your program has been created, see Managing libraries.

Tip: When you import a program from os.mbed.com or a Git hosting service, Mbed Studio clones the repository. You can push changes back to the remote repository from Mbed Studio. For more information, see Source control.

Importing a program from the Mbed Online Compiler

To import a program from the Mbed Online Compiler:

  1. From the Mbed Online Compiler, export your program:

    • Export Target: Your export will contain only the part of Mbed OS that the selected target needs. To be able to work with other targets in Mbed Studio, you will need to repopulate the mbed-os library with the missing file. See step 3.

    • Export Toolchain: Select Zip Archive (with repositories). Specify the export target.

      Exporting from the Mbed Online Compiler

    The program is exported as a ZIP file.

  2. Unzip the file and add it to Mbed Studio. You can:

  3. Update the mbed-os library to:

    • Remove existing libraries and automatically download the latest versions, using the information contained in the {library_name}.lib file or files included in your program.
    • Repopulate the mbed-os library with the files for all supported targets.

    To update:

    1. Make your program active by right-clicking it and selecting Set Active Program.

    2. Open the Libraries view: View > Libraries.

    3. Click the Fix problems button.

      Mbed Studio will download a clean copy of Mbed OS, with all libraries, for the same version the program was already using. Please note that if that version of Mbed OS is not supported in Mbed Studio, you will need to change to a supported version.

      Fixing the mbed-os library in your imported program will repopulate it with all target files.

Further reading

You are now ready to work on your program. You can learn more about Mbed OS APIs and programming on the Mbed OS documentation site. When you're ready, build and run your program.

Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.