1# Copyright 2022 Google LLC 2# 3# Licensed under the Apache License, Version 2.0 (the "License"); 4# you may not use this file except in compliance with the License. 5# You may obtain a copy of the License at 6# 7# https://www.apache.org/licenses/LICENSE-2.0 8# 9# Unless required by applicable law or agreed to in writing, software 10# distributed under the License is distributed on an "AS IS" BASIS, 11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12# See the License for the specific language governing permissions and 13# limitations under the License. 14 15openapi: 3.0.0 16info: 17 description: | 18 Pica aims to be a platform agnostic UWB virtual controller. Pica should scale UWB testing since no hardware 19 is required and thus have a massive impact on testing afterwards. 20 version: "1.0.0" 21 title: Pica - A platform agnostic UWB virtual controller 22 contact: 23 name: Pica core team 24 email: [email protected] 25 license: 26 name: Apache 2.0 27 url: 'http://www.apache.org/licenses/LICENSE-2.0.html' 28tags: 29 - name: Commands 30 description: sent to the scene to interact with Devices or get the current State of Pica. 31 32 - name: Events 33 description: Events coming from Pica for the associated Device. 34 35components: 36 requestBodies: 37 PositionBodyRequired: 38 description: A JSON object containing Position information 39 required: true 40 content: 41 application/json: 42 schema: 43 $ref: '#/components/schemas/Position' 44 PositionBodyOptionnal: 45 description: A JSON object containing Position information 46 content: 47 application/json: 48 schema: 49 $ref: '#/components/schemas/Position' 50 schemas: 51 Device: 52 description: 53 A Device is a generic term representing an Anchor, noted `anchor`, 54 or an UCI Device as described in the Fira UCI Specification, noted `uci`. 55 type: object 56 properties: 57 category: 58 $ref: "#/components/schemas/Category" 59 mac_address: 60 $ref: "#/components/schemas/MacAddress" 61 position: 62 $ref: "#/components/schemas/Position" 63 Category: 64 description: Represents the device's category, uci or anchor. 65 type: string 66 enum: [uci, anchor] 67 MacAddress: 68 description: | 69 Valid UWB mac addresses must follow the above format 70 * Short Mode: "XX:XX" 71 * Extend Mode: "XX:XX:XX:XX:XX:XX:XX:XX" 72 where X is an hexadecimal number. 73 type: string 74 Position: 75 description: 76 The position includes the Cartesian coordinates in cm, and the yaw, pitch, roll angles in degrees. 77 type: object 78 properties: 79 x: 80 type: integer 81 description: x coordinate in cm 82 y: 83 type: integer 84 description: y coordinate in cm 85 z: 86 type: integer 87 description: z coordinate in cm 88 yaw: 89 type: integer 90 description: yaw in degrees 91 minimum: -180 92 maximum: 180 93 pitch: 94 type: integer 95 description: pitch in degrees 96 minimum: -90 97 maximum: 90 98 roll: 99 type: integer 100 description: roll in degrees 101 minimum: -180 102 maximum: 180 103 parameters: 104 MacAddress: 105 name: mac-address 106 in: path 107 description: | 108 Valid UWB mac addresses must follow the above format 109 * Short Mode: "XX:XX" 110 * Extend Mode: "XX:XX:XX:XX:XX:XX:XX:XX" 111 where X is an hexadecimal number. 112 required: true 113 schema: 114 type: string 115paths: 116 /init-uci-device/{mac-address}: 117 post: 118 tags: [Commands] 119 summary: Init a new uwb subsystem and instantiate an UCI Device 120 description: 121 This command should be call by any host wishing to use Pica as an UWB Subsystem 122 and shall be called only once by UCI Device. 123 parameters: 124 - $ref: "#/components/parameters/MacAddress" 125 requestBody: 126 $ref: "#/components/requestBodies/PositionBodyOptionnal" 127 responses: 128 '200': { description: Success } 129 '403': { description: Device already initialized } 130 '500': { description: Internal error } 131 /set-position/{mac-address}: 132 post: 133 tags: [Commands] 134 summary: Set the position of a Device 135 description: | 136 Set the position of the Device for x, y, z, yaw, pitch and roll. Pica will trigger the 137 `neighbor-updated` event for every other device present in the scene closer that the maximum distance UINT16_MAX cm. 138 parameters: 139 - $ref: "#/components/parameters/MacAddress" 140 requestBody: 141 $ref: "#/components/requestBodies/PositionBodyRequired" 142 responses: 143 '200': { description: Success } 144 '404': { description: Device not found } 145 '500': { description: Internal error } 146 /create-anchor/{mac-address}: 147 post: 148 tags: [Commands] 149 summary: Create an anchor Device in the scene 150 description: 151 Create an anchor Device in the scene with a given MacAddress. If the position 152 is not specified then the anchor will be create at the origin of the 153 scene, [0,0,0,0,0,0] 154 parameters: 155 - $ref: "#/components/parameters/MacAddress" 156 requestBody: 157 $ref: "#/components/requestBodies/PositionBodyOptionnal" 158 responses: 159 '200': { description: Success } 160 '406': { description: Wrong argument } 161 '409': { description: Anchor already exist } 162 /destroy-anchor/{mac-address}: 163 delete: 164 tags: [Commands] 165 summary: Delete the anchor Device 166 description: 167 Delete the anchor Device from the scene 168 sessions 169 parameters: 170 - $ref: "#/components/parameters/MacAddress" 171 responses: 172 '200': { description: Success } 173 '404': { description: Anchor not found } 174 '500': { description: Internal error } 175 /get-state: 176 get: 177 tags: [Commands] 178 summary: Get state of Pica itself 179 description: 180 Get the state of Pica itself and return a list of connected 181 Devices 182 responses: 183 '200': 184 description: Success, return a list of Devices 185 content: 186 application/json: 187 schema: 188 type: array 189 items: 190 $ref: "#/components/schemas/Device" 191 '500': { description: Internal error } 192 /events: 193 get: 194 tags: [Events] 195 summary: Events from Pica 196 description: | 197 Events coming from Pica for the associated Device. 198 * device-added - Device added to the scene 199 * device-removed - Device deleted from the scene 200 * device-updated - Device position updated 201 * neighbor-updated - Neighbor position updated 202 203 responses: 204 '200': 205 description: | 206 Represent an event source: https://developer.mozilla.org/en-US/docs/Web/API/EventSource 207 Pica triggers an event everytime a command is completed. 208 content: 209 text/event-stream: 210 schema: 211 type: array 212 format: event-stream 213 items: 214 oneOf: 215 - type: object 216 properties: 217 event: 218 const: device-added 219 description: Device added to the scene 220 data: 221 $ref: "#/components/schemas/Device" 222 - type: object 223 properties: 224 event: 225 const: device-removed 226 description: Device removed from the scene, the device's position is ignored 227 data: 228 type: object 229 properties: 230 category: 231 $ref: "#/components/schemas/Category" 232 mac_address: 233 $ref: "#/components/schemas/MacAddress" 234 - type: object 235 properties: 236 event: 237 const: device-updated 238 description: Device position updated 239 data: 240 $ref: "#/components/schemas/Device" 241 - type: object 242 properties: 243 event: 244 const: neighbor-updated 245 description: Neighbor device updated 246 data: 247 type: object 248 properties: 249 source_category: 250 $ref: "#/components/schemas/Category" 251 source_mac_address: 252 $ref: "#/components/schemas/MacAddress" 253 destination_category: 254 $ref: "#/components/schemas/Category" 255 destination_mac_address: 256 $ref: "#/components/schemas/MacAddress" 257 distance: 258 description: Distance in cm. 259 type: integer # u16 260 minimum: 0 261 maximum: 65535 262 azimuth: 263 description: Azimuth in degrees 264 type: integer 265 minimum: -180 266 maximum: 180 267 elevation: 268 description: Elevation is degrees 269 type: integer 270 minimum: -90 271 maximum: 90 272 273 274 '500': { description: Internal error } 275