Docs › Creating or importing a program

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).

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:

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

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
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

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.
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.
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.

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.
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.
3. 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.
4. 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:

Open the File menu and select Import Program...
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.
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.
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.