Marvelmind API

检查与API的连接

运行示例软件后，在终端中按“空格”键，输入命令‘version’并按回车。如果示例软件打印出API版本，说明它可以与API库通信。

Marvelmind API库说明

API以MS Windows动态链接库（DLL）和Linux共享库（x86和ARM平台）的形式提供。该库包含一组函数，用于通过连接在计算机USB端口上的调制解调器监控和控制Marvelmind系统。本节介绍所有这些函数。

为了更好地兼容不同的编程语言，大多数复杂数据结构通过无类型内存指针传递。函数说明中给出了每个数据字段在内存池中的偏移量。在示例软件的‘marvelmind_api.c’文件中，可以看到在内存池与C结构体字段之间传递数据的实现。

说明中的参数类型采用C语法表示。类型说明如下：

每个函数说明都列出了支持该函数的API版本。新的API版本将支持更多函数，以对应Marvelmind系统的新功能。目前并非Dashboard中的所有功能都可通过API使用，如需更多API函数，请发邮件至 info@marvelmind.com.

支持的函数列表：

获取Marvelmind API库版本

读取API库版本。用于确认该版本的库中提供所需函数。

函数名： mm_api_version

C语言声明：bool mm_api_version(void *pdata);

适用的API版本：V1+

所需许可：无

返回值：

参数：

通过指针返回的数据结构。

获取上一次错误

读取API库上一次操作的状态，以区分错误原因。

函数名： mm_get_last_error

C语言声明：bool mm_get_last_error(void *pdata);

适用的API版本：V6+

所需许可：无

返回值：

参数：

通过指针返回的数据结构。

打开串口

打开Marvelmind设备（调制解调器或信标）通过USB（虚拟串口）连接的端口。无需指定串口名称，因为API会搜索所有串口，并检查其是否对应Marvelmind设备。

函数名： mm_open_port

C语言声明：bool mm_open_port ();

适用的API版本：V1+

所需许可：无

返回值：

参数：无

按指定名称打开串口

打开Marvelmind设备（调制解调器或信标）通过USB（虚拟串口）连接的端口。函数尝试打开具有指定名称的端口。

函数名： mm_open_port_by_name

C语言声明：bool mm_open_port_by_name(void *pdata);

适用的API版本：V2+

所需许可：无

返回值：

参数：

打开UDP端口

允许通过UDP而非USB与Super-Modem建立通信。

函数名： mm_open_port_udp

C语言声明：bool mm_open_port_udp(void *pdata);

适用的API版本：V9+

所需许可：无

返回值：

参数：

指针所指数据的结构：

IP地址和UDP端口应与Super-Modem的设置一致（见下方截图）。

关闭串口

关闭端口（如果此前已通过 mm_open_port 函数打开）。

函数名： mm_close_port

C语言声明：bool mm_close_port ();

适用的API版本：V1+

所需许可：无

返回值：

参数：无

获取Marvelmind设备的版本和CPU ID

读取版本和CPU ID。版本包括固件版本和设备硬件类型信息。CPU ID是每台设备独有的ID。

函数名： mm_get_device_version_and_id

C语言声明：bool mm_get_device_version_and_id (uint8_t address, void *pdata);

适用的API版本：V1+

所需许可：无

返回值：

参数：

通过指针返回的数据结构：

获取设备列表

读取调制解调器已知的Marvelmind设备列表。该列表包括通过无线电连接到调制解调器网络的所有设备，包括休眠设备。

函数名： mm_get_devices_list

C语言声明：bool mm_get_devices_list (void *pdata);

适用的API版本：V1+

所需许可：无

返回值：

参数：

通过指针返回的数据结构：

列表中每个设备的结构：

唤醒设备

向指定设备发送唤醒命令。如果唤醒命令已发送且该设备存在，设备将在几秒钟内连接到调制解调器，并出现在 设备列表.

函数名： mm_wake_device

C语言声明：bool mm_wake_device (uint8_t address);

适用的API版本：V1+

所需许可：无

返回值：

参数：

使设备休眠

使现有设备进入休眠。

函数名： mm_send_to_sleep_device

C语言声明：bool mm_send_to_sleep_device (uint8_t address);

适用的API版本：V1+

所需许可：无

返回值：

参数：

获取信标遥测数据

读取Marvelmind信标的遥测数据。

函数名： mm_get_beacon_telemetry

C语言声明：bool mm_get_beacon_telemetry (uint8_t address, void *pdata);

适用的API版本：V1+

所需许可：无

返回值：

参数：

通过指针返回的数据结构：

获取最新位置数据

从调制解调器读取最新更新的坐标包。如有用户负载数据，也一并读取。

函数名： mm_get_last_locations

C语言声明：bool mm_get_last_locations(void *pdata);

适用的API版本：V1+

所需许可：无

返回值：

参数：

通过指针返回的数据结构：

每个位置数据项的结构：

获取最新位置数据（含角度）

从调制解调器读取最新更新的坐标包（配对信标含角度）。如有用户负载数据，也一并读取。

函数名： mm_get_last_locations2

C语言声明：bool mm_get_last_locations2(void *pdata);

适用的API版本：V3+

所需许可：无

返回值：

参数：

通过指针返回的数据结构：

每个位置数据项的结构：

设置信标位置

手动设置指定信标的位置。

函数名： mm_set_beacon_location

C语言声明：bool mm_set_beacon_location (uint8_t address, void *pdata);

适用的API版本：V3+

所需许可： MMSW0005

返回值：

参数：

指针所指数据的结构（应在调用函数前填写）：

设置信标间距离

手动设置信标间距离。

函数名： mm_set_beacons_distance

C语言声明：bool mm_set_beacons_distance (void *pdata);

适用API版本：V4+

所需许可： MMSW0005

返回值：

参数：

指针所指数据的结构（应在调用函数前填写）：

获取最新原始距离数据

从调制解调器读取最新更新的原始距离数据包。

函数名： mm_get_last_distances

C语言声明：bool mm_get_last_distances(void *pdata);

适用的API版本：V1+

所需许可：无

返回值：

参数：

通过指针返回的数据结构：

每个原始距离数据项的结构：

获取移动信标高度

返回移动信标（hedgehog）的高度。

函数名： mm_get_hedge_height

C语言声明：bool mm_get_hedge_height (uint8_t address, void *pdata);

适用API版本：V4+

所需许可：无

返回值：

参数：

指针所指数据的结构：

设置移动信标高度

设置移动信标（hedgehog）的高度。

函数名： mm_set_hedge_height

C语言声明：bool mm_set_hedge_height (uint8_t address, void *pdata);

适用API版本：V4+

所需许可： MMSW0005

返回值：

参数：

指针所指数据的结构（应在调用函数前填写）：

获取子地图中固定信标的高度

返回子地图中固定信标的高度。

函数名： mm_get_beacon_height

C语言声明：bool mm_get_beacon_height (uint8_t address, void *pdata);

适用API版本：V4+

所需许可：无

返回值：

参数：

指针所指数据的结构：

设置子地图中固定信标的高度

设置子地图中固定信标的高度。

函数名： mm_set_beacon_height

C语言声明：bool mm_set_beacon_height (uint8_t address, void *pdata);

适用API版本：V4+

所需许可： MMSW0005

返回值：

参数：

指针所指数据的结构（应在调用函数前填写）：

获取位置更新率设置

从调制解调器读取位置更新率设置。

函数名： mm_get_update_rate_setting

C语言声明：bool mm_get_update_rate_setting (void *pdata);

适用的API版本：V1+

所需许可：无

返回值：

参数：

通过指针返回的数据结构：

设置位置更新率

向调制解调器写入位置更新率设置。

函数名： mm_set_update_rate_setting

C语言声明：bool mm_set_update_rate_setting (void *pdata);

适用的API版本：V1+

所需许可： MMSW0005

返回值：

参数：

指针所指数据的结构（应在调用函数前填写）：

添加子地图

添加新的子地图。

函数名： mm_add_submap

C语言声明：bool mm_add_submap (uint8_t submapId);

适用的API版本：V1+

所需许可： MMSW0005

返回值：

参数：

删除子地图

删除已有子地图。

函数名： mm_delete_submap

C语言声明：bool mm_delete_submap (uint8_t submapId);

适用的API版本：V1+

所需许可： MMSW0005

返回值：

参数：

冻结子地图

冻结子地图。

函数名： mm_freeze_submap

C语言声明：bool mm_freeze_submap (uint8_t submapId);

适用的API版本：V1+

所需许可： MMSW0005

返回值：

参数：

解冻子地图

解冻子地图。

函数名： mm_unfreeze_submap

C语言声明：bool mm_unfreeze_submap (uint8_t submapId);

适用的API版本：V1+

所需许可： MMSW0005

返回值：

参数：

获取子地图设置

从调制解调器读取子地图设置。

函数名： mm_get_submap_settings

C语言声明：bool mm_get_submap_settings (uint8_t submapId, void *pdata);

适用的API版本：V1+

所需许可：无

返回值：

参数：

通过指针返回的数据结构：

服务区多边形顶点结构：

设置子地图参数

向调制解调器写入子地图设置。

函数名： mm_set_submap_settings

C语言声明：bool mm_set_submap_settings (uint8_t submapId, void *pdata);

适用的API版本：V1+

所需许可： MMSW0005

返回值：

参数：

冻结地图

冻结子地图。

函数名： mm_freeze_map

C语言声明：bool mm_freeze_map ();

适用API版本：V4+

所需许可： MMSW0005

返回值：

解冻地图

冻结子地图。

函数名： mm_unfreeze_map

C语言声明：bool mm_freeze_map ();

适用API版本：V4+

所需许可： MMSW0005

返回值：

获取信标的超声波设置

读取指定信标的超声波设置。

函数名： mm_get_ultrasound_settings

C语言声明：bool mm_get_ultrasound_settings (uint8_t address, void *pdata);

适用的API版本：V1+

所需许可：无

返回值：

参数：

通过指针返回的数据结构：

设置信标的超声波参数

向指定信标写入超声波设置。

函数名： mm_set_ultrasound_settings

C语言声明：bool mm_set_ultrasound_settings (uint8_t address, void *pdata);

适用的API版本：V1+

所需许可： MMSW0005

返回值：

参数：

清除地图

擦除调制解调器中的地图——删除所有子地图（子地图0除外），将子地图0复位到初始状态，并将所有已连接的信标移出网络。

函数名： mm_erase_map

C语言声明：bool mm_erase_map ();

适用的API版本：V1+

所需许可： MMSW0005

返回值：

参数：无

将设备恢复为默认设置

将设备恢复为默认设置（无线电、超声波等）。

函数名： mm_set_default_settings

C语言声明：bool mm_set_default_settings (uint8_t address);

适用的API版本：V1+

所需许可： MMSW0005

返回值：

参数：

将信标关联到坐标轴

平移地图，使选定的信标位于坐标轴上。

函数名： mm_beacons_to_axes

C语言声明：bool mm_beacons_to_axes (uint8_t address_0, uint8_t address_x, uint8_t address_y);

适用的API版本：V2+

所需许可： MMSW0005

返回值：

参数：

读取调制解调器配置存储器转储

读取调制解调器配置存储器的转储，可用于保存调制解调器的设置和已存储的地图。

函数名： mm_read_flash_dump

C语言声明：bool mm_read_flash_dump(uint32_t offset, uint32_t size, void *pdata);

适用的API版本：V3+

所需许可： MMSW0005

返回值：

参数：

写入调制解调器配置存储器转储

将数据转储写入调制解调器配置存储器，可用于恢复调制解调器的设置和地图。

函数名： mm_write_flash_dump

C语言声明：bool mm_write_flash_dump(uint32_t offset, uint32_t size, void *pdata);

适用的API版本：V3+

所需许可： MMSW0005

返回值：

参数：

注意：写入配置后，建议对调制解调器执行 软件复位 （mm_reset_device(255)），以应用新设置并防止其被覆盖。

设备重启（软件复位）

对指定设备执行软件复位。

函数名： mm_reset_device

C语言声明：bool mm_reset_device (uint8_t address);

适用的API版本：V3+

所需许可：无

返回值：

参数：

从调制解调器读取空气温度设置

从调制解调器读取空气温度设置（摄氏度）。

函数名： mm_get_air_temperature

C语言声明：bool mm_get_air_temperature (void *pdata);

适用的API版本：V3+

所需许可：无

返回值：

通过pdata指针返回的数据结构：

向调制解调器写入空气温度设置

在调制解调器中设置空气温度（摄氏度）。

函数名： mm_set_air_temperature

C语言声明：bool mm_set_air_temperature (void *pdata);

适用的API版本：V3+

所需许可：无

返回值：

用户需通过pdata指针提供的数据结构：

获取信标实时播放器设置

读取信标的实时播放器设置。

函数名： mm_get_realtime_player_settings

C语言声明：bool mm_get_realtime_player_settings (uint8_t address, void *pdata);

适用的API版本：V6+

所需许可：无

返回值：

参数：

通过指针返回的数据结构：

设置信标实时播放器参数

设置信标的实时播放器参数。

函数名： mm_set_realtime_player_settings

C语言声明：bool mm_set_realtime_player_settings (uint8_t address, void *pdata);

适用的API版本：V6+

所需许可： MMSW0005

返回值：

参数：

获取地理配准设置

读取地理参考设置（Marvelmind地图原点（X=0,Y=0）的地理位置）。

函数名： mm_get_georeferencing_settings

C语言声明：bool mm_get_georeferencing_settings (void *pdata);

适用的API版本：V6+

所需许可：无

返回值：

参数：

通过指针返回的数据结构：

设置地理配准参数

设置地理参考（Marvelmind地图原点（X=0,Y=0）的地理位置）。

函数名： mm_set_georeferencing_settings

C语言声明：bool mm_set_georeferencing_settings (void *pdata);

适用的API版本：V6+

所需许可： MMSW0005

返回值：

参数：

获取位置更新模式

读取移动信标位置的当前更新模式。

函数名： mm_get_update_position_mode

C语言声明：bool mm_get_update_position_mode (void *pdata);

适用的API版本：V6+

所需许可：无

返回值：

参数：

通过指针返回的数据结构：

设置位置更新模式

设置移动信标位置更新模式。

函数名： mm_set_update_position_mode

C语言声明：bool mm_set_update_position_mode (void *pdata);

适用的API版本：V6+

所需许可： MMSW0005

返回值：

参数：

更新位置的命令

发送更新移动信标位置的命令（当 更新模式 为非自动时）。

函数名： mm_set_update_position_command

C语言声明：bool mm_set_update_position_command (void *pdata);

适用的API版本：V6+

所需许可： MMSW0005

返回值：

参数：

指针所指数据的结构：

设置信标的电子围栏报警状态

发送命令，设置信标报警引脚的报警状态（适用于Super-Beacon）。

引脚的报警状态可通过Dashboard设置中“Interfaces”部分的“Alarm pin mode”设置来指定（如已激活 MMSW0006 许可证）。

函数名： mm_set_alarm_state

C语言声明：bool mm_set_alarm_state (uint8_t address, void *pdata);

适用的API版本：V9+

所需许可： MMSW0005, MMSW0006

返回值：

参数：

指针所指数据的结构：

发送通用用户负载数据

发送通用用户有效载荷数据。若API连接到调制解调器，数据将通过指定移动信标的UART/USB端口传输；若API连接到移动信标，数据将通过调制解调器的UART/USB端口传输。远端可通过 接收API函数、Arduino示例、ROS及其他软件获取接收到的数据。

函数名： mm_send_user_payload_data

C语言声明：bool mm_send_user_payload_data (uint8_t address, void *pdata);

适用的API版本：V9+

所需许可： MMSW0005

返回值：

参数：

指针所指数据的结构：

获取通用用户负载数据

接收由 发送API函数、Arduino、ROS或其他用户软件发送的通用用户有效载荷数据。若API连接到调制解调器，该函数可接收经移动信标UART/USB端口传输的数据；若API连接到移动信标，该函数可接收经调制解调器传输的数据。

函数名： mm_get_user_payload_data

C语言声明：bool mm_get_user_payload_data (void *pdata);

适用的API版本：V9+

所需许可： MMSW0005

返回值：

参数：

指针所指接收数据的结构：

发送手动测距命令

发送命令，测量指定信标到系统中其他信标的距离。在当前软件版本中，该功能 支持IA （逆向架构）。

函数名： mm_send_distances_measurement_command

C语言声明：bool mm_send_distances_measurement_command (void *pdata);

适用的API版本：V9+

所需许可： MMSW0011

返回值：

参数：

指针所指数据的结构：

从调制解调器获取流数据

读取调制解调器的流数据，采用 前文所述的格式.

函数名： mm_get_stream_data

C语言声明：bool mm_get_stream_data (void *pdata);

适用的API版本：V9+

所需许可：无

返回值：

参数：

指针所指数据的结构：

流记录结构：

检查设备类型是否为调制解调器

检查指定的设备类型是否对应调制解调器。

函数名： mm_device_is_modem

C语言声明：bool mm_device_is_modem (uint8_t deviceType);

适用的API版本：V1+

所需许可：无

返回值：

参数：

检查设备类型是否为固定信标

检查指定的设备类型是否对应固定信标。

函数名： mm_device_is_beacon

C语言声明：bool mm_device_is_beacon (uint8_t deviceType);

适用的API版本：V1+

所需许可：无

返回值：

参数：

检查设备类型是否为移动信标（hedgehog）

检查指定的设备类型是否对应移动信标（hedgehog）。

函数名： mm_device_is_hedgehog

C语言声明：bool mm_device_is_hedgehog (uint8_t deviceType);

适用的API版本：V1+

所需许可：无

返回值：

参数：

Marvelmind API的C语言示例说明

C语言示例用于测试Marvelmind API，也可作为开发用户应用程序的基础。

该C语言示例为控制台应用程序，已在以下平台上测试：

• CPU：Intel Core 2 Duo，操作系统：MS Windows XP；
• CPU：Intel Core i5，操作系统：Linux Ubuntu 16.04；
• Raspberry Pi 3 Model B+，操作系统：Raspbian（2018-11-13-raspbian-stretch-full）

在Windows平台上，示例使用CodeBlocks IDE构建，因此附带CodeBlocks项目文件。

在Linux平台上，示例使用make工具构建，因此附带相应的makefile。

示例包含以下模块：

示例工作流程：

1. 尝试 打开 串口，直至成功
2. 端口打开后，程序读取通过USB连接的设备版本。如果是调制解调器，程序继续执行后续步骤
3. 连接到调制解调器后，程序读取 设备列表 ，频率为1 Hz。将设备列表与marvelmind_devices.c模块中当前存储的列表进行比较，如发现变化则更新marvelmind_devices.c中的列表。所有变化都会打印到控制台
4. 连接到调制解调器后，程序读取 最新位置数据 ，频率为20 Hz。如果设置了新原始距离数据标志，程序将读取 最新原始距离。程序将位置和距离与marvelmind_devices.c中设备列表的数据进行比较，如有变化则更新。所有变化的数据都会打印到控制台
5. 如果程序连续10次无法获取最新位置数据，将 关闭端口 并返回第1步——重新尝试打开端口。当调制解调器从USB断开后又重新连接时，需要重新打开端口
6. 如果用户按下“空格”键，程序将显示“Enter command:”提示并等待用户命令。大部分API函数通过用户命令调用，详见下文

用户命令：

如果用户按下“空格”键（程序运行期间），程序将显示提示“Enter command: ”。用户应通过键盘输入命令并按 回车键.

下表列出了所有用户命令的格式：

设备类型

以下是各设备的“设备类型ID”取值列表：

设备类型ID可通过 设备列表 和 读取设备版本 命令获取。

与用户设备之间收发用户数据

Marvelmind支持通过Marvelmind系统以多种方式传输用户数据：

• 通过调制解调器的UART或USB发送数据，并通过移动信标的UART或USB接收
• 通过移动信标的UART或USB发送数据，并通过调制解调器的UART或USB接收。

Super-Modem还支持通过UDP收发用户数据。

数据传输协议已在本文档前面的章节中说明：

• 数据传输协议： 发往用户设备 和 来自用户设备;
• API函数，用于 发送 和 接收 数据的说明。

Marvelmind提供多种通信软件示例：

示例完整列表：

• Arduino的用户数据收发示例位于Marvelmind软件包的“01_Common_Indoor_positioning_SW/ 06_Examples/ arduino”文件夹中。“hedgehog_sample_uart_user_data_receive_v2”用于接收用户数据，“hedgehog_sample_uart_user_data_send_v2”用于发送用户数据
• API通信示例位于Marvelmind软件包的“01_Common_Indoor_positioning_SW/ 05_API/example_source”（源代码）和“01_Common_Indoor_positioning_SW/ 05_API/example_bin_win32”（Windows可执行文件）文件夹中。数据的发送或接收可按本文档 所述 方式调用。
• 用于接收流数据的C语言示例位于Marvelmind软件包的“01_Common_Indoor_positioning_SW/ 06_Examples/ c”文件夹中。该示例也可在 GitHub代码库中获取。该示例会打印从移动信标或调制解调器接收到的所有数据，包括用户数据。
• 用于接收流数据的Python示例位于Marvelmind软件包的“01_Common_Indoor_positioning_SW/ 06_Examples/ python”文件夹中。该示例也可在 GitHub代码库中获取。该示例会打印从移动信标或调制解调器接收到的所有数据，包括用户数据。
• 用于接收流数据的ROS软件包示例位于Marvelmind软件包的“01_Common_Indoor_positioning_SW/ 06_Examples/ ROS”文件夹中。该软件包也可在 代码库中获取。该ROS软件包可通过API接收和发送用户数据。请参阅 文档（英文） 了解详情。
• 用于接收流数据的ROS-2软件包示例位于Marvelmind软件包的“01_Common_Indoor_positioning_SW/ 06_Examples/ ROS2”文件夹中。该软件包也可在 代码库中获取。该ROS软件包可通过API接收和发送用户数据。请参阅 文档（英文） 了解详情。
• 通过UDP接收数据的C语言示例位于Marvelmind软件包的“01_Common_Indoor_positioning_SW/ 06_Examples/ c”文件夹中。该示例会打印通过UDP从Super-Modem或Dashboard接收到的所有数据，包括用户数据。如果API用于 通过UDP连接Super-Modem （而非USB），则可通过API经UDP发送用户数据。

联系方式

如需更多支持，请将问题发送至 info@marvelmind.com

附录1. CRC-16计算

校验和采用CRC-16。N字节帧的最后两个字节填入CRC-16，该CRC-16针对帧的前(N-2)个字节计算。校验数据时，可对整个N字节帧计算CRC-16，结果应为零。

以下是该算法的C语言实现：

typedef uint16_t ModbusCrc;

typedef union { uint16_t w; struct{ uint8_t lo; uint8_t hi; } b; uint8_t bs[2]; } Bytes;

static ModbusCrc modbusCalcCrc(const void *buf, uint16_t length)

{

uint8_t *arr = (uint8_t *)buf;

Bytes crc; crc.w = 0xffff; while(length--){ char i; bool odd; crc.b.lo ^= *arr++;

for(i = 0; i< 8; i++){

odd = crc.w& 0x01; crc.w>>= 1; if (odd) crc.w ^= 0xa001; } }

return (ModbusCrc) crc.w;

}

附录2. 调制解调器错误应答格式

错误帧格式（调制解调器发往主机）

错误数据包的类型为请求帧的数据包类型加上最高位。例如，如果请求的数据包类型为0x03，则错误数据包的类型为0x83。

错误代码可能为以下之一：

1 – 请求中的数据包类型未知

2 – 请求中的数据代码未知

3 – 请求的数据字段有误

6 – 设备忙

10 – 远端设备返回错误消息

11 – 远端设备应答超时