build: Add flash option to build command

Add `-f/--flash` option to `build` command to flash the generated binary
onto the device connected to host machine.

By default `.bin` file will be used for flashing. If `--hex-file`
option is passed on the command line, then `.hex` will be used.

Author: urutva

news/20201112095757.feature

@@ -0,0 +1 @@
+Add flash option to build command

src/mbed_tools/build/__init__.py

@@ -12,3 +12,4 @@
 """
 from mbed_tools.build.build import build_project, generate_build_system
 from mbed_tools.build.config import generate_config
+from mbed_tools.build.flash import flash_binary

src/mbed_tools/build/exceptions.py

@@ -12,3 +12,11 @@ class MbedBuildError(ToolsError):
 
 class InvalidExportOutputDirectory(MbedBuildError):
     """It is not possible to export to the provided output directory."""
+
+
+class BinaryFileNotFoundError(MbedBuildError):
+    """The binary file (.bin/.hex) cannot be found in cmake_build directory."""
+
+
+class DeviceNotFoundError(MbedBuildError):
+    """The requested device is not connected to your system."""

src/mbed_tools/build/flash.py

@@ -0,0 +1,85 @@
+#
+# Copyright (C) 2020 Arm Mbed. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+"""Flash binary onto the connected device."""
+
+import shutil
+import os
+import pathlib
+import platform
+
+from mbed_tools.devices.device import Device
+from mbed_tools.devices.devices import get_connected_devices
+from mbed_tools.build.exceptions import BinaryFileNotFoundError, DeviceNotFoundError
+
+
+def _flash_dev(disk: pathlib.Path, image_path: pathlib.Path) -> None:
+    """Flash device using copy method.
+
+    Args:
+        disk: Device mount point.
+        image_path: Image file to be copied to device.
+    """
+    shutil.copy(image_path, disk, follow_symlinks=False)
+    if not platform.system() == "Windows":
+        os.sync()
+
+
+def _find_connected_device(mbed_target: str) -> Device:
+    """Check if requested device is connected to the system.
+
+    Look through the devices connected to the system and if a requested device is found then return it.
+
+    Args:
+       mbed_target: The name of the Mbed target to build for.
+
+    Returns:
+        Device if requested device is connected to system.
+
+    Raises:
+        DeviceNotFoundError: the requested board is not connected to the system
+    """
+    connected_devices = get_connected_devices()
+    for device in connected_devices.identified_devices:
+        if device.mbed_board.board_type.upper() == mbed_target.upper():
+            return device
+
+    raise DeviceNotFoundError("The target board you compiled for is not connected to your system.")
+
+
+def _build_binary_file_path(program_path: pathlib.Path, build_dir: pathlib.Path, hex_file: bool) -> pathlib.Path:
+    """Build binary file name.
+
+    Args:
+       program_path: Path to the Mbed project.
+       build_dir: Path to the CMake build folder.
+       hex_file: Use hex file.
+
+    Returns:
+        Path to binary file.
+
+    Raises:
+        BinaryFileNotFoundError: binary file not found in the path specified
+    """
+    fw_fbase = build_dir / program_path.name
+    fw_file = fw_fbase.with_suffix(".hex" if hex_file else ".bin")
+    if not fw_file.exists():
+        raise BinaryFileNotFoundError(f"Build program file (firmware) not found {fw_file}")
+    return fw_file
+
+
+def flash_binary(program_path: pathlib.Path, build_dir: pathlib.Path, mbed_target: str, hex_file: bool) -> None:
+    """Flash binary onto a device.
+
+    Look through the connected devices and flash the binary if the connected and built target matches.
+
+    Args:
+       program_path: Path to the Mbed project.
+       build_dir: Path to the CMake build folder.
+       mbed_target: The name of the Mbed target to build for.
+       hex_file: Use hex file.
+    """
+    device = _find_connected_device(mbed_target)
+    fw_file = _build_binary_file_path(program_path, build_dir, hex_file)
+    _flash_dev(device.mount_points[0].resolve(), fw_file)

src/mbed_tools/cli/build.py

@@ -9,7 +9,7 @@
 
 import click
 
-from mbed_tools.build import build_project, generate_build_system, generate_config
+from mbed_tools.build import build_project, generate_build_system, generate_config, flash_binary
 from mbed_tools.project import MbedProgram
 
 
@@ -29,7 +29,21 @@
     default=os.getcwd(),
     help="Path to local Mbed program. By default it is the current working directory.",
 )
-def build(program_path: str, build_type: str, toolchain: str = "", mbed_target: str = "", clean: bool = False) -> None:
+@click.option(
+    "-f", "--flash", is_flag=True, default=False, help="Flash the binary onto a device",
+)
+@click.option(
+    "--hex-file", is_flag=True, default=False, help="Use hex file, this option should be used with '-f/--flash' option",
+)
+def build(
+    program_path: str,
+    build_type: str,
+    toolchain: str = "",
+    mbed_target: str = "",
+    clean: bool = False,
+    flash: bool = False,
+    hex_file: bool = False,
+) -> None:
     """Configure and build an Mbed project using CMake and Ninja.
 
     If the project has already been configured and contains '.mbedbuild/mbed_config.cmake', this command will skip the
@@ -44,6 +58,8 @@ def build(program_path: str, build_type: str, toolchain: str = "", mbed_target:
        toolchain: The toolchain to use for the build.
        mbed_target: The name of the Mbed target to build for.
        clean: Perform a clean build.
+       flash: Flash the binary onto a device.
+       hex_file: Use hex file, this option should be used with '-f/--flash' option.
     """
     program = MbedProgram.from_existing(pathlib.Path(program_path))
     mbed_config_file = program.files.cmake_config_file
@@ -60,6 +76,11 @@ def build(program_path: str, build_type: str, toolchain: str = "", mbed_target:
     click.echo("Building Mbed project...")
     build_project(build_tree)
 
+    if flash:
+        flash_binary(program.root, build_tree, mbed_target, hex_file)
+    elif hex_file:
+        click.echo("'--hex-file' option should be used with '-f/--flash' option")
+
 
 def _validate_target_and_toolchain_args(target: str, toolchain: str) -> None:
     if not all([toolchain, target]):

tests/build/factories.py

@@ -0,0 +1,43 @@
+#
+# Copyright (C) 2020 Arm Mbed. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+import factory
+import pathlib
+
+from typing import List
+
+from mbed_tools.devices.device import Device, ConnectedDevices
+from mbed_tools.targets.board import Board
+
+
+class BoardFactory(factory.Factory):
+    class Meta:
+        model = Board
+
+    board_type = "TEST"
+    board_name = ""
+    product_code = ""
+    target_type = ""
+    slug = ""
+    build_variant = []
+    mbed_os_support = []
+    mbed_enabled = []
+
+
+class DeviceFactory(factory.Factory):
+    class Meta:
+        model = Device
+
+    serial_port = ""
+    serial_number = ""
+    mount_points = [pathlib.Path(".")]
+    mbed_board = BoardFactory()
+
+
+class ConnectedDevicesFactory(factory.Factory):
+    class Meta:
+        model = ConnectedDevices
+
+    identified_devices: List[Device]
+    unidentified_devices: List[Device]

tests/build/test_flash.py

@@ -0,0 +1,108 @@
+#
+# Copyright (C) 2020 Arm Mbed. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+
+import pathlib
+import tempfile
+
+from unittest import TestCase, mock
+
+from mbed_tools.devices.device import ConnectedDevices
+from mbed_tools.build.flash import flash_binary, _build_binary_file_path, _find_connected_device, _flash_dev
+from mbed_tools.build.exceptions import BinaryFileNotFoundError, DeviceNotFoundError
+
+from tests.build.factories import DeviceFactory, ConnectedDevicesFactory
+
+
+@mock.patch("mbed_tools.build.flash._find_connected_device")
+@mock.patch("mbed_tools.build.flash._build_binary_file_path")
+@mock.patch("mbed_tools.build.flash._flash_dev")
+class TestFlashBinary(TestCase):
+    def test_check_flashing(self, _flash_dev, _build_binary_file_path, _find_connected_device):
+        test_device = DeviceFactory()
+
+        _find_connected_device.return_value = test_device
+        _flash_dev.return_value = True
+
+        with tempfile.TemporaryDirectory() as tmpDir:
+            base_dir = pathlib.Path(tmpDir)
+            build_dir = base_dir / "cmake_build"
+            build_dir.mkdir()
+            bin_file = base_dir.name + ".bin"
+            bin_file = build_dir / bin_file
+            bin_file.touch()
+            _build_binary_file_path.return_value = bin_file
+
+            flash_binary(base_dir, build_dir, "TEST", False)
+
+            _find_connected_device.assert_called_once_with("TEST")
+            _build_binary_file_path.assert_called_once_with(base_dir, build_dir, False)
+            _flash_dev.assert_called_once_with(test_device.mount_points[0].resolve(), bin_file)
+
+
+class TestBuildBinFilePath(TestCase):
+    def test_build_bin_file_path(self):
+        with tempfile.TemporaryDirectory() as tmpDir:
+            base_dir = pathlib.Path(tmpDir)
+            build_dir = base_dir / "cmake_build"
+            build_dir.mkdir()
+            bin_file = base_dir.name + ".bin"
+            bin_file = build_dir / bin_file
+            bin_file.touch()
+
+            self.assertEqual(_build_binary_file_path(base_dir, build_dir, False), bin_file)
+
+    def test_build_hex_file_path(self):
+        with tempfile.TemporaryDirectory() as tmpDir:
+            base_dir = pathlib.Path(tmpDir)
+            build_dir = base_dir / "cmake_build"
+            build_dir.mkdir()
+            bin_file = base_dir.name + ".hex"
+            bin_file = build_dir / bin_file
+            bin_file.touch()
+
+            self.assertEqual(_build_binary_file_path(base_dir, build_dir, True), bin_file)
+
+    def test_missing_binary_file(self):
+        with tempfile.TemporaryDirectory() as tmpDir:
+            base_dir = pathlib.Path(tmpDir)
+            build_dir = base_dir / "cmake_build"
+            build_dir.mkdir()
+
+            with self.assertRaises(BinaryFileNotFoundError):
+                _build_binary_file_path(base_dir, build_dir, False)
+
+
+@mock.patch("mbed_tools.build.flash.get_connected_devices")
+class TestFindConnectedDevices(TestCase):
+    def test_check_missing_device(self, get_connected_devices):
+        get_connected_devices.return_value = ConnectedDevicesFactory()
+        with self.assertRaises(DeviceNotFoundError):
+            _find_connected_device("TEST")
+
+    def test_connected_device(self, get_connected_devices):
+        test_device = DeviceFactory()
+
+        test_connected_devices = ConnectedDevices()
+        test_connected_devices.identified_devices = [test_device]
+        get_connected_devices.return_value = test_connected_devices
+
+        self.assertEqual(_find_connected_device("TEST"), test_device)
+
+
+@mock.patch("mbed_tools.build.flash.shutil.copy")
+class TestCopyToDevice(TestCase):
+    def test_copy_to_device(self, copy):
+        test_device = DeviceFactory()
+
+        with tempfile.TemporaryDirectory() as tmpDir:
+            base_dir = pathlib.Path(tmpDir)
+            build_dir = base_dir / "cmake_build"
+            build_dir.mkdir()
+            bin_file = base_dir.name + ".bin"
+            bin_file = build_dir / bin_file
+            bin_file.touch()
+            _flash_dev(test_device.mount_points[0].resolve(), bin_file)
+
+            copy.assert_called_once_with(bin_file, test_device.mount_points[0].resolve(), follow_symlinks=False)

tests/cli/test_build.py

@@ -143,3 +143,27 @@ def test_build_folder_removed_when_clean_flag_passed(
             generate_config.assert_called_once_with(target.upper(), toolchain.upper(), program)
             generate_build_system.assert_called_once_with(program.root, program.files.cmake_build_dir, "develop")
             self.assertFalse(program.files.cmake_build_dir.exists())
+
+    @mock.patch("mbed_tools.cli.build.flash_binary")
+    def test_build_flash_option(
+        self, flash_binary, generate_config, mbed_program, build_project, generate_build_system
+    ):
+        runner = CliRunner()
+        runner.invoke(build, ["--flash"])
+        flash_binary.assert_called_once()
+
+    @mock.patch("mbed_tools.cli.build.flash_binary")
+    def test_build_flash_and_hex_file_options(
+        self, flash_binary, generate_config, mbed_program, build_project, generate_build_system
+    ):
+        runner = CliRunner()
+        runner.invoke(build, ["--flash", "--hex-file"])
+        call_args = flash_binary.call_args
+        args, kwargs = call_args
+        flash_binary.assert_called_once_with(args[0], args[1], args[2], True)
+
+    def test_build_only_hex_file_option(self, generate_config, mbed_program, build_project, generate_build_system):
+        runner = CliRunner()
+        result = runner.invoke(build, ["--hex-file"])
+
+        self.assertRegex(result.output, "-f/--flash")