doc: Add usage doc

Signed-off-by: Sylvain Munaut <tnt@246tNt.com>
This commit is contained in:
Sylvain Munaut 2018-12-17 14:16:07 +01:00
parent 2c6a5e0409
commit e7f24e144c
1 changed files with 138 additions and 0 deletions

138
doc/usage.md Normal file
View File

@ -0,0 +1,138 @@
osmo-rfds usage
===============
Flashing image
--------------
Refer to the [official documentation](https://wiki.analog.com/university/tools/pluto/users/firmware).
In short, you can mount the pluto as a mass storage device, copy the
`pluto.frm` file into it at the root, then umount and eject the device.
The led should start blinking quickly, incicating the flash is in progress.
Do **NOT** disconnect the pluto from power while this is in progress.
Wait for it to stop blinking quickly and the new image should be ready to use.
Connect to the pluto
--------------------
Refer to official analog wiki for full details but here are the cliff notes:
* Console:
* `minicom -D /dev/ttyACM0`
* Network :
* `ip link set enp0s20u3 up`
* `ip addr add 192.168.2.2/24 dev enp0s20u3`
* (replace `enp0s20u3` with whatever name the CDC ECM device was assigned on your machine)
* `ssh root@192.168.2.1`
* Credentials: root / analog
Running `osmo-rfds`
-------------------
Once connected, the `osmo-rfds` binary can be used to control the loopback.
```
# osmo-rfds -h
osmo-rfds [options]
-t, --tx-freq
-r, --rx-freq
-T, --tx-gain
-R, --rx-gain
-s, --samplerate
-c, --buffer-count
-b, --buffer-size
-a, --amplitude
-d, --delay
-h, --help
```
Options should be fairly self-explanatory.
* `tx-freq` / `rx-freq` are the frequencies used, in Hz.
* `tx-gain` / `rx-gain` are the gain settings in dB. (Refer to iio_info for valid values)
* `samplerate` is the configured sample rate in Hz.
This will influence the bandwidth that's echoed back as well as the delay
granularity. Minimum sample rate supported by IIO is ~ 2.1 Msps.
* `buffer-count` / `buffer-size` are advanced IIO parameters which are
included only for testing and should be left to their default values.
* `amplitude` is the scaling applied to the received signal before retransmission.
Beware of overflows !
* `delay` is the delay to be applied, in number of samples before
retransmitting the signal. Range is from 0 to 32767
To do a quick test, place the pluto near an UHD device.
Start the pluto relay with RX on 1G and TX on 1.1G with a 1000 samples delay:
```
# osmo-rfds -t 1100000000 -r 1000000000 -d 1000
[+] Options :
. TX frequency : 1100.000 MHz
. TX gain : -40.0 dB
. RX frequency : 1000.000 MHz
. RX gain : 40.0 dB
. Sample Rate : 4.000 Msps
. Buffer count : 4
. Buffer size : 4096 bytes
. Echo amplitude : 0.2
. Echo delay : 1000 samples
```
Then start the uhd pinger to Tx on 1G and RX on 1.1G :
```
./pinger -r 1100000000 -t 1000000000
[+] Options :
. TX frequency : 1000.000 MHz
. TX gain : 60.0 dB
. RX frequency : 1100.000 MHz
. RX gain : 60.0 dB
. Master Clock Rate : Auto
. Sample Rate : 2.000 Msps
. Burst length : 256 samples
. Burst period : 250.000 ms
. Maximum delay : 5.000 ms
[INFO] [UHD] linux; GNU C++ version 6.4.0; Boost_106500; UHD_3.14.0.0-99-g8e7768c7
[INFO] [B200] Detected Device: B205mini
[INFO] [B200] Operating over USB 3.
[INFO] [B200] Initialize CODEC control...
[INFO] [B200] Initialize Radio control...
[INFO] [B200] Performing register loopback test...
[INFO] [B200] Register loopback test passed
[INFO] [B200] Setting master clock rate selection to 'automatic'.
[INFO] [B200] Asking for clock rate 16.000000 MHz...
[INFO] [B200] Actually got clock rate 16.000000 MHz.
[INFO] [B200] Asking for clock rate 32.000000 MHz...
[INFO] [B200] Actually got clock rate 32.000000 MHz.
[+] Echo at (0.000000, 0.000000, 159487) :
[+] Echo at (0.098540, 615.705994, 549) : 549 (615.705994)
[+] Echo at (0.072381, 1.956668, 583) : 583 (1.956668)
[+] Echo at (0.073429, 2.770400, 583) : 583 (2.770400)
[+] Echo at (0.073496, 2.343132, 583) : 583 (2.343132)
[+] Echo at (0.072222, 2.368830, 583) : 583 (2.368830)
[+] Echo at (0.073371, 3.440041, 583) : 583 (3.440041)
```
This shows a delay of 583 samples.
If we run the pinger with RX on the same frequency as TX we get a 50 samples
delay. So of those 583 samples, only 533 samples are due to the pluto echo.
533 samples at 2 Msps = 266.5 us.
We asked for a delay of 1000 samples at 4 Msps = 250 us.
The additional 16.5 us represent the minimal delay due to analog delays and
fixed processing pipelines in the pluto.