im200 Payload Autonomy Interface for Heron USVs Fall 2017 Alon Yaari, ayaari@mit.edu Michael Benjamin, mikerb@mit.edu Department of Mechanical Engineering, CSAIL MIT, Cambridge MA 02139 1 im200 Payload Autonomy Interface for Heron USVs 1 2 Using the im200 Application 1 2.1 Thrust Modes............................................. 1 2.2 Vehicle Position............................................ 2 2.3 Magnetic Variation.......................................... 2 2.4 The XY Grid............................................. 2 3 Configuration Parameters for im200 3 3.1 An Example MOOS Configuration Block.............................. 4 4 Publications and Subscriptions for im200 4 4.1 Variables Published by im200.................................... 5 4.2 Variables Subscribed for by im200................................. 5 1 im200 Payload Autonomy Interface for Heron USVs The im200 application is a driver that interfaces a MOOS community to the Clearpath Robotics Heron M300 vehicle. The onboard front-seat computer manages vehicle actuation per received instructions. Using a documented wire protocol, thrust commands from an outside entity are published to the front-seat via an IP port on its wireless Ethernet interface. The vehicle returns data from onboard navigation sensors and limited health status. The im200 application converts DESIRED * from the MOOS community into Clearpath protocol motor commands and pushes instructions to the vehicle. Regular position details received from the front-seat are parsed and published to the MOOS community as NAV * variables, along with an occasional battery voltage message. 2 Using the im200 Application 2.1 Thrust Modes As the M200 vehicle has two thrusters, one on each pontoon. Forward movement and turning is under differential-thrust control. To transit straight-ahead, thrust both motors equally, to turn toward the right, thrust only the left-side motor, and so on. Typically, the output of MOOS-IvP navigation decisions is desired rudder and thrust. Therefore, im200 has two thrust modes: 1
Rudder-thrust. In this mode, DESIRED THRUST and DESIRED RUDDER MOOS messages are the input to im200. They are translated into percent thrust and pushed to the vehicle for actuation. This is the default mode of im200 and requires no special parameters in the mission file to enact it. Direct-thrust. This mode is a pass-through, allowing another MOOS application to send exact thrust percentages to each thruster. DESIRED THRUST L and DESIRED THRUST R messages are the input to im200. Values are pushed to the vehicle for actuation. Direct-thrust mode is enacted when the direct thrust parameter is set to true in the mission file. 2.2 Vehicle Position The Clearpath controller in the M200 front-seat receives sentences from the GPS, digital compass, and IMU. A filter estimates pose and position, packages data into the wire protocol format, then pushes the data over the IP interface. The im200 application receives the 5Hz updates, parses incoming position data, then publishes the following messages: message name [prefix] X [prefix] Y [prefix] LAT [prefix] LON [prefix] SPEED [prefix] HEADING Description X-position on the local grid (based on current lat-lon) Y-position on the local grid (based on current lat-lon) Latitude, as reported by the Clearpath controller Longitude, as reported by the Clearpath controller Speed over ground, as reported by the Clearpath controller Heading,as reported by the Clearpath controller Each message name is preceded by [prefix], a string value set in the GPS PREFIX mission file parameter. By default, the prefix is NAV, making im200 the source of NAV * variables removing the need for a dedicated GPS or digital compass interface MOOS module. 2.3 Magnetic Variation The front-seat s estimation filter takes into account magnetic variation, the difference between true and magnetic north at the compass reading location. In the unlikely event that the offset is incorrect or in certain specific situations (e.g., taking readings from M200 while it is on the deck of a moving boat), the reported heading can be adjusted using the heading offset parameter. 2.4 The XY Grid The NAV X and NAV Y variables are transformations of latitude and longitude fixes provided by the M200 s integrated GPS. X,Y positions are referenced in number of meters from a 0,0 origin location as defined in the mission file. Historically, MOOS has used two different methods to convert geographic positions into X,Y, the MOOS Grid and UTM-based Grid. Note that in both cases, 0,0 will always be the origin specified in the mission file and the X,Y is a report of position in meters away from the origin in meters. MOOS Grid. Historically, the core MOOSGeodesy library included the concept of a local tangent plane centered about the origin. Angular distance of any position fix is converted using simple 2
trigonometry based on WGS84 spheroid approximations of the earth. Surface curvature is negligible within a 300 square kilometer area centered on the origin. UTM-based Grid. MOOSGeodesy has also included the option of transforming positions to X,Y using the Universal Transverse Mercator (UTM) projection. A concise description of UTM is provided by the USGS: http://pubs.usgs.gov/fs/2001/0077/report.pdf. Working with UTMbased transformations provides multiple benefits, including a larger area of accurate gird positions, compatibility to positioning systems outside of MOOS, and reliance on the dedicated proj.4 conversion code base instead of static historical functions. Which grid to use? Those without historical reasons to do so should use UTM-based X,Y transformations. Besides the benefits listed above, UTM-based Grid is the default for applications like pmarineviewer. MOOS Grid conversions are appropriate for those who must remain compatible with historical X,Y positions originally calculated using MOOS Grid. 3 Configuration Parameters for im200 The im200 application may be configured with a configuration block within a MOOS mission file, typically with a.moos file suffix. The following parameters are defined for im200: Listing 3.1: Configuration Parameters for im200. ip address: The IPv4 address of the M200 front-seat computer that is being interfaced with. Default value is localhost, which implies that the im200 application is being run on the front-seat vehicle itself. port number: At the defined ip address, this is the port number to communicate with the vehicle. gps prefix: This string is inserted at the start of X, Y, heading, and speed publications. Default is nav. The underscore will be added if not supplied in the mission file. direct thrust: When true, im200 is in direct-thrust mode. When false or if this parameter is omitted, im200 operates in rudder-thrust mode. See 2.1 for more details. heading offset: Degrees offset added to the published heading. Value can be negative. Default is 0.0. See 2.1 for more details. publish raw: The Clearpath controller publishes updates to im200 using NMEA sentences as defined in the formal wire protocol. When true, all sentences are published under the MOOS message M200 RAW NMEA, while still being processed normally by im200. No raw messages are published with false or if this parameter is omitted. max rudder: DESIRED RUDDER will be constrained to this value (+ or ) when converted to thrust values for the front-seat. Value must be a real number greater than 0.0 and less than 180.0. Default value is 50.0. max thrust: DESIRED THRUST will be constrained to this value when converted to thrust values for the front-seat. Value must be a real number greater than 0.0 and less than or equal to 100.0. Default value is 100.0. 3
publish thrust: xy source: When true, im200 publishes M200 THRUST L and M200 THRUST R MOOS messages whenever a thrust command is sent to the vehicle. Method for converting latitude and longitude position fixes into X,Y positions on the local grid. See?? for more details. Valid values are UTM (default) and GRID. If unsure, use the default value. 3.1 An Example MOOS Configuration Block An example MOOS configuration block is provided in Listing 2 below. This can also be obtained from a terminal window with: $ im200 --example or -e Listing 3.2: Example configuration of the im200 application. 1 ============================================================================ 2 im200 Example MOOS Configuration 3 ============================================================================ 4 5 ProcessConfig = im200 6 { 7 AppTick = 10 8 CommsTick = 10 9 10 PORT_NUMBER = 29500 11 IP_ADDRESS = localhost // Default is localhost 12 GPS_PREFIX = NAV_ // Prepended to GPS position messages. 13 DIRECT_THRUST = false // Default is false. 14 // When true, vehicle is in direct-thrust mode. 15 // When false, vehicle is in rudder-thrust mode. 16 HEADING_OFFSET = 0.0 // Offset to add to published heading 17 PUBLISH_RAW = false // When true, publish all messages from 18 // front seat to M200_RAW_NMEA 19 MAX_RUDDER = 50.0 // Rudder value will be capped to this, +/- 20 MAX_THRUST = 100.0 // Thrust value to each motor will be 21 // capped to this value, +/- 22 PUBLISH_THRUST = false // When true, publishes M200_THRUST_L and _R 23 } 4 Publications and Subscriptions for im200 The interface for im200, in terms of publications and subscriptions, is described below. This same information may also be obtained from the terminal with: $ im200 --interface or -i 4
4.1 Variables Published by im200 APPCAST: Contains an appcast report identical to the terminal output. Reports are posted only in response to an appcast request messages. [prefix] X: Last reported X position of the vehicle, in meters east or west of the MOOS origin. [prefix] Y: Last reported Y position of the vehicle, in meters north or south of the MOOS origin. [prefix] LAT: Last reported latitude of the vehicle, in decimal degrees. [prefix] LON: Last reported longitude of the vehicle, in decimal degrees. [prefix] SPEED: Last reported vehicle speed over ground, in meters per second. [prefix] HEADING: Last reported vehicle heading, in degrees clockwise from true north. Will be offset by heading offset, if defined. M200 BATTERY VOLTAGE: Last reported battery voltage, in volts. M200 RAW NMEA: If publish raw=true, all incoming Clearpath wire protocol messages will be published to this MOOS message. Note that im200 will continue to process messages when publishing raw. M200 THRUST L: Published at the time a thrust command is sent to the vehicle, if mission parameter publish thrust=true Value is the actual percent thrust requested at the left thruster. M200 THRUST R: Published at the time a thrust command is sent to the vehicle, if mission parameter publish thrust=true Value is the actual percent thrust requested at the right thruster. 4.2 Variables Subscribed for by im200 The im200 always subscribes for appcasting events: APPCAST REQ: A request to generate and post a new apppcast report, with reporting criteria, and expiration. When in direct thrust mode, im200 listens for commands to be sent directly to the motors: DESIRED THRUST L: Push this percent thrust value to the vehicle for commanding the left thruster. Constrained by im200 to 100.0and100.0. DESIRED THRUST R: Push this percent thrust value to the vehicle for commanding the right thruster. Constrained by im200 between 100.0and100.0. When in Ruddder thrust mode, im200 listens for commands to be sent directly to the motors: DESIRED THRUST: Percent thrust requested of the vehicle. When combined with the DESIRED RUDDER value, is used to calculate percent thrust for each motor. Constrained by im200 between the value set in mission file parameter max thrust and 0 the value. DESIRED RUDDER: Notional rudder angle requested of the vehicle. When combined with the DESIRED THRUST value, is used to calculate percent thrust for each motor. Constrained by im200 to between the value set in mission file parameter max rudder and 0.0 the value. 5