Walabot简介

在本篇文章中，我翻译了射频设备Walabot的API文档中的简介部分(Overview of Walabot Application)，目的是使读者对Walabot有初步的了解。由于本人英语水平有限，难免出现：

• 译名不统一
• 意译
• 句子、词汇不够准确

想要进一步了解Walabot API细节或者希望阅读准确无误的文档，请访问原文：api.walabot.com

序言

尽管Walabot只有口袋大小，但它使用了尖端的立体(3D)射频(RF)感应技术，使得以下精密的应用成为可能：

• 呼吸监测
• 物体追踪与掉落检测
• 墙内水管与电线检测

我们给您提供了几个示例应用，除此以外您也能创建属于自己的应用，并利用Walabot灵活的API访问作为外围设备的Walabot。用USB连接Walabot并安装好Walabot SDK后，您的自制应用可以使用Walabot API来接收多种类型的图像（经处理的和未处理的）。应用可以根据需要使用图像数据，包括进行图像的额外处理，比如追踪图像之间的差异来检测物体的移动。

在创建自己的应用之前，首先您需要了解Walabot到底可以做什么，这点将会在图像特征中解释。在此之后，您可以根据成像步骤中的内容设计应用的高层流程，再根据编码流程将其实现。您也可以参考示范代码。

图像特征

Walabot可以为您的应用提供多种类型的图像数据。它们的区别主要依赖于两种设定：

• 扫描配置（Scan profile）：定义各种扫描细节，比如使用的内部天线组和频率。
• 拉取数据（Get action）：定义图像应被怎样处理、给应用提供什么数据。

扫描配置

可用以下配置：

• Short-range：捕捉范围小，但是能穿透介电材料，比如墙体。
• 用于长距离扫描的配置：
  • Sensor或Tracker：图像解析度高，但是捕捉速率较慢。
  • Sensor narrow：低解析度高捕捉速率，用于追踪移动迅速的物体。

拉取数据

可以使用的Get action类型：

• Raw image 原始图像：提供立体的（3D）图像数据。
• Raw image slice 原始图像切片：提供信号最强的切片的平面（2D）图像数据（3D图像投影至2D平面）。
• Image energy 图像能量：提供一个数字，代表原始图像所有像素的信号能量之和。
• Imaging targets(若使用short-range扫描配置)，Sensor targets(若使用sensor扫描配置)，Tracker targets(若使用tracker扫描配置)：提供识别出的目标列表还有数量。（在当前API版本中，Imaging targets只提供一个信号强度最大的目标）
• Raw Signals 原始信号：传感器收集到的原始信号。信号(i,j)表示反射脉冲从天线i发出，被目标反射并由天线j接收。

示例

下面的用于展示数据的示例应用使用了不同的扫描配置和拉取数据类型组合：

• 使用short-range扫描获取Raw image slice：

  

• 使用sensor（或tracking）扫描获取Raw image slice和sensor targets：

  

• 使用short-range扫描获取Imaging target（管道）：

  

动态滤波

对于需要追踪运动的应用，Walabot可以使用动态成像滤波器过滤掉固定的信号，只留下变化的信号。除了移动目标（Moving Target Identification）滤波器以外，微分滤波器（derivative filter）可用于特定的呼吸频率上。下面展示了sensor-narrow扫描（呼吸）的图像能量，并使用了微分滤波器：

校准与灵敏度

Walabot的校准扫描可以忽略或者减弱固定反射物体（比如墙）的信号。除此以外，对于原始图像（3D和切片的），Walabot会根据设置的灵敏度阈值来忽略一些强度较弱的信号。

Arena

在您使用Get action时，Walabot处理并提供一块可配置、限定的空间（称之为arena）的图像数据（图像解析度可配置）。当您使用短距离（short-range profile）扫描时，arena的大小会与Walabot的尺寸差不多，并且用的是空间直角坐标系。如果使用传感(Sensor profile)或者追踪(Tracker profile)扫描，arena会大得多，这时使用的是球坐标系。

您的应用可以使用如下公式将球坐标系转换为空间直角坐标系：
$$\begin{array}{rl}X& =R\cdot \sin \theta \\ Y& =R\cdot \cos \theta \cdot \sin \varphi \\ Z& =R\cdot \cos \theta \cdot \cos \varphi \end{array}$$
比如：

坐标系统

对于arena定义，还有Walabot提供的图像数据，直角坐标的原点位于Walabot的中心，而坐标轴的正方向如下所示（如果有壳，将Walabot的logo朝下放置。）：

对于球坐标，坐标系中任一点M用$R、\theta 、\varphi$描述。R代表半径，$\theta$代表OM与z轴正方向之间的夹角，$\theta$是平面$ZOM$与平面$ZOX$之间的夹角。（注：因为原文描述不是特别清楚，此描述与图片来源百度百科）

单位为厘米和度。

成像步骤

在您设计高层应用流程之前，请确认您已经理解图像特征中的内容。

在应用接收到一张图像之前，要进行以下步骤：

1. Connect 连接：与Walabot建立通信
2. Configure 配置：设置扫描配置(scan profile)与arena。可以配置动态滤波器和灵敏度阈值。
3. Calibrate 校准：根据所处环境，忽略或者减弱固定反射物（比如墙）的信号。
4. Start 启动：系统准备好开始扫描。需要已设定一个扫描方式。
5. Trigger 触发：根据设定好的配置扫描，记录下可被处理和检索的信号。
6. Get action 拉取数据：根据特定的Get action、动态滤波器（若启用）和灵敏阈值，处理并提供当前arena的图像数据。Get action会检索最近的触发记录，Walabot自动保证应用不会接收同样的记录两次（于是您可以实现多个并行的触发和拉取数据）。
7. Stop and Disconnect 停止工作与断开连接。

您能在任意阶段改变配置设定，Walabot保证接下来拉取的数据都是在设置后触发的。

扫描方式也能在任意阶段进行改变。Walabot会自动执行停止工作$\to$修改配置。每次改变扫描方式，Walabot都要再校准和再启动。

在您根据以上内容设计好高层的程序流程后，就可以根据编码流程来将其实现了。

编码流程

在您开始编码之前，请现根据成像步骤的内容设计高层应用流程，然后再根据以下指导将其实现。示范代码也许对您有帮助。

• 应用必须包含API头文件和iostream库。比如：

  #include "WalabotApi.h"
  #include <iostream>
  

• 一般情况下：Walabot API并不线程安全

• 连接Walabot：Walabot_ConnectAny()

• 配置（初始化和后续）

  • 设定扫描方式：Walabot_SetProfile()
  • 若使用了短程扫描，则使用空间直角坐标系来设置arena： Walabot_SetArenaX(), Walabot_SetArenaY(), Walabot_SetArenaZ()
  • 若使用了Sensor或者Tracker扫描，用球坐标系设置arena：Walabot_SetArenaR(), Walabot_SetArenaTheta(), Walabot_SetArenaPhi()
  • 如有必要，设置动态滤波器：Walabot_SetDynamicImageFilter()
  • 您也可以改变灵敏阈值：Walabot_SetDynamicImageFilter()

• 对于以上每个配置（除了扫描方式配置以外），基本上你都可以把函数中的set改为get来查看当前的配置。在对应修改配置函数的文档链接中，您可以找到查看配置函数的文档链接。

• 启动（需要设置过扫描方式）：Walabot_Start()

• 应用循环通常至少要包含以下步骤：

  • 触发：Walabot_Trigger()
  • 拉取数据：Walabot_GetRawImage(),Walabot_GetRawImageSlice(),Walabot_GetImageEnergy(),Walabot_GetImagingTargets(), Walabot_GetSensorTargets(), Walabot_GetTrackerTargets()

• 校准（初始化、扫描方式变更、或有必要应对环境变化时）：Walabot_StartCalibration()

  要检查校准的进度，请使用 Walabot_GetStatus()。若校准还在进行中，它会返回进度百分比。你可以根据此函数的返回值来决定开始扫描还是继续等待。

  你也可以中断校准进程：Walabot_CancelCalibration()

• 停止：Walabot_Stop()

• 断开连接：Walabot_Disconnect()

• 在程序任意一处你可以查看Walabot的状态：Walabot_GetStatus()

所有的函数都返回：WALABOT_RESULT，您的程序应该检查这个返回值。

还有一些进阶的函数：

• 连接多个Walabot中的一个：Walabot_Connect(), Walabot_GetInstrumentsList()
• 查看详细的错误信息：Walabot_GetErrorString()
• 设置Walabot内置数据库的路径：Walabot_SetSettingsFolder()或Walabot_Initialize()
• 从指定的天线获取原始图像数据： Walabot_GetSignal(), Walabot_GetAntennaPairs()

安装与故障排查

安装文件可在此处下载:http://www.walabot.com/getting-started-beta （此网址可以访问，但是下载文件似乎是被墙了）

Windows

安装程序会检查你的电脑中是否已经安装过相应软件，如果还没有，它就会为您尝试进行安装。

故障排查

1. Walabot SDK因各种原因安装失败

   修复：中途安装失败可能会使系统处于不一致状态。请先卸载Walabot包，然后再次尝试运行安装程序。

2. 安装好Walabot SDK后，WalabotDemo报告有缺失的dll文件。

   修复：在少数情况中，安装后需要你重启系统。请在重启后再尝试运行WalabotDemo。

3. 驱动安装错误

   弹出窗口提示：“设备驱动没有成功安装（device driver was not successfully installed）”

   修复：重启系统

   提示：在事件窗口(event viewer)中如果有提示：Device manager "... with exit code 0xD 0xD = The data is invalid"，也意味着驱动问题。

Linux

Linux上使用debian包安装。在上述链接中下载安装包，然后在对应路径下输入以下命令：

sudo dpkg -i walabot-maker.deb

安装包会在一下路径下安装文件：

1. /usr/lib/libWalabotAPI.so walabot库
2. /usr/include/WalabotAPI.h walabot库头文件
3. /var/lib/walabot/... walabot数据库与配置文件。把这个路径交给Walabot_SetSettingsFolder()。
4. /usr/share/doc/walabot/... 范例代码、许可、README文件
5. /etc/udev/rules.d/...Walabot设备特殊的udev规则，所以您能在没有root权限的情况下访问它。