安装Detour
1. 前言
您如果首次使用MDCS，建议阅读【MDCS概述】，在了解MDCS各子系统功能后下载安装Detour。
2. 下载Detour及依赖包
浏览器打开：https://dl.lessokaji.com 。这是MDCS下载站，可下载MDCS（AMR控制全栈软件）发布版。
图 2-1 MDCS下载页面
下载页面由两部分构成：
- 软件包清单。
- 下载按钮（Zip）。
点击软件包名称，展开分类列表，勾选后点击下载按钮，选中软件被打包到一个zip文件下载。
图 2-2 勾选软件清单后下载 以Windows版Detour下载为例，如图2-2，“Selected Files”下是选中软件清单，点击“Zip”按钮打包下载。
以Windows版Detour下载为例，如图2-2，“Selected Files”下是选中软件清单，点击“Zip”按钮打包下载。
3. 安装
Detour与Medulla配套使用。Medulla接收激光雷达发送的测量数据，统一转换格式后通过共享内存发布给Detour。
说明：Windows环境使用Detour.exe，Ubuntu环境使用DetourLite.dll（Detour内核功能）并配套Detour.exe（作为远程客户端）使用。Ubuntu环境通过Mono启动Medulla.exe。
3.1 Windows环境
图 3-1 Windows环境的软件清单
| 模块 | 程序 | 用途 |
|---|---|---|
| Detour | Detour.exe | Detour主程序 |
| Medulla2 | Medulla2.exe | Medulla2主程序 |
| LidarControler.dll | 激光雷达控制器，部署在medulla的plugins子目录下（下同） |
说明：Medulla2 & Detour运行在Windows 10以上版本，依赖 .netframework 4.8 Download .NET Framework 4.8 | Free official downloads (microsoft.com) 。
建议把Detour和Medulla存放在MDCS目录下，以便管理。MDCS目录所在分区至少有80G空闲容量，用于存储Detour和Medulla运行时生成的日志文件和配置数据。
Medulla的目录结构如下：
D:\work\Playground\mdcs\Medulla 的目录
2024/06/18 10:14 <DIR> .
2024/06/18 10:14 <DIR> ..
2024/06/13 08:18 3,420,672 Camera3D.dll // 3D相机控制器，只用激光SLAM时不需要
2024/06/13 08:18 643,072 CartActivator.dll // 底盘驱动加载器
2024/06/13 16:39 <DIR> diagnosis // 运行时日志目录
2024/06/13 08:18 854,016 LidarController.dll // 激光雷达控制器
2024/05/21 13:00 3,335,168 MDCSToolBox.dll // 工具箱，只用激光SLAM时不需要
2024/06/13 08:18 2,609,152 Medulla.exe // 主程序，Ubuntu用mono启动
2024/05/21 13:00 14,544 Medulla.sys // 主程序库
2024/06/13 08:18 752,128 NetRemote.exe // 底盘遥控器，只用激光SLAM时不需要
2024/06/13 16:20 <DIR> plugins // 底盘驱动目录，激光雷达驱动存在此
2024/05/21 13:00 1,646 remoteconf.json // 底盘遥控器配置文件
2024/06/13 16:20 192 startup.iocmd // 自动加载驱动脚本
2024/06/13 08:18 758,784 USBCamera.dll // USB相机控制器，只用激光SLAM时不需要
2024/06/13 08:18 1,715,712 WinMedulla.dll // Medulla控制台库
Detour的目录结构如下：
D:\work\Playground\mdcs\Detour 的目录
2024/06/18 09:23 <DIR> .
2024/06/18 09:23 <DIR> ..
2024/06/17 09:05 142,640 critical.log // 错误日志
2024/06/13 10:54 152,167,424 cufft64_10.dll // 库
2024/06/13 10:54 226,816 cufftw64_10.dll // 库
2024/06/13 10:54 127,488 d2dlib64.dll // 库
2024/06/17 09:05 5,914,624 Detour.exe // 主程序
2024/06/18 09:28 5,744 detour_127.0.0.1.json // 作为客户端连接远程DetourLite时
// 自动下载的DetourLite配置文件，
// detour_{detour_lite_ip}.json
2024/06/13 10:54 <DIR> log // 日志目录
2024/06/13 10:54 53,050,368 OpenCvSharpExtern.dll // 库
2024/06/13 10:54 735,744 regcore_cuda.dll // 库
2024/06/18 09:28 154,166 tmpmap.2dlm // *.2dlm是激光地图文件
生产环境需要自动启动Medulla & Detour，且要监控并重启异常退出的进程，我们配套了看门狗程序Wawa，详见【看门狗Wawa使用说明】。
3.2 Ubuntu环境
图 3-2 Ubuntu环境下的软件清单
| 模块 | 程序 | 用途 |
|---|---|---|
| Detour | DetourLite | DetourLite是Detour内核功能，依赖DotNetCore，与Windows版Detour（作为远程客户端）配套使用。 |
| DetourLiteDepends | DetourLite的依赖库，解压后放到DetourLite目录。 | |
| libOpenCvSharpExtern | OpenCV依赖库，根据目标系统处理器架构选择arm64 / x64。 | |
| GDI+（可选） | 如果使用DetourLite的/getMapPng接口，则要安装GDI+库（sudo apt-get install -y libgdiplus）。 | |
| Medullar | Medulla.exe | Medulla主程序，依赖Mono。 |
| LidarControler.dll | 激光雷达控制器，部署在medulla的plugins子目录下（下同） | |
| WinMedulla.dll | Medulla库。 | |
| CartActivator.dll | 插件加载器。 |
3.2.1 安装Medulla
注意：应使用Ubuntu 16、18或20，截止2024年6月，Mono官方支持的Ubuntu最高版本是20.04，Medulla & DetourLite在这3个发布版做过充分测试。
参考Mono官网指南安装Mono。安装完毕后使用"mono --version"核对其版本，应是6.12以上，如下。
Mono JIT compiler version 6.12.0.200 (tarball Tue Jul 11 21:34:53 UTC 2023)
Copyright (C) 2002-2014 Novell, Inc, Xamarin Inc and Contributors. www.mono-project.com
TLS: __thread
SIGSEGV: altstack
Notifications: epoll
Architecture: amd64
Disabled: none
Misc: softdebug
Interpreter: yes
LLVM: yes(610)
Suspend: hybrid
GC: sgen (concurrent by default)
Medulla使用.netframework 4.8开发，在Ubuntu使用Mono启动。Mono是.NET Framework的开源实现，由微软赞助。请根据官网指南 Download - Stable | Mono (mono-project.com) 安装。 使用mono启动Medulla：
$ mono Medulla.exe
Lessokaji Medulla Version 1.2.0.3961, 64bit
Main Thread ID: 1
Medulla starting up...
Medulla command ready
Initialize Shared Objects for program Medulla
Mono or Linux which doesn't support named MMF, use file.
Create Shared Object dumplog
SO>> Exist dumplog:6579279
Initialize Diagnosis cache
Run on Mono or Linux which doesn't support named MMF, use file.
initializing io object
Create Shared Object mse
SO>> Exist mse:6581375
MSE engine initialized
run startup.iocmd script...
$: loader = io load CartActivator.dll
[IO] Loading Library CartActivator.dll...
Costura attach required assemblies for CartActivator.dll...
$: frontlidar = io load plugins/sicknano.dll
[IO] Loading Library plugins/sicknano.dll...
$: frontlidar setMaskDist 50 20000
$: frontlidar Start 6060
$: frontlidar setMirror false
$: ui=io load WinMedulla.dll
[IO] Loading Library WinMedulla.dll...
Costura attach required assemblies for WinMedulla.dll...
Starting HTTP Server, STM
HTTP Server listen on http://*:8007/
Medulla启动后在8007端口启动Web端口，可用浏览器访问 http://192.168.100.100:8007/simple.html （假设Medulla所在工控机的IP是192.168.100.100），可见Medulla运行状态，如下图所示。
图 3-3 Medulla的监控页面
3.2.2 安装DetourLite
根据微软dotNet官网指南 Download .NET 6.0 (Linux, macOS, and Windows) (microsoft.com) 安装.NET SDK 6.0。
备注：Ubuntu16、18、20的包管理器没有.NET 6源（参见官网指南），因此使用二进制安装，安装后应把dotnet加入PATH环境变量。 假设dotnet安装目录是~/dotnet，则在~/.bashrc加入 export PATH=$PATH:~/dotnet/dotnet 。
使用dotnet启动DetourLite：
dotnet DetourLite.dll
DetourLite不包括UI功能，因此要在Windows上运行Detour（作为客户端），远程连接到DetourLite。
看门狗Wawa也支持Ubuntu，详见【看门狗Wawa使用说明】。
图 3-3 作为远程客户端使用的Detour
客户端Detour连接远程DetourLite步骤：
- 概览标签，选择“使用远程算法核（简单配置）”。
- 填入DetourLite所在主机的IP地址，然后点击“连接”按钮。
- 连接成功后，状态栏会提示“已获取x.x.x.x上的配置文件。
注意：在启动作为客户端的Detour时，必须删除Detour目录下的detour.json，否则Detour会加载本地配置文件，拒绝连接远程Detour。
自2024/6/17后，下载站的Detour.exe支持远程设置DetourLite参数，如果您使用老版本，请升级。
图 3-5 Detour可远程同步的组件参数
Detour可远程同步DetourLite的组件、里程计参数。组件是车体编辑器中的传感器，激光SLAM传感器就是2D/3D激光雷达；里程计是“里程计”标签列表的"odometry_n"(n≥0)，包括激光里程计、地纹里程计和轮里程计。
当Detour连接DetourLite后，在Detour配置激光雷达或里程计属性时，Detour更新本地配置副本后同步DetourLite。下面我们详细讲解Detour和DetourLite的协作关系。
DetourLite启动时自动读取同目录的detour.json，如果detour.json包含激光地图文件属性，则自动加载激光地图。观察DetourLite控制台输出可见此过程，如下图所示。
图 3-6 DetourLite启动后的控制台输出
如图3-6所示，DetourLite加载"detour.json"，随后加载配置文件中指向的激光地图"mainmap_0618_edit_yh.2dlm"。
Detour连接DetourLite，状态栏提示"load map, but cannot find ..."，如下图所示。
图 3-7 远程连接DetourLite时的提示
如果DetourLite未加载激光雷达，Detour提示”读取...远程配置成功“。出现"cannot find map file"提示是因为本地没有激光地图文件。此时有两种处理方法，一是从DetourLtie拷贝激光地图文件到本地，二是使用”单线激光SLAM“标签下”其他功能 / 下载远程图层数据至本机图层“。建议使用方法一。Detour在连接DetourLite后，将其配置读入内存，并在Detour目录下生成"detour_{ip}.json"副本（ip是DetourLite所在PC地址），其图层关联的激光地图文件名称与DetourLite一致，如下图所示。如果使用“加载图层”装入另一个本地激光地图文件，就会同步给DetourLite，导致DetourLite下次启动错误加载不存在激光地图而报错。
图 3-8 DetourLite配置所用的激光地图文件名
由于底盘轮廓不在远程同步范围，因此在项目开始时，应使用Detour在本地编辑好底盘宽高和轮廓（概况 / 车体布局 / 编辑），在车体编辑器中部署激光雷达，然后上传到DetourLite，使用Detour的远程参数同步功能标定雷达外参。
在建图时，如果DetourLite没加载激光地图，则会自动创建。建图完毕后使用“其他功能 / 下载远程图层数据到本地图层”，然后另存为与DetourLite相同的名称，或者从DetourLite目录下载都可以。
4. 配置激光雷达
图 4-1 激光雷达电气原理示例
我们用2D激光雷达来说明配置方法。如图4-1所示，Medulla通过激光雷达驱动（插件）接收2D激光雷达的测量数据，经解码后传给Detour（或DetourLite）。
4.1 兼容激光雷达清单
Medulla支持的激光雷达型号（通过项目实践验证）如下。激光雷达驱动开发请阅读【开发激光雷达驱动】。
2D雷达清单：
| 品牌 | 型号 |
|---|---|
| SICK（西克） | LMS511，nano，S300 |
| P+F（倍加福） | R2000 |
| 万集 | 716，716mini，719 |
| 兴颂 | HE-3051，SE1035 |
| 富瑞 | H1系列 |
3D雷达清单：
| 品牌 | 型号 |
|---|---|
| 觅道（Livox） | Mid70（用于物体识别，不能用于导航），Mid360（非均匀扫描周期，可用于<1m/s的低速导航） |
| 速腾 | M1，Helios |
| 万集 | WLR720 |
雷达驱动可在开发站下载：传感器/功能插件
4.2 2D激光雷达驱动
Medulla启动时自动读取同目录下的startup.iocmd，根据指令启动驱动，举例如下。
// 指令使用类JavaScript语法。
// 加载CartActivator.dll，作为WinMedulla加载器。
loader = io load plugins/CartActivator.dll
// 加载前激光雷达驱动，以SICK nano3为例。
// frontlidar是激光雷达名称，在WinMedulla的对象列表可见
frontlidar = io load plugins/sicknano.dll
// 设置前雷达测量距离：50mm内忽略，最大测距20,000mm。
frontlidar setMaskDist 50 20000
// 前雷达驱动监听6060端口（SICK SOPAS配置nano3，使用UDP单播，目标端口6060）。
frontlidar Start 6060
// 前雷达正装。如果是倒装雷达，则setMirror为true（雷达倒装后，扫描顺序颠倒）。
frontlidar setMirror false
// 加载Medulla控制台，并显示。
// Ubuntu环境则注释以下两行，改用 :8007/simple.html 监控页面
ui=io load plugins\WinMedulla.dll
ui Show
修改完startup.iocmd后，启动Medulla.exe，出现WinMedulla主窗口。
图 4-2 查看前激光雷达的数据
WinMedulla是Medulla控制台，在左侧对象列表中可见刚配置的frontlidar。如果驱动工作正常，则可见窗体中间的数据在变化，说明已收到雷达数据。点击窗体右侧的“view”按钮，弹出点云监控窗口，使用鼠标滚轮缩放，鼠标中键按压拖动，检查点云是否与雷达观测一致。
备注：由于Mono不支持WinForm，因此Ubuntu环境下改用:8007/simple.html监控Medulla运行，激光雷达数据更新时可在页面观察到。由于监控页面不能显示点云数据，因此在首次使用Medulla时，建议先用Windows版Medulla熟悉激光雷达输出点云，掌握Medulla的激光雷达应用后再切到Ubuntu环境。
4.3 3D激光雷达驱动
3D激光雷达驱动使用与2D激光雷达相同。
5. 配置Detour
Detour配置可分为三步：部署激光雷达、标定激光雷达外参，启用激光里程计。
对于潜伏车型，激光雷达一般安装在车头/车尾或对角，不在底盘运动中心上；对于单舵轮底盘（比如叉车），也是如此（运动中心在两个从动轮连线中心）。为了把激光雷达（逻辑上）移动到底盘运动中心，使观测中心与运动中心重合，以便运动控制算法根据当前位姿跟踪轨迹。我们需要知道激光雷达安装在车体的那个位置，这就是“部署激光雷达”步骤，使用车体编辑器把激光雷达放到底盘上。然后调整激光雷达外参，使其“移动”到底盘运动中心，这就是“标定激光雷达外参”，通过激光雷达参数配置执行。标定完成后就可以启动激光里程计，使用激光SLAM输出的实时位姿。
注意：激光SLAM有其能力边界。如果您首次使用激光SLAM，建议阅读【激光SLAM能力边界】。
5.1 部署激光雷达
启动Detour，在“概况”页面上点击”车体布局“的“编辑”按钮，打开车体编辑器。
图 5-1 车体编辑器
激光雷达安装在底盘之上（我们把AMR抽象为底盘），因此先要编辑底盘，如下图所示。
图 5-2 选择底盘
鼠标点击底盘内空白处选择。本例的属性列表可见该底盘W750L1200，contour是构成矩形底盘的4个角的坐标。对于矩形底盘，在修改长宽后，可直接修改contour的坐标值。对于多边形底盘，使用“动作”标签的“重绘轮廓“，使用鼠标左键依次点击创建底盘轮廓。
注意：Detour会过滤底盘轮廓之内的点云。在重绘底盘后，应在“概况”页面观察AMR图标附近是否有车体造成点云（噪音），如有则适当扩大底盘轮廓。这种车体与激光雷达干涉造成的噪音点必须清除，否则会干扰建图和定位。
点击车体编辑器的“添加”按钮，在下拉菜单中选择激光雷达类型，然后点击菜单下方的车体布局的激光雷达安装位置，新增一个激光雷达。
图 5-3 增加菜单的传感器类型
“添加”菜单中的激光雷达类型如下表：
| 类型 | 用途 |
|---|---|
| 单线激光雷达 | 即2D激光雷达，只有一个0度的扫描平面，适用于室内导航场景。 |
| 同步多2D雷达拼接 | 用于把多个2D激光雷达测量数据拼接为一个，适用于单个2D激光雷达视野不足，用2个激光雷达拼接以形成全向视野场景。 |
| 3D激光雷达 | 一般为16、32线的多线激光雷达，在垂直方向以不同角度扫描，形成立体点云，适用于室外导航（包括避障）场景。 |
| 二向化3D雷达 | 把3D雷达测量数据二向化为具备空间特征的二向化数据，供SLAM算法使用。（3D激光雷达都要二向化后使用） |
图 5-3 激光雷达的安装位置外参
选择新增的激光雷达，属性列表中的x、y、th就是其安装位姿，x & y可根据车体机械设计图参数填入，th根据激光雷达手册提供的参数填入。Detour使用右手坐标系，+X轴为食指方向，+Y轴为中指方向，+Z为大拇指方向，th就是激光雷达相对于+X轴的角度。对于3D激光雷达，z是雷达安装高度，根据车体机械设计图参数填入。
激光雷达的命名风格如下：
| 名称 | 用途 |
|---|---|
| frontlidar | 安装在车头的激光雷达，一般是第一个雷达。 |
| backlidar | 安装在车尾的激光雷达，一般是第二个雷达。 |
| midlidar | 拼接frontlidar & backlidar后的“中”雷达，位于车体中心，坐标为 ( x: 0, y: 0, th:0 )。 |
5.1.1 3D激光雷达
3D激光雷达能够提供三维空间特征，这是它与2D雷达不同之处。所谓“二向化3D雷达“，是把空间特征投影为2D，因此需要配置相关参数。
打开车体编辑器，选择要设置的二向化3D雷达，以下图为例。
图 5-5 二向化3D雷达相关参数
| 参数 | 含义 | 取值建议 |
|---|---|---|
| minVStruct | 垂直结构最小高度。墙、树形成的垂直结构形成空间特征。 | 以垂直扫描间隔2度的速腾16线雷达为例，两条相邻扫描线在 30米处的高度差是1046mm（小于这个值的物体只是一个点， 不能形成垂直线段）。如果建图轮廓在30米内，minVStruct=1000（大于1米的垂直结构参与计算）。 |
| minScans | 扫描到垂直结构的最少扫描线数。 | 与minVStruct配套使用。本例为3，表示长度>1000mm且至少被3条线扫描到的垂直结构可用于计算。 |
| Zfadout | 垂直结构距离0度扫描平面的距离。 | 越靠近0度扫描线的垂直结构，其计算权重越高。与0度扫描线 相交的垂直结构，其距离为0。小于Zfadout的垂直结构将被 赋予高权重。 |
| scale | 点云缩放比例。 | 对点云计算有影响力的点集中在30米之内，用于室内导航的 2D激光雷达测量距离一般30米以内，在室外则不然。因此 室外场景需要把3D激光雷达的点云尺度做适当缩放，以利 点云配准。一般而言，3D激光雷达的scale=0.5，对应于 60米以内点云，如果距离更远，则scale适当降低。在调整 scale时，底盘尺寸（宽高）和雷达外参（x & y）等比调整， 比如scale=0.5时，底盘尺寸如果是L2000W1000，则改为 L1000W500。调整scale后，遥控AMR自旋，detour输出 位姿应平滑变化，不应出现抖动或大幅跳动现象（这种 现象由于尺度配置错误导致应配准点云被过滤造成）。 |
5.2 标定激光雷达外参
如果您是首次标定激光雷达外参，请顺序阅读以下文章：
5.3 启用激光里程计
激光雷达测量数据输入激光SLAM算法，通过激光里程计计算，输出为机器人实时位姿。
图 5-4 激光里程计 在“里程计”标签，选择2D激光（odometry_0），其"lidar"字段的值与激光雷达关联。对于使用单激光雷达的车型，一般为"frontlidar"（参考4.1的激光雷达命名风格）；对于使用双激光雷达的车型，一般为“midlidar”。
在“里程计”标签，选择2D激光（odometry_0），其"lidar"字段的值与激光雷达关联。对于使用单激光雷达的车型，一般为"frontlidar"（参考4.1的激光雷达命名风格）；对于使用双激光雷达的车型，一般为“midlidar”。
查看选中的激光里程计状态，应该为“已启动”，否则点击“启动”按钮。激光里程计数据可在“状态”标签的列表查看。
6. 获取授权证书
未授权的Detour可以使用60分钟，供体验Detour功能或测试Detour性能使用，超时后重起Detour可继续使用60分钟。
如果您已购买Detour授权证书，请按照以下步骤在Auth站注册，然后下载证书。如果您希望购买Detour授权证书，或试用有疑问，请联系懒书科技技术支持唐工（13501683672，微信同号）咨询。
- 浏览器打开：https://auth.lessokaji.com/login
- 点击“Register”链接以注册账号。请不要使用简单密码（比如1234之类），以保护您的数字资产安全。
- 注册后通知懒书科技，等待设置证书数量。
在需要授权的工控机上启动Detour，复制“概况”标签下方的“DeviceID”。
图 6-1 授权信息的DeviceID
如果您使用DetourLite，请从DetourLite的控制台输出获取DeviceID，如图6-2所示。
图 6-2 DetourLite的Device ID
登入Auth站，选择Inventory的"MDCS2-license"。
注意：MDCS-license将被废弃，请勿使用！
图 6-3 选择MDCS2授权证书
点击“Activate”按钮，输入Device ID"。以图5-1为例，DeviceID是"4D222EB2BEE27897"，则输入"4D222EB2BEE27897"（没有双引号）。如果是"x2"规格授权，则在DeviceID后加"x2"后缀，比如"4D222EB2BEE27897x2"。
提示：授权规格分为"x1"、“x2"。"x1"就是不带后缀的DeviceID。请根据报价单给出的授权规格输入后缀，如有疑问请咨询懒书技术支持工程师。
图 6-4 激活设备
Description建议使用车型命名，以便管理。比如"{项目编号} - {序号}"。
填写完毕后，点击“Activate”按钮，把下载的证书文件存入Detour目录（与Detour.exe或DetourLite.exe同级）。重启Detour，此时主界面的“试用版”信息消失，激活成功。 填写完毕后，点击“Activate”按钮，把下载的证书文件存入Detour目录（与Detour.exe或DetourLite.exe同级）。重启Detour，此时主界面的“试用版”信息消失，激活成功。