用过AirSim 1.3.1的人应该都对settings.json有印象。这个文件说大不大、说小不小但它决定着你仿真环境里飞的是什么机型、带没带激光雷达、GPS误差多大、天上下不下雨、录不录像。我最初接触这个版本的时候照教程把环境跑通很容易可一旦想按自己的需求改飞机、加传感器、调天气就一头扎进这个JSON文件里出不来。这篇东西就是给同样被setting.json折磨的人写的尽量把1.3.1版本里常见配置项、参数含义、实操用法和踩坑点一次讲清楚。先说清楚一个事网上很多教程用的是新版本AirSim的配置格式直接抄到1.3.1上经常不生效。AirSim每个版本的配置项都有细微差异尤其SettingsVersion、VehicleType这种关键字段新旧版本差别不小。我下面讲的都是基于1.3.1这个版本的实际行为你用别的版本时记得留个心眼。1. setting.json在AirSim里的定位先搞懂这个文件是怎么被读取的1.1 配置文件的加载路径AirSim启动Unreal场景时会去当前用户的文档目录下找一个固定路径的配置文件。Windows下路径是C:\Users\你的用户名\Documents\AirSim\settings.jsonLinux下是~/Documents/AirSim/settings.json。注意不是放在你的Unreal工程目录下也不是放在AirSim仓库里。很多人第一次找不到文件在哪就是因为不知道AirSim是从文档目录读配置的。如果这个文件不存在AirSim会使用内置的默认配置启动默认创建一架SimpleFlight无人机场景里也没有额外传感器。所以你想改任何东西第一步永远是去这个路径下新建或编辑settings.json。1.2 加载流程决定了你改配置后要做什么AirSim只在启动时读取一次配置文件运行时不会热加载。这意味着你改了settings.json之后必须把Unreal环境整个停掉重新播放或者重新启动修改才会生效。有些时候比如你只是改了传感器参数可以试试场景里的重启按钮但最稳妥的做法还是完全退出再启动。我自己的习惯是维护好这个JSON文件后先启动Unreal编辑器再用启动后的控制台日志确认配置是否加载成功。日志里会打印AirSimSettings相关的信息能看到Loaded settings之类的输出。如果JSON解析失败AirSim会打出一段错误信息然后回退到默认配置。很多时候你以为自己配置了实际上JSON写坏了AirSim悄悄用了默认值这是最坑的一种情况。2. 全局配置项逐个拆解相当于AirSim的“总控制台”2.1 SettingsVersion和SimMode两个必须先搞明白的字段settings.json最外层一定有这几个字段SettingsVersion、SimMode一般还有ClockSpeed。1.3.1版本支持的SettingsVersion是1.2这个值基本固定。它存在的意义是告诉AirSim这套配置是按哪个版本的规范写的方便后续版本做兼容。你网上找配置模板时优先找SettingsVersion为1.2的因为那是和这个版本匹配的。SimMode可选的值有三个Multirotor、Car、ComputerVision。默认是Multirotor也就是多旋翼无人机模式这是大部分做无人机仿真的人最常用的。Car模式是无人车用于自动驾驶相关研究。ComputerVision比较特殊它不创建任何带物理模型的载具只给你一个可以自由移动的相机专门用来做视觉数据采集比如生成一批带深度图、分割图的训练数据集这种模式下没有飞控逻辑也就没有飞机可飞。这个字段是大小写敏感的写成computerVision、multirotor都不行AirSim识别不了就直接用默认值。我见过好几个朋友因为这个问题折腾了半天。2.2 ClockSpeed、Wind这些环境参数是怎么影响仿真的ClockSpeed控制仿真时钟相对于真实时间的快慢。值为1时是实时仿真值为5表示仿真时间比真实时间快5倍。这个字段对两类人特别有用做强化学习训练的人经常把它设成3到5加快数据采集速度。做真实飞控硬件在环测试的人必须把它设成1否则PX4内部的时间戳逻辑会乱掉。但要注意一点ClockSpeed设大之后物理引擎的计算步长不会变只是每秒钟模拟了更多个物理步。飞控极不稳定的时候用高倍速仿真容易出问题飞机可能出现奇怪的抖动或者直接飞丢。我自己做控制算法调试时宁可慢一点也要保持物理真实性所以基本只用1。环境相关还有一个很实用的配置是Wind它设置一个恒定的风场Wind: { X: 3.0, Y: 0.0, Z: -0.5 }单位是米/秒XYZ方向对应世界坐标系。Z轴向下为正所以-0.5表示有轻微向上的风。这个配置在做抗风控制实验时非常有用可以给无人机一个持续的风扰动。另外ViewMode配置控制仿真窗口的视角常用的有Fpv第一人称视角从飞机摄像头看、FlyWithMe跟随视角、GroundObserver地面观察、NoDisplay不开窗口适合跑批处理数据。记住ViewMode的值也是大小写敏感的。3. 车辆、传感器与数据采集真正干活的部分3.1 定义车辆Vehicles和VehicleType1.3.1版本里Vehicles字段是一个字典可以同时定义多辆车比如一架无人机加一辆无人车。每辆车需要指定VehicleType。常见取值有两个SimpleFlight和PX4Multirotor。SimpleFlight是AirSim内置的纯仿真飞控不需要外部硬件和固件适合做视觉数据采集、控制算法验证、强化学习训练。它有一套简化的状态机支持Armed、Takeoff、Land等操作用Python API控制起来非常方便。PX4Multirotor是给接真实PX4固件的场景用的分软件在环和硬件在环两种情况。软件在环时PX4固件在宿主机上跑通过MAVLink和AirSim通信硬件在环时通过串口连接真实的PX4飞控板。一个只跑SimpleFlight的最小车辆配置长这样Vehicles: { MyDrone: { VehicleType: SimpleFlight, DefaultVehicleState: Armed, AutoCreate: true } }车辆名MyDrone可以随便起后面用Python API连接时要用这个名字所以尽量起个容易记住的。DefaultVehicleState设为Armed意味着启动时电机已经上电省去了手动解锁的操作流程做数据采集时比较省事。AutoCreate默认是true如果改成false这辆车不会自动创建你需要通过API动态生成一般来说保持默认就行。3.2 传感器挂载Sensors里的每个传感器到底怎么配这是1.3.1里最值得花时间研究的配置。Sensors字段定义在每辆车的下面是一个字典键名可以自己定义但每个传感器必须有对应的SensorType数字这个数字不能乱写。1.3.1版本的对应关系如下SensorType值传感器类型典型用途1Barometer 气压计高度估计2IMU 惯性测量单元角速度和加速度测量3GPS 全球定位系统位置定位4Magnetometer 磁力计航向估计5Distance 距离传感器避障、定高6Lidar 激光雷达建图、避障、点云数据采集一个常见的传感器配置示例是这样的Vehicles: { MyDrone: { VehicleType: SimpleFlight, Sensors: { Imu: { SensorType: 2, Enabled: true, AngularRandomWalk: 0.008, GyroBiasStabilityNss: 0.025, VelocityRandomWalk: 0.06, AccelBiasStabilityNss: 0.06 }, Gps: { SensorType: 3, Enabled: true, Eph: 1.0, Epv: 1.0 }, Lidar1: { SensorType: 6, Enabled: true, NumberOfLasers: 16, PointsPerScan: 1000, Range: 100, HorizontalFOVStart: -90, HorizontalFOVEnd: 90, VerticalFOVUpper: 15, VerticalFOVLower: -15, X: 0, Y: 0, Z: 0, Roll: 0, Pitch: 0, Yaw: 0, RotationalFrequency: 10, DataChannel: 0 } } } }GPS配置里的Eph和Epv分别是水平误差和垂直误差单位是米。默认值都是1.0但实际场景中很少有人用这么高精度的GPS我一般会把它调到2到3模拟真实消费级GPS的定位精度这样后期做传感器融合算法时才能暴露问题。IMU配置里的几个参数直接决定噪声特性。AngularRandomWalk是角度随机游走GyroBiasStabilityNss是陀螺零偏稳定性VelocityRandomWalk是速度随机游走AccelBiasStabilityNss是加速度计零偏稳定性。这些名词看着高端实际上你不需要完全理解背后的随机过程模型。你只需要知道这些值调大传感器输出会越“脏”调小输出越“干净”。做算法验证时先用默认值跑通再按你的传感器标称精度去调。NumberOfLasers是激光雷达的线数16线、32线、64线都是常见选择。PointsPerScan决定一帧点云里每条激光线的点数可以理解为水平扫描分辨率。它越大点云越密但计算开销也越大。如果你是做纯视觉算法、顺便用激光雷达辅助16线、每线500点左右就够了。HorizontalFOVStart和HorizontalFOVEnd是水平扫描范围单位是度。-90到90就是180度半圈-180到180就是360度一圈。RotationalFrequency是扫描频率单位Hz一般设10也就是每秒转10圈一帧点云是0.1秒的数据。传感器装在哪由X、Y、Z和Roll、Pitch、Yaw这几个字段控制这是相对载具坐标系的位置和姿态。特别注意AirSim的坐标系是Z轴向下所以想装在无人机上方Z应该是负值。传感器位置影响点云和图像的视角调试的时候要多试几个位置。3.3 相机配置与数据录制把图像数据落到本地CameraSettings是相机列表每辆车可以挂多个相机。1.3.1版本里相机的命名有一部分还保留着数字索引形式比如0代表默认前视相机。一个典型的配置CameraSettings: [ { CaptureSettings: [ { ImageType: 0, Width: 960, Height: 540, FOV_Degrees: 90, AutoExposureSpeed: 50 } ] } ]ImageType决定相机输出的图像类型这个枚举值要背下来0是场景图也就是RGB图1是深度可视化图2是分割图3是深度平面图输出真实的深度值4是红外图5是法线图。深度可视化图和深度平面图的区别是前者是给人看的伪彩色图后者是给算法用的深度数据每个像素值代表距离单位是厘米。用API读深度数据时用ImageType为3的DepthPlanner拿到像素值记得除以100转成米。录制数据是很多人的核心需求。Recording字段配置方式如下Recording: { RecordOnMove: true, RecordInterval: 0.05, Cameras: [ { CameraName: 0, ImageType: 0 }, { CameraName: 0, ImageType: 1 } ] }RecordOnMove为true时只有载具在运动时才记录减少无用帧。RecordInterval是记录间隔单位秒0.05就是每秒20帧0.1就是每秒10帧。别小看这个参数它直接决定你录出来的数据量和后续标注工作量。做视觉SLAM测试时我用0.05做低速巡检模拟时用0.1就够。录制的数据默认保存到Documents\AirSim\目录下每次启动会生成一个带时间戳的文件夹。里面有图像文件和一个airsim_rec.txt文件记录每帧的时间戳、位置、姿态、速度等真值。这个txt文件就是你做视觉SLAM时用来对齐真值的核心依据所以Recording字段看起来简单实际作用非常大。4. 环境气象与地理参数让仿真环境贴近真实4.1 天气效果不是所有场景都要艳阳天AirSim从1.3左右开始支持天气模拟配置方式是定义一个Weather对象Weather: { Enabled: true, Rain: 0.5, Snow: 0, Maple: 0.3, Road: 0, Fog: 0.2 }Enabled必须为true天气效果才会生效后面各项的取值范围是0到10表示没有1表示最强。Rain是雨量Snow是雪量Fog是雾浓度。Maple是枫叶飘落效果这个效果比较特殊它模拟的是秋天落叶的场景做视觉算法的鲁棒性测试时有点用。Road是路面湿润效果会模拟地面积水反光。这里建议做仿真的人不要忽略天气尤其是做视觉导航算法。你辛辛苦苦在晴天场景训练的模型换到测试环境里加一点雾、加一点雨模型鲁棒性立刻见分晓。AirSim的天气系统给算法验证提供了很好的测试维度。4.2 OriginGeopoint和TimeOfDay地理坐标与光照OriginGeopoint定义仿真地图原点对应的真实地理坐标在PX4相关实验中会直接影响GPS输出的经纬度和高度。配置格式OriginGeopoint: { Latitude: 47.641468, Longitude: -122.140165, Altitude: 122 }这个字段大多数人会忽略但如果你的算法要从仿真结果映射到真实GPS坐标或者你在做真实场地的数字孪生仿真原点坐标必须设成你实际关心的地理位置。默认值用的是西雅图一个地方我记得是AirSim默认地图的基准点。TimeOfDay控制太阳位置和光照变化做视觉数据增强很有用TimeOfDay: { Enabled: true, StartDateTime: 2018-07-01 12:00:00, CelestialClockSpeed: 3600 }StartDateTime是仿真起始时间CelestialClockSpeed是时间流逝速度3600代表仿真里过1秒太阳位置相当于真实时间过了1小时。做室内实验的时候很少有人开这个因为它会增加光照计算结果的开销。但如果你要生成“白天到黄昏”的光照变化数据集这个配置就是你的利器。5. 从零配置一个可用的无人机仿真环境实操全过程5.1 最小配置跑通先飞起来再谈其他无论你最终要做什么我强烈建议先从一个最小配置开始。最小配置的内容甚至不需要Vehicles字段{ SettingsVersion: 1.2, SimMode: Multirotor }保存到Documents\AirSim\settings.json后启动Unreal场景默认就会创建一架SimpleFlight无人机并有前视相机。用Python客户端验证一下import airsim client airsim.MultirotorClient() client.confirmConnection() client.enableApiControl(True) client.armDisarm(True) client.takeoffAsync().join() print(takeoff finished)这一步能跑通说明AirSim环境本身没问题接下来再往配置里加东西。很多人的错误在于刚开始就试图配置PX4、配激光雷达、配多相机结果环境起不来根本不知道问题出在哪。最小配置是定位问题的分界线。5.2 加激光雷达和IMU按需扩展配置跑通之后我给这个最小配置加上了IMU、GPS和Lidar做一个带完整感知的无人机。配置结构如下{ SettingsVersion: 1.2, SimMode: Multirotor, ClockSpeed: 1, Vehicles: { MyDrone: { VehicleType: SimpleFlight, DefaultVehicleState: Armed, Sensors: { Imu: { SensorType: 2, Enabled: true }, Gps: { SensorType: 3, Enabled: true, Eph: 2.0, Epv: 2.0 }, Lidar1: { SensorType: 6, Enabled: true, NumberOfLasers: 16, PointsPerScan: 800, Range: 50, HorizontalFOVStart: -180, HorizontalFOVEnd: 180, VerticalFOVUpper: 15, VerticalFOVLower: -15, RotationalFrequency: 10 } } } } }然后通过Python API读取传感器数据import airsim client airsim.MultirotorClient() client.confirmConnection() imu_data client.getImuData() gps_data client.getGpsData() lidar_data client.getLidarData() print(IMU angular velocity:, imu_data.angular_velocity) print(GPS location:, gps_data.gnss.location) print(Lidar points count:, len(lidar_data.point_cloud))这里有个小细节在1.3.1版本中getImuData()、getGpsData()这类API如果没有指定车辆名默认取的是第一辆车。如果配置里只有一个车辆直接调用没问题。如果你的场景里有多个车辆记得在API调用里传入车辆名否则可能读到错误车辆的数据。5.3 连接外部地面站或飞控的配置参考如果你是做PX4相关开发想用真实PX4固件和AirSim联调配置文件会复杂一些。1.3.1版本中连接PX4的常用配置如下{ SettingsVersion: 1.2, SimMode: Multirotor, ClockSpeed: 1, Vehicles: { PX4: { VehicleType: PX4Multirotor, UseSerial: true, UseTcp: true, TcpPort: 4560, ControlPort: 14580, SerialPort: /dev/ttyACM0, SerialBaudRate: 115200, DefaultVehicleState: Armed } } }UseSerial为true表示通过串口连接硬件SerialPort和SerialBaudRate对应你的设备路径和波特率。UseTcp为true配合TcpPort用于MAVLink的TCP连接。ControlPort是给QGroundControl等地面站用的端口。这里提醒两点第一PX4连接有时候失败不是配置问题而是时序问题——PX4固件启动时AirSim还没准备好。我建议先启动AirSim等场景完全加载、无人机出现之后再启动PX4那一侧。第二做PX4联调时ClockSpeed一定要是1这是硬性的别为了加速训练去改这个值否则PX4和仿真环境的时间同步会出大问题。6. 常见问题与排查实录都是我用时间换来的经验6.1 配置不生效按这个顺序排查配置不生效是最多的问题我把它分成几类按优先级从高到低排查路径和文件名错了。Linux下Settings.json和settings.json是两个不同的文件如果你的项目部署在Linux服务器上注意大小写必须精确。JSON格式错误。settings.json不支持注释从网上复制的配置务必删掉所有//和#注释。我推荐用VS Code编辑保存时它会自动提示JSON语法错误。没有完全重启仿真。AirSim只在场景启动时读一次配置改完必须完全停止再启动。字段拼写错误。这里举几个我已经踩过的SettingsVersion是首字母大写SimMode中间没有下划线VehicleType不能简写成Type。AirSim对这些字段名是精确匹配的。版本不匹配。网上的配置可能是新版本的里面的字段在1.3.1里不存在。比如新版本用了一些新传感器类型编号在1.3.1里SensorType枚举值不一样。6.2 传感器数据异常的几个典型表现传感器配了但读不到数据或者数据看着不对这是第二大类问题。如果Lidar返回的点云为空先检查Range是不是太小而且你的飞机周围有没有障碍物。空旷场景下雷达扫描不到东西点云就是空的。如果GPS数据经纬度全是0或者明显不对检查OriginGeopoint是否配置。GPS输出是基于原点坐标偏移计算的原点默认值离你实际位置太远时经纬度看起来会特别怪。如果图像全是黑的或者深度图不显示检查ImageType是不是写成了字符串。ImageType要写数字ImageType: scene这种写法在1.3.1里不会被正确解析需要写成0。6.3 多车辆场景的坑车辆名和传感器名要对上有些场景需要同时开多架无人机或者一架无人机加一辆无人车这时Vehicles字典下每个名字对应一个独立的载具。最容易犯的错是Python API调用时不传车辆名AirSim默认取第一辆车。你要是第二辆车上挂了激光雷达却没有指定车辆名雷达数据一直读不到还以为是配置问题。另外多车辆场景中每辆车的传感器是可以独立配置的同一辆车下可以用不同的键名挂多个同类型传感器比如挂三个不同的相机每个相机命名不同。后续API读取时要用对应的键名这个键名就是传感器在Sensors字典里的key别搞混。最后再分享一个我自己的习惯每次改配置文件之前先把当前能跑通的版本另存一份比如settings_backup.json。因为调试过程中你一定会碰到把配置改坏的情况改坏了还能快速回滚不用从头回忆原来是怎么写的。AirSim的配置这套东西本身逻辑不复杂坑都在细节上。你把上面这些字段和排查顺序记熟1.3.1版本的setting.json对你来说基本上就没有秘密了。