{"action":"created","issue":{"url":"https://api.github.com/repos/mavlink/qgroundcontrol/issues/2243","labels_url":"https://api.github.com/repos/mavlink/qgroundcontrol/issues/2243/labels{/name}","comments_url":"https://api.github.com/repos/mavlink/qgroundcontrol/issues/2243/comments","events_url":"https://api.github.com/repos/mavlink/qgroundcontrol/issues/2243/events","html_url":"https://github.com/mavlink/qgroundcontrol/issues/2243","id":117856164,"number":2243,"title":"Mission file format clarifications","user":{"login":"mairsbw","id":13241204,"avatar_url":"https://avatars.githubusercontent.com/u/13241204?v=3","gravatar_id":"","url":"https://api.github.com/users/mairsbw","html_url":"https://github.com/mairsbw","followers_url":"https://api.github.com/users/mairsbw/followers","following_url":"https://api.github.com/users/mairsbw/following{/other_user}","gists_url":"https://api.github.com/users/mairsbw/gists{/gist_id}","starred_url":"https://api.github.com/users/mairsbw/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mairsbw/subscriptions","organizations_url":"https://api.github.com/users/mairsbw/orgs","repos_url":"https://api.github.com/users/mairsbw/repos","events_url":"https://api.github.com/users/mairsbw/events{/privacy}","received_events_url":"https://api.github.com/users/mairsbw/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":18,"created_at":"2015-11-19T16:51:27Z","updated_at":"2015-11-20T17:20:29Z","closed_at":null,"body":"## Documenting the current version\r\nThe mission file format is woefully under described. Right now the only documentation is [here](http://qgroundcontrol.org/mavlink/waypoint_protocol#waypoint_file_format). This is not descriptive enough.\r\n\r\nI propose the following documentation:\r\n```\r\n - Whitespace-delimited file.\r\n - Carriage return/newline indicates the end of the line\r\n - Metadata on the first line (separated by a space): \"QGC\", \"WPL\", VERSION\r\n   - VERSION is the version * 100, currently 120\r\n - Following lines are tab-delimited and formatted in the same order as the fields for a MISSION_ITEM MAVLink message.\r\n   - Mission index, current waypoint, coordinate frame, command, param1, param2, param3, param4, param5/x/lon, param6/y/lat, param7/z/alt, autocontinue\r\n```\r\n\r\n## Documenting 1.1 & 1.0\r\nNow a question is what is the file format as specified in the 1.1 version, as MissionPlanner had been outputting that version string until recently (see discussion [here](https://github.com/diydrones/MissionPlanner/pull/1050#issuecomment-157954758)). I'm unsure as this code has been moved around so much I got 3 commits deep and then gave up. Was there a difference between the 1.2 version now and the 1.1 version?\r\n\r\n## Standardizing on a common file format\r\nAdditionally, I propose extending the file format (bumping it to 130) to account for the home location. This can be important to save during a mission, as it's normally used for at least the aircraft's recovery if not also the take-off location. This is already done by Mission Planner, and possibly other software.\r\n\r\nI suggest adding the home location as a \"-1\" index as the first mission listed and then the actual missions are listed from 0 to N. Mission Planner already outputs the first mission with a \"0\" index, so if there are a second 0-indexed mission, it should be interpreted as the \"first\" one and the previous one should be interpreted as the home location.\r\n\r\n## Handing version mismatches\r\nA big problem with this file is that versioning isn't specified in any real sense so programs aren't sure how strictly to check the file format. This was part of the reason for [MissionPlanner PR](https://github.com/diydrones/MissionPlanner/pull/1050). I'd like to clarify the meaning of the version string. I suggest that it should follow [semantic versioning](http://www.sitepoint.com/semantic-versioning-why-you-should-using/). Such that the major versions (first number) indicates a change to the format that will likely cause parsing to fail. The minor version (second digit) indicates that the semantic meaning of fields within the format has changed and it could be misinterpreted.\r\n\r\nNow with the version better defined, error checking should be:\r\n  * If the major version doesn't match, the user should be alerted that the file is incompatible and it shouldn't be imported given that previous version of this file format are not specified. Moving forward, as the file format becomes better specified, programs could implement parsing of older files as they see fit.\r\n  * If the minor version doesn't match, parsing will likely succeed, though the field values could be wrong during import. Therefore the user should be alerted, but could be allowed to proceed depending on how the program decides to handle this. I see a \"Ok\"/\"Cancel\" dialog here being useful for desktop applications to give the user this option.\r\n\r\n## References\r\n[Waypoint file format](http://qgroundcontrol.org/mavlink/waypoint_protocol#waypoint_file_format)\r\n[MissionPlanner file format PR](https://github.com/diydrones/MissionPlanner/pull/1050)"},"comment":{"url":"https://api.github.com/repos/mavlink/qgroundcontrol/issues/comments/158464724","html_url":"https://github.com/mavlink/qgroundcontrol/issues/2243#issuecomment-158464724","issue_url":"https://api.github.com/repos/mavlink/qgroundcontrol/issues/2243","id":158464724,"user":{"login":"billbonney","id":959994,"avatar_url":"https://avatars.githubusercontent.com/u/959994?v=3","gravatar_id":"","url":"https://api.github.com/users/billbonney","html_url":"https://github.com/billbonney","followers_url":"https://api.github.com/users/billbonney/followers","following_url":"https://api.github.com/users/billbonney/following{/other_user}","gists_url":"https://api.github.com/users/billbonney/gists{/gist_id}","starred_url":"https://api.github.com/users/billbonney/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/billbonney/subscriptions","organizations_url":"https://api.github.com/users/billbonney/orgs","repos_url":"https://api.github.com/users/billbonney/repos","events_url":"https://api.github.com/users/billbonney/events{/privacy}","received_events_url":"https://api.github.com/users/billbonney/received_events","type":"User","site_admin":false},"created_at":"2015-11-20T17:20:29Z","updated_at":"2015-11-20T17:20:29Z","body":"@LorenzMeier Maybe it's a idea to standardize on GeoJSON http://geojson.org as well\r\n\r\n@mairsbw I'm not saying we shouldn't drop the current tab delimited format, for now. It serves a purpose, but it quickly limited when you start do try and represent a more 'dynamic' type missions.  Specifying mission based on a line by line, procedural set of actions get rather large set of waypoints quickly \r\n\r\nFor example, it would be awesome to be able to save a mission, not as a set of waypoints, but descriptions of higher order actions. A good example is for mapping an area, if that is stored as a polygon shape, you can create the lawnmower pattern based on conditions the day you fly, like flying with the current wind direction, you may have changed cameras, so it can recalculate distance between passes for a desired overlap etc... \r\n\r\nAnother  example would be using a line string to plot a takeoff procedure. Or a line string for a path to inspect a Transmission Pylon, which is entered around a new current home point for each mission.\r\n\r\nThe lowest common denominator for a mission list would be a set of Mission-Items some with GeoPoints, some without.  \r\n"}}