M2 Technical Reference 
¶
ROS2 Nodes¶
The M2 Reference Design includes the following nodes. Click on the item to expand its description.
Node: m2_supervisor_node
This node manages a number of MODAQ's core functionality, which include system logger, email alerts, and rate limiter (snoozer)
Package: m2_supervisor
Alias: M2Supervisor
Configuration Parameters: log file path, log file size limit, SMTP settings, distribution email lists (2x), analyzed topics, email snooze interval
Publishers: /system_messenger
Subscriptions: /system_messenger
Node: bag_recorder_node
Node description
Package: bag_recorder
Alias: N/A
Configuration Parameters: IP address
Publishers: /system_messenger
Subscriptions: /system_messenger, /ain, /do, /din, /rtd, /bag_control
Node: labjack_ain_reader
Reads up to 8 AI channels simultaneously from a single Labjack T8. This node uses a configurable timer to fetch (poll) channel reads from the T8.
Package: labjack_t8_ros2
Alias: LabjackAINSlow
Configuration Parameters: IP address, sample rate, topic name
Publishers: /system_messenger, /ain_slow
Subscriptions: none
Node: labjack_ain_streamer
Streams up to 8 AI channels from a single Labjack T8. This node sets the T8 to stream data continuously at rates up to 40 kHz. Channel reads are simultaneous. To better manage network resources for high speed streams, data transfers are batched by the ScansPerRead parameter.
Package: labjack_t8_ros22
Alias: LabjackAINFast
Configuration Parameters: IP address, sample rate, scans per read, topic name
Publishers: /system_messenger, /ain_fast
Subscriptions: none
Node: labjack_dac_writer
Controls one or more analog outputs on the T8. Output voltage can be adjusted between 0-10 VDC or ±10v with the LJTick-DAC
Package: labjack_t8_ros2
Alias: LabjackDAC
Configuration Parameters: IP address, channel selection, topic name
Publishers: /system_messenger
Subscriptions: /LJ_Ctl_Pub
Node: labjack_do_node
Switches one or more digital output (logic level) channels on the T8 high or low.
Package: labjack_t8_ros2
Alias: LabjackDO
Configuration Parameters: IP address, topic name
Publishers: /system_messenger
Subscriptions: /do
Node: labjack_dio_reader
Reads the logic state of one or more DIO channels.
Package: labjack_t8_ros2
Alias: LabjackDIN
Configuration Parameters: IP address, topic name
Publishers: /system_messenger, /din
Subscriptions: none
Node: adnav_driver
Manages configuration and initialization of the Advanced Navigation GNSS Compass and publishes its data.
Package: adnav_gnss_compass
Alias: AdnavCompass
Configuration Parameters: too many to list here
Publishers: /system_messenger, /nav
Subscriptions: none
Node: xsens_mti_node
Manages configuration and initialization of the Xsens MTi-G-710 and publishes its data. This is a 3rd party package cloned from here. This can work with other Xsens inertial sensors too.
Package: bluespace_ai_xsens_ros_mti_driver
Alias: XsensINS
Configuration Parameters: too many to list here
Publishers: /system_messenger, /imu/acceleration
Subscriptions: none
Node: ed582_driver
Reads up to four channels of RTD temperature measurements from a Brainbox ED-582. This is adapted from a 3rd party API available here.
Package: ed582
Alias: RTDed582
Configuration Parameters: IP address, sample rate, topic name
Publishers: /system_messenger, /rtd
Subscriptions: none
Node: m2_control
This node can read directives published by the HMI and/or incorporate control logic and publish actions for digital or analog output channels.
Package: m2_control
Alias: M2Control
Configuration Parameters: IP address, sample rate, topic name
Publishers: /system_messenger, /dac, /do
Subscriptions: /hmi_ctl
Node: rosbridge_websocket
This node creates a bridge between ROS2 and a websocket that is used to subscribe to and publish topics from a webpage using roslibjs. This is a lightly modified version of rosbridge_server from the rosbridge_suite github repo.
Package: rosbridge_server_m2
Alias: Rosbridge
Configuration Parameters: none
Publishers: /hmi_ctl
Subscriptions: /din, /ain_slow, /rtd
Real-Time¶
A real-time system is one that assures certain deadlines are met reliably within expected time constraints. See this Wikipedia article for a more complete definition.
Recommended Reading
This series of blog posts by Shuhao Wu is an excellent, easy to read distillation of numerous resources on real-time computing. This is highly recommended reading to provide context to some of the topics that will be discussed in this section.
Using a real-time architecture and approach in MODAQ allows better management of sources of latency and reduction of jitter. What this means in practical terms is that certain time-critical loops, processes, or functions can execute deterministically and that variation in timing of successive iterations is kept low.
Latency¶
Opening Task Manager in Windows or the equivalent in in other operating systems (OS), there may be hundreds of processes listed that are all vying for a slice of the CPU's time. These include things like device drivers, software updaters, user software, malware detectors, and lots of other things that comprise the modern computing experience. With fast, multi-core processors, these appear to be seamlessly juggled, usually with little delay apparent to the user. This is all managed by the scheduler and it tries to be fair as it doles out access to a CPU core. Under critical analysis, an application may have to wait a non-deterministic amount of time for that CPU attention- and that wait time might vary considerably for each request. This variation may be only a few milliseconds (or longer) but for DAQs running loops hundreds or several thousand times per second, that's an eternity.
A properly configured real-time stack offers the software developer some tools to better manage how the real-time code gets its CPU time by preempting lower priority processes (jumping to the head of the line). The end effect is that the real-time code should experience less of this source of latency.
Info
Determinism
A deterministic real-time system should complete a task within a bound time period in a consistent and repeatable manner.
Different real-time approaches yield better or worse maximum latency periods. Specific project requirements or use-cases often dictate the maximum acceptable latency for a particular application. This is most common for safety-critical systems, such as an anti-lock brake controller, where missing a deadline can result in disaster. These will often be associated with terms such as "guaranteed" or "hard" real-time. From a system architecture and software development standpoint, achieving this level of latency and determinism is difficult and probably not practical nor even necessary for a DAQ such as M2.
However, in the space between extremely low latency, safety-critical, real-time systems and general purpose operating systems without real-time support, there is Real-Time Linux. Or, more correctly, the PREEMPT_RT patch for Linux kernels.
Real-Time Linux¶
Linux with the PREEMPT_RT patch has been successfully used in various industries such as automotive, space, and industrial automation for years and by organizations including National Instruments, NASA, and SpaceX.12 This lends confidence that it's appropriate for M2 applications.
At the time of writing, it appears that the mainline Linux kernel is expected to gain real-time support3 in a coming release. Until that happens, it's necessary to manually compile the kernel with the PREEMPT_RT patch or find a distribution for an already patched RT kernel.
Validating RT Performance¶
Once patched kernel has been installed and the necessary changes to BIOS have been made, it's necessary to conduct some tests on the system to validate the 'as-built' latency performance.
A very useful tool for this is provided by intel: RTPM. This tool will evaluate the settings on your computer to ensure they are optimized for real-time performance. It also will conduct several tests that will characterize your real-time performance.
Precision Time Protocol¶
The promise of PTP is that all connected PTP-aware devices will be synchronized and reference-time accurate to 100's, if not 10's of nanoseconds- without drift. By comparison, Network Time Protocol (NTP), which is what most consumer computers and laptops use as a time reference, can at best achieve 10's of milliseconds accuracy. While NTP accuracy might be perfectly acceptable to some and often better than a real time clock (which can drift several seconds a day), it's a ~6 order of magnitude difference in accuracy as compared to PTP. If a quality time reference is not available, samples taken from input modules on the same DAQ controller will be disciplined by the same clock and will likely be precisely timestamped relative each other, but may not be accurate to actual time (i.e. UTC) .
Where the real power of PTP is realized is in synchronizing samples taken by disparate systems. These can be DAQs on the same subnet, sharing the same master clock or systems completely disconnected from each other and separated miles apart. As long as each system is disciplined to a healthy PTP reference clock, the samples will be synchronized to the aforementioned nanosecond time precision. This is a boon for distributed architectures and system design flexibility, allowing multi-controller synchronization without physical interconnections.
In our experience, PTP implementation either works magically or is a real bear. It does help to have some knowledge of networking and configuring managed switches. PTP requires the following for optimal performance:
- PTP time server
- PTP-capable endpoints (e.g. M2 controller, ethernet based devices)
- PTP services configured and running on the endpoints
- PTP-capable network switch
These items need to be properly configured, otherwise the PTP performance may be degraded or non-existent.
ADCs¶
Coming soon...
4-20 mA Current Loops¶
Coming soon...
Heading¶
Getting a reliable estimate of heading on a fixed or semi-stationary device can be tricky. Devices that rely on Earth's magnetic field need to be calibrated in-situ and have the proper magnetic declination correction applied.
Since a calibration procedure generally requires rotating the sensor 360° in one or more axis, this is often difficult or near impossible once the sensor is mounted on the device (WEC, buoy, etc). It's easier to calibrate the compass prior to installation, however this is not effective, since the magnetic field will most likely be distorted by the presence of hard and soft iron sources near the mounting location.