src/devtools/example-api-gps.yml

   1 %YAML 1.3
   2 ---
   3 afbidl: "0.1"
   4
   5 info:
   6   apiname: gps
   7   title: Service for geolocation
   8   description:
   9         GPS service reports current WGS84 coordinates from GNSS devices
  10         via the gpsd application.
  11   version: "0.1"
  12   author: AGL
  13   maintainer: Scott Rifenbark
  14   homepage: https://doc.automotivelinux.org/...
  15
  16 tools:
  17
  18     afb-genskel:
  19         scope: static
  20         prefix: req_
  21         postfix: _cb
  22         init: init_gps
  23
  24     doc:
  25         id: gps-api
  26         keywords: gps
  27         author:
  28         version:
  29         src_prefix: api-gps
  30         chapters:
  31         - name: Abstract
  32           url: abstract.md
  33         - name: User Guide
  34           url: userguide.md
  35
  36 verbs:
  37
  38     subscribe:
  39         description: subscribe to gps/gnss events
  40         request: $/schemas/subscription-desc
  41         reply:
  42             success:
  43                 schema: $/schemas/none
  44                 set-state:
  45                     listening: yes
  46
  47     unsubscribe:
  48         description: unsubscribe to gps/gnss events
  49         request: $/schemas/subscription-desc
  50         reply:
  51             success:
  52                 schema: $/schemas/none
  53                 set-state:
  54                     listening: no
  55
  56     location:
  57         description: get current gps/gnss coordinates
  58         request: $/schemas/none
  59         reply:
  60             success: $/schemas/location
  61             _: An error can be returned when the service isn't ready
  62
  63     record:
  64         description: |
  65             Entering *record* mode you must send **{"state": "on"}** with the **record**
  66             verb which will have a JSON response of **{"filename": "gps_YYYYMMDD_hhmm.log"}**
  67             pointing to log under *app-data/agl-service-gps*
  68
  69             Now to enter *replaying* mode you must symlink or copy a GPS dump to
  70             *app-data/agl-service-gps/recording.log* and restart the service.
  71             From then on out the previously recorded GPS data will loop infinitely
  72             which is useful for testing or demonstration purposes.
  73         request: $/schemas/record/request
  74         reply:
  75             success:
  76                 schema: $/schemas/record/reply
  77                 set-state:
  78                     recording: yes
  79             _: An error can be returned when the service isn't ready
  80
  81 events:
  82     location:
  83         schema: $/schemas/location
  84         when-state:
  85             listening: yes
  86
  87 state-machines:
  88     listening:
  89         states: [ no, yes ]
  90         initial: no
  91     recording:
  92         states: [ no, yes ]
  93         initial: no
  94
  95 # Follow JsonSchema specification (https://json-schema.org/)
  96 schemas:
  97     subscription-desc:
  98         title: Description of the event subscribed or unsubscribed
  99         type: object
 100         properties:
 101             value: { enum: [ location ] }
 102         required: [ value ]
 103
 104     location:
 105         title: the location
 106         type: object
 107         properties:
 108             altitude:
 109                 title: the altitude in meters above the normal geoide
 110                 type: number
 111                 minimum: -20000
 112                 maximum: 20000
 113             latitude:
 114                 title: the latitude in degrees
 115                 type: number
 116                 minimum: -90
 117                 maximum: 90
 118             longitude:
 119                 title: the longitude in degrees
 120                 type: number
 121                 minimum: -180
 122                 maximum: 180
 123             speed:
 124                 title: the speed in meter per seconds m/s
 125                 type: number
 126                 minimum: 0
 127                 maximum: 6000
 128             track:
 129                 title: the heading in degrees
 130                 type: number
 131                 minimum: 0
 132                 maximum: 360
 133             timestamp:
 134                 title: time stamp of the location as a ISO8601 date
 135                 type: string #ISO8601
 136                 pattern: \d{4,}-[01][0-9]-[0-3][0-9]T[012][0-9]:[0-5][0-9]:[0-5][0-9].*
 137
 138     record:
 139         request:
 140             type: object
 141             properties:
 142                 state: { const: "on" }
 143             required: [ state ]
 144
 145         reply:
 146             type: object
 147             properties:
 148                 filename:
 149                     title: the name of the file that records the data of format gps_YYYYMMDD_hhmm.log
 150                     type: string
 151                     pattern: gps_\d{4}\d{2}\d{2}_\d{2}\d{2}.log
 152             required: [ filename ]
 153
 154     none:
 155         title: no value, just null
 156         const: null