Files
PX4-Autopilot/docs/en/sensor/microstrain.md
T
Jacob Dahl e40501eba0 refactor(msg): rename GPS to GNSS in messages, topics and sensor parameters (#24399)
* refactor(msg): rename SensorGps to SensorGnss and add VehicleGnss

GPS is one constellation; the receivers and the rest of PX4 handle GNSS. Field names lose their units (latitude, speed_accuracy, course, ...), which move into the metadata comments. The sensors module's output becomes VehicleGnss on vehicle_gnss: the selected receiver's sample next to what the sensors module adds to it (corrected sample time, antenna position, selected instance), so a consumer can tell the two apart and later selection and check results have a place to go.

Assisted-by: Claude:claude-opus-5-5

* refactor(drivers/gps): publish sensor_gnss

Follows the SensorGps to SensorGnss and vehicle_gps_position to VehicleGnss rename.

Assisted-by: Claude:claude-opus-5-5

* refactor(drivers/septentrio): publish sensor_gnss

Follows the SensorGps to SensorGnss and vehicle_gps_position to VehicleGnss rename.

Assisted-by: Claude:claude-opus-5-5

* refactor(drivers/pps_capture): read sensor_gnss

Follows the SensorGps to SensorGnss and vehicle_gps_position to VehicleGnss rename.

Assisted-by: Claude:claude-opus-5-5

* refactor(lib/gnss): select receivers on sensor_gnss

Follows the SensorGps to SensorGnss and vehicle_gps_position to VehicleGnss rename.

Assisted-by: Claude:claude-opus-5-5

* refactor(sensors): publish VehicleGnss on vehicle_gnss and rename SENS_GPS* to SENS_GNSS*

The sensors module's output nests the selected receiver's sample, with the corrected sample time, antenna position and selected instance next to it. SENS_GPS_MASK/TAU/PRIME and SENS_GPSn_ID/OFFX/OFFY/OFFZ/DELAY take the SENS_GNSS name the heading parameters already use; saved parameters migrate on import, and the EKF2_GPS_POS/EKF2_GPS_DELAY translations now land on the new names directly.

Assisted-by: Claude:claude-opus-5-5

* refactor(logger): log sensor_gnss and vehicle_gnss

Follows the SensorGps to SensorGnss and vehicle_gps_position to VehicleGnss rename.

Assisted-by: Claude:claude-opus-5-5

* refactor(ekf2): fuse vehicle_gnss

Follows the SensorGps to SensorGnss and vehicle_gps_position to VehicleGnss rename.

Assisted-by: Claude:claude-opus-5-5

* refactor(replay): replay vehicle_gnss

Follows the SensorGps to SensorGnss and vehicle_gps_position to VehicleGnss rename.

Assisted-by: Claude:claude-opus-5-5

* refactor(local_position_estimator): read vehicle_gnss

Follows the SensorGps to SensorGnss and vehicle_gps_position to VehicleGnss rename.

Assisted-by: Claude:claude-opus-5-5

* refactor(attitude_estimator_q): read vehicle_gnss

Follows the SensorGps to SensorGnss and vehicle_gps_position to VehicleGnss rename.

Assisted-by: Claude:claude-opus-5-5

* refactor(lib/terrain_estimation): take sensor_gnss

Follows the SensorGps to SensorGnss and vehicle_gps_position to VehicleGnss rename.

Assisted-by: Claude:claude-opus-5-5

* refactor(lib/wind_estimator): read vehicle_gnss in the replay script

Follows the SensorGps to SensorGnss and vehicle_gps_position to VehicleGnss rename.

Assisted-by: Claude:claude-opus-5-5

* refactor(vision_target_estimator): read vehicle_gnss

Follows the SensorGps to SensorGnss and vehicle_gps_position to VehicleGnss rename.

Assisted-by: Claude:claude-opus-5-5

* refactor(navigator): read vehicle_gnss

Follows the SensorGps to SensorGnss and vehicle_gps_position to VehicleGnss rename.

Assisted-by: Claude:claude-opus-5-5

* refactor(commander): read sensor_gnss and vehicle_gnss

Follows the SensorGps to SensorGnss and vehicle_gps_position to VehicleGnss rename.

Assisted-by: Claude:claude-opus-5-5

* refactor(mavlink): stream sensor_gnss and vehicle_gnss

Follows the SensorGps to SensorGnss and vehicle_gps_position to VehicleGnss rename.

Assisted-by: Claude:claude-opus-5-5

* refactor(uxrce_dds_client): bridge vehicle_gnss

Follows the SensorGps to SensorGnss and vehicle_gps_position to VehicleGnss rename.

Assisted-by: Claude:claude-opus-5-5

* refactor(zenoh): bridge vehicle_gnss

Follows the SensorGps to SensorGnss and vehicle_gps_position to VehicleGnss rename.

Assisted-by: Claude:claude-opus-5-5

* refactor(failure_injection): inject GNSS failures on sensor_gnss

Follows the SensorGps to SensorGnss and vehicle_gps_position to VehicleGnss rename.

Assisted-by: Claude:claude-opus-5-5

* refactor(drivers/ins): publish sensor_gnss

Follows the SensorGps to SensorGnss and vehicle_gps_position to VehicleGnss rename.

Assisted-by: Claude:claude-opus-5-5

* refactor(drivers/uavcan): publish sensor_gnss

Follows the SensorGps to SensorGnss and vehicle_gps_position to VehicleGnss rename.

Assisted-by: Claude:claude-opus-5-5

* refactor(drivers/uavcannode): read sensor_gnss

Follows the SensorGps to SensorGnss and vehicle_gps_position to VehicleGnss rename.

Assisted-by: Claude:claude-opus-5-5

* refactor(drivers/cyphal): bridge sensor_gnss

Follows the SensorGps to SensorGnss and vehicle_gps_position to VehicleGnss rename.

Assisted-by: Claude:claude-opus-5-5

* refactor(drivers/telemetry): read vehicle_gnss

Follows the SensorGps to SensorGnss and vehicle_gps_position to VehicleGnss rename.

Assisted-by: Claude:claude-opus-5-5

* refactor(drivers/rc): read vehicle_gnss for telemetry

Follows the SensorGps to SensorGnss and vehicle_gps_position to VehicleGnss rename.

Assisted-by: Claude:claude-opus-5-5

* refactor(drivers/osd): read vehicle_gnss

Follows the SensorGps to SensorGnss and vehicle_gps_position to VehicleGnss rename.

Assisted-by: Claude:claude-opus-5-5

* refactor(drivers/transponder): read sensor_gnss

Follows the SensorGps to SensorGnss and vehicle_gps_position to VehicleGnss rename.

Assisted-by: Claude:claude-opus-5-5

* refactor(boards/modalai): publish sensor_gnss from the voxl2 drivers

Follows the SensorGps to SensorGnss and vehicle_gps_position to VehicleGnss rename.

Assisted-by: Claude:claude-opus-5-5

* refactor(examples): publish sensor_gnss and read vehicle_gnss

Follows the SensorGps to SensorGnss and vehicle_gps_position to VehicleGnss rename.

Assisted-by: Claude:claude-opus-5-5

* refactor(simulation): publish sensor_gnss

Follows the SensorGps to SensorGnss and vehicle_gps_position to VehicleGnss rename.

Assisted-by: Claude:claude-opus-5-5

* refactor(gnss): name GNSS variables gnss in the sensors module and receiver drivers

GPS is one constellation. Identifiers that hold or handle GNSS samples, or bind to the renamed parameters, follow the message and parameter rename; classes, files, modules and names tied to parameters that keep GPS stay.

Assisted-by: Claude:claude-opus-5-5

* refactor(gnss): name GNSS variables gnss in the estimators and navigator

GPS is one constellation. Identifiers that hold or handle GNSS samples, or bind to the renamed parameters, follow the message and parameter rename; classes, files, modules and names tied to parameters that keep GPS stay.

Assisted-by: Claude:claude-opus-5-5

* refactor(gnss): name GNSS variables gnss in commander, mavlink and failure injection

GPS is one constellation. Identifiers that hold or handle GNSS samples, or bind to the renamed parameters, follow the message and parameter rename; classes, files, modules and names tied to parameters that keep GPS stay.

Assisted-by: Claude:claude-opus-5-5

* refactor(gnss): name GNSS variables gnss in the remaining drivers and simulation

GPS is one constellation. Identifiers that hold or handle GNSS samples, or bind to the renamed parameters, follow the message and parameter rename; classes, files, modules and names tied to parameters that keep GPS stay.

Assisted-by: Claude:claude-opus-5-5

* docs(gnss): reference sensor_gnss, vehicle_gnss and SENS_GNSS* parameters

The upgrade guide covers the topic, field, ROS 2, parameter and Cyphal register renames.

Assisted-by: Claude:claude-opus-5-5

* fix(boards): name EKF2::UpdateGnssSample in the fmu-v6xrt ITCM lists

The rename left the old UpdateGpsSample symbol in the lists, so the ITCM check fails and the function drops out of ITCM on the boards it doesn't check.

Assisted-by: Claude:claude-opus-5-5

* chore(drivers/gps): bump PX4-GPSDrivers to the merged sensor_gnss rename

The submodule pointed at the PX4-GPSDrivers#243 branch commit; #243 is merged.

Assisted-by: Claude:claude-opus-5-5

* docs(msg): restore WGS84 in SensorGnss and point VehicleGlobalPosition at vehicle_gnss

The rename dropped the only mention of the WGS84 datum and ellipsoid, and left VehicleGlobalPosition referring to the removed vehicle_gps_position topic.

Assisted-by: Claude:claude-opus-5-5

* refactor(msg): drop selected_instance from VehicleGnss

receiver.device_id already names the selected receiver, and 0 while blended. The sensor_gnss instance depends on the order drivers advertise at boot, so it doesn't identify a receiver across boots or logs, and nothing reads it. It would also be meaningless on the per-receiver VehicleGnss instances proposed in #28894.

Assisted-by: Claude:claude-opus-5-5

* refactor(gnss): fuse vehicle_gnss.timestamp_sample directly and document the receiver's corrected time

vehicle_gnss.timestamp is now the sensors module's publish time, so EKF2's check of timestamp_sample against it was always true; the sensors module always fills timestamp_sample. The message docs described receiver.timestamp_sample as the driver's uncorrected value, but the sensors module writes the corrected time into it as well.

Assisted-by: Claude:claude-opus-5-5

* docs(msg): point VehicleGnss users at the top-level timestamp_sample

uXRCE-DDS shifts only top-level timestamp and timestamp_sample into agent time, so receiver.timestamp_sample reaches ROS 2 on the PX4 boot clock even though it holds the same value on uORB.

Assisted-by: Claude:claude-opus-5-5

* docs(releases): tell ROS 2 users which VehicleGnss timestamps to read

Only top-level timestamps are converted to ROS time, so a port that reads receiver.timestamp gets the PX4 boot clock, and vehicle_gnss.timestamp is now the sensors module's publish time rather than the receiver's.

Assisted-by: Claude:claude-opus-5-5
2026-09-29 10:36:49 -06:00

189 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# MicroStrain (INS, IMU, VRU, AHRS)
MicroStrain by HBK provides high-performance inertial sensors engineered for reliability and precision in challenging environments.
Widely used across industries like aerospace, robotics, industrial automation, and research, MicroStrain sensors are optimized for real-time, accurate motion tracking and orientation data.
![CV7](../../assets/hardware/sensors/inertial/microstrain_3dm_cv7_hbk.png)
The driver currently supports the following hardware:
- [`MicroStrain CV7-AR`](https://www.hbkworld.com/en/products/transducers/inertial-sensors/vertical-reference/3dm-cv7-ar): Inertial Measurement Unit (IMU) and Vertical Reference Unit (VRU)
- [`MicroStrain CV7-AHRS`](https://www.hbkworld.com/en/products/transducers/inertial-sensors/attitude-and-heading/3dm-cv7-ahrs): Inertial Measurement Unit (IMU) and Attitude Heading Reference System (AHRS)
- [`MicroStrain CV7-INS`](https://www.hbkworld.com/en/products/transducers/inertial-sensors/navigation/3dm-cv7-ins): Inertial Measurement Unit (IMU) and Inertial Navigation System (INS).
- [`MicroStrain CV7-GNSS/INS`](https://www.hbkworld.com/en/products/transducers/inertial-sensors/navigation/3dm-cv7-gnss-ins): Inertial Measurement Unit (IMU) and Inertial Navigation System (INS) combined with dual multiband (GNSS) receivers.
PX4 can use these sensors to provide raw IMU data for EKF2 or to replace EKF2 as an external INS.
For more information, including user manuals and datasheets, please refer to the sensors product page.
## Where to Buy
MicroStrain sensors can be purchased through HBK's official [MicroStrain product page](https://www.hbkworld.com/en/products/transducers/inertial-sensors) or through authorized distributors globally.
For large orders, custom requirements, or technical inquiries, reach out directly to [sales](https://www.hbkworld.com/en/contact-us)
## Hardware Setup
### Wiring
Connect the main UART port of the MicroStrain sensor to any unused serial port on the flight controller.
This port needs to be specified while starting the device.
### Mounting
The MicroStrain sensor can be mounted in any orientation.
The default coordinate system uses X for the front, Y for the right, and Z for down, with directions marked on the device.
## Firmware Configuration
### PX4 Configuration
To use the MicroStrain driver:
1. Include the module in firmware in the [kconfig board configuration](../hardware/porting_guide_config.md#px4-board-configuration-kconfig) by setting the kconfig variables: `CONFIG_DRIVERS_INS_MICROSTRAIN` or `CONFIG_COMMON_INS`.
2. Configure the driver mode by setting [MS_MODE](../advanced_config/parameter_reference.md#MS_MODE)
- To use the MicroStrain sensor to provide raw IMU data to EKF2
1. Set [MS_MODE](../advanced_config/parameter_reference.md#MS_MODE) to 0
2. Update the [EKF2_MULTI_IMU](../advanced_config/parameter_reference.md#EKF2_MULTI_IMU) parameter to account for the added MicroStrain sensor.
3. Enable EKF2 by setting [EKF2_EN](../advanced_config/parameter_reference.md#EKF2_EN) to 1
4. To prioritize MicroStrain sensor output, adjust the priority level of individual sensors from 0-100 using the following parameters:
- [CAL_ACCn_PRIO](../advanced_config/parameter_reference.md#CAL_ACC0_PRIO)
- [CAL_GYROn_PRIO](../advanced_config/parameter_reference.md#CAL_GYRO0_PRIO)
- [CAL_MAGn_PRIO](../advanced_config/parameter_reference.md#CAL_MAG0_PRIO)
- [CAL_BAROn_PRIO](../advanced_config/parameter_reference.md#CAL_BARO0_PRIO)
where `n` corresponds to the index of the corresponding sensor.
::: tip
Sensors can be identified by their device id, which can be found by checking the parameters:
- [CAL_ACCn_ID](../advanced_config/parameter_reference.md#CAL_ACC0_ID)
- [CAL_GYROn_ID](../advanced_config/parameter_reference.md#CAL_GYRO0_ID)
- [CAL_MAGn_ID](../advanced_config/parameter_reference.md#CAL_MAG0_ID)
- [CAL_BAROn_ID](../advanced_config/parameter_reference.md#CAL_BARO0_ID)
:::
- To use the MicroStrain sensor as an external INS
1. Set [MS_MODE](../advanced_config/parameter_reference.md#MS_MODE) to 1
2. Disable EKF2 by setting [EKF2_EN](../advanced_config/parameter_reference.md#EKF2_EN) to 0
3. Reboot and start the driver
- `microstrain start -d <port>`
- To start the driver automatically when the flight controller powers on, set [SENS_MS_CFG](../advanced_config/parameter_reference.md#SENS_MS_CFG) to the sensor’s connected port.
## MicroStrain Configuration
1. Rates:
- By default, accel and gyro data are published at 500 Hz, magnetometer at 50 Hz, and barometric pressure at 50 Hz.
This can be changed by adjusting the following parameters:
- [MS_IMU_RATE_HZ](../advanced_config/parameter_reference.md#MS_IMU_RATE_HZ)
- [MS_MAG_RATE_HZ](../advanced_config/parameter_reference.md#MS_MAG_RATE_HZ)
- [MS_BARO_RATE_HZ](../advanced_config/parameter_reference.md#MS_BARO_RATE_HZ)
- Global position, local position, attitude and odometry will be published at 250 Hz by default.
This can be configured via:
- [MS_FILT_RATE_HZ](../advanced_config/parameter_reference.md#MS_FILT_RATE_HZ)
- For the CV7-GNSS/INS, the GNSS receiver 1 and 2 will publish data at 5Hz by default.
This can be changed using:
- [MS_GNSS_RATE_HZ](../advanced_config/parameter_reference.md#MS_GNSS_RATE_HZ)
- The driver will automatically configure data outputs based on the specific sensor model and available data streams.
- The driver is scheduled to run at twice the fastest configured data rate.
2. Aiding measurements:
- If supported, GNSS position and velocity aiding are always enabled.
- Internal/external magnetometer and heading aiding, as well as optical flow aiding, are disabled by default. They can be enabled using the following parameters:
- [MS_INT_MAG_EN](../advanced_config/parameter_reference.md#MS_INT_MAG_EN)
- [MS_INT_HEAD_EN](../advanced_config/parameter_reference.md#MS_INT_HEAD_EN)
- [MS_EXT_HEAD_EN](../advanced_config/parameter_reference.md#MS_EXT_HEAD_EN)
- [MS_EXT_MAG_EN](../advanced_config/parameter_reference.md#MS_EXT_MAG_EN)
- [MS_OPT_FLOW_EN](../advanced_config/parameter_reference.md#MS_OPT_FLOW_EN)
- The aiding frames for external sources can be configured using the following parameters:
- [MS_EHEAD_YAW](../advanced_config/parameter_reference.md#MS_EHEAD_YAW)
- [MS_EMAG_ROLL](../advanced_config/parameter_reference.md#MS_EMAG_ROLL)
- [MS_EMAG_PTCH](../advanced_config/parameter_reference.md#MS_EMAG_PTCH)
- [MS_EMAG_YAW](../advanced_config/parameter_reference.md#MS_EMAG_YAW)
- [MS_OFLW_OFF_X](../advanced_config/parameter_reference.md#MS_OFLW_OFF_X)
- [MS_OFLW_OFF_Y](../advanced_config/parameter_reference.md#MS_OFLW_OFF_Y)
- [MS_OFLW_OFF_Z](../advanced_config/parameter_reference.md#MS_OFLW_OFF_Z)
- [SENS_FLOW_ROT](../advanced_config/parameter_reference.md#SENS_FLOW_ROT)
- The uncertainty for optical flow and external magnetometer aiding must be specified using the following parameters:
- [MS_EMAG_UNCERT](../advanced_config/parameter_reference.md#MS_EMAG_UNCERT)
- [MS_OFLW_UNCERT](../advanced_config/parameter_reference.md#MS_OFLW_UNCERT)
::: tip
1. When optical flow aiding is enabled, the sensor uses the `vehicle_optical_flow_vel` output from the flight controller as a body-frame velocity aiding measurement.
2. If the MicroStrain sensor does not support these aiding sources but they are enabled, sensor initialization will fail.
:::
3. Initial heading alignment:
- Initial heading alignment is set to kinematic by default. This can be changed by adjusting
- [MS_ALIGNMENT](../advanced_config/parameter_reference.md#MS_ALIGNMENT)
4. GNSS Aiding Source Control (GNSS/INS only)
- The Source of the GNSS aiding data can be configured using:
- [MS_GNSS_AID_SRC](../advanced_config/parameter_reference.md#MS_GNSS_AID_SRC)
5. Sensor to vehicle transform:
- If the sensor is mounted in an orientation different from the vehicle frame. A sensor to vehicle transform can be enabled using
- [MS_SVT_EN](../advanced_config/parameter_reference.md#MS_SVT_EN)
- The transform is defined using the following parameters
- [MS_SENSOR_ROLL](../advanced_config/parameter_reference.md#MS_SENSOR_ROLL)
- [MS_SENSOR_PTCH](../advanced_config/parameter_reference.md#MS_SENSOR_PTCH)
- [MS_SENSOR_YAW](../advanced_config/parameter_reference.md#MS_SENSOR_YAW)
6. IMU ranges:
- The accelerometer and gyroscope ranges on the device are configurable using:
- [MS_ACCEL_RANGE](../advanced_config/parameter_reference.md#MS_ACCEL_RANGE)
- [MS_GYRO_RANGE](../advanced_config/parameter_reference.md#MS_GYRO_RANGE)
::: tip
Available range settings depend on the specific [sensor](https://www.hbkworld.com/en/products/transducers/inertial-sensors) and can be found in the corresponding user manual.
By default, the ranges are not changed.
:::
7. GNSS Lever arm offsets:
- The lever arm offset for the external GNSS receiver can be configured using:
- [MS_GNSS_OFF1_X](../advanced_config/parameter_reference.md#MS_GNSS_OFF1_X)
- [MS_GNSS_OFF1_Y](../advanced_config/parameter_reference.md#MS_GNSS_OFF1_Y)
- [MS_GNSS_OFF1_Z](../advanced_config/parameter_reference.md#MS_GNSS_OFF1_Z)
- For dual-antenna configurations, the second GNSS receiver’s offset is configured using:
- [MS_GNSS_OFF2_X](../advanced_config/parameter_reference.md#MS_GNSS_OFF2_X)
- [MS_GNSS_OFF2_Y](../advanced_config/parameter_reference.md#MS_GNSS_OFF2_Y)
- [MS_GNSS_OFF2_Z](../advanced_config/parameter_reference.md#MS_GNSS_OFF2_Z)
## Published Data
The MicroStrain driver continuously publishes sensor data to the following uORB topics:
- [sensor_accel](../msg_docs/SensorAccel.md)
- [sensor_gyro](../msg_docs/SensorGyro.md)
- [sensor_mag](../msg_docs/SensorMag.md)
- [sensor_baro](../msg_docs/SensorBaro.md)
For GNSS/INS devices, GPS data is also published to:
- [sensor_gnss](../msg_docs/SensorGnss.md)
If used as an external INS replacing EKF2, it publishes:
- [vehicle_global_position](../msg_docs/VehicleGlobalPosition.md)
- [vehicle_local_position](../msg_docs/VehicleLocalPosition.md)
- [vehicle_attitude](../msg_docs/VehicleAttitude.md)
- [vehicle_odometry](../msg_docs/VehicleOdometry.md)
otherwise the same data is published to the following topics
- `external_ins_global_position`
- `external_ins_attitude`
- `external_ins_local_position`
::: tip
Published topics can be viewed using the `listener` command.
:::