Overview
The Advanced IMU sensor provides the functionality of a tri-axial IMU sensor, providing acceleration and gyroscopic data. Users can attach multiple instances of this sensor to vehicles and set the local tri-axial coordinate systems for each. The rate at which readings are measured can also be set as required, up to 2000Hz.
The readings from the sensor include angular velocity and acceleration, linear acceleration, mass at sensor, position and direction.
The sensor data readings are a collection of time-stamped raw samples (with which the user can perform their own smoothing). We also provide a smoothed linear acceleration vector – the user should provide either a cutoff frequency or a window with, if this smoothing is to be used.
Usage
The Advanced IMU code is written in Lua directly, rather than C++. It has a very similar API to the other sensors in our suite.
For other usage examples with this sensor, please look at the beamNGpy scripts.
sensorId = extensions.tech_sensors.createAdvancedIMU(vehicleId, args)
Args:
vehicleID(int): The vehicle ID. This cannot be nil - the Advanced IMU sensor must be attached to a vehicle.
The args parameter is a Lua table containing as many of the following properties as required. If any property is not set manually then a default value is used, so it is entirely possible to create the Advanced IMU sensor with args being an empty table. What follows is a complete list of these arguments:
pos(Point3F): The position of the Advanced IMU sensor, in vehicle space.
dir(Point3F): The forward direction in which the Advanced IMU sensor points.
up(Point3F): The up direction of the Advanced IMU sensor.
GFXUpdateTime(float): How often the Advanced IMU sensor should update its readings in the simulator (in seconds). This determines how often the user will be able to retrieve a new reading from the sensor.
physicsUpdateTime(float): How often in the simulator’s physics step, we should update the Advanced IMU readings (in seconds). This parameter should be smaller than GFXUpdateTime, and can be as small as 1/2000 seconds, since this is currently the rate at which the physics steps cycles. This value determines how often we poll the Advanced IMU to get a snapshot of data at a given time, so the smaller this is, the more accurate the readings will be (at the cost of computation load in the simulation - for a small number of sensors this should not matter, either way).
windowWidth(float): If smoothing is to be used with the linear acceleration data, then this parameter can be used to set the window width of the smoother (exponential smoothing is currently used).
frequencyCutoff(float): Alternatively, a direct cut-off frequency can be used when smoothing the linear acceleration data. If both values (frequencyCutoff and windowWidth) are provided, we use the windowWidth by default.
isUseGravity(bool): A flag which indicates if the Advanced IMU sensor should include gravity in its computations.
isAllowWheelNodes(bool): A flag which indicates if we should include vehicle wheel nodes when looking for attach points. If we wish to attach an Advanced IMU to a vehicle wheel, we should set this to true and then set pos to a point near to or on the wheel. If this is not set, the sensor would attach itself to the nearest part of the vehicle which does not comprise any wheel nodes.
isVisualised(bool): A flag which indicates if the Advanced IMU sensor should be visualised.
isSnappingDesired(bool): True if the Advanced IMU sensor position should be forced onto the surface of the vehicle, at its closest vehicle point. This is useful if finding it hard to have the sensor on the vehicle itself. False, otherwise, eg if the sensor should be suspended at a fixed point relative to the vehicle.
isForceInsideTriangle(bool): Used with isSnappingDesired. True, if the Advanced IMU sensor should be forced to be inside its nearest vehicle triangle. Otherwise false.
Returns: sensorId(int): The unique Id number of this sensor, in order to refer to it later eg when closing it.
readings = extensions.tech_sensors.getAdvancedIMUReadings(sensorId)
Args:
sensorId(int): The ID number of the Advanced IMU sensor.
Returns: readings(vec3): The latest readings from the sensor.
extensions.tech_sensors.setAdvancedIMUUpdateTime(sensorId, updateTime)
Args:
sensorId(int): The ID number of the Advanced IMU sensor.
updateTime(float): The new update time for this sensor.
Returns: nil
extensions.tech_sensors.setAdvancedIMUIsUsingGravity(sensorId, isUsingGravity)
Args:
sensorId(int): The ID number of the Advanced IMU sensor.
isUsingGravity(bool): Whether the Advanced IMU should include gravity in its computations, or not.
Returns: nil
extensions.tech_sensors.setAdvancedIMUIsVisualised(sensorId, isVisualised)
Args:
sensorId(int): The ID number of the Advanced IMU sensor.
isVisualised(bool): Whether the Advanced IMU should be visualised or not.
Returns: nil
The following three functions can be used to send ad-hoc polling requests to an Advanced IMU sensor. This is for when we just want an occasional reading. We need to first send a request using sendAdvancedIMURequest, then wait for it. We can check it is complete using isVluaRequestComplete (see below), then retrieve it using collectAdvancedIMURequest.
requestId = extensions.tech_sensors.sendAdvancedIMURequest(sensorId)
Args:
sensorId(int): The ID number of the Advanced IMU sensor.
Returns: The unique Id number of the ad-hoc sensor polling request which is being sent.
isComplete = extensions.tech_sensors.isVluaRequestComplete(requestId)
Args:
requestId(int): The ID number of the ad-hoc sensor polling request to check on.
Returns: isComplete(bool): True if the ad-hoc polling request has been completed, otherwise false.
data = extensions.tech_sensors.collectAdvancedIMURequest(requestId)
Args:
requestId(int): The ID number of the ad-hoc sensor polling request.
Returns: data(vec3): The Advanced IMU readings.
extensions.tech_sensors.removeAdvancedIMU(sensorId)
Args:
sensorId(int): The ID number of the AdvancedIMU sensor to remove.
Returns: nil.
