mxos cube 是 MXCHIP 开发的 mxos 软件开发管理工具，脚本名称：mxos-cube。它用于管理基于mxos的完整开发流程，包括：代码库版本管理，维护代码依赖，发布代码，从远程代码仓库更新以及启动mxos编译系统实现编译，下载，调试等。

本文档包含 mxos cube 的安装和使用方法。

写在前面

mxos cube 基本工作流程:

  1. 新建或者导入一个项目或组件，并为它创建一个版本库。无论新建还是导入，都会在项目中自动附带一个mxos os的版本库.
  2. 编译，下载和调试应用程序代码.
  3. 发布您的应用程序.

除了以上基本的工作流，mxos cube 针对长期的开发和维护，提供了额外的版本控制功能。它可以基于版本库进行选择性的升级，使得您的应用程序 在mxos OS和其他组件持续更新时，仍然能够维持开发时的版本，保障应用程序的可用性。

小窍门: 使用mxos --help可以列出所有mxos cube所支持的指令，特定某一个指令的帮助可以使用mxos <command> --help。

mxos cube 支持 Windows, Linux 和 macOS 三个平台 。

安装 Python

  • Python - mxos cube 是一个Python脚本，所以您需要在系统中安装Python。mxos cube 在Python version 2.7.13 下开发和测试. 不兼容Python 3。
    注意: Python的可执行文件目录(Python)需要添加到系统的PATH环境变量中，在Python安装时指定。
    在终端上输入python命令来验证Python是否正确安装：
    1. $ python --version
    2. Python 2.7.13

安装 Git

  • Git or Mercurial - mxos cube支持Git和Mercurial两种, 任选其一安装即可:
    • Git - 版本 1.9.5 及以上。
    • Mercurial - 版本 2.2.2 及以上。

注意: Git和Mercurial的可执行文件目录需要添加到系统的PATH环境变量中。
在终端上输入git --version命令来验证是否正确安装：

  1. git --version
  2. git version 2.11.0 (Apple Git-81)

下载 MiCoder Toolchain 工具包

  • MiCoder - mxos cube 调用 mxos OS 中的脚本来完成诸如编译，下载，调试等各项功能. 这些脚本的运行需要用到MiCoder 工具链，它包含了编译 mxos 应用程序所需要的工具链，根据各个 PC 平台提供相应版本。

安装 mxos cube

您可以从执行 pip install mxos-cube 命令来安装 mxos cube：

  1. $ pip install mxos-cube
  2.   Collecting mxos-cube
  3.   Downloading https://files.pythonhosted.org/packages/53/3a/71fe1e6d4685e639d195dfcfcc050e4b5d672760668fa35ea0bc7b3d1488/mxos_cube-0.1.0-py2-none-any.whl
  4.   Installing collected packages: mxos-cube
  5.   Successfully installed mxos-cube-0.1.0

在 Linux 和 macOS 上, 需要加上 sudo 获得安装权限.

在macOS上，默认已经安装了python 2.7，可以通过下面的方法安装对应的pip工具。

  1. curl https://bootstrap.pypa.io/pip/2.7/get-pip.py -o get-pip.py
  2. python get-pip.py

下载完mxos-cube后，记得把mxos可执行文件路径添加到PATH中。

升级 mxos cube

mxos cube安装完成后，可以通过pip install --upgrade mxos-cube命令来升级mxos cube的版本。

  1. $ pip install --upgrade mxos-cube
  2. Requirement already up-to-date: mxos-cube in /usr/local/lib/python2.7/site-packages (0.1.0)

在Linux和macOS上, 需要加上sudo获得安装权限.

了解工作交换区和项目根目录

mxos cube 和 Git，Mercurial 等其命令行工具一样，使用当前路径作为工作交换区。所以当您执行任何mxos cube的版本控制命令之前，需要首先将当前路径切换到包含需要操作的代码目录。

例如，如果您需要升级你的 mxos-example-program 项目中的 mxos os 的源代码：

  1. $ cd mxos-example-program
  2. $ cd mxos
  3. $ mxos update master   # This will update "mxos", not "mxos-example-program"

mxos os 也是包含版本管理的开源项目，允许各个开发者向 mxos os 贡献代码。

mxos 项目开发时，需要实现对整个项目以及包含的组件能够自由地切换版本，管理历史记录，与版本库同步，与其他开发者共享等等。因此需要一个基于版本控制 Git 或者 Mercurial 的项目根目录。此外，项目根目录下保存了项目的一些配置信息，所以在编译mxos项目时，应将路径切换到项目根目录下。使用mxos new，mxos import命令会自动将源代码根目录设置成项目根目录。而如果从Git仓库上直接下载的源代码，则应该进入源代码路径，并且执行mxos new .将当前目录设置成项目根目录。

注意: mxos cube 在以.component 为后缀的文件（例如lib_name.component）中保存依赖组件的链接信息; 以.code 为后缀的文件（例如name_src.codes）中保存可选依赖组件的链接信息. 这些文件都是可读的文本文件，但是我们强烈建议不要手动修改文件的内容，而是使用mxos cube的相应命令来自动生成和修改，例如：$ mxos sync。这些文件我们称之为依赖描述文件。

创建和导入项目

mxos cube 可以创建和导入基于 mxos 的软件项目。

创建一个新项目

每当你创建一个新项目，mxos cube 自动导入最新的 mxos sdk 每一个发布都包含了所有组件: 代码和编译调试脚本。

接下来让我们来创建一个新的项目 (命名为mxos-program):

  1. $ mxos new mxos-program
  2. [mxos] Creating new program "mxos-program" (git)
  3. [mxos] Adding component "mxos" from "https://code.aliyun.com/mxos/mxos.git" at latest revision in the current branch
  4. [mxos] Updating reference "mxos" -> "https://code.aliyun.com/mxos/mxos.git/#cdb0b3b8ab9aea947ea2a2972841237d1bf7276f"

Tips:若需要看到详细的项目创建过程 log 信息，可以在指令中加入 -v -vv 后缀，形如： $ mxos new mxos-program -v -vv

这个命令创建了一个新的目录”mxos-os-program”，初始化了一个新的版本库并且在项目中导入了一个最新版本的mxos-os依赖。

Tips: 使用参数--scm [name|none]， 您能够选择版本库的格式，或者选择不初始化版本库。

使用mxos ls列出项目中所有导入的组件

  1. $ cd mxos-program
  2. $ mxos ls -a
  3. mxos-program (jenny_git/test2/mxos-program)
  4. `- mxos (https://code.aliyun.com/mxos/mxos.git#26acf1a9d635)

Note: 如果您从一个现有的空目录开始，可以使用mxos new .命令来初始化mxos项目，并且在该文件夹中初始化版本仓库。

  1. $ cd emptyfolder
  2. $ mxos new .
  3. [mxos] Creating new program "test2" (git)
  4. [mxos] Adding component "mxos" from "https://code.aliyun.com/mxos/mxos.git" at latest revision in the current branch
  5. no[mxos] Updating reference "mxos" -> "https://code.aliyun.com/mxos/mxos.git/#26acf1a9d6359e19e0039b8d97f53c61ecf5fbe9"

创建不包含mxos os的新项目

你可以通过命令参数 --create-only 来创建一个不包含mxos os，也即 无包含 mxos 文件夹目录的空工程。

  1. $ mxos new noos --creat-only
  2. [mxos] Creating new program "noos" (git)
  3. [mxos] Adding component "mxos" from "https://code.aliyun.com/mxos/mxos.git" at latest revision in the current branch
  4. [mxos] Updating reference "mxos" -> "https://code.aliyun.com/mxos/mxos.git/#26acf1a9d6359e19e0039b8d97f53c61ecf5fbe9"

导入一个现有的项目

导入第一个mxos应用程序demos

你可以使用 mxos import 命令从一个版本仓库克隆一个项目到本地，并且部署所有依赖项：

  1. $ mxos import https://code.aliyun.com/mxos/demos.git
  2. [mxos] Importing program "demos" from "https://code.aliyun.com/mxos/demos.git" at latest revision in the current branch
  3. [mxos] Adding component "mxos" from "https://code.aliyun.com/mxos/mxos.git" at rev #576c9ee9fb7d

Tips:若需要看到详细的项目导入过程 log 信息，可以在指令中加入 -v -vv 后缀，形如：

$ mxos import https://code.aliyun.com/mxos/demos.git -v -vv

说明：如果你在”import”命令中不指定完整的路径，mxos cube会自动加上默认的路径前缀 (https://code.aliyun.com/mxos) 。例如，以下命令:

  1. $ mxos import demos

与这个命令等价

  1. $ mxos import https://code.aliyun.com/mxos/demos.git

提示：更多的项目仓库地址可查看：mxos的项目和组件 获取到的项目开发包中的 mxos os 有可能不是最新版本，可通过进入 mxos 目录，查看最新版本并更新。指令如下：

  1. $ cd mxos
  2. $ git tag
  3. 0.1
  4. 0.2
  5. $ mxos update 0.2
  6. [mxos] Updating library "mxos" to branch 0.2
  7. [mxos] Adding component "platform/MCU/RTL8721D/sdk" from "https://code.aliyun.com/mico_inner_developer/ameba-d.git" at rev #a62178232ae1

demos 是什么

demos 中包含了各单个功能的示例代码，如：os内核，hardware外设，wifi无线，wifi_uart串口透传，安全算法，net网络通信，http通信等。

  1. $ mxos import https://code.aliyun.com/mxos/mxos-demos.git
  2. [mxos] Importing program "mxos-demos" from "https://code.aliyun.com/mxos/mxos-demos.git" at latest revision in the current branch
  3. [mxos] Adding library "mxos-os" from "https://code.aliyun.com/mxos/mxos-os.git" at rev #dd36dc4228b5
  4. $ cd mxos-demos

Tips:若需要看到详细的项目导入过程 log 信息，可以在指令中加入 -v -vv 后缀，形如： $ mxos import https://code.aliyun.com/mxos/mxos-demos.git -v -vv

从一个现有的 Git 仓库克隆导入

如果你在工作区中手动克隆了一个Git版本库，现有想要添加所有丢失的依赖组件。可以使用 deploy 命令：

  1. $ mxos deploy
  2. [mxos] Updating component "mxos" to rev #3534b5cadeeb
  3. [mxos] Updating component "mxos/platform/MCU/RTL8721D/sdk" to rev #a62178232ae1

然后，不要忘了将当前项目路径设置为项目根目录:

  1. $ mxos new .

添加和移除组件

在编写mxos代码时，常常需要在应用程序中添加另一个组件（依赖），或者移除一个现有的组件。

mxos cube添加和删除功能不等同于hg, git版本管理软件的内置功能，而是针对mxos项目的特点进行了改造：

  • 将新的组件添加到项目中不等同于从版本库中克隆一个仓库，所以不要使用 hg 或 git 命令，而要使用 mxos add 来添加组件。它可以保证所有的依赖（组件以及子组件）都能被同时生成出来。
  • 移除一个组件也不仅仅是删除这个组件目录 - 依赖描述文件（.component）也需要删除和升级。使用 mxos remove 命令来移除组件，而不要简单地使用 rm 命令。

添加组件

使用 mxos add 命令添加组件的最新版本：

  1. $ mxos add https://code.aliyun.com/mxos/Lib_aws.git

可以使用URL#hash格式来添加一个组件的特定版本 format to add a library at a specific revision:

  1. $ mxos add https://code.aliyun.com/mxos/Lib_aws.git/#e5a0dcb43ecc

提示：更多的组件仓库地址可查看：mxos的项目和组件。

移除组件

如果不再需要一个组件，你能够使用 mxos remove 命令来删除这个组件：

  1. $ mxos remove Lib_aws

代码编译

配置 MiCoder 路径

完成项目创建和导入后，你需要为 mxos cube 设置 MiCoder 工具链的路径，以便mxos cube调用这些工具来编译mxos项目。
你可以通过以下命令来设置 MiCoder 的路径（注意:路径中不可以包含空格，否则路径无效）：

  1. $ mxos config --global MICODER /Users/haiqin/jenny_tools/MiCoder
  2. [mxos] /Users/haiqin/jenny_tools/MiCoder now set as default MICODER in program "demos"

-G 或 --global 开关可以让mxos Cube设置一个全局的参数，而不是针对当前项目的私有参数。

你可以通过下面的命令查看 MiCoder 的配置路径：

  1. $ mxos config --list
  2. [mxos] Global config:
  3. MICODER=/Users/haiqin/jenny_tools/MiCoder
  5. [mxos] Local config (/Users/haiqin/jenny_git/test/demos):
  6. MICODER=/Users/haiqin/jenny_tools/MiCoder

编译项目

使用mxos make 命令来编译项目:

  1. $ mxos make helloworld@MK3165
  2. make helloworld@MK3165
  3. Making config file for first time
  4. processing components: helloworld MK3165 FreeRTOS LwIP wolfSSL mxos
  5. mxos core based on pre-build library: ===mxos.3165.GCC.a=== 
  6. Skipping building bootloader due to "total" is not set
  8. Compiling App_Helloworld
  9. Compiling Board_MK3165
  10. Compiling FreeRTOS
  11. ... [SNIP] ...
  12. Making build/helloworld@MK3165/libraries/STM32F4xx_Peripheral_Libraries.a
  13. Making helloworld@MK3165.elf
  15. Making helloworld@MK3165.hex
  16. Making helloworld@MK3165.bin
  18.                         mxos MEMORY MAP                            
  19. |=================================================================|
  20. | MODULE                                   | ROM       | RAM      |
  21. |=================================================================|
  22. | App_Helloworld                           | 141       | 0        |
  23. ... [SNIP] ...
  24. | STM32F4xx_Peripheral_Drivers             | 9299      | 236      |
  25. | STM32F4xx_Peripheral_Libraries           | 5948      | 16       |
  26. | *fill*                                   | 253       | 926      |
  27. |=================================================================|
  28. | TOTAL (bytes)                            | 243524    | 34971    |
  29. |=================================================================|
  30. Build complete
  31. Making .gdbinit
  32. Making .openocd_cfg

make 编译命令格式：

<target> [download] [run | debug] [JTAG=xxx] [VERBOSE=1] [JOBS=<jobs>]

具体参数如下:

  • <target>用于选择编译目标. 目标由参与编译的各个组件构成, 以下的每一个组件用’@’分割开来。
    • Application （项目中需要编译的应用程序组件，即应用程序在项目中的路径，并将/替换成.）
    • Board ( mxos/board/*中定义的硬件平台组件 )
    • [RTOS] ( mxos/mxos/rtos/*中定义的RTOS内核组件, 默认使用 FreeRTOS )
    • [Network Stack] ( mxos/mxos/net/*中定义的网络协议栈组件，默认使用 LwIP )
    • [TLS] ( mxos/mxos/security/TLS/*中定义的安全传输组件, 默认使用 wolfSSL )
    • [debug | release_log | release] ( 编译选项默认使用release_log ）
  • [download] 通过调试器下载目标固件到硬件平台，。
  • [run|debug] 通过调试器复位硬件并运行程序或者连接到目标处理器进行调试。
  • [JTAG=xxx] mxos/makefiles/OpenOCD/interface 中定义的JTAG接口配置文件。省略不写即默认使用jlink_swd。
  • [VERBOSE=1] (可选) 显示编译过程中运行的命令。
  • [JOBS=<jobs>] (可选) 控制多线程编译，提高编译速度。默认值是 4。可以根据处理器核心的数量来设置这个参数，也可以使用 JOBS=1 来执行单线程的顺序编译。

如：

  • 编译基于 MiCOKit-3165 的 Helloworld 应用程序，使用命令：mxos make helloworld@MK3165 JTAG=jlink_swd
  • 编译基于 MiCOKit-3165 的 Helloworld 应用程序和其他固件，使用命令：mxos make helloworld@MK3165 total
  • 编译并且下载基于 MiCOKit-3031 的 Helloworld 应用程序和其他相关固件，使用命令：mxos make helloworld@MK3031 total download JTAG=jlink_swd
  • 编译并且下载基于 MXKit-3080B 的 Helloworld 应用程序和其他相关固件，使用命令： mxos make helloworld@MK3080B total download JTAG=jlink_swd

注意：

  • 编译生成的可执行文件，ELF文件，内存使用和链接数据可以在 build/<target>/binary 目录下找到。

编译静态库

使用 mxos makelib 命令来将您自己的代码编译成静态库。

命令： mxos makelib --new source

参数：

  • [--new]：用于生成静态库编译依赖.mk文件。
  • <source>：源文件所在目录。

步骤：

  1. 使用 mxos makelib --new 命令生成静态库编译描述文件 .mk；
  2. 打开 .mk 文件，添加编译静态库需要的编译参数、宏，搜索路径和源代码文件；
  3. 使用 mxos makelib 命令在上层文件夹中生成静态库文件。

案例：
假设项目根目录为 demos，在demos/mxos/staticlib下有需要编译成静态库的头文件mystaticlib.h和源文件mystaticlib.c。

  1. 进入mxos项目根目录 cd demos。
  2. 运行 mxos makelib --new mxos/staticlib。在 “staticlib” 目录下会自动生成 “staticlib_src.mk”。
  3. 修改文件 staticlib_src.mk ``` NAME := staticlib

Add compiler flags here

$(NAME)_CFLAGS :=

Add definations here

$(NAME)_DEFINES :=

Add includes path here, should be realtive path to current directory

$(NAME)_INCLUDES := .

Add sources path here, should be realtive path to current directory

$(NAME)_SOURCES := mystaticlib.c

  2. 4. 运行`mxos makelib mxos-os/staticlib`命令，在目录 "demos/mxos" 下将会生成所编译的静态库文件。

$ mxos makelib mxos/staticlib

Compiling mxos-os/mystaticlib/mystaticlib.c Make staticlib.Cortex-M3.GCC.release.a DONE

Compiling mxos-os/mystaticlib/mystaticlib.c Make staticlib.Cortex-M4.GCC.release.a DONE

Compiling mxos-os/mystaticlib/mystaticlib.c Make staticlib.Cortex-M4F.GCC.release.a DONE

  3. <a name="0353496e"></a>
  4. ## 推送改动
  6. <a name="7072ea2f"></a>
  7. ### 检查本地状态
  9. 在软件开发过程中，你总是会对你的代码或者是依赖的组件中的代码进行修改。通过运行 `mxos status` 命令，你可以递归地获得当前项目以及所有依赖组件的修改状态，如果版本库中有没有提交的修改，指令的运行结果会显示这些改动。<br />例如：

$ mxos status [mxos] Status for “demos”: M mxos.component

[mxos] Status for “mxos”: M platform/MCU/STM32F4xx/platform_init.c

  2. 你可以提交或者丢弃这些改动。
  4. <a name="84b98b47"></a>
  5. ### 推送到远端仓库
  7. 使用 `mxos publish`命令将本地的改动推送到远端。`publish` 是递归执行的，它首先推送树叶依赖项，然后更新上层的依赖描述文件，再推送上层.
  9. 下面举一个例子说明，假设我们的项目的依赖关系如下（使用 `mxos ls` 命令）：

my-mxos-example (a5ac4bf2e468) |- mxos(5fea6e69ec1a) - my-libs (e39199afa2da) |- my-libs/iot-client (571cfef17dd0)- my-libs/test-framework (cd18b5a50df4)

  2. 我们假设在 `iot-client` 组件上作了修改。  `mxos publish` 会执行以下操作：
  4. 1. 检测树叶依赖项 `iot-client` ，并且询问你是否要提交改动。
  5. 2. 检测父项 `my-libs`。
  7. - 更新 `my-libs` 的依赖描述文件（ `iot-client.component`  文件），将描述文件中的链接地址更新到最新的 `iot-client` 版本。
  8. - 再询问您是否要提交`my-libs` 的改动。
  10. 3. 最终检查 `my-mxos-os-example` 项目，更新依赖描述文件并提交。
  12. <a name="efed2291"></a>
  13. ## 发布本地项目或组件
  15. 当你新建一个新的（本地）基于版本控制的项目或者组件，他们的版本历史仅存在于本地，而没有远程仓库同步。你可以按照以下步骤将本地版本库推送到远端，而不丢失本地保存的历史版本：
  17. 1. 首先在远程服务器上创建一个新的版本库，服务器可以是一个公共的代码管理服务（ GitHub, Bitbucke，code.aliyun 等），你自己的私有服务，甚至是你本地系统上的另一个地址 (例如创建一个本地版本库 `mxos-os-example/local-lib`)。
  18. 2. 关联远程仓库。
  20. - 使用Git命令 `git remote add origin <url-or-paht-to-your-remote-repo>`.
  22. 4. 运行 `mxos publish` 来发布您的改动。
  24. 在使用了嵌套的本地版本库，应先从叶子版本库开始。
  26. <a name="e8f8c36b"></a>
  27. ### 从原始仓库派生的工作流-Forking
  29. Git支持非对称工作流：发布／推送的远端仓库和原始("origin")不同。这就使得新的版本存放在一个由原始仓库派生的版本仓库中的同时，又可以和原始的仓库保持同步。通过这种方式，在一个有没有权限的仓库派生的仓库中修改代码，完成版本的同步，最终向原始仓库提交推送请求。
  31. 为了实现这个功能，应首先导入一个mxos OS项目，组件或者mxos OS本身，然后设置他们的推送目标到一个由原始仓库派生（"Fork"）的远程仓库。例如：

$ git remote set-url —push origin https://code.aliyun.com/william/repo-fork.git

  2. 这样，每次你使用`git`来提交或者推送，或是使用 `mxos publish`，新的版本将会推送到你的派生仓库。你仍然可以从原始仓库中通过 `mxos update` 或 `git pull`更新版本。如果你希望从你的衍生仓库拉取版本，可以使用`git pull https://code.aliyun.com/william/repo-fork [branch]`。
  4. 通过上面描述的工作流，mxos cube 保持了与原始版本库（最终你会提交一个推送请求）的联系，并且记录了你推送到衍生版本库的版本记录。在原始仓库接受您的衍生仓库生成的推送请求（ pull request ）之前，所有记录的版本链接对于其他开发者都是无效的。一旦推送请求被接受，您的衍生仓库中的版本就变成了原始版本库的一部分，版本链接也就生效了。
  6. <a name="e484ee4f"></a>
  7. ## 升级项目和组件
  9. 你可以从远程仓库中拉取改动到本地项目和组件。
  11. 在升级时，有两种主要的应用场景：
  13. - 升级到 _持续更新_ 版本, 例如一个分支的最新版本。
  14. - 升级到 _特定_ 版本，版本通过提交的哈希值或者标签名称来定义。
  16. 每一种场景又两种案例：
  18. - 更新并保留本地的改动 - _污染_ 升级。
  19. - 更新并删除本地的改动 - _干净_ 升级。
  21. 和其他的mxos cube命令一行，`mxos update` 命令使用当前目录作为工作交换区，所以在执行 `mxos update` 之前，应首先将当前的工作目录切换到需要更新的版本库目录。例如，如果你需要更新mxos-os，先使用 `cd mxos-os` 。
  23. **Tip: 同步组件链接:** 在触发更新之前，你可能需要同步您之前对项目架构所做的改动，`mxos sync` 命令可以自动更新必须的组件依赖描述文件，并且删除无效的描述文件。
  25. <a name="2d2a1fdf"></a>
  26. ### 防止覆盖本地改动
  28. 如果在执行升级时，如果本地的改动会被覆盖， `update` 命令会直接报错。这是mxos cube的设计初衷，可以防止任何本地未提交的改动被覆盖，从而丢失代码。所以在升级时如果出错，看一下本地的改动（提交改动，或者使用下面的选项），然后重新运行 `update`。
  30. <a name="dfa4836f"></a>
  31. ### 升级到远端版本
  33. **_升级项目_**
  35. 要将你的项目升级到远程仓库的另一个版本，先进入项目的根目录，然后运行：

$ mxos update [branch|tag|revision]

  2. 该命令从远程仓库读取版本，将当前项目升级到指定的分支，标签和版本。如果都没有指定，则升级到当前分支的最新版本。该命令是递归执行的，新版本项目中的所有依赖和子依赖都同步更新。
  4. **_升级组件_**
  6. 当你将当前工作目录切换到组件的目录下，执行 `mxos update` 可以升级组件和他的依赖项到另一个版本，而不是父项目中依赖描述文件中指定的版本。这个功能允许你使用非原本项目树中指定的版本来进行实验，而不需要去修改软件项目或是上级组件。
  8. <a name="b548b8d9"></a>
  9. ### 升级示例
  11. 以下示例帮助你理解mxos cube的各种升级选项。
  13. **案例 1: 我要升级一个项目或者组件到指定的或当前分支的最新版本**
  15. **我希望保留本地未提交的改动**
  17. 运行 `mxos update [branch]`。<br />如果本地有改动则命令会报错，除非你用版本控制工具（Git）将这些改动提交到一个分支 `git commit`，或者储藏起来`git stash`。
  19. **我需要一个干净的升级（丢弃所有本地未提交的改动）**
  21. 运行 `mxos update [branch] --clean`
  23. 在 `mxos update` 命令中指定另一个远程分支，仅仅将这个分支check out出来，而不会合并或者fast-forward。你也可以使用 `mxos update`命令，不加参数来获得远程仓库中的最新版本并与本地版本进行合并（fast-forward）。“mxos update”和`git pull`等价。
  25. **Warning**: `--clean` 告诉mxos Cube升级项目或者组件以及他们的依赖项，并且覆盖所有本地的改动。这个操纵无法复原，所以要谨慎执行。
  27. **案例 2: 我要升级一个项目或者组件到指定版本或者标签**
  29. **我希望保留本地未提交的改动**
  31. 运行 `mxos update [branch]`。<br />如果本地有改动则命令会报错，除非你用版本控制工具（Git）将这些改动提交到一个分支 `git commit`，或者储藏起来`git stash`。
  33. **我需要一个干净的升级（丢弃所有本地未提交的改动）**
  35. 运行 `mxos update <tag_name|revision> --clean`
  37. **当我有未发布的本地组件**
  39. 这里有额外的三个选项来处理本地未发布的组件：
  41. - `mxos update --clean-deps` - 升级当前项目和组件以及他们的依赖项，丢弃所有本地未发布的版本库。所以用这个参数需要谨慎，因为你的本地未发布的版本库是无法恢复的。
  42. - `mxos update --clean-files` - 升级当前项目和组件以及他们的依赖项，丢弃所有未提交的改动，删除所有未跟踪或者忽略的文件。所以用这个参数需要谨慎，因为你的本地未发布的版本库是无法恢复的。
  43. - `mxos update --ignore` - 升级当前项目和组件以及他们的依赖项，丢弃所有未提交的改动并且忽略所有本地未发布的版本库（这些版本库不会被删除或修改，仅仅是忽略了）。
  45. **合并升级选项**
  47. 在以下场景中，升级选项可以合并起来使用：
  49. - `mxos update --clean --clean-deps --clean-files` - 升级当前项目和组件以及他们的依赖项，丢弃所有本地未发布的版本库，丢弃所有未提交的改动，删除所有未跟踪或者忽略的文件。这个现象丢弃了所有你在本地项目和组件中所做的改动，恢复项目的布局。
  50. - `mxos update --clean --ignore` - 升级当前项目和组件以及他们的依赖项，但是忽略所有的本地未提交的版本库。mxos Cube尽可能地从远端公共仓库获取新的版本。
  52. <a name="3b95bc38"></a>
  53. ## MXOS IDE
  55. MXOS 采用 Visual Studio Code 作为其图形化 IDE 集成开发环境，提高代码开发效率并提升调试的体验。
  57. 开发者也可以进一步在 VSCode 上添加额外的插件增强功能。VSCode 的功能非常强大，本文仅介绍其基本使用方法。
  59. > **注意：使用 VSCode 编译调试 MXOS SDK 之前，请先完成安装mxos cube，完成 MXOS 项目的编译和下载。**
  62. <a name="6e9dd5d9"></a>
  63. ## 安装 Visual Studio Code
  65. 请从以下链接中获取您的 PC 系统类型对应的安装包，并根据提示完成安装: [Visual Studio Code](https://code.visualstudio.com)
  67. <a name="de8d9aaf"></a>
  68. ## Visual Studio Code使用
  70. 1. **打开软件**
  72. 双击图标，打开 Visual Studio Code 软件：
  74. 2. **导入MXOS项目SDK**
  76. 打开 Visual Studio Code 软件，选择菜单栏：File-->open，选择：mxos sdk，如demos文件夹，点击 打开 。
  78. 3. **编译与下载**
  80. （1） 选择菜单栏：View，选择：Terminal， 打开命令终端 功能区。
  82. （2） 命令终端中输入 mxos make target 命令，如图：
  84. ![](image/3.mxos_ide/make_target.jpg#id=q2qwY&originalType=binary&ratio=1&status=done&style=none)
  86. 这些Target的名称是 mxos cube 中的 `mxos make` 命令中的参数，参考：[mxos cube 编译项目](/docs/MXOS/%E7%8E%AF%E5%A2%83%E6%90%AD%E5%BB%BA.html)。
  88. (3)  若编译中有错误，将自动报错，双击该报错处可自动跳至改行，进行修改调试。
  90. ![](image/3.mxos_ide/compile_error.jpg#id=oHgPp&originalType=binary&ratio=1&status=done&style=none)
  92. <a name="d760edae"></a>
  93. ## 其它调试工具与驱动
  95. <a name="12a2da11"></a>
  96. ### 1.JTAG调试器使用
  98. JTAG 调试器用于连接 PC 和目标硬件，将 PC 上编译的可执行文件下载到目标硬件上，并且可以对目标硬件进行调试。

PC == == 调试器 == == 目标硬件

  2. > 注：如果目标硬件上已经包含了一个调试器，就只需要将PC和目标硬件用USB线连接起来即可。
  5. 在 MXOS 的开发中，可以使用以下调试器：JLink, STLink, DAPLink。有些调试器需要安装驱动程序（详见下文），此外，在编译应用程序时，应使用参数 JTAG=XXX 选择使用的调试器。
  7. | 调试器 | 编译参数 |
  8. | --- | --- |
  9. | JLink SWD接口（默认） | JTAG=jlink_swd |
  10. | JLink JTAG接口 | JTAG=jlink |
  11. | STLink | JTAG=stlink-v2或者stlink-v2-1 |
  12. | DAPLink | JTAG=cmsis-dap |
  15. 例如，在 MiCOKit-3165 板上外接不同的 JTAG 调试器来下载和调试 helloworld 应用，需首先编译命令如下：

mxos make helloworld@MK3165 download JTAG=jlink_swd 或 mxos make helloworld@MK3165 download JTAG=jlink 或 mxos make helloworld@MK3165 download JTAG=stlink-v2 或 mxos make helloworld@MK3165 download JTAG=stlink-v2-1

  2. <a name="c8ed4761"></a>
  3. #### JLink驱动
  5. 目前由 MXOS 支持的所有硬件平台均支持 JLink 调试器 （V8 或 V9）。在macOS，Linux平台上将Jlink连接上PC的USB接口后即可使用。
  7. 在Windows下的安装步骤如下：
  9. 1.下载和安装 JLink 驱动程序：[Setup_JLink_V600i.zip](http://developer.mxchip.com/fileDownload/338).安装完成显示：
  11. ![](image/5.jtag/jlink.png#id=regVi&originalType=binary&ratio=1&status=done&style=none)
  13. 2.下载 Jlink 的 libusb 驱动：[Jlink_Driver_for_mxos.zip](http://firmware.mxchip.com/jlink_driver_for_mxos.zip)，解压缩后运行： zadig.exe 或 zadig_xp.exe（用于Windows XP）
  15. ![](image/5.jtag/exe_path.png#id=DlPDh&originalType=binary&ratio=1&status=done&style=none)
  17. 3.选择菜单： Options->List All Devices，下拉列表选择 J-Link，Driver 选择 “libusb-win32（v1.2.6.0）"，点击 "Replace Driver"，返回 "successful" 后即可关闭。在设备管理器中会出现 "libusb-win32 devices。
  19. 如果您用的是 JLinkV8，更新过程如下：
  21. ![](image/5.jtag/jlink_v8_old.png#id=jzLPQ&originalType=binary&ratio=1&status=done&style=none)   ![](image/5.jtag/jlinkv8_update.png#id=gDTIf&originalType=binary&ratio=1&status=done&style=none)
  23. 如果您用的是 JLinkV9，更新过程如下：
  25. ![](image/5.jtag/jlink_v9_old.png#id=oYK6S&originalType=binary&ratio=1&status=done&style=none)   ![](image/5.jtag/jlinkv9_update1.png#id=c7eSU&originalType=binary&ratio=1&status=done&style=none)
  27. ![](image/5.jtag/jlinkv9_update2.png#id=hS3fG&originalType=binary&ratio=1&status=done&style=none)
  29. > 注意：由于不同厂家的 JLink 固件版本不同，导致部分JLink驱动更换为libusb-win32（v1.2.6.0）后可能无法正常工作。这种情况下可尝试使用 "libusbK (v3.0.7.0)"。
  32. ![](image/5.jtag/jlink_libusbk_update.png#id=GMboS&originalType=binary&ratio=1&status=done&style=none)  ![](image/5.jtag/jlink_libusbk_show.png#id=b3U5f&originalType=binary&ratio=1&status=done&style=none)
  34. <a name="STLink"></a>
  35. ### STLink
  37. 如使用 ST 系列的 MCU作为主控制器，可使用 STLink 仿真器下载和调试。驱动程序下载：[STLINK/V2](http://www.st.com/content/st_com/en/products/development-tools/hardware-development-tools/development-tool-hardware-for-mcus/debug-hardware-for-mcus/debug-hardware-for-stm32-mcus/st-link-v2.html)
  39. ![](image/5.jtag/stlink_show.png#id=t2eXq&originalType=binary&ratio=1&status=done&style=none)
  41. <a name="DAPLink"></a>
  42. ### DAPLink
  44. DAPLink 是由ARM提供的开源调试器，支持所有使用Corrtex-M内核的微控制器，且无需安装驱动程序，但是下载和调试的速度比JLink慢。
  46. <a name="df8699e0"></a>
  47. ### 在串口终端上进行调试
  49. 运行mxos的设备可以通过串口与主机输出调试信息，处理用户指令。在mxos系统启动时，通常会从串口上输出类似的调试信息：
  51. ![](image/5.serial/serial_log.png#id=L88oY&originalType=binary&ratio=1&status=done&style=none)
  53. 传统串口通讯的硬件连接方式如下：

PC==<串口线>==目标硬件

  2. 由于现在的PC上通常不带串行端口，因此通常使用USB／串口转换器将串口的数据转换成USB的数据，并在PC上生成一个虚拟的串口，实现设备和PC的交互。

PC====USB／串口转换器==<串口线>==目标硬件 ```

FTDI系列

FTDI系列性能较好，点击： 线上购买链接

FIDI串口转换器驱动程序：FTDI_D2XX Driver。

集成了FTDI系列串口转换器的开发板有：MXKit系列开发板。

CP2102串口转换器

CP2102也是常用的串口转换器，对应的USB／串口转换线也可以买到： 驱动程序下载：CP2102 Driver

串口调试终端

串口调试终端是在PC上运行的，通过图形化窗口向串口收发数据的软件。其中一些软件支持特定的文件传输协议，如 XModem，YModem等。

SecureCRT（建议安装）

SecureCRT支持在Windows和macOS下运行，不仅支持串口交互，也支持文件传输协议。下载地址
该软件还支持 “Ymodem 协议” ，可在 mxos 的 bootloader模式下进行固件更新等操作。点击了解Bootloader命令详情

格西烽火

格西烽火适用于针对 mxos AT 指令的开发与调试。

Tips：同时针对MXCHIP提供的AT指令，提供命令工程模版。

第三方开发工具及驱动

以下是：基于 MXOS 系统二次开发物联网智能设备时，需要用到的第三方工具及驱动程序。

串口转换工具 TTL转USB

当使用 mxos 用户串口进行开发调试时，通常需要外接 TTL转USB 模块，与 PC 连接进行调试，这里推荐使用：CP2102 USB Bridge Driver。
安装后，即可通过 PC 端串口调试软件，连接对应的 COM 端口，进行串口通信调试。

micro usb串口驱动

mxosKit 开发板的 micro-usb 调试串口log信息查看，需要 PC 端安装驱动软件，可至：
FTDI_D2XX Driver 页面，根据您的 PC 系统类型下载。

Socket 调试工具

mxos 为开发者提供的基本的 TCP、UDP通信服务接口，开发时通常要用到 Socket 通信调试工具，推荐一个soket 调试工具下载链接：TCPUDPDebug102_Setup.exe。

MQTT 服务测试工具

mxos 设备连接的一些云服务支持 MQTT协议，开发者通常需要搭建一个 MQTT客户端进行测试，这里推荐一个 MQTT客户端测试工具下载链接：MQTT.fx。