275 lines
9.9 KiB
YAML
275 lines
9.9 KiB
YAML
# 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 }
|