1[![Crate](https://img.shields.io/crates/v/pica?style=flat-square)](https://crates.io/crates/pica)
2[![Build workflow](https://img.shields.io/github/actions/workflow/status/google/pica/build.yml?style=flat-square)](https://github.com/google/pica/actions/workflows/build_and_test.yml?query=branch%3Amain)
3
4# Pica
5
6Pica is a virtual UWB Controller implementing the FiRa UCI specification.
7It has been designed for testing UWB ranging capabilities.
8Pica supports the following features:
9
10- Pica keeps an internal representation of a 3-D scene.
11- Pica lets multiple clients connect through TCP sockets.
12  Each new connection spawns an attached UWB subsystem. Connected hosts can
13  interact together as if they existed in a single 3-D scene.
14- Pica implements a nice GUI through a web server.
15- Pica provides HTTP commands to interact with the scene directly such as create and destroy
16  virtual anchors.
17
18# Build and Run
19
20```bash
21$> git clone https://github.com/google/pica.git
22$> cd pica/
23$> cargo run
24```
25
26You should receive the following output:
27
28```
29Pica: Listening on: 7000
30Pica: Web server started on http://0.0.0.0:3000
31```
32
33You can now open the web interface at `http://0.0.0.0:3000` and the HTTP commands documentation
34at `http://0.0.0.0:3000/openapi`. The scene should be empty and look like this:
35
36![Pica empty scene](./res/empty_scene.png)
37
38# Command line
39
40A command line tool is available to trigger some action such as creating an anchor.
41Run pica in a terminal then open a new one and do:
42```
43$> cd pica/
44$> python3 scripts/console.py
45```
46
47If you hit `Enter`, the console will list you all the available commands:
48```
49device_reset                    Reset the UWBS.
50get_device_info                 Retrieve the device information like (UCI version and other vendor specific info).
51get_caps_info                   Get the capability of the UWBS.
52session_init                    Initialize the session
53session_deinit                  Deinitialize the session
54session_set_app_config          set APP Configuration Parameters for the requested UWB session.
55session_get_app_config          retrieve the current APP Configuration Parameters of the requested UWB session.
56session_get_count               Retrieve number of UWB sessions in the UWBS.
57session_get_state               Query the current state of the UWB session.
58range_start                     start a UWB session.
59range_stop                      Stop a UWB session.
60get_ranging_count               Get the number of times ranging has been attempted during the ranging session..
61pica_create_anchor              Create a Pica anchor
62pica_destroy_anchor             Destroy a Pica anchor
63pica_get_state                  Return the internal Pica state
64pica_init_uci_device            Initialize an uci device
65pica_set_position               Set the position of a Device
66```
67
68If you wish to create a virtual anchor:
69
70```bash
71$> cd pica/ && python3 scripts/console.py # If the console is not started yet
72$> --> pica_create_anchor 00:00 # pica_create_anchor <mac_address>
73$> --> pica_create_anchor 00:01 # Create another one
74```
75# Architecture
76
77- *Device* UWB subsystem created for a connected host.
78- *Session* UWB ranging session opened by a connected host.
79- *Anchor* virtual UWB host, responding to ranging requests from
80  connected hosts.
81
82```
83                 ┌────────────────────┐
84                 │ Web                │
85                 │                    │
86                 └─────┬─────────▲────┘
87                       │         │    HTTP localhost:3000
88  ┌────────────────────▼─────────┴───────┐
89  │                                      │
90  │                 Pica                 │
91  │                                      │
92  │  ┌────────┐  ┌────────┐  ┌────────┐  │
93  │  │Anchor1 │  │Device1 │  │Device2 │  │
94  │  ├────────┤  │        │  │        │  │
95  │  │Anchor2 │  ├────────┤  ├────────┤  │
96  │  ├────────┤  │Session1│  │Session1│  │
97  │  │...     │  ├────────┤  ├────────┤  │
98  │  │        │  │Session2│  │Session2│  │
99  │  └────────┘  └──▲──┬──┘  └──▲──┬──┘  │
100  │                 │  │        │  │     │
101  └─────────────────┼──┼────────┼──┼─────┘
102                    │  │        │  │  TCP localhost:7000
103                 ┌──┴──▼──┐  ┌──┴──▼──┐
104                 │Client1 │  │Client2 │
105                 │        │  │        │
106                 ├────────┤  ├────────┤
107                 │VirtIO  │  │        │
108                 ├────────┤  │        │
109                 │UWB HAL │  │        │
110                 ├────────┤  │Python  │
111                 │Cuttle  │  │console │
112                 │fish    │  │        │
113                 └────────┘  └────────┘
114```
115
116# Http commands
117
118Pica also implements HTTP commands, the documentation is available at `http://0.0.0.0:3000/openapi`.
119The set of HTTP commands let the user interact with Pica amd modify its scene.
120
121# Tests
122
123Setup your python env:
124
125```bash
126python3 -m venv venv
127source venv/bin/activate
128pip install pytest
129pip install pytest_asyncio
130pip install -e py/pica/
131```
132
133Then run the tests
134
135```bash
136pytest --log-cli-level=DEBUG -v
137```
138
139The tests are located in `./tests/`
140