19、PIM恒温器示例：硬件、安装、构建与使用全解析

PIM恒温器示例：硬件、安装、构建与使用全解析

1. 目标硬件

恒温器示例可在ARM Cortex - M4微控制器上运行，同时还有一个支持在Windows和Linux上作为控制台应用程序执行的功能模拟器。硬件平台详情如图1所示（此处虽未展示图，但文档中有提及）。

硬件相关说明	详情
运行平台	ARM Cortex - M4微控制器
模拟器支持系统	Windows和Linux（控制台应用程序）

恒温器示例有如下需求：
|需求编号|需求描述|
|----|----|
|C001|应能够将室内温度控制到零误差（简单误差控制不可接受），不过在没有可变容量HVAC设备的情况下，零误差控制无法实现，但控制算法应具备在有可变容量设备时实现零误差的能力。|
|C002|应提供“自动模式”，能智能确定恒温器应处于加热还是冷却模式。|
|C003|应让用户能够将HVAC系统设置为“风扇自动”或“风扇连续”模式。|
|C004|应跟踪室内风扇的运行小时数，在达到可配置的小时数后，提醒房主更换室内空气过滤器。|
|A001|当室外机组出现故障时应发出警报，此要求仅适用于物理HVAC设备能够向恒温器报告此类故障的情况（如通信HVAC系统）。|
|A002|当室内机组出现故障时应发出警报，此要求仅适用于物理HVAC设备能够向恒温器报告此类故障的情况（如通信HVAC系统）。|
|A003|当温度传感器出现故障时应发出警报。|

2. 安装和设置

恒温器示例的源代码可在GitHub的https://github.com/johnttaylor/pim 仓库中找到，该示例代码在Windows和Linux PC上均可运行，但使用Linux作为主机环境存在一些限制：
- 不支持针对目标硬件进行构建，但支持为Linux构建模拟器。
- 代码覆盖率脚本不能保证正常工作。
- ratt脚本不能保证正常工作，ratt是基于Python pexpect库构建的测试工具，用于对算法代码进行一些自动化测试。
- 不支持Doxygen。

Windows和Linux的最低先决条件如下：
- Python 3.6或更高版本。
- 至少安装一个编译器。
- 安装Git客户端（如果不想克隆仓库，而是使用从GitHub下载的zip文件，则此为可选）。

在目标平台上运行还需要以下额外物品：
- Adafruit Grand Central M4 Arduino板。
- 带有10针插头和连接器的兼容JTAG编程器（如Segger JLINK）。
- 用于ATSAM51/Arduino的GCC - ARM Cortex M/R交叉编译器（建议使用Arduino IDE安装此编译器，且仅在Windows主机环境下支持针对目标硬件进行构建）。
- 串行终端应用程序（如Windows的PuTTY或Linux的minicom）。

3. Linux设置

在Linux上，需要进行以下设置：
1. 在Linux PC上安装GCC编译器，安装整个GCC工具链和工具，安装后假设GCC编译器在命令路径中。
2. 将PIM仓库克隆到PC，仓库可以安装在PC的任何位置，但仓库位置的根路径不能包含任何空格。
3. 使用source shell命令运行env.sh脚本，该脚本位于克隆仓库的根目录，示例如下：

~/work/pim $ source env.sh

env.sh shell脚本每个终端窗口只需运行一次，此时即可构建任何linux/gcc项目或单元测试。

4. Windows设置

在Windows上，需要进行以下设置：
1. 安装至少一个编译器，用于构建恒温器示例和大多数单元测试的Windows编译器列表如下：
- Microsoft Visual Studio（社区版免费且效果良好，需要支持C++11语言标准的版本，若只安装一个编译器，推荐此款）。
- GCC for Windows（即mingw - w64编译器，http://mingw - w64.org/doku.php ，安装64位版本，且建议安装支持生成32位和64位应用程序的编译器工具链，因为mingw_w64构建脚本默认进行32位构建）。
- GCC - ARM Cortex M/R交叉编译器用于ATSAM51/Arduino（构建目标硬件时使用，可通过Arduino IDE安装）。
2. 将PIM仓库克隆到PC，仓库可安装在任何位置，但根路径不能包含空格，且不要将仓库放置在文件系统过深的位置，以免路径过长触及Windows路径长度限制。
3. 设置支持脚本，使在Windows上构建时，PIM环境能够找到已安装的编译器。需要为每个安装的编译器编辑这些脚本，脚本位于top/compilers/目录，每个安装的编译器都需要一个Windows批处理文件。这些脚本负责更新该编译器的环境，例如将编译器添加到Windows命令路径、设置编译器或调试工具所需的环境变量等。每个脚本还提供一个“友好名称”，用于在运行env.bat脚本时识别编译器。以下是top/compilers/vcvars32 - vc16.bat文件示例：

01|@echo off
02|IF "/%1"=="/name" ECHO:Visual Studio VC16 (32bit) compiler
  |for |Windows & exit /b 0
03|
04|call "C:\Program Files (x86)\Microsoft Visual
  |Studio\2019\Community\VC\Auxiliary\Build\vcvars32.bat"

第2行设置“友好名称”，第4行调用Visual Studio提供的批处理文件，需根据本地安装情况编辑此线。

以下是top/compilers/atsamd51 - arduino - v7.bat批处理文件示例：

01|@echo off
02|IF "/%1"=="/name" ECHO:GCC - ARM Cortex M/R cross compiler for
  |ATSAM51/Arduino & exit /b 0
03|
04|:: Core Arduino tools
05|set ARDUINO_TOOLS=C:\Users\User\AppData\Local\Arduino15\ 
|packages\adafruit
06|set ARDUINO_COMPILER_VER=7 - 2017q4
07|set ARDUINO_BSP_VER=1.5.7
08|
09|:: Additional/extras
10|set SEGGER_TOOLS_JLINK="e:\Program Files (x86)\SEGGER\JLink"
11|set SEGGER_TOOLS_OZONE="e:\Program Files\SEGGER\Ozone V3.10a"
12|
13|echo:GCC ARM - Cortex M4 (%ARDUINO_COMPILER_VER%), Adafruit's
  |Grand Central BSP (v%ARDUINO_BSP_VER%) setup

第2行设置“友好名称”，第5 - 7行定义Arduino编译器的安装位置，需根据本地安装情况编辑。Arduino编译器不添加到Windows命令路径，因为PIM构建脚本直接使用ARDUINO_xxxx环境变量。第9 - 11行设置使用Segger JLINK JTAG调试器的环境，若不使用JLINK，可删除这些行，若需要添加支持JTAG工具的额外行，可在此处添加。
4. 运行env.bat文件，从命令窗口（即DOS框）切换到克隆仓库的根目录，然后运行env.bat脚本，示例如下：

c:\work\pim> env.bat

不带任何参数运行脚本将显示可用编译器列表，要选择编译器工具链，再次运行脚本并指定所需编译器工具链的编号，例如：

c:\work\pim> env.bat 1

env.bat shell脚本每个命令窗口每个编译器只需运行一次，要选择不同的编译器，只需再次运行env.bat脚本并指定不同的编号（由于编译器环境设置方式，对于给定编译器，可能无法无限制地运行env.bat，若环境空间耗尽，只需关闭终端窗口并打开新的命令窗口）。此时即可构建任何windows/ 项目或测试， 的可能值如下：
- windows/vc12（任何支持C++11的Visual Studio编译器）。
- windows/mingw_w64（任何支持C++11的MinGW_64编译器）。
- adafruit - grand - central - m4/windows/gcc（用于ATSAM51 Arduino的ARM Cortex M/R交叉编译器）。

5. 构建

PIM仓库的目录结构将源代码目录与执行构建的目录分开，在以下顶级目录结构中，应用程序构建和单元测试分别在projects/和tests/目录树中进行，源代码位于src/或xsrc/目录树中。

<workspace root>
├───docs
├───projects       ; Build applications/released images
├───resources
├───scripts
├───src
├───tests          ; Build unit tests
├───top
└───xsrc

要构建应用程序或单元测试，只需导航到projects/或tests/目录内的叶目录，然后运行nqbp.py脚本，所有项目和单元测试都通过运行nqbp.py脚本来构建。

6. 使用GCC编译器在Linux上构建

以下是构建功能模拟器的脚本示例，示例从运行env.sh脚本开始，env.sh脚本每个编译器每个终端窗口只需运行一次：

~/work/pim $ . ./env.sh
Environment set (using native GCC compiler)
~/work/pim $ cd projects/Storm/Thermostat/simulation/linux/gcc
~/work/pim/projects/Storm/Thermostat/simulation/linux/gcc $ nqbp.py
===========================================================================
= START of build for:  thermostat - simulation.out
= Project Directory:   pim/projects/Storm/Thermostat/simulation/linux/gcc
= Toolchain:           GCC
= Build Configuration: posix64
= Begin (UTC):         Sun, 26 Jul 2020 17:10:17
= Build Time:          1595783417 (5f1db8f9)
===========================================================================
= Cleaning Built artifacts...
= Cleaning Project and local Package derived objects...
= Cleaning External Package derived objects...
= Cleaning Absolute Path derived objects...
=====================
= Building Directory: src/Storm/Thermostat/Main
= Compiling: Main.cpp
=
= Archiving: library.a
=====================
= Building Directory: src/Storm/Thermostat
= Compiling: Algorithm.cpp
= Compiling: ModelPoints.cpp
=
= Archiving: library.a
...
=====================
= Building Project Directory:
main.cpp
=====================
= Linking...
===========================================================================
= END of build for:    thermostat - simulation.out
= Project Directory    pim/projects/Storm/Thermostat/simulation/linux/gcc
= Toolchain:           GCC
= Build Configuration: posix64
= Elapsed Time (hh mm:ss): 00 00:38
===========================================================================

7. 使用Visual Studio编译器在Windows上构建

以下是构建功能模拟器的脚本示例，示例从运行env.bat脚本开始，env.bat脚本每个编译器每个终端窗口只需运行一次：

c:\work\pim>env.bat
NO TOOLCHAIN SET
1 - GCC - ARM Cortex M/R cross compiler for ATSAM51/Arduino
2 - GCC - AVR cross compiler for Atmel AVR/arduino
3 - GCC - RX cross compiler for Renesas RX
4 - MINGW64 v5.1.0 compiler for Windows
5 - GCC - ARM Cortex M/R cross compiler for NRF52/Arduino
6 - Visual Studio VC14 (32bit) compiler for Windows
7 - Visual Studio VC16 (32bit) compiler for Windows
8 - Visual Studio VC16 (64bit) compiler for Windows
c:\work\pim>env.bat 7
**********************************************************************
** Visual Studio 2019 Developer Command Prompt v16.3.10
** Copyright (c) 2019 Microsoft Corporation
**********************************************************************
[vcvarsall.bat] Environment initialized for: 'x86'
c:\work\pim>cd projects\Storm\Thermostat\simulation\windows\vc12
c:\work\pim\projects\Storm\Thermostat\simulation\windows\vc12>nqbp.py
===========================================================================
= START of build for: thermostat - simulation.exe
= Project Directory   pim\projects\Storm\Thermostat\simulation\windows\vc12
= Toolchain:          VC++ 12, 32bit (Visual Studio 2013)
= Build Configuration: win32
= Begin (UTC):         Sun, 26 Jul 2020 17:04:01
= Build Time:          1595783041 (5f1db781)
===========================================================================
= Cleaning Built artifacts...
= Cleaning Project and local Package derived objects...
= Cleaning External Package derived objects...
= Cleaning Absolute Path derived objects...
=====================
= Building Directory: src\Storm\Thermostat\Main
Main.cpp
=
= Archiving: library.lib
=====================
= Building Directory: src\Storm\Thermostat
Algorithm.cpp
ModelPoints.cpp
=
= Archiving: library.lib
...
=====================
= Building Project Directory:
main.cpp
=====================
= Linking...
===========================================================================
= END of build for:   thermostat - simulation.exe
= Project Directory   pim\projects\Storm\Thermostat\simulation\windows\vc12
= Toolchain:          VC++ 12, 32bit (Visual Studio 2013)
= Build Configuration: win32
= Elapsed Time (hh mm:ss): 00 01:11
===========================================================================

8. 构建目录命名约定

PIM鼓励构建功能模拟器和大量单元测试，这意味着要使用多个编译器和多个目标平台（如目标硬件、PC控制台应用程序等），为防止名称冲突，PIM建议从一开始就为构建目录制定包含管理不同编译器和不同目标平台的命名约定。

PIM仓库分别使用projects/和tests/目录将发布实体与单元测试分开，具体定义如下：
- projects/树包含任何非自动化或手动单元测试的应用程序或实体。
- tests/树仅包含自动化和手动单元测试的构建目录。

对于项目，PIM仓库使用以下命名约定：

projects/<project - name>/<hostplatform>/<compiler>

其中：
- 是一个或多个子目录，用于标识项目，需考虑应用程序变体（如产品系列中的不同产品）、目标硬件与模拟平台等。
- 是执行构建所需的主机平台，通常是Windows或Linux。
- 是使用的编译器，编译器名称没有正式的命名结构，但在所有项目和测试构建中命名要保持一致。

对于单元测试，PIM仓库使用以下命名约定：

tests/<component - path>
        /_0test/[<qualifier>/][<targetplatform>/]<hostplatform>/<compiler>

其中：
- 是一个或多个子目录，是被测试组件的命名空间目录路径，例如src/Cpl/Container组件的 是tests/Cpl/Container。
- 是可选参数，可指定一个或多个子目录，典型用例是单个组件或命名空间有多个单元测试可执行文件的情况，例如src/Cpl/System组件有验证组件实时运行的单元测试以及使用模拟时间的单元测试，示例如下：

tests/Cpl/System/_0test/realtime, tests/Cpl/System/_0test/simtime

• 是可选参数，可为一个或多个子目录，用例是有通用单元测试代码可在不同平台上执行的情况，例如src/Cpl/File组件可使用以下任何一种作为底层实现：
  • C标准库FILE*函数。
  • POSIX文件描述符。
  • 原生Win32文件函数。
    当使用FILE*函数测试Cpl::File组件时，单元测试仍需在Linux和Windows下构建，因此使用ansi作为 限定符，会得到以下两个目录树：

tests/Cpl/Io/File/_0test/ansi/linux
tests/Cpl/Io/File/_0test/ansi/windows

• 是执行构建所需的主机平台，通常是Windows或Linux。
• 是使用的编译器，编译器名称没有正式的命名结构，但在所有项目和测试构建中命名要保持一致。

PIM建议为单元测试可执行文件名称制定命名约定，一致的测试映像命名约定可大大简化CI构建脚本中单元测试的构建和执行，例如NQBP构建引擎有两个支持脚本bob.py和chuck.py，可递归构建和执行单元测试，以下是使用Visual Studio编译器构建并执行tests/目录下构建的单元测试（一次并行执行四个）的bob.py和chuck.py脚本的命令行用法示例：

c:\work\pim\tests>bob.py vc12
...
c:\work\pim\tests>chuck.py -4 --match a.exe –dir vc12

单元测试命名约定示例如下表：
|单元测试|映像名称|描述|
|----|----|----|
|自动化且可并行执行的单元测试|a.exe | a.out|可直接执行且能与其他单元测试并行运行的所有自动化单元测试的名称。|
|自动化但不可并行执行的单元测试|aa.exe | aa.out|可直接执行但不能与其他单元测试并行运行的自动化单元测试的名称，例如使用硬编码TCP/IP套接字端口号的单元测试。|
|通过脚本调用且可并行执行的自动化单元测试|b.exe | b.out|通过脚本调用且可与其他单元测试并行运行的所有自动化单元测试的名称。|
|通过脚本调用且不可并行执行的单元测试|bb.exe | bb.out|通过脚本调用但不能与其他单元测试并行运行的单元测试的名称。|
|负责调用测试映像且可并行运行的脚本|a.py|负责调用测试映像且可与其他单元测试并行运行的所有脚本的名称，例如Cpl::Io::Stdio组件的单元测试验证来自STDIO的输入/输出，a.py脚本将测试文本管道传输到a.exe单元测试映像。|
|负责调用测试映像且不可并行运行的脚本|aa.py|负责调用测试映像且不能与其他单元测试并行运行的所有脚本的名称。|

9. PIM恒温器应用程序使用

本节提供了执行PIM恒温器应用程序的一些基本入门说明，在硬件或模拟器上运行后，可尝试各种CLI命令，并通过直接读写模型点来深入了解其内部机制。

10. 在目标硬件上运行

构建脚本设置为为Atmel SAMD51微控制器构建独立的固件映像（无引导加载程序），此外，需要一个兼容的JTAG编程器将映像编程到板上，构建目录中有支持脚本，可对板进行编程并启动Segger的Ozone调试工具，这些脚本特定于Segger工具。

PIM恒温器示例：硬件、安装、构建与使用全解析

11. 恒温器功能与需求分析

恒温器示例具备一系列重要功能，这些功能通过具体的需求来定义，以下是详细的需求列表：
|需求编号|需求描述|
|----|----|
|C001|应实现室内温度零误差控制，但需可变容量HVAC设备支持，控制算法要具备在有该设备时实现零误差的能力。|
|C002|提供“自动模式”，能智能判断恒温器应处于加热还是冷却模式。|
|C003|允许用户将HVAC系统设置为“风扇自动”或“风扇连续”模式。|
|C004|跟踪室内风扇运行小时数，达到可配置小时数后提醒房主更换室内空气过滤器。|
|A001|当室外机组故障且物理HVAC设备能向恒温器报告时发出警报。|
|A002|当室内机组故障且物理HVAC设备能向恒温器报告时发出警报。|
|A003|温度传感器故障时发出警报。|

这些需求明确了恒温器的核心功能，为后续的开发和测试提供了清晰的方向。

12. 硬件平台概述

恒温器示例可在ARM Cortex - M4微控制器上运行，同时也有支持在Windows和Linux上作为控制台应用程序的功能模拟器。硬件平台的详细信息如下：

graph LR
    classDef process fill:#E5F6FF,stroke:#73A6FF,stroke-width:2px;
    A(ARM Cortex - M4微控制器):::process --> B(运行恒温器示例):::process
    C(功能模拟器):::process --> D(Windows):::process
    C --> E(Linux):::process
    D --> F(控制台应用程序):::process
    E --> F

该流程图展示了恒温器示例在不同硬件和系统环境下的运行关系。

13. 安装与设置流程总结

无论是在Linux还是Windows环境下，安装和设置都有明确的步骤和要求。下面通过表格总结不同环境下的安装设置要点：
|环境|设置步骤|
|----|----|
|Linux|1. 安装GCC编译器及工具链，确保在命令路径中。
2. 克隆PIM仓库，根路径无空格。
3. 使用 source 命令运行 env.sh 脚本。|
|Windows|1. 安装至少一个编译器（如Microsoft Visual Studio、GCC for Windows、GCC - ARM Cortex M/R交叉编译器）。
2. 克隆PIM仓库，注意路径无空格且不过深。
3. 设置支持脚本，为每个编译器创建批处理文件。
4. 运行 env.bat 脚本选择编译器。|

14. 构建过程解析

PIM仓库的构建过程有其独特的目录结构和脚本使用方式。
- 目录结构 ：源代码与构建目录分离，应用程序和单元测试分别在 projects/ 和 tests/ 目录树中构建，源代码位于 src/ 或 xsrc/ 目录树。

<workspace root>
├───docs
├───projects       ; Build applications/released images
├───resources
├───scripts
├───src
├───tests          ; Build unit tests
├───top
└───xsrc

• 构建脚本 ：所有项目和单元测试都通过运行 nqbp.py 脚本来构建，不同环境下构建示例如下：
  • Linux（GCC编译器） ：

~/work/pim $ . ./env.sh
~/work/pim $ cd projects/Storm/Thermostat/simulation/linux/gcc
~/work/pim/projects/Storm/Thermostat/simulation/linux/gcc $ nqbp.py

- **Windows（Visual Studio编译器）**：

c:\work\pim>env.bat
c:\work\pim>env.bat 7
c:\work\pim>cd projects\Storm\Thermostat\simulation\windows\vc12
c:\work\pim\projects\Storm\Thermostat\simulation\windows\vc12>nqbp.py

15. 构建目录命名策略

为避免不同编译器和目标平台下的名称冲突，PIM仓库采用了特定的命名约定：
- 项目命名约定 ： projects/<project - name>/<hostplatform>/<compiler>
- <project - name> ：标识项目，考虑应用变体、目标硬件与模拟平台等。
- <hostplatform> ：执行构建的主机平台，通常是Windows或Linux。
- <compiler> ：使用的编译器，命名保持一致。
- 单元测试命名约定 ： tests/<component - path>/_0test/[<qualifier>/][<targetplatform>/]<hostplatform>/<compiler>
- <component - path> ：被测试组件的命名空间目录路径。
- <qualifier> ：可选，用于区分同一组件的多个单元测试。
- <targetplatform> ：可选，适用于通用单元测试代码在不同平台执行的情况。
- <hostplatform> ：执行构建的主机平台。
- <compiler> ：使用的编译器。

16. 单元测试命名规范及执行

单元测试的命名规范有助于简化CI构建脚本，以下是具体的命名规范及示例：
|单元测试类型|映像名称|描述|
|----|----|----|
|自动化且可并行执行|a.exe | a.out|可直接执行且能并行运行的自动化单元测试。|
|自动化但不可并行执行|aa.exe | aa.out|使用硬编码端口号等情况的单元测试。|
|通过脚本调用且可并行执行|b.exe | b.out|通过脚本调用且可并行的自动化单元测试。|
|通过脚本调用且不可并行执行|bb.exe | bb.out|通过脚本调用但不可并行的单元测试。|
|负责调用测试映像且可并行运行的脚本|a.py|将测试文本管道传输到测试映像的脚本。|
|负责调用测试映像且不可并行运行的脚本|aa.py|不可并行运行的调用脚本。|

使用NQBP构建引擎的 bob.py 和 chuck.py 脚本可以递归构建和执行单元测试，示例命令如下：

c:\work\pim\tests>bob.py vc12
c:\work\pim\tests>chuck.py -4 --match a.exe –dir vc12

17. 恒温器应用运行要点

在目标硬件上运行PIM恒温器应用时，构建脚本会为Atmel SAMD51微控制器构建独立固件映像（无引导加载程序），还需要兼容的JTAG编程器将映像编程到板上，构建目录中的支持脚本可实现板的编程和Segger Ozone调试工具的启动。

在硬件或模拟器上运行后，用户可以通过各种CLI命令进行操作，并通过直接读写模型点深入了解恒温器的工作机制。例如，可以使用CLI命令设置恒温器的温度、模式等参数，通过读写模型点获取和修改内部状态信息。

综上所述，PIM恒温器示例涵盖了从硬件平台选择、安装设置、构建过程到应用使用的完整流程，通过合理的目录命名约定和单元测试规范，为开发和测试提供了高效、有序的方法。遵循这些步骤和规范，能够顺利地进行恒温器应用的开发和部署。