code/network-generator/network_generation/model/yang/ietf-geo-location@2022-02-11.yang

   1 module ietf-geo-location {
   2   yang-version 1.1;
   3   namespace "urn:ietf:params:xml:ns:yang:ietf-geo-location";
   4   prefix geo;
   5   import ietf-yang-types {
   6     prefix yang;
   7     reference "RFC 6991: Common YANG Data Types";
   8   }
   9
  10   organization
  11     "IETF NETMOD Working Group (NETMOD)";
  12   contact
  13    "WG Web:   <https://datatracker.ietf.org/wg/netmod/>
  14     WG List:  <mailto:netmod@ietf.org>
  15
  16     Editor:   Christian Hopps
  17               <mailto:chopps@chopps.org>";
  18
  19   description
  20     "This module defines a grouping of a container object for
  21      specifying a location on or around an astronomical object (e.g.,
  22      'earth').
  23
  24      The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL
  25      NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED',
  26      'MAY', and 'OPTIONAL' in this document are to be interpreted as
  27      described in BCP 14 (RFC 2119) (RFC 8174) when, and only when,
  28      they appear in all capitals, as shown here.
  29
  30      Copyright (c) 2022 IETF Trust and the persons identified as
  31      authors of the code.  All rights reserved.
  32
  33      Redistribution and use in source and binary forms,
  34      with or without modification, is permitted pursuant to,
  35      and subject to the license terms contained in, the
  36      Revised BSD License set forth in Section 4.c of the
  37      IETF Trust's Legal Provisions Relating to IETF Documents
  38      (https://trustee.ietf.org/license-info).
  39
  40      This version of this YANG module is part of RFC 9179
  41      (https://www.rfc-editor.org/info/rfc9179); see the RFC itself
  42      for full legal notices.";
  43
  44   revision 2022-02-11 {
  45     description
  46       "Initial Revision";
  47     reference
  48       "RFC 9179: A YANG Grouping for Geographic Locations";
  49   }
  50
  51   feature alternate-systems {
  52     description
  53       "This feature means the device supports specifying locations
  54        using alternate systems for reference frames.";
  55   }
  56
  57   grouping geo-location {
  58     description
  59       "Grouping to identify a location on an astronomical object.";
  60
  61     container geo-location {
  62       description
  63         "A location on an astronomical body (e.g., 'earth')
  64          somewhere in a universe.";
  65
  66       container reference-frame {
  67         description
  68           "The Frame of Reference for the location values.";
  69
  70         leaf alternate-system {
  71           if-feature "alternate-systems";
  72           type string;
  73           description
  74             "The system in which the astronomical body and
  75              geodetic-datum is defined.  Normally, this value is not
  76              present and the system is the natural universe; however,
  77              when present, this value allows for specifying alternate
  78              systems (e.g., virtual realities).  An alternate-system
  79              modifies the definition (but not the type) of the other
  80              values in the reference frame.";
  81         }
  82         leaf astronomical-body {
  83           type string {
  84             pattern '[ -@\[-\^_-~]*';
  85           }
  86           default "earth";
  87           description
  88             "An astronomical body as named by the International
  89              Astronomical Union (IAU) or according to the alternate
  90              system if specified.  Examples include 'sun' (our star),
  91              'earth' (our planet), 'moon' (our moon), 'enceladus' (a
  92              moon of Saturn), 'ceres' (an asteroid), and
  93              '67p/churyumov-gerasimenko (a comet).  The ASCII value
  94              SHOULD have uppercase converted to lowercase and not
  95              include control characters (i.e., values 32..64, and
  96              91..126).  Any preceding 'the' in the name SHOULD NOT be
  97              included.";
  98           reference
  99             "https://www.iau.org/";
 100         }
 101         container geodetic-system {
 102           description
 103             "The geodetic system of the location data.";
 104           leaf geodetic-datum {
 105             type string {
 106               pattern '[ -@\[-\^_-~]*';
 107             }
 108             description
 109               "A geodetic-datum defining the meaning of latitude,
 110                longitude, and height.  The default when the
 111                astronomical body is 'earth' is 'wgs-84', which is
 112                used by the Global Positioning System (GPS).  The
 113                ASCII value SHOULD have uppercase converted to
 114                lowercase and not include control characters
 115                (i.e., values 32..64, and 91..126).  The IANA registry
 116                further restricts the value by converting all spaces
 117                (' ') to dashes ('-').
 118                The specification for the geodetic-datum indicates
 119                how accurately it models the astronomical body in
 120                question, both for the 'horizontal'
 121                latitude/longitude coordinates and for height
 122                coordinates.";
 123             reference
 124               "RFC 9179: A YANG Grouping for Geographic Locations,
 125                Section 6.1";
 126           }
 127           leaf coord-accuracy {
 128             type decimal64 {
 129               fraction-digits 6;
 130             }
 131             description
 132               "The accuracy of the latitude/longitude pair for
 133                ellipsoidal coordinates, or the X, Y, and Z components
 134                for Cartesian coordinates.  When coord-accuracy is
 135                specified, it indicates how precisely the coordinates
 136                in the associated list of locations have been
 137                determined with respect to the coordinate system
 138                defined by the geodetic-datum.  For example, there
 139                might be uncertainty due to measurement error if an
 140                experimental measurement was made to determine each
 141                location.";
 142           }
 143           leaf height-accuracy {
 144             type decimal64 {
 145               fraction-digits 6;
 146             }
 147             units "meters";
 148             description
 149               "The accuracy of the height value for ellipsoidal
 150                coordinates; this value is not used with Cartesian
 151                coordinates.  When height-accuracy is specified, it
 152                indicates how precisely the heights in the
 153                associated list of locations have been determined
 154                with respect to the coordinate system defined by the
 155                geodetic-datum.  For example, there might be
 156                uncertainty due to measurement error if an
 157                experimental measurement was made to determine each
 158                location.";
 159           }
 160         }
 161       }
 162       choice location {
 163         description
 164           "The location data either in latitude/longitude or
 165            Cartesian values";
 166         case ellipsoid {
 167           leaf latitude {
 168             type decimal64 {
 169               fraction-digits 16;
 170             }
 171             units "decimal degrees";
 172             description
 173               "The latitude value on the astronomical body.  The
 174                definition and precision of this measurement is
 175                indicated by the reference-frame.";
 176           }
 177           leaf longitude {
 178             type decimal64 {
 179               fraction-digits 16;
 180             }
 181             units "decimal degrees";
 182             description
 183               "The longitude value on the astronomical body.  The
 184                definition and precision of this measurement is
 185                indicated by the reference-frame.";
 186           }
 187           leaf height {
 188             type decimal64 {
 189               fraction-digits 6;
 190             }
 191             units "meters";
 192             description
 193               "Height from a reference 0 value.  The precision and
 194                '0' value is defined by the reference-frame.";
 195           }
 196         }
 197         case cartesian {
 198           leaf x {
 199             type decimal64 {
 200               fraction-digits 6;
 201             }
 202             units "meters";
 203             description
 204               "The X value as defined by the reference-frame.";
 205           }
 206           leaf y {
 207             type decimal64 {
 208               fraction-digits 6;
 209             }
 210             units "meters";
 211             description
 212               "The Y value as defined by the reference-frame.";
 213           }
 214           leaf z {
 215             type decimal64 {
 216               fraction-digits 6;
 217             }
 218             units "meters";
 219             description
 220               "The Z value as defined by the reference-frame.";
 221           }
 222         }
 223       }
 224       container velocity {
 225         description
 226           "If the object is in motion, the velocity vector describes
 227            this motion at the time given by the timestamp.  For a
 228            formula to convert these values to speed and heading, see
 229            RFC 9179.";
 230         reference
 231           "RFC 9179: A YANG Grouping for Geographic Locations";
 232
 233         leaf v-north {
 234           type decimal64 {
 235             fraction-digits 12;
 236           }
 237           units "meters per second";
 238           description
 239             "v-north is the rate of change (i.e., speed) towards
 240              true north as defined by the geodetic-system.";
 241         }
 242
 243         leaf v-east {
 244           type decimal64 {
 245             fraction-digits 12;
 246           }
 247           units "meters per second";
 248           description
 249             "v-east is the rate of change (i.e., speed) perpendicular
 250              to the right of true north as defined by
 251              the geodetic-system.";
 252         }
 253
 254         leaf v-up {
 255           type decimal64 {
 256             fraction-digits 12;
 257           }
 258           units "meters per second";
 259           description
 260             "v-up is the rate of change (i.e., speed) away from the
 261              center of mass.";
 262         }
 263       }
 264       leaf timestamp {
 265         type yang:date-and-time;
 266         description
 267           "Reference time when location was recorded.";
 268       }
 269       leaf valid-until {
 270         type yang:date-and-time;
 271         description
 272           "The timestamp for which this geo-location is valid until.
 273            If unspecified, the geo-location has no specific
 274            expiration time.";
 275       }
 276     }
 277   }
 278 }