From d6bd2d295fac86f773039422b4580d9f9e603ab4 Mon Sep 17 00:00:00 2001 From: Bartosz Podrygajlo Date: Wed, 29 Oct 2025 08:06:30 +0100 Subject: [PATCH] Add beam section to RFSimulator README.md --- radio/rfsimulator/README.md | 51 +++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) diff --git a/radio/rfsimulator/README.md b/radio/rfsimulator/README.md index 40688b755a..3b4c91d61d 100644 --- a/radio/rfsimulator/README.md +++ b/radio/rfsimulator/README.md @@ -209,3 +209,54 @@ to reduce the amount of transported samples: A possible, unimplemented optimization would be to compress samples. You can further [tune your machine](../../doc/tuning_and_security.md) + +# Beam simulation + +RFsimulator supports beam domain simulation. + +## Configuration + +Several new CLI parameters were added + +* `--rfsimulator.enable_beams` : enable beam domain simulation. Should match on server and all clients. +* `--rfsimulator.beam_gains ` : define a matrix of additional pathloss values (in dB) +to simulate the effect of different beam combinations in the RF simulator. You provide a comma-separated +list of numbers, which forms the first row of a square matrix. The rest of the matrix is filled by projecting +these values onto the diagonals, making it symmetric. + + Example list: `0,-2,-3` + Resulting matrix: + ``` + [[0,-2,-3], + [-2,0,-2], + [-3,-2,0]] + ``` + + The beam gain matrix will be used during beam combining. RX beam selects the row and TX beam selects column. + Using the example above, if gNB is receiving in beam 1 and the UE is transmitting in beam 1, an additional + 2 dB pathloss will be applied on top of the pathloss from the channel model (if present). + +* `--rfsimulator.beam_map ` : where `` is a `uint64_t` value where each bit is an enabled TX/RX beam. + For gNB: Initial beam_map, i.e. which beams gNB transmits/receives before calling beam APIs. + For UE: Beam position in beam space in the simulation. The UE is not expected to use the beam APIs for now. + +## Runtime commands + +### Moving the UE in beam space + +Use telnet command `rfsimu setbeams `. It works similar to the CLI command `--rfsimulator.beam_map `. +Suggest to only use single bits here + +### Modifying the gNB beam + +It is possible to test the beam domain simulation without implementing the beam APIs. The same telnet command can be used +to modify the tx/rx beam of the gNB. The gNB does not need to be beam-aware and use the new APIs. + +## Programming guide + +RFsimulator is attempting to simulate hardware device operation, but there are differences. Like with real hardware, +it is expected that you provide the configured beams in `set_beams` function ahead of sample reception. This is due +to the fact that a hardware device will buffer received samples before the driver requests them. + +For rfsimulator, as long as the call to `set_beams` with timestamp `n` is done before `trx_read` which is expected +to return sample `n` the beam switch command will apply to the received samples.