= Configuration of novatel_oem7_driver =
<<TableOfContents(2)>>
----
== Configuration Files ==
The [[novatel_oem7_driver]] configuration can be altered through yaml files referenced by the `.launch` files.
=== OEM7 Receiver configuration via std_init_commands.yaml ===
The novatel_oem7_driver by Hexagon | NovAtel® generates ROS messages from multiple !NovAtel OEM7® logs. OEM7 logs are formatted in an open log format that is heavily documented at the !NovAtel Documentation Portal available here:
https://docs.novatel.com/OEM7/Content/Logs/Log_Reference.htm
The list of !NovAtel commands and log requests sent to the OEM7 receiver upon ROS driver startup are contained in the `std_init_commands.yaml` file.
Some of the included log commands are required for proper ROS driver operation. The logs that are needed for the novatel_oem7_driver to function are categorized under a ‘do not remove these messages’ header. The user may choose to add additional NovAtel configuration commands or log requests if they are customizing the driver.
The path to the template `std_init_commands.yaml` file from the binary installation is:
{{{
/opt/ros/${ROS_DISTRO}/share/novatel_oem7_driver/config/std_init_commands.yaml
}}}
=== OEM7 Logging Configuration via std_oem7_raw_msgs.yaml ===
`std_oem7_raw_msgs.yaml` configures OEM7 logs that will be logged as binary blobs for post-processing in to the `/novatel/oem7/oem7raw` ROS topic. These logs can used for troubleshooting the OEM7 receiver and can be provided to NovAtel Customer Support if support is required.
`std_oem7_raw_msgs.yaml` is typically a subset of the list of the logs requested in `std_init_commands.yaml`.
The path to the template `std_oem7_raw_msgs.yaml` file from the binary installation is:
{{{
/opt/ros/${ROS_DISTRO}/share/novatel_oem7_driver/config/std_oem7_raw_msgs.yaml
}}}
=== OEM7 log names and IDs registered in oem7_msgs.yaml ===
Typically, this does not need modification, unless you are optimizing the driver and have revised the `std_init_commands.yaml` file.
`oem7_msgs.yaml` lists the OEM7 log names along with the corresponding binary ID’s. The binary ID for each log can be found in the OEM7 manual. It is necessary for each listed log name and binary ID pair to be correct. Messages not in this list will be ignored by novatel_oem7_driver.
The template `oem7_msgs.yaml` file from the binary installation is located at:
{{{
/opt/ros/${ROS_DISTRO}/share/novatel_oem7_driver/config/oem7_msgs.yaml
}}}
=== Driver Plugins std_driver_config.xml and std_msg_handlers.yaml ===
The novatel_oem7_driver for ROS contains two plugins to be loaded. There is no need to modify these unless you are developing your own plugins or optimizing driver footprint.
When installed via the binary release, the templates for these two plugins are located at:
{{{
/opt/ros/${ROS_DISTRO}/share/novatel_oem7_driver/config/std_driver_config.xml
/opt/ros/${ROS_DISTRO}/share/novatel_oem7_driver/config/std_msg_handlers.yaml
}}}
----
== Customizing Logging Configuration ==
The user may edit the driver's configuration files to customize their OEM7 receiver's configuration upon ROS start up.
This will impact what is reported to the ROS topic: `/novatel/oem7/oem7raw`
=== SPAN Lever Arm and Rotation Example ===
For this example, suppose the user wanted to add novatel_oem7_driver start up commands to configure the SPAN lever arm and rotation: <<BR>>
* [[https://docs.novatel.com/OEM7/Content/SPAN_Commands/SETINSTRANSLATION.htm|SETINSTRANSLATION ANT1]]
* [[https://docs.novatel.com/OEM7/Content/SPAN_Commands/SETINSROTATION.htm|SETINSROTATION RBV]]
Then, suppose the user wanted to rotate the system's output to a frame other than the receiver default (such as the [[https://www.ros.org/reps/rep-0105.html|REP105]] standard): <<BR>>
* [[https://docs.novatel.com/OEM7/Content/SPAN_Commands/SETINSROTATION.htm|SETINSROTATION USER]]
And, further suppose the user wanted to add additional log requests: <<BR>>
* [[https://docs.novatel.com/OEM7/Content/Logs/MARKxTIME.htm|MARK1TIME]]
* [[https://docs.novatel.com/OEM7/Content/Logs/MARKxPOS.htm|MARKPOS]]
The following modifications would be necessary.
==== std_init_commands.yaml - receiver_init_commands ====
Edit `std_init_commands.yaml` to include the SETINSTRANSLATION and SETINSROTATION OEM7 commands. The `receiver_init_commands` section would appear as follows:
{{{
...
receiver_init_commands:
#------------------------------------------------------------------------------
# Reset logging
- "UNLOGALL THISPORT"
- "SETINSTRANSLATION ANT1 1 2 3 0.05 0.05 0.05"
- "SETINSROTATION RBV 0 90 180 3 3 3"
#- "!PAUSE 10"
#- "SETINSPROFILE LAND"
#- "SETINSTRANSLATION ANT1 <x> <y> <z> <std. x> <std. y> <std. z>
#- ... etc.
#-----------------------------------------------------------------------------
...
}}}
Above the added lines were:
* `- "SETINSTRANSLATION ANT1 1 2 3 0.05 0.05 0.05"`
* `- "SETINSROTATION RBV 0 90 180 3 3 3"`
==== Changing Output Reference Frame ====
There is often motivation to output attitude measurements in some other frame than the [[https://docs.novatel.com/OEM7/Content/SPAN_Operation/Definition_Reference_Frames.htm|vehicle frame defined by NovAtel]], X-right, Y-forward, Z-up.
As an example, the vehicle frame defined in [[https://www.ros.org/reps/rep-0105.html|REP105]] is X-forward, Y-left, Z-up and this output frame may be required to work with other sensors in ROS.
The USER argument can be used with both the [[https://docs.novatel.com/OEM7/Content/SPAN_Commands/SETINSTRANSLATION.htm|SETINSTRANSLATION]] and [[https://docs.novatel.com/OEM7/Content/SPAN_Commands/SETINSROTATION.htm|SETINSROTATION]] commands to output the inertial attitude in whatever frame the end-user desires.
The SETINSROTATION USER command rotates from the IMU body frame to the user output frame. As an example, suppose the IMU is sitting in the vehicle with its coordinate frame aligned with the vehicle frame defined by NovAtel: X-right, Y-forward, Z-up. To rotate the inertial output frame from this orientation to X-forward, Y-left, Z-up, edit the `receiver_init_commands` section of the `std_init_commands.yaml` file as follows:
{{{
...
receiver_init_commands:
#------------------------------------------------------------------------------
# Reset logging
- "UNLOGALL THISPORT"
- "SETINSTRANSLATION ANT1 1 2 3 0.05 0.05 0.05"
- "SETINSROTATION RBV 0 90 180 3 3 3"
- "SETINSROTATION USER 0 0 90"
#- "!PAUSE 10"
#- "SETINSPROFILE LAND"
#- "SETINSTRANSLATION ANT1 <x> <y> <z> <std. x> <std. y> <std. z>
#- ... etc.
#-----------------------------------------------------------------------------
...
}}}
Above the added line was:
* `- "SETINSROTATION USER 0 0 90"`
which would rotate the frame 90 degrees right-handed positively about the Z-axis. The USER frame now aligns with the frame defined by REP105, X-forward, Y-left, Z-up.
==== std_init_commands.yaml - End of File ====
Add the additional logs to the end of `std_init_commands.yaml`, under the "Post-Processing Messages" text:
{{{
# Post-Processing Messages; not directly used to generate ROS messages.
- "LOG RAWIMUSXB ONNEW"
- "LOG INSUPDATESTATUSB ONNEW"
- "LOG RAWEPHEMB ONNEW"
- "LOG GLOEPHEMERISB ONNEW"
- "LOG BDSEPHEMERISB ONNEW"
- "LOG GALFNAVEPHEMERISB ONNEW"
- "LOG GALINAVEPHEMERISB ONNEW"
- "LOG RANGEB ONTIME 1"
- "LOG MARK1TIMEB ONNEW"
- "LOG MARKPOSB ONNEW"
}}}
Note that the added lines were:
* `- "LOG MARK1TIMEB ONNEW"`
* `- "LOG MARKPOSB ONNEW"`
==== oem7_msgs.yaml ====
Edit the `oem7_msgs.yaml` to add the new log names as well as the binary ID’s. Refer to the OEM7 manual to obtain the binary ID’s:
Add the additional message names below under the ‘More messages may be added...’ comment:
{{{
# Standard messages - Do not remove.
BESTPOS: 42
BESTVEL: 99
BESTUTM: 726
...
RXSTATUS: 93
INSUPDATESTATUS: 1825
INSCONFIG: 1945
PSRDOP2: 1163
# More messages may be added in order to process Oem7 'raw' messages.
MARK1TIME: 1130
MARKPOS: 181
}}}
==== std_oem7_raw_msgs.yaml ====
Edit the `std_oem7_raw_msgs.yaml` to add the new log requests to have them included in the /novatel/oem7/oem7raw ROS topic:
Append the new log names to the end of the file:
{{{
oem7_raw_msgs:
- BESTPOS
- BESTVEL
- INSPVAX
- INSUPDATESTATUS
- RAWIMUSX
- RAWEPHEM
- GLOEPHEMERIS
- BDSEPHEMERIS
- GALFNAVEPHEMERIS
- GALINAVEPHEMERIS
- RANGE
- HEADING2
- TIME
- RXSTATUS
- INSCONFIG
- MARK1TIME
- MARKPOS
}}}
----
== Correction Services ==
=== TerraStar, Oceanix and VERIPOS Correction Services Overview ===
!NovAtel OEM7 receivers can use !NovAtel Correction Services to receive PPP corrections. This can improve your real-time position accuracy to as fine as 2.5cm RMS (via !TerraStar-X™).
<<BR>>
!NovAtel offers correction services for different applications:
|| '''Correction Service''' || '''Application Types''' ||
|| !TerraStar™ || Various applications including precision agriculture, survey, automotive and aerial. ||
|| Oceanix || Marine applications including dredging, hydrographic survey and mapping. ||
|| VERIPOS || Offshore Oil and Gas ||
<<BR>>
=== Correction Service Activation ===
To use !NovAtel Correction Services with novatel_oem7_driver, you must:
* Have a receiver model that supports corrections
* Have an active subscription for your receiver's serial number (PSN)
* Have configured your receiver appropriately
<<BR>>
To purchase a subscription, please contact your !NovAtel Sales representative. To request a temporary, test subscription, please contact !NovAtel Customer Support: <<BR>>
[[https://docs.novatel.com/OEM7/Content/Front_Matter/Customer_Support.htm]]
----
== OEM7 Firmware & Model Considerations ==
=== OEM7 Firmware for ROS ===
To use the novatel_oem7_driver for ROS with an OEM7 receiver, make sure you are running a current OEM7 firmware for your specific hardware. To update your OEM7 firmware, go to the !NovAtel support site, locate your OEM7 hardware and follow the update instructions.
''' SPAN®-enabled receivers '''<<BR>>
[[https://novatel.com/support/span-gnss-inertial-navigation-systems|novatel.com/support/span-gnss-inertial-navigation-systems]]
''' Smart Antennas '''<<BR>>
[[https://novatel.com/support/smart-antennas|novatel.com/support/smart-antennas]]
''' GNSS Receivers (Non-SPAN) '''<<BR>>
[[https://novatel.com/support/high-precision-gnss-gps-receivers|novatel.com/support/high-precision-gnss-gps-receivers]]
If you require assistance, you may contact !NovAtel Customer Support. Please be sure to include a text copy and paste of your OEM7 receiver's output to the command:
{{{
LOG VERSION
}}}
You may contact !NovAtel Customer Support here:<<BR>>
[[https://docs.novatel.com/OEM7/Content/Front_Matter/Customer_Support.htm]]
=== OEM7 Models ===
!NovAtel receivers are able to run a range of functions which are determined by what the paid model of each OEM7 receiver. It is possible to purchase upgrades to your model once you have your OEM7 hardware. ROS users may consider this to add functionality such as:
* Extra GNSS constellation support (To add Glonass, Galileo, Beidou, etc)
* Add PPP/RTK correction support
* Add SPAN support (sensor fusion positioning such as to integrate an IMU)
To view the latest models please view (note the table on the last page): <<BR>>
[[https://novatel.com/products/model-list-and-discontinued-products]]
To purchase a model upgrade, please contact your !NovAtel Sales representative. To request a temporary model upgrade, please contact !NovAtel Customer Support: <<BR>>
[[https://docs.novatel.com/OEM7/Content/Front_Matter/Customer_Support.htm]]
----
Return to the [[novatel_oem7_driver]] page for next steps