Runtime Operation
Contents
Run the novatel_oem7_driver
The following sections illustrate how to launch and use the novatel_oem7_driver by Hexagon | NovAtel® for use with your OEM7® type GNSS or SPAN® sensor.
Setting Driver Network Protocol and Port
When connecting to your receiver over a network, you will need to make sure the OEM7 receiver's IP address and intended ICOM port are correctly configured in novatel_oem7_driver.
The protocol (TCP or UDP) and port numbers used can be configured by editing the file named oem7_net.launch. When using novatel_oem7_driver via binary package installation, the template for this file is located at the location:
/opt/ros/{$ROS_DISTRO}/share/novatel_oem7_driver/launch/oem7_net.launchFor example, Melodic users would therefore find this template file at:
/opt/ros/melodic/share/novatel_oem7_driver/launch/oem7_net.launch
Users may copy this template to a project directory, edit it and then run it with roslaunch. To change the default TCP port that novatel_oem7_driver is configured to use, edit the default value of the oem7_port argument in your copy of the oem7_net.launch file.
Alternatively, users may launch by referring to the template launch file and then overriding parameters (like the IP address) as needed.
Operation over TCP/IP
Assumptions:
- OEM7 Receiver is reachable over IP networking at 192.168.1.10
- OEM7 Receiver's internal ICOM ports are configured for access over TCP (default)
Here is the corresponding example of running the novatel_oem7_driver with roslaunch, by overriding the default parameters in the template oem7_net.launch file:
roslaunch novatel_oem7_driver oem7_net.launch oem7_ip_addr:=192.168.1.10
Suppose that you wanted to also override the default port specified in the oem7_net.launch file to instead be 3005, then you could run:
roslaunch novatel_oem7_driver oem7_net.launch oem7_ip_addr:=192.168.1.10 oem7_port:=3005
Suppose you copied the template oem7_net.launch file to /path/to/my_novatel_oem7_net.launch. You could then edit the contents of this file with whatever parameters you like and then launch it with roslaunch by running:
roslaunch /path/to/my_novatel_oem7_net.launch
Operation over UDP/IP
Configure OEM7 ICOM Port(s) for UDP
OEM7 receivers default to TCP-based network communication (on hardware models with networking support). You can reconfigure your OEM7 receiver to have some or all internal ICOM ports instead accessible via UDP ports. For this, you will have to manually connect to your receiver and configure it with the ICOMCONFIG command, followed by the SAVECONFIG command.
For example, the internal port ICOM2 could be reconfigured to be reachable on the receiver via UDP port number 3002 as follows:
ICOMCONFIG ICOM2 UDP ":3002" SAVECONFIG
For more details about the ICOMCONFIG command, please refer to our OEM7 documentation portal, here:
https://docs.novatel.com/OEM7/Content/Commands/ICOMCONFIG.htm
The ICOM Communications documentation is also relevant and is available here:
https://docs.novatel.com/OEM7/Content/Operation/ICOM_Communications.htm
Run novatel_oem7_driver with UDP profile
Assuming your receiver is reachable at UDP port 3002 at IP address 192.168.1.10, you can then connect novatel_oem7_driver with the roslaunch command:
roslaunch novatel_oem7_driver oem7_net.launch oem7_if:=Oem7ReceiverUdp oem7_ip_addr:=192.168.1.10 oem7_port:=3002
Operation over USB
novatel_oem7_driver can be used to communicate with your OEM7 receiver directly over a serial port or a virtual serial port (connected via USB to your receiver). You must make sure your computer can reach the OEM7 receiver at the given port, or novatel_oem7_driver won't be able to connect.
Newer Linux Kernels will show your OEM7 receiver when connected over USB (visible via the 'lsusb' command). Older systems need to be configured to know to connect your OEM7 receiver to the common 'usbserial' kernel module.
Note that on Ubuntu Linux systems, for a user account to use a serial device, the account must be a member of the 'dialout' user group.
If you do not see your NovAtel receiver listed by 'lsusb' when USB connected and powered-on, then you must configure your Linux system to attach the USB device to the 'usbserial' kernel module.
Suppose that your receiver is connected via USB, then, when properly configured the receiver will enumerate under /dev/ttyUSB*, such as /dev/ttyUSB0. novatel_oem7_driver could be launched with:
roslaunch novatel_oem7_driver oem7_tty.launch oem7_tty_name:=/dev/ttyUSB0
Note that OEM7 receivers connected via USB do not need the baud rate set.
Optional: Persistent USB driver configuration with usbserial via udev
1. Create a new udev rules file, such as: /etc/udev/rules.d/z90_novatel.rules
2. Paste the following contents in to your new udev rules file:
SUBSYSTEM=="usb", SYSFS{idProduct}=="0100", SYSFS{idVendor}=="09d7",
PROGRAM="/sbin/modprobe usbserial vendor=0x09d7 product=0x0100"
BUS=="usb", SYSFS{idProduct}=="0100", SYSFS{idVendor}=="09d7",
SYSFS{product}=="NovAtel GPS Receiver", SYSFS{manufacturer}=="NovAtel Inc.", SYMLINK+="gps%n" 3. Reboot your system (or restart the necessary services for the changes to take full effect).
Optional: Temporary USB driver configuration with usbserial
You can use the following line at the command line to temporarily instruct the Linux USB serial kernel module to drive your OEM7 device:
echo '09d7 0100' > /sys/bus/usb-serial/drivers/generic/new_id
Optional: Legacy USB Driver
Legacy systems may try the NovAtel Linux USB driver. This should not be necessary due to Linux's usbserial kernel module. You can download the installer for this driver here: https://novatel.com/support/support-materials/usb-drivers
Operation over Serial
novatel_oem7_driver can be used to communicate with your OEM7 receiver directly over a serial port. You must make sure your computer can reach the OEM7 receiver at the given port, or novatel_oem7_driver won't be able to connect.
Note that on Ubuntu Linux systems, for a user account to use a serial device, the account must be a member of the 'dialout' user group.
For serial connections, you can optionally set the baud rate such as to 115200, using the argument oem7_tty_baud:=115200
This baud rate must correspond to your receiver's internal COM port configuration. To manually change the connection parameters of a COM port within your OEM7 receiver, please refer to the Serial Port Communications documentation in the OEM7 Documentation Portal, here:
https://docs.novatel.com/OEM7/Content/Operation/Serial_Port_Communications.htm
Runtime OEM7 Reconfiguration
The driver implements ROS Service /novatel_oem7_driver/receivers/main/Oem7Cmd. This service allows the user to send OEM7 Abbreviated ASCII commands from the terminal to the receiver using the "rosservice" tool.
Oem7Cmd syntax
rosservice call /novatel/oem7/receivers/main/Oem7Cmd "$oem7_abbreviated_ascii_command"
Oem7Cmd example
rosservice call /novatel/oem7/receivers/main/Oem7Cmd "LOG BESTPOSB ONTIME 0.1" rsp: "OK"
Note that the OEM7 response is printed out verbatim. This is to notify the user if the command was accepted or if there was an error. All standard OEM7 abbreviated ASCII commands are supported. The commands are executed as-is, the syntax is not modified. Oem7Cmd does not support binary or ASCII command input.
OEM7 Abbreviated ASCII commands are commands that resemble:
LOG [optional: internal port] [log name] [trigger+interval][CR]
For example:
LOG ICOM1 BESTPOSA ONTIME 1[CR]
For more information regarding the available OEM7 commands your receiver can handle, please refer to the OEM7 Documentation Portal, here:
https://docs.novatel.com/OEM7/Content/Commands/Command_Reference.htm
Recording data to a ROS bag
Configuring OEM7 Logs in ROS bag
novatel_oem7_driver requests NovAtel OEM7 logs as part of normal operation. Logs specified in the std_oem7_raw_msgs.yaml file are recorded in ROS under the /novatel/oem7/oem7raw topic.
Record a ROS bag
novatel_oem7_driver does not automatically record the ROS bag. The user must choose to record the bag as required for the application. This can be done using the rosbag command-line tool and the record command.
Recording the bag is required if NovAtel OEM7 logs are needed for troubleshooting or post-processing.
For instance, to record all topics with rosbag, for later filtering and processing, run:
rosbag record -a
Filter a ROS bag for post-processing
To post-process OEM7 data from a ROS bag, it may be necessary to filter out the /novatel/oem7/oem7raw topic if there is a lot of other data in the bag. This can be done using the rosbag command-line tool with the filter command.
The rosbag command can inspect any ROS bag (such as a bag named my.bag) to see a list of the topics published in the bag by running:
rosbag info my.bag
Once you know the name of the topic to filter, such as /novatel/oem7/oem7raw, you can filter the data with:
rosbag filter my.bag only-novatel.bag "topic == '/novatel/oem7/oem7raw'"
ROS bags (.bag files) containing the /novatel/oem7/oem7raw topic can be loaded into NovAtel Convert to convert the data into ASCII, KML, RINEX. ROS bags can also be loaded into Inertial Explorer® for post-processing.
Viewing live ROS topic data
You may wish to observe data published in a ROS topic at runtime. You can use the rostopic command for this.
To see available topics, you can run:
rostopic list
Here are some typical novatel_oem7_topics this command returns when you have the novatel_oem7_driver installed:
/novatel/oem7/bestpos /novatel/oem7/bestutm /novatel/oem7/bestvel /novatel/oem7/corrimu /novatel/oem7/driver/bond /novatel/oem7/heading2 /novatel/oem7/insconfig /novatel/oem7/inspva /novatel/oem7/inspvax /novatel/oem7/insstdev /novatel/oem7/oem7raw /novatel/oem7/rxstatus /novatel/oem7/time
The novatel_oem7_driver also contributes data to:
/gps/fix /gps/gps /gps/imu
Suppose you wanted to then observe bestpos messages, you could run:
rostopic echo novatel/oem7/bestpos
Position Quality Indicators
The /novatel/oem7/bestpos topic may be observed at runtime to observe some key indicators of position quality.
Below is an example /novatel/oem7/bestpos record that will be referred to for the rest of this documentation section:
header:
seq: 2603
stamp:
secs: 1598887658
nsecs: 580854223
frame_id: "gps"
nov_header:
message_name: "BESTPOS"
message_id: 42
message_type: 0
sequence_number: 0
time_status: 180
gps_week_number: 2121
gps_week_milliseconds: 142076500
sol_status:
status: 0
pos_type:
type: 69
lat: 51.1503897563
lon: -114.030699187
hgt: 1097.37025877
undulation: -17.0
datum_id: 61
lat_stdev: 0.017622647807
lon_stdev: 0.0169686395675
hgt_stdev: 0.0348801650107
stn_id: "TSTR"
diff_age: 16.5
sol_age: 0.0
num_svs: 39
num_sol_svs: 31
num_sol_l1_svs: 31
num_sol_multi_svs: 25
reserved: 0
ext_sol_stat:
status: 128
galileo_beidou_sig_mask: 53
gps_glonass_sig_mask: 51Note that these records are populated using the OEM7 BESTPOS log data from your receiver. The firmware documentation for this log type is available here:
https://docs.novatel.com/OEM7/Content/Logs/BESTPOS.htm
Latitude, Longitude, Height Standard Deviations
... lat_stdev: 0.017622647807 lon_stdev: 0.0169686395675 hgt_stdev: 0.0348801650107 ...
The BESTPOS standard deviations (lat_stdev, lon_stdev, hgt_stdev) give a good sense of the quality of the position solution. These are computed separately, in meters, for latitude, longitude and height. In the above example, they are: 0.017622647807m, 0.0169686395675m, 0.0348801650107m
Number of Satellites Tracked
... num_sol_svs: 31 ...
The num_sol_svs gives the number of GNSS satellites tracked that are used in the position solution. In the above example, this was 31 SVs.
Position Type
... pos_type: type: 69 ...
The Position Type (pos_type) reported indicates the method of positioning being reported through the BESTPOS log. BESTPOS selects the position type with the best real-time performance for your receiver model and environment. In the above example, this was type 69. There is a table of position types that lists the type IDs and their corresponding names, available here:
https://docs.novatel.com/OEM7/Content/Logs/BESTPOS.htm?Highlight=bestpos#Position_VelocityType
In this example, the position type was PPP.
Solution Status
... sol_status: status: 0 ...
Use the Solution Status (sol_status) field to check the BESTPOS log's solution status. In this example, the status was 0, which corresponds to the status SOL_COMPUTED. Here's a direct link to the table of solution status ID's and their names:
https://docs.novatel.com/OEM7/Content/Logs/BESTPOS.htm?Highlight=bestpos#SolutionStatus
Time Status
... time_status: 180 ...
The time_status field gives the GPS solution's time status which is also a key status indicator. In the above example, the status was 180, this corresponds to a healthy status of FINESTEERING.
Here's the table of status IDs and their names:
https://docs.novatel.com/OEM7/Content/Messages/GPS_Reference_Time_Statu.htm
Return to the novatel_oem7_driver page for next steps