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 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 }