| # Copyright 2022 Google LLC |
| # |
| # Licensed under the Apache License, Version 2.0 (the "License"); |
| # you may not use this file except in compliance with the License. |
| # You may obtain a copy of the License at |
| # |
| # https://www.apache.org/licenses/LICENSE-2.0 |
| # |
| # Unless required by applicable law or agreed to in writing, software |
| # distributed under the License is distributed on an "AS IS" BASIS, |
| # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| # See the License for the specific language governing permissions and |
| # limitations under the License. |
| |
| openapi: 3.0.0 |
| info: |
| description: | |
| Pica aims to be a platform agnostic UWB virtual controller. Pica should scale UWB testing since no hardware |
| is required and thus have a massive impact on testing afterwards. |
| version: "1.0.0" |
| title: Pica - A platform agnostic UWB virtual controller |
| contact: |
| name: Pica core team |
| email: pica-core@google.com |
| license: |
| name: Apache 2.0 |
| url: 'http://www.apache.org/licenses/LICENSE-2.0.html' |
| tags: |
| - name: Commands |
| description: sent to the scene to interact with Devices or get the current State of Pica. |
| |
| - name: Events |
| description: Events coming from Pica for the associated Device. |
| |
| components: |
| requestBodies: |
| PositionBodyRequired: |
| description: A JSON object containing Position information |
| required: true |
| content: |
| application/json: |
| schema: |
| $ref: '#/components/schemas/Position' |
| PositionBodyOptionnal: |
| description: A JSON object containing Position information |
| content: |
| application/json: |
| schema: |
| $ref: '#/components/schemas/Position' |
| schemas: |
| Device: |
| description: |
| A Device is a generic term representing an Anchor, noted `anchor`, |
| or an UCI Device as described in the Fira UCI Specification, noted `uci`. |
| type: object |
| properties: |
| category: |
| $ref: "#/components/schemas/Category" |
| mac_address: |
| $ref: "#/components/schemas/MacAddress" |
| position: |
| $ref: "#/components/schemas/Position" |
| Category: |
| description: Represents the device's category, uci or anchor. |
| type: string |
| enum: [uci, anchor] |
| MacAddress: |
| description: | |
| Valid UWB mac addresses must follow the above format |
| * Short Mode: "XX:XX" |
| * Extend Mode: "XX:XX:XX:XX:XX:XX:XX:XX" |
| where X is an hexadecimal number. |
| type: string |
| Position: |
| description: |
| The position includes the Cartesian coordinates in cm, and the yaw, pitch, roll angles in degrees. |
| type: object |
| properties: |
| x: |
| type: integer |
| description: x coordinate in cm |
| y: |
| type: integer |
| description: y coordinate in cm |
| z: |
| type: integer |
| description: z coordinate in cm |
| yaw: |
| type: integer |
| description: yaw in degrees |
| minimum: -180 |
| maximum: 180 |
| pitch: |
| type: integer |
| description: pitch in degrees |
| minimum: -90 |
| maximum: 90 |
| roll: |
| type: integer |
| description: roll in degrees |
| minimum: -180 |
| maximum: 180 |
| parameters: |
| MacAddress: |
| name: mac-address |
| in: path |
| description: | |
| Valid UWB mac addresses must follow the above format |
| * Short Mode: "XX:XX" |
| * Extend Mode: "XX:XX:XX:XX:XX:XX:XX:XX" |
| where X is an hexadecimal number. |
| required: true |
| schema: |
| type: string |
| paths: |
| /init-uci-device/{mac-address}: |
| post: |
| tags: [Commands] |
| summary: Init a new uwb subsystem and instantiate an UCI Device |
| description: |
| This command should be call by any host wishing to use Pica as an UWB Subsystem |
| and shall be called only once by UCI Device. |
| parameters: |
| - $ref: "#/components/parameters/MacAddress" |
| requestBody: |
| $ref: "#/components/requestBodies/PositionBodyOptionnal" |
| responses: |
| '200': { description: Success } |
| '403': { description: Device already initialized } |
| '500': { description: Internal error } |
| /set-position/{mac-address}: |
| post: |
| tags: [Commands] |
| summary: Set the position of a Device |
| description: | |
| Set the position of the Device for x, y, z, yaw, pitch and roll. Pica will trigger the |
| `neighbor-updated` event for every other device present in the scene closer that the maximum distance UINT16_MAX cm. |
| parameters: |
| - $ref: "#/components/parameters/MacAddress" |
| requestBody: |
| $ref: "#/components/requestBodies/PositionBodyRequired" |
| responses: |
| '200': { description: Success } |
| '404': { description: Device not found } |
| '500': { description: Internal error } |
| /create-anchor/{mac-address}: |
| post: |
| tags: [Commands] |
| summary: Create an anchor Device in the scene |
| description: |
| Create an anchor Device in the scene with a given MacAddress. If the position |
| is not specified then the anchor will be create at the origin of the |
| scene, [0,0,0,0,0,0] |
| parameters: |
| - $ref: "#/components/parameters/MacAddress" |
| requestBody: |
| $ref: "#/components/requestBodies/PositionBodyOptionnal" |
| responses: |
| '200': { description: Success } |
| '406': { description: Wrong argument } |
| '409': { description: Anchor already exist } |
| /destroy-anchor/{mac-address}: |
| delete: |
| tags: [Commands] |
| summary: Delete the anchor Device |
| description: |
| Delete the anchor Device from the scene |
| sessions |
| parameters: |
| - $ref: "#/components/parameters/MacAddress" |
| responses: |
| '200': { description: Success } |
| '404': { description: Anchor not found } |
| '500': { description: Internal error } |
| /get-state: |
| get: |
| tags: [Commands] |
| summary: Get state of Pica itself |
| description: |
| Get the state of Pica itself and return a list of connected |
| Devices |
| responses: |
| '200': |
| description: Success, return a list of Devices |
| content: |
| application/json: |
| schema: |
| type: array |
| items: |
| $ref: "#/components/schemas/Device" |
| '500': { description: Internal error } |
| /events: |
| get: |
| tags: [Events] |
| summary: Events from Pica |
| description: | |
| Events coming from Pica for the associated Device. |
| * device-added - Device added to the scene |
| * device-removed - Device deleted from the scene |
| * device-updated - Device position updated |
| * neighbor-updated - Neighbor position updated |
| |
| responses: |
| '200': |
| description: | |
| Represent an event source: https://developer.mozilla.org/en-US/docs/Web/API/EventSource |
| Pica triggers an event everytime a command is completed. |
| content: |
| text/event-stream: |
| schema: |
| type: array |
| format: event-stream |
| items: |
| oneOf: |
| - type: object |
| properties: |
| event: |
| const: device-added |
| description: Device added to the scene |
| data: |
| $ref: "#/components/schemas/Device" |
| - type: object |
| properties: |
| event: |
| const: device-removed |
| description: Device removed from the scene, the device's position is ignored |
| data: |
| type: object |
| properties: |
| category: |
| $ref: "#/components/schemas/Category" |
| mac_address: |
| $ref: "#/components/schemas/MacAddress" |
| - type: object |
| properties: |
| event: |
| const: device-updated |
| description: Device position updated |
| data: |
| $ref: "#/components/schemas/Device" |
| - type: object |
| properties: |
| event: |
| const: neighbor-updated |
| description: Neighbor device updated |
| data: |
| type: object |
| properties: |
| source_category: |
| $ref: "#/components/schemas/Category" |
| source_mac_address: |
| $ref: "#/components/schemas/MacAddress" |
| destination_category: |
| $ref: "#/components/schemas/Category" |
| destination_mac_address: |
| $ref: "#/components/schemas/MacAddress" |
| distance: |
| description: Distance in cm. |
| type: integer # u16 |
| minimum: 0 |
| maximum: 65535 |
| azimuth: |
| description: Azimuth in degrees |
| type: integer |
| minimum: -180 |
| maximum: 180 |
| elevation: |
| description: Elevation is degrees |
| type: integer |
| minimum: -90 |
| maximum: 90 |
| |
| |
| '500': { description: Internal error } |
