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