Using tools in the terminal

Mbed Studio's terminal supports all command line interfaces for its integrated tools. Use the terminal to access commands not directly exposed in Mbed Studio's UI, such as pyOCD debugging and cherry picking between Git branches.

Warning: Python library versions

Some commands import Python libraries automatically. This can cause Mbed Studio to become unstable or unusable where it requires different versions of the same libraries. These commands include:

• mbed import

  An Mbed CLI command that updates all Python libraries based on the Mbed OS version of the imported program. As an example, see the Mbed OS master branch's requirements file.

• pip install and pip uninstall

  pip automatically replaces Python libraries to match the package you're installing. Mbed Studio ships with its own Python installation, and pip in the Mbed Studio terminal modifies this installation, which may cause elements of the UI that rely on Python libraries to fail.

We therefore strongly recommend that you do not use these commands in Mbed Studio.

Note: If you are experiencing problems with Mbed Studio after using the terminal, please use our support forum and let us know which tools and commands you used.

Opening the terminal and setting working directory

There are two ways to open the terminal:

• From the main menu choose Terminal > New terminal.

  The new terminal opens with the current working directory set to the workspace path. The default for this path is {home_directory}/Mbed Programs; if you open a different workspace, the terminal will default to it instead.

  If you need to change your working directory, use cd to navigate to the correct program, as shown in the image below.

• Right-click the program name and choose Open in Terminal.

  The new terminal uses the program as its working directory.

You can open more than one terminal. Each terminal opens in a new tab that "hides" the other tabs. If you want to see two terminals side by side, click the Split button to the right of the terminal tab (shown in red below). This creates a new terminal in a separate series of tabs:

Splitting a terminal. When opening a terminal, use cd to navigate to the correct program.

Running Greentea tests

Greentea is the automated testing tool for Mbed OS. It flashes tests to development boards, starts the tests and generates test reports. The full documentation for Greentea is available on the Mbed OS documentation site, and includes an explanation of command line options.

You can familiarise yourself with Greentea by using the tests included in the example program mbed-os-example-blinky:

1. Import mbed-os-example-blinky to Mbed Studio.

2. Right-click the program and select Open in Terminal.

   The terminal opens with your program as the working context.

   The general form of commands for Greentea is mbed test.

3. To see all tests:

   mbed test --compile-list
   

4. Use the MBED_TEST_MODE macro to prevent multiple main() functions in your program. See the Greentea documentation for instructions.

5. To run a test (in this example, the RTC driver tests):

   mbed test -t ARMC6 -m K64F -v -n mbed-os-tests-mbed_drivers-rtc
   

   Tip: If you connect a board over serial, you don't have to specify it with -m <target name>.

Using Mbed CLI

Mbed CLI is the Mbed OS build system. It's documented in full in the Mbed OS documentation.

You may want to use Mbed CLI in the terminal if:

• You want to refine the features Mbed Studio offers, such as compile. For example, you may want to define macros.

  Tip: You don't have to use the target flag or toolchain flag when using mbed compile; Mbed Studio take those from the selections you made in the UI. If you do use the flag, note that it supersedes the UI selection if they contradict.

• You want to use features that Mbed Studio doesn't fully support, such as the export feature.

Warning: Mbed CLI and Mbed Studio manage Mbed OS libraries differently, which can lead to problems when using mbed import. For example, you may not be able to build a program if you've imported another program with different library versions. Additionally, mbed import is one of the two commands that can change Mbed Studio Python libraries, as explained above. For these reasons we strongly recommend not using mbed import.