应用笔记 •二零二五年四月十八日

Moku 自定义编程：入门指南

获取有关如何编译和部署自定义 FPGA 代码到 Moku 设备的步骤说明

更新日期：2025年12月1日

Moku 自定义编程是 Moku 基于 FPGA 的测试测量工具的一项创新功能。Moku 自定义仪器允许您将 VHDL 或 Verilog 代码部署到 Moku 设备上。这些代码可以提供自定义功能，并与其他预置的仪器交互，从而解锁全新且独特的仪器功能，这得益于 Moku 的片上仪器架构。

本应用说明将指导您如何开始使用 Moku 自定义编程。阅读完本指南后，您将掌握编译自定义代码并将其部署到 Moku 设备的基本知识。以下每个示例都适用于任意一款 Moku 设备。

概述

Moku 自定义编程让您能够设计自定义信号处理功能，并部署在 Moku 硬件上。与基于 CPU 和专用集成电路 (ASIC) 的 DSP 方法相比，FPGA 平台在提供接近 ASIC 级别的延迟和性能的同时，仍然能够像传统 CPU 一样进行软件编程。

虽然有很多广泛使用的软件语言可用于编写基于 CPU 设计的软件，但 FPGA 编程通常仅限于 VHDL 或 Verilog。这些需要安装庞大而复杂的本地工具和编译环境。可用于部署 HDL 代码的平台通常仅限于 FPGA 供应商提供的评估板或各种功能有限的开源硬件板。Moku 自定义编程包含两个特性：

Moku 云编译，一个基于网页端的 VHDL 和 Verilog 编译器
Moku 自定义仪器，是在 Moku 设备上用来部署编译后的代码。

Moku 自定义编程旨在满足在高性能实验室和科研硬件上进行信号自定义处理的需求，同时避免传统 FPGA 设计软件带来的额外开销。Moku 云编译网站用来编译您的自定义代码，并提供一个可直接部署任意一款 Moku 设备的 bitstream 文件。

图1：Moku 自定义编程部署流程

多仪器并行模式和 Moku 自定义编程

多仪器并行模式允许部署和同时运行多个仪器。多仪器并行模式在 Moku 平台上提供多个插槽，代表 FPGA 的不同分区。您可以灵活地将仪器部署到这些插槽中。图 2 显示了多仪器并行模式的界面，其中示波器部署在插槽 1，频谱分析仪部署在插槽 2，而插槽 3 和 4 尚未部署仪器。Moku 平台上不断扩展的仪器列表中的任何仪器都可以被部署到剩余的插槽上，包括通过自定义仪器来加载自定义 bitstream 文件。完整的仪器列表可点击这里来获取。

图 2：使用多仪器并行模式构建测试系统。

图三中的插槽四是 Moku 自定义仪器，您可以在此部署已编译好的自定义仪器。自定义仪器可以在多仪器并行模式下被部署到任何可用的插槽，除了与 ADC 和 DAC 的输入/输出交互外，还能与其他 Moku 仪器进行交互。

图 3：在插槽 4 部署 Moku 自定义仪器来构建多仪器并行模式设置。

创建 Moku 云编译账户

在编译或部署代码到 Moku 设备之前，您必须先创建一个在线帐户。流程很简单：

创建 Moku 云编译账户请点击： compile.liquidinstruments.com。如果您使用的是旧版本的 MokuOS（v4.0 之前），请点击访问旧版 Moku 云编译网站： compile-legacy.liquidinstruments.com.
如果是首次登录，您需要选择“注册”。
注册页面只需要填写用户自选的用户名、有效的电子邮件地址和用户定义的密码。
一旦注册成功并登录，您将看到项目页面，该页面初始是空白的，如图 4 所示。

图 4：Moku 云编译项目创建页面。

创建第一个项目

注册账号并登录 Moku 云编译后，您之前的所有工作和设计均可访问。此外，您还可以创建新项目，或重新构建之前的设计，以适应 Moku 平台未来的功能提升。项目页面如图 5 所示。您可以从以下位置导入现有代码： Github 点击即可进入存储库 导入示例现在，点击即可开始一个新项目。 创建项目 按钮。

图 5：Moku 云编译项目界面。

接下来，使用图 6 所示的弹出对话框，您可以为您的项目提供一个名称并开始为您的自定义功能编写代码。

图 6：新建项目对话框。

然后您将进入项目配置屏幕，如图 7 所示。请注意 构建配置 位于屏幕左下方。

图 7：项目配置页面。

在构建自定义编程之前，您必须首先指定所使用的硬件型号和 MokuOS 版本。打开构建配置下拉菜单后，硬件型号下拉菜单将允许您指定当前使用的 Moku 设备。选择正确的设备后，下拉菜单插槽数系统会根据情况自动填充。Moku:Go 和 Moku:Lab 提供两个或三个插槽的选项。最后，您必须指定 Moku 设备当前运行的 MokuOS 版本。如果您不确定正在使用哪个版本的 MokuOS 版本，您可以在 Moku App 主界面的右下角找到相关信息，如图 8 所示。最后，如果这是你的第一个云编译项目，选择目标接口下拉菜单下的 CustomInstrument（CustomWrapper 可用于确保与旧项目的兼容性）。

注意：每次在设备上更新 MokuOS 或将代码部署到不同的 Moku 硬件时，都需要重新编译。这可以通过打开项目、更改硬件类型和 MokuOS 版本选择、选择构建并下载新的 bitstream 文件来轻松完成。

图 8：设备选择屏幕，右下角显示 MokuOS 版本号。

构建你的设计

实体 CustomInstrument 是您让 HDL 代码与 Moku 硬件连接交互的方式。该实体定义了自定义设计需要实现的接口和变量。当您在 Moku 云编译上创建新文件时，代码将默认包含此实体的定义；无需进行任何更改。请注意，旧代码或示例使用实体 CustomWrapper。这两者功能类似，旨在兼容旧版代码，所有新设计确保应使用 CustomInstrument。

虽然通过 Moku 云编译成功编译的自定义仪器可以通过多仪器并行模式部署为独立仪器，但在与其他 Moku 预置的仪器结合部署运行时才能发挥其真正的优势。

你的第一个项目

在这个项目中，我们将设计一个自定义仪器，它将通过多仪器并行模式从输入 A 和输入 B 端口接收两个输入信号，并执行基本的数学运算。这两个输入信号的加法（输入A + 输入B）将从输出A输出，如图9所示。这两个输入信号的减法将从输出B输出，如图10所示。

编写 VHDL 代码

我们将使用 VHDL 语言编写这个示例，当然也可以使用 Verilog 语言。有两种方法可以将 HDL 代码集成到您项目中。首先，您可以通过点击图 11 中高亮显示的按钮，在 Moku 云编译界面中输入代码。您必须先创建一个文件来存储这段代码。在本例中，我们将创建一个名为 Adder.vhd 的文件。

图 11：在项目中创建 VHDL 文件。

我们将在此文件中输入 VHDL 设计的代码。文件创建完成后，您将看到一个可编写代码的空白模板，如图 12 所示。

图 12：在文件模板中输入代码。

对于第一个项目，您可以将完整的代码直接复制粘贴到 Adder.vhd 文件中，完成后保存即可。为了便于演示，您可以改写并覆盖 Adder.vhd 文件中的现有代码，并添加下方代码。

library ieee；

architecture Behavioural of CustomInstrument is

begin

OutputA <= InputA + InputB;

OutputB <= InputA – InputB;

end architecture;

上传 VHDL 代码

Moku 云编译用户页面还允许您直接上传已创建的 .vhd 或 .v 文件。如果您的项目很复杂，包含多个文件，或者您喜欢使用特定的文本编辑器，该功能将非常有用。图 13 显示了上传按钮，您可以通过单击它来上传您自己编写好的 VHDL 代码文件。

图 13：在 Moku 页面内上传 VHDL 代码。

从 VHDL 代码生成 bitstream

要构建您的 VHDL 设计，只需将所有 VHDL 文件保存到 Moku 云编译即可。确保构建配置正确，然后选择项目窗口右上角的 Build。项目构建过程将如图 14 所示。构建过程中的任何错误都会被突出显示，并在构建日志中提供问题描述。

图 14：Moku Cloud Compile 编译过程的各个阶段。

代码编译完成后，“IP”、“Synthesis”、“Route”和“Bitstream”图标应该全部变为绿色。您可能会看到许多编译器或合成器警告，警告信息在编译日志中显示为黄色。对于我们而言，这些警告通常可以忽略。但是，任何错误都需要引起注意，因为它们会中断编译过程。

下载并保存 bitstream

您可以将编译好的 bitstream 保存到您的计算机，以便将来在各种多仪器并行模式配置下使用和部署，而无需重新构建设计。您首先需要去到屏幕左下方，在 Build Configuration 下方点击展开 Latest Build。然后，如图 15 所示，您只需下载 bitstream.tar 文件并将其保存到任意位置，以便导入到 Moku App 中。请勿解压缩或解包此文件，但您可以将其重命名来描述其功能。

图 15：下载 bitstream。

部署自定义仪器

编译后的 bitstream 通过自定义仪器部署，通常通过多仪器并行模式与其他 Moku 预置的仪器配合使用。即使 bitstream 被设计为独立运行，您也必须通过 Moku 设备上的多仪器并行模式来使用和访问它。

多仪器并行模式配置

Moku 自定义仪器可以部署在 Moku 的任何空白插槽上。插槽的选择取决于您希望在 Moku 中实现的信号处理链路和功能。在本示例中，我们可以使用图 16 所示的 Moku:Go 多仪器并行配置。

图 16：多仪器模式配置。

我们在插槽 1 上部署示波器，示波器的输出 A 和输出 B 分别连接到插槽 2 的输入 A 和输入 B，该插槽部署了自定义仪器。默认情况下，自定义仪器的输出 A 和输出 B 会连接回插槽 1 的输入 A 和输入 B。此设置允许我们使用单个 Moku:Go 设备验证自定义仪器的功能。

加载并部署 bitstream

配置好多仪器并行配置，并构建和下载编译好的 bitstream 后，即可准备部署 bitstream。为此，请点击 Moku 自定义仪器图标下方的三个点。点击“浏览比特流”打开 Moku bitstream 浏览器，如图 17 所示。此功能可以连接到您的 Moku 云编译帐户，以便将 bitstream 直接下载到 Moku 设备。具体步骤如下所述。现在，请点击本地比特流... 找到您之前下载过的。加载完成后，点击在多仪器并行模式右上角的修改生效，您的自定义仪器即刻运行。

图 17：Moku 编译比特流浏览器。

关联您的 Moku 云编译帐户

如果您希望使用 Bitstream Browser 将比特流直接下载到您的设备，您首先需要从 Moku 云编译网站获取 API 密钥。登录后，点击右上角的图标（您的姓名首字母），然后在下拉菜单中看到偏好设置，如图 18 所示。

图 18. Moku Cloud Compile 首选项菜单。

在左侧菜单中，点击 API Keys。这样您就可以看到所有已创建的密钥。点击 Create API Key 然后输入名称。点击 Select All 启用所有复选框。准备好后，单击 Create，如图 19 所示。

图 19. API 密钥创建菜单。

然后会弹出一个窗口，其中包含您的 API 密钥。点击 Copy 将此密钥粘贴到某个位置，因为之后您将无法再次查看它。复制完成后，关闭菜单返回 API 密钥菜单，您将在该菜单中看到新密钥的名称。

返回 Moku 设备上的多仪器并使模式界面，并按照上一节图 16 中的说明进行配置。选择浏览比特流，然后单击设置 API 密钥，如图 20 所示。复制并粘贴您获得的密钥，然后单击接受。

图 20. 比特流浏览器中的 API 密钥对话框。

完成此操作后，您将在左侧看到过往创建的项目逐渐开始显示，并显示最新的构建信息。查看 “MyFirstProject”，它应该是最近编译的，如图 21 所示。点击使用比特流将其加载到您的 Moku 设备上。上传完成后，您应该返回多仪器并行模式配置界面。再继续下一步骤之前，请点击修改生效来完成配置您的 Moku。

图 21：使用比特流浏览器选择比特流。

功能验证

我们将使用示波器中的信号发生器功能来演示这个自定义仪器-加法器的功能。为了验证 Moku 自定义设计是否按预期运行，请在两个输出通道上设置一个简单的 2 VDC 信号。示波器的 A 输入端应读取两个信号的加法结果，并输出稳定的 4 V 信号。示波器的 B 输入端应读取两个信号的差值，并输出稳定的 0 V 信号，如下图所示。